> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bijection.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Consumer SDK packages

> Distribute selected public contracts to applications in separate repositories

Generate an installable package containing typed collections, selected relationships,
business operations, questions, ordinary public functions, and resource documentation.
Consumers need the package and a business session; backend source and handwritten
contract types are unnecessary.

## Select public resources

Use `bijection discover --format json` and `bijection describe <ref> --format json`
under the business identity that may export the public metadata. Copy exact resource
references into `bijection.sdk.json`:

```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "version": 1,
  "package": {
    "name": "@acme/operations-sdk",
    "version": "0.1.0"
  },
  "resources": [
    "collection:orders",
    "collection:customers",
    "relation:orders/customer",
    "operation:orders:approve",
    "function:analytics:revenue"
  ],
  "output": "./generated/operations-sdk"
}
```

Questions use the `function:` reference returned by discovery and have kind
`question`. Names and casing are preserved. Selecting a relationship requires its
source and target collections. An object-bound operation requires its public target
collection. The generator reports missing selections; it does not recursively add
other collections or operations. Operation companion routes are included automatically.

Select whole public resources. A reference to another ID domain supplies an ID type
without adding a reader for that collection. Unvalidated functions are refused;
explicit `v.any()` validators retain their declared permissive type. Collections
require supported object readers or native series metadata. For a remote rowset,
select its admitted question instead.

## Generate and distribute

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection sdk generate --config bijection.sdk.json --url "$BIJECTION_URL"
npm pack ./generated/operations-sdk
```

The command reads public metadata at one fixed timestamp under the selected
business identity. It writes the package and an adjacent `bijection.sdk.lock.json`
containing the complete selected contract. Output paths are relative to the config.
Commit both configuration and lockfile. Treat the lockfile and package as public
metadata for the audience to which you distribute them.

The package contains ESM JavaScript, TypeScript declarations, `contract.json`,
resource-specific Markdown documentation, and typed usage examples. Its exact
runtime dependency is installed automatically under the `bijection` alias from
the supported `@bijectionhq/bijection` package. Release CLIs pin that runtime;
contributor builds must supply `--runtime-version` with an exact supported version.

Install the tarball in a separate application, or publish it through your normal
private npm registry workflow. Generation never publishes a package.

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
npm install ./acme-operations-sdk-0.1.0.tgz
```

```ts theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import { createWorkspace, type Objects } from "@acme/operations-sdk";

const client = createWorkspace({
  url: deploymentUrl,
  token: async () => getBusinessSessionToken(),
});

const page = await client.collections.orders.page({
  fields: ["_id", "status"],
  page_size: 25,
});

async function customerFor(id: Objects["collection:orders"]["_id"]) {
  return client.collections.orders.related(id, "customer");
}
```

Autocomplete and declarations expose only selected resources. The package exports
`api`, `createWorkspace`, `Workspace`, `Objects`, `Operations`, `Questions`,
`Functions`, `Interfaces`, `Id`, and `ComponentId`. Root and component IDs retain
distinct type domains even when their table names match. Read its `docs/index.md` and
`examples/usage.ts` for the actual selected inputs and results. Ordinary public
function references also work with `BijectionHttpClient` and `BijectionClient`,
re-exported by the package so consumers do not depend on dependency hoisting.

For a headless Node application, import durable request storage from the generated
package's `/node` entry point. Give it a private directory and a namespace for the
authenticated principal. This retains operation and question request identities
across process restarts:

```ts theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import { createWorkspace } from "@acme/operations-sdk";
import { fileRequests } from "@acme/operations-sdk/node";

const client = createWorkspace({
  url: deploymentUrl,
  token: async () => getBusinessSessionToken(),
  requests: fileRequests(privateJournalDirectory, {
    deployment: deploymentUrl,
    namespace: authenticatedPrincipal,
  }),
});
```

The generated `examples/node.ts` configures this journal. Resource examples include
operation capture and restoration, and question output collection with cleanup.

## Reproduce and review changes

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection sdk generate --config bijection.sdk.json --frozen
bijection sdk generate --config bijection.sdk.json --frozen --check
bijection sdk diff --config bijection.sdk.json --url "$BIJECTION_URL" --format json
bijection sdk diff --config bijection.sdk.json --url "$BIJECTION_URL" --check
```

Frozen generation reads the complete lockfile and requires no deployment, backend
source, or JavaScript build toolchain. It refuses changed selections. `--check`
compares expected files without changing them. Generated output has an ownership
inventory; regeneration refuses directories containing unrelated files or symlinks.

The diff reports selected resource additions, removals, validator changes,
relationship changes, operation contracts, question outputs and bindings, and
documentation changes. `--check` exits unsuccessfully on drift. Review changes,
choose the package's next version, then generate without `--frozen` to refresh the
lockfile and package. Package versions are independent of contract fingerprints.

When a replacement contract cannot generate a supported package, the diff still
reports its changes, with `generatable: false` and a `generationError` diagnostic.
Unavailable resources retain discovery's existing refusal behavior.

The executable contract digest excludes labels and descriptions. The content
digest also includes documentation and the exact runtime version. Discovery's
caller-bound basis is used only during capture and is absent from the package.

## Runtime contracts and authorization

Generated operation and question references retain their native contract digests.
Collection reads check the generated shape, component identity, and predicate
contract; selected relationship reads also check their traversal metadata and
endpoint contracts. An unrelated public resource change does not change the selected SDK.

All calls still check current business authorization. Package selection grants no
read or invocation permission. Use runtime credentials in the consuming application;
credentials and administrative keys are never included in the generated package.

Contract diagnostics identify the resource and include a regeneration command using
the publisher's configuration filename and the current runtime deployment URL.
Run it from the publisher's configuration directory after reviewing `sdk diff`.
An operation's unknown outcome must be recovered with its existing request identity. Keep the
existing operation capture, review, acceptance, and recovery workflow described in
[business operations](/operations/overview). Question examples retain the named
output contracts and use the existing [question lifecycle](/views/questions).

`bijection sdk export` remains the command for exporting the general runtime SDK
tarball. Consumer package generation is `bijection sdk generate`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.