Skip to content
Lombok Docs

Core SDK

The Core SDK is the general-purpose, typed client for the Lombok platform API. It pairs an OpenAPI-typed HTTP client with a token-aware authenticator so that callers get end-to-end request/response typing and transparent access-token handling (attach, refresh, and logout-on-401) without wiring those concerns themselves.

Package

Section titled “Package”
@lombokapp/sdk

Exports

Section titled “Exports”

The package surface is intentionally small. From src/index.ts:

  • LombokSdk — the single exported class.
  • export * from '@lombokapp/types' — the shared platform types are re-exported, so consumers can import request/response and domain types from @lombokapp/sdk directly.

Runtime dependency: openapi-fetch. The authenticator type used by the constructor (TokenStore) lives in @lombokapp/auth-utils, not in this package.

LombokSdk

Section titled “LombokSdk”

A LombokSdk instance owns two public members:

MemberTypePurpose
apiClienttyped OpenAPI fetch clientOpenAPI-typed HTTP client, typed against the platform paths. Every request is authenticated automatically.
authenticatorAuthenticatorSession/auth surface: login, signup, SSO, viewer lookup, logout, and auth-state events.

Constructor

Section titled “Constructor”
new LombokSdk({
  basePath,
  tokenStore,
  onTokensCreated,
  onTokensRefreshed,
  onLogout,
})

Constructor options:

  • basePath: string — base URL the typed client and authenticator point at.
  • tokenStore?: TokenStore — pluggable persistence for access/refresh tokens.
  • onTokensCreated?: (tokens) => void | Promise<void> — invoked when a new token pair is set.
  • onTokensRefreshed?: (tokens) => void | Promise<void> — invoked after a successful refresh.
  • onLogout?: () => void | Promise<void> — invoked when the session is cleared.

The tokens passed to the callbacks have the shape:

{
  accessToken: string
  refreshToken: string
}

Authenticated request handling

Section titled “Authenticated request handling”

The apiClient does not issue raw fetch calls. Its fetch is wrapped so that every request:

  1. resolves a valid access token via authenticator.getAccessToken()
  2. sets Authorization: Bearer <token> when a token is available
  3. sends the request
  4. on a 401 response, triggers logout

This means callers can treat apiClient as an already-authenticated client — token attachment, refresh, and session teardown are handled for them.

The apiClient

Section titled “The apiClient”

apiClient is an openapi-fetch client typed against the platform OpenAPI paths. You call it with HTTP-method helpers and a typed path; request bodies, params, and response data are all type-checked against the contract.

import { LombokSdk } from '@lombokapp/sdk'


const sdk = new LombokSdk({ basePath: 'https://api.example.com' })
const { data, error, response } = await sdk.apiClient.GET('/api/v1/viewer')

Because the client follows the openapi-fetch shape, each call returns { data, error, response } rather than throwing on non-2xx.

The authenticator

Section titled “The authenticator”

sdk.authenticator is an Authenticator from @lombokapp/auth-utils. The SDK constructs it for you and exposes it for session operations. Its practical surface includes:

  • getAccessToken()
  • setTokens()
  • login()
  • signup()
  • handleSSOCallback()
  • completeSSOSignup()
  • verifyEmail()
  • getViewer()
  • logout()
  • state
  • addEventListener('onStateChanged', cb)
  • removeEventListener(...)

The exact request/response types for these flows come from @lombokapp/types. This page summarizes the surface reachable through sdk.authenticator; treat the source in @lombokapp/auth-utils as authoritative for signatures.

TokenStore

Section titled “TokenStore”

If you want tokens to persist, pass a TokenStore. The interface uses the same all-or-nothing TokensType shape as the authenticator itself:

type TokensType =
  | { accessToken: string; refreshToken: string }
  | { accessToken: undefined; refreshToken: undefined }


interface TokenStore {
  ready: () => Promise<void>
  setTokens: (tokens: TokensType) => Promise<void>
  getTokens: () => Promise<TokensType>
}

When no tokenStore is supplied, an in-memory store is used and tokens are lost when the instance is discarded.

Usage

Section titled “Usage”

Browser app, tokens in local storage

Section titled “Browser app, tokens in local storage”

Grounded in the main UI service wiring:

import { LombokSdk } from '@lombokapp/sdk'


export const sdkInstance = new LombokSdk({
  basePath,
  tokenStore: {
    ready: () => Promise.resolve(),
    setTokens: async (newTokens) => saveTokens(newTokens),
    getTokens: () => Promise.resolve(loadTokens()),
  },
  onTokensCreated: (tokens) => saveTokens(tokens),
  onTokensRefreshed: (tokens) => saveTokens(tokens),
  onLogout: () => {
    clearTokens()
    redirectToLogin()
  },
})


export const apiClient = sdkInstance.apiClient

Embedded app context

Section titled “Embedded app context”

The App Browser SDK constructs a LombokSdk internally with a bridge-backed token store and exposes it as part of its browser-side surface. If you are building an embedded app UI, prefer the App Browser SDK, which wraps the Core SDK for that environment.

When to use the Core SDK

Section titled “When to use the Core SDK”

Use it when you need a typed, authenticated client to the platform API and you are not specifically in a worker or embedded-app-browser runtime.

For specialized runtimes, prefer:

Section titled “Related”