SDK: npm install

npm i @forgeco/sdk @forgeco/contracts

Published, and pinned to the kernel you run

The nineteen @forgeco/* packages went to npm at the v0.3.0 cut; @forgeco/sdk and @forgeco/contracts carry the kernel’s own version, so install the pair that matches the instance you are calling. Everything on this page was executed against a live instance with the published packages.

1. A client

import { createClient } from '@forgeco/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: four methods, because there are four 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
forge.readBulk(name, params)	the bulk read face — the public answer, charged to a budget of its own	tenant (its own stores) or platform (platform.bulk_read)

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: store is fenced, extra params depend on the read

Every public read declares store as required, so forge.read('products', {}) does not compile. Unknown extra params are another matter: a read with a closed schema (categories, availability) rejects them at compile time, but products and search accept any key — the merchant’s own filter vocabulary (option.*, cf.*) cannot be known at build time — so a misspelled filter compiles there.

Pass store — the store id, not its handle — on every public read.

4. What is in the client

forge.commands.length      // 150 — the tenant command port
forge.reads.length         // 32  — the public read face
forge.internalReads.length // 100 — the operator read face
forge.bulkReads.length     // 10  — the bulk read face

Four 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.