Generated clients

Use app-native generated SDK helpers when your Valqio schema defines product actions.

Generated clients turn Valqio configuration into app-native TypeScript helpers. They keep product code close to your domain language while preserving Valqio's runtime decision model.

Generated client files come from Console or Valqio's SDK tooling for your project.

For a full integration path, see the end-to-end generated client guide.

For non-consuming feature and parameter checks, see feature and parameter access.

When to use generated clients

Use a generated client when your project has product actions, meters, flags, limits, plans, or configs that should be referenced by stable app aliases.

Generated clients help you avoid:

hard-coded meter keys scattered through app code
mismatched subject shapes
missing request IDs
unresolved binding drift
hand-written reserve, commit, and release glue for common actions

Typical shape

import {
  createInvoicingValqioClientFromEnv,
  inspectInvoicingValqioReadiness,
} from './valqio.generated'

async function createReadyInvoicingClient() {
  const bindings = inspectInvoicingValqioReadiness()
  if (!bindings.ready) {
    throw new Error(`Valqio bindings unresolved: ${bindings.unresolved.join(', ')}`)
  }

  const invoicing = createInvoicingValqioClientFromEnv({
    runtimeOverrides: { mode: 'remote-only' },
  })
  const runtime = await invoicing.ready()
  if (!runtime.snapshotReady) {
    throw new Error('Valqio published runtime snapshot is unavailable')
  }

  return invoicing
}

const invoicingPromise = createReadyInvoicingClient()

export async function sendInvoiceForWorkspace(workspaceId: string, requestId: string) {
  const invoicing = await invoicingPromise
  const customer = invoicing.customer({ id: workspaceId }, { requestId })
  const action = await customer.actions.sendInvoice.run({
    requestId,
    idempotencyKey: `sendInvoice:${requestId}`,
    context: { endpoint: '/invoices/send' },
  })

  if (!action.ok) {
    return {
      status: action.status === 'blocked' ? 402 : 503,
      body: { status: action.status, requestId },
    }
  }

  const invoice = await sendInvoice()
  return { status: 200, body: { invoice, requestId } }
}

Readiness

Run both checks at startup or health-check time:

inspectInvoicingValqioReadiness() synchronously verifies that generated aliases resolve to concrete bindings.
await invoicing.ready() checks whether the runtime client can obtain a published snapshot. Require snapshotReady before serving product work that depends on that environment. After the first load, this check may use the client's cached snapshot; it is not a general data-plane health probe.

Failing fast is better than silently running product work without enforcement.

Reservations

For async work, prefer generated reservation helpers when the action is backed by a reservation:

The recordPendingValqio* and markValqio*Applied calls below represent app-owned durable storage. A reconciliation worker should retry any pending operation with the same idempotency key.

export async function renderVideoForCustomer(workspaceId: string, jobId: string) {
  const invoicing = await invoicingPromise
  const customer = invoicing.customer({ id: workspaceId }, { requestId: jobId })
  const keys = customer.actions.renderVideo.createIdempotencyKeys(`renderVideo:${jobId}`)
  const reserved = await customer.actions.renderVideo.reserve({
    quantity: 1,
    requestId: jobId,
    idempotencyKey: keys.reserve,
  })

  if (!reserved.allowed || !reserved.reservation?.reservationId) {
    return {
      status: 402,
      body: { reasonCode: reserved.reasonCode, requestId: jobId },
    }
  }

  const reservationId = reserved.reservation.reservationId
  let video

  try {
    video = await renderVideo()
  } catch (error) {
    await recordPendingValqioRelease({
      reservationId,
      requestId: jobId,
      idempotencyKey: keys.release,
    })
    await customer.actions.renderVideo.releaseWithRetry({
      reservationId,
      requestId: jobId,
      idempotencyKey: keys.release,
    })
    await markValqioReleaseApplied(reservationId)
    throw error
  }

  await recordPendingValqioCommit({ reservationId, requestId: jobId, idempotencyKey: keys.commit })
  await customer.actions.renderVideo.commitWithRetry({
    reservationId,
    requestId: jobId,
    idempotencyKey: keys.commit,
  })
  await markValqioCommitApplied(reservationId)

  return video
}

Commit only after the app has completed the work it intends to charge for. Release if the work fails before completion. If commit or release remains uncertain after retries, keep its durable pending record and reconcile with the same key. Do not release completed work.

Generated clients

When to use generated clients

Typical shape

Readiness

Reservations

On this page