@opencollectiblesfoundry/api-client

Typed SDK for the OCF Core API. Handles Auth0 client credentials auth automatically — no token management required.

Installation

npm install @opencollectiblesfoundry/api-client

Quick Start

import { createOcfClient } from '@opencollectiblesfoundry/api-client'

const sdk = createOcfClient({
  clientId: process.env.OCF_CLIENT_ID,
  clientSecret: process.env.OCF_CLIENT_SECRET,
  projectSecret: process.env.OCF_PROJECT_SECRET, // 64-char hex from POST /projects/:id/secret
})

// List tokens
const { data: tokens, error } = await sdk.tokens.findAll({
  body: { limit: 10 },
})
if (error) {
  console.error(error)
} else {
  console.log(`Fetched ${tokens.data.length} of ${tokens.total} tokens`)
}

// Issue a token — pass `email`, the SDK derives `identityToken` automatically
const { data: token } = await sdk.tokens.issue({
  body: {
    collectibleId: 'abc',
    clientUserId: 'user-123',
    email: '[email protected]',
  },
})

// Transfer a token to another collector
await sdk.tokens.transfer({
  path: { id: 'token-id' },
  body: {
    toClientUserId: 'user-456',
  },
})

// Issue a batch — collectors carry email, not identityToken
await sdk.tokens.issueBatch({
  body: {
    collectibleIds: ['abc', 'def'],
    collectors: [
      { clientUserId: 'user-123', email: '[email protected]' },
      { clientUserId: 'user-124', email: '[email protected]' },
    ],
  },
})

// Get the caller's project
const { data: project } = await sdk.projects.findMine()
console.log(`Project: ${project.name}`)

Configuration

Environment presets

Pass environment to use a named preset. 'dev' and 'prod' are populated; 'sandbox' will be added when that environment launches.

const sdk = createOcfClient({
  clientId: '...',
  clientSecret: '...',
  environment: 'prod', // 'dev' | 'prod' — defaults to 'dev'
})

Explicit overrides

Any of baseUrl, auth0Domain, and audience can be overridden individually.

const sdk = createOcfClient({
  clientId: '...',
  clientSecret: '...',
  baseUrl: 'http://localhost:3000',
  auth0Domain: 'ocf-dev-enterprise.us.auth0.com',
  audience: 'https://dev-ocf-core.com',
})

Config reference

| Field | Type | Default | Description | |---|---|---|---| | clientId | string | required | Auth0 client ID | | clientSecret | string | required | Auth0 client secret | | projectSecret | string | required | 64-char hex HMAC secret returned by POST /projects/:id/secret. Used to derive identityToken from email. | | environment | 'dev' \| 'sandbox' \| 'prod' | 'dev' | Named preset | | baseUrl | string | from preset | API base URL | | auth0Domain | string | from preset | Auth0 tenant domain | | audience | string | from preset | Auth0 API audience identifier |

Identity tokens

tokens.issue and tokens.issueBatch accept email and the SDK substitutes it with identityToken before forwarding. The token is HMAC-SHA256(canonicalize(email), hexDecode(projectSecret)) as a 64-char lowercase hex digest, where canonicalize is email.trim().toLowerCase().

This must match what ocf-secrets-service computes at resolve time, byte-for-byte. The contractual fixture is pinned in src/identity-token.spec.ts and mirrored in ocf-secrets-service. If you regenerate or change the helper, both specs must continue to agree.

computeIdentityToken is exported if you need to compute it yourself.

Sorting

Token search accepts sortBy: 'issuedAt' or sortBy: 'metadata.<field>', where <field> is a top-level token metadata field. Metadata sorting requires either exactly one collectibleId filter, or both an accountLinkId/clientUserId and a tokenSchemaId filter.

Collectible search accepts sortBy: 'createdAt' or sortBy: 'tokenCount'.

Auth

The SDK uses the Auth0 client credentials flow. The token is fetched lazily on the first request, cached in memory, and refreshed automatically 60 seconds before it expires.

Error Handling

All methods return { data, error }. HTTP errors do not throw — check error instead.

const { data, error } = await sdk.collectibles.findOne({ path: { id: 'some-id' } })
if (error) {
  // typed from the OpenAPI spec
}

Resources

sdk.tokens

findAll · findOne · issue · issueBatch · transfer · update · remove

sdk.collectibles

findAll · findOne · create · update · remove

sdk.accountLinks

findAll · findOne · update · remove · removeByClientUserId

await sdk.accountLinks.removeByClientUserId({
  projectId: 'project-id',
  clientUserId: 'user-123',
})

sdk.projects

findAll · findOne · findMine · create · update · remove · getMembers · addMember · inviteMember · updateRole · removeMember

sdk.schemas

findAll · findOne · create · update · remove

sdk.users

findAll · findOne · findMe · create · update · remove

sdk.provisioning

provision

Generated Types

All types and SDK classes are generated from the OpenAPI spec via @hey-api/openapi-ts. To regenerate (requires a running local API server):

yarn generate

To run the smoke test against the dev environment:

yarn generate && yarn smoke-test

Requires a .env file with OCF_CLIENT_ID and OCF_CLIENT_SECRET.