SDK: npm install

npm i @forgecommerce/sdk @forgecommerce/contracts

Until the first published release

The packages are published at a release cut. Before that, install the tarballs your instance was built from — they are the same bytes, and everything on this page was verified against them.

1. A client

import { createClient } from '@forgecommerce/sdk';

const forge = createClient({
  baseUrl: 'https://your-instance.example',
  token: process.env.FORGE_TOKEN,
});

That is the whole setup. There is no per-resource client and no builder: three methods, because there are three faces.

Method	Face	Credential
forge.call(name, input)	the command port	tenant
forge.read(name, params)	the public read face	none — the store resolves the tenant
forge.readInternal(name, params)	the operator read face	tenant

2. Nothing throws

const me = await forge.readInternal('whoami', {});
if (!me.ok) throw new Error(me.error.kind);

console.log(me.value.scopes);
// [ 'catalog.admin.read', 'logistics.read', 'order.read' ]

Every method returns { ok: true, value } or { ok: false, error }. A refusal is a value, so the compiler makes you handle it — you cannot forget a catch that was never there.

const denied = await forge.readInternal('api_keys', {});
// { ok: false, error: { kind: 'forbidden', message: 'read requires the admin.users.write scope' } }

3. The names are checked at compile time

await forge.call('catalog.product.nao_existe', {});

error TS2345: Argument of type '"catalog.product.nao_existe"' is not assignable to parameter of type
'"admin_user.disable" | … | "warehouse.update"'.

await forge.call('catalog.brand.create', { nome: 'X' });

error TS2353: Object literal may only specify known properties, and 'nome' does not exist in
type 'CatalogBrandCreateInput'.

The types come from the same JSON Schemas the kernel validates against, so a wrong field is a red squiggle rather than a 400 in production.

Read params are not fenced the same way — yet

Command inputs are strongly typed, as above. Read params are not: the registry does not declare store as required, so forge.read('products', {}) compiles and then fails at runtime with not_found: unknown store:. An unknown extra param compiles too.

Pass store — the store id — on every public read. This is a known gap in the registry, not in the SDK, which mirrors it faithfully.

4. What is in the client

forge.commands.length      // 149 — the tenant command port
forge.reads.length         // 31  — the public read face
forge.internalReads.length // 91  — the operator read face

Three name lists, if you need to enumerate at runtime.

⚠️ forge.commands does not include the public shopper-journey commands or the platform commands: those live on different faces, and the SDK deliberately does not pretend otherwise. See surfaces.

5. A whole call

const products = await forge.read('products', {
  store: 'sto_…',
  limit: 1,
  projection: 'feed',
});

if (products.ok) console.log(products.value.items[0].title);

Ask for projection: 'feed' on lists — the default is full, which carries everything a product page needs and is far more than a list does.

Next

• Connect an ERP — the shape of a real integration.
• Reference · SDK — generated from the registry.