SDK Overview

The SeptemCore SDK is a monorepo of TypeScript packages that gives module developers a single, consistent interface to all 7 platform primitives. Every package follows the same design — imperative calls for backend interactions, React hooks for reactive UI state, and a shared HTTP client with automatic error handling.

Package Ecosystem

12 SDK packages

10 frontend packages

Architecture: sdk-core → Domain SDKs

All domain packages depend on @platform/sdk-core. sdk-core provides:

• Typed HTTP client — wraps fetch with retry logic, automatic Authorization: Bearer header injection, and RFC 9457 error parsing.
• PlatformError class — typed error with type, status, detail, traceId, and errors[] fields.
• Shared TypeScript types — TenantId, UserId, CursorMeta, ListResponse<T>, and all primitive domain types.
• kernel factory — the entry point that returns namespaced primitive interfaces after kernel.init().

@platform/sdk-core
  ├── @platform/sdk-auth
  ├── @platform/sdk-data
  ├── @platform/sdk-events
  ├── @platform/sdk-notify
  ├── @platform/sdk-files
  ├── @platform/sdk-money
  ├── @platform/sdk-audit
  └── @platform/sdk-flags

The kernel.primitive() Pattern

Every SDK interaction goes through the kernel singleton. The pattern is intentional: it prevents modules from constructing raw fetch calls, ensures all requests carry the correct tenant context, and allows the platform to swap the underlying transport without breaking modules.

// module entry point — initialize once
import { kernel } from '@platform/sdk-core';

await kernel.init({
  tenantId: import.meta.env.VITE_TENANT_ID,
  // token is managed automatically via the shell's auth context
});

// access any primitive via the same gateway
const contact = await kernel.data().retrieve('contacts', 'rec_01j9...');
const wallet  = await kernel.money().retrieve('01j9p3...');
await kernel.audit().record('crm.contact.viewed', 'contact', contact.id);

Each kernel.{primitive}() call returns an interface scoped to the current tenant. Cross-tenant calls are structurally impossible — the tenant ID is stored in sdk-core's internal context and injected into every request header automatically.

Frontend Hooks vs Imperative API

The SDK provides two surfaces for every primitive:

Hooks — reactive, for React components

Hooks use TanStack Query v5 under the hood. They handle loading states, background refetching, and cache invalidation automatically.

import { useQuery, useMutation } from '@platform/sdk-data';

export function ContactList() {
  const { data, isLoading } = useQuery('contacts');

  const create = useMutation('contacts', {
    onSuccess: () => {
      // TanStack Query invalidates the 'contacts' cache automatically
    },
  });

  if (isLoading) return <Spinner />;

  return (
    <>
      {data.data.map((c) => <ContactRow key={c.id} contact={c} />)}
      <button onClick={() => create.mutate({ name: 'New contact' })}>
        Add
      </button>
    </>
  );
}

Imperative API — for business logic

Useful in event handlers, background jobs, lifecycle hooks, and anywhere outside a React component tree.

import { kernel } from '@platform/sdk-core';

// In an event handler registered at module startup
kernel.events().subscribe('crm.contact.created', async (event) => {
  const contact = await kernel.data().retrieve('contacts', event.data.contactId);
  await kernel.notify().send({
    userId: event.data.assignedTo,
    channel: 'in_app',
    title: 'New contact assigned',
    body: contact.name,
  });
  await kernel.audit().record(
    'crm.contact.auto_notified',
    'contact',
    contact.id,
    { after: { notified: true } },
  );
});

SDK Package Reference

@platform/sdk-auth

Install: pnpm add @platform/sdk-auth

@platform/sdk-data

Install: pnpm add @platform/sdk-data

@platform/sdk-events

Install: pnpm add @platform/sdk-events

Events are automatically scoped to the current tenant. Attempting to publish a type not in manifest.events.publishes[] returns 403 Forbidden.

@platform/sdk-notify

Install: pnpm add @platform/sdk-notify

@platform/sdk-files

Install: pnpm add @platform/sdk-files

@platform/sdk-money

Install: pnpm add @platform/sdk-money

All money amounts are integers in the minor currency unit (cents for USD). Floating-point values are rejected at the schema level.

@platform/sdk-audit

Install: pnpm add @platform/sdk-audit

record() is fire-and-forget. The SDK returns immediately; the record is written asynchronously via Kafka → ClickHouse.

@platform/sdk-flags

Install: pnpm add @platform/sdk-flags

Flags are evaluated from an in-memory snapshot refreshed every 15 seconds. No network call per evaluation. If GoFeatureFlag is unavailable, the SDK uses the stale in-memory cache; if the cache is empty, all flags return false (fail-closed).

sdk-testing — Test Utilities

Install: pnpm add -D @platform/sdk-testing

Provides factory functions and mock implementations for every SDK package, so module tests run without a real backend:

import { kernel } from '@platform/sdk-testing';

// kernel from sdk-testing is a full mock — no HTTP calls
const mockContact = kernel.data().mockFactory('contacts', {
  name: 'Test Contact',
  email: '[email protected]',
});

// All SDK methods are jest-compatible spies
kernel.money().credit.mockResolvedValue({ id: 'tx_01j9...' });

Built-in fixtures:

import { fixtures } from '@platform/sdk-testing';

const tenant  = fixtures.tenant();      // TenantRow with valid UUID v7
const user    = fixtures.user();        // UserRow with email and roles
const wallet  = fixtures.wallet();      // WalletRow (USD, zero balance)
const file    = fixtures.file();        // FileRow (status: available)

sdk-codegen — Type Generation Pipeline

Install: pnpm add -D @platform/sdk-codegen

Generates TypeScript types and client code from platform specs:

# Generate types from module's OpenAPI spec
npx sdk-codegen openapi --input ./api/openapi.yaml --output ./src/gen/api.ts

# Generate event types from Avro schemas in Event Bus
npx sdk-codegen events --input services/event-bus/schemas/ --output ./src/gen/events.ts

The output files are type-safe, tree-shakeable, and imported directly into the module's TypeScript codebase. The codegen step runs in CI on every PR that modifies openapi.yaml or event schemas.

Installation Summary

# Install the primitives your module uses
pnpm add @platform/sdk-core @platform/sdk-auth @platform/sdk-data

# Add dev utilities
pnpm add -D @platform/sdk-testing @platform/sdk-codegen

# Or scaffold a new module with everything pre-configured
npx @platform/create-module my-module

After scaffolding, kernel.init() is called once at module bootstrap. All SDK packages read tenant context from the same shared Zustand store injected by the UI Shell at login.