SDK — Overview

The Platform SDK is the developer interface for building modules on top of the Platform-Kernel. Instead of hand-rolling HTTP clients, JWT handling, and service integrations, every module author imports one or more @platform/sdk-* packages and gets production-grade, fully typed primitives immediately.

All SDK packages are written in TypeScript (strict mode) and share a single underlying HTTP client and authentication layer from @platform/sdk-core.

Package Ecosystem

Package	Primary exports	Purpose
`@platform/sdk-core`	`kernel.init()`, HTTP client, error types	Foundation — shared HTTP, token management, interceptors
`@platform/sdk-auth`	`useAuth()`, `useRBAC()`, `requireRole()`	Identity, access control, provider management
`@platform/sdk-data`	`useQuery()`, `useMutation()`, `useRealtime()`	Data layer — TanStack Query wrapper with platform types
`@platform/sdk-events`	`publish()`, `subscribe()`, `onEvent()`	Event Bus — tenant-scoped, typed event system
`@platform/sdk-notify`	`send()`, `sendBatch()`, `sendFromTemplate()`	Notifications — email, SMS, WebSocket, push
`@platform/sdk-files`	`upload()`, `download()`, `getUrl()`, `processImage()`	File storage — S3 presigned URLs, image processing
`@platform/sdk-money`	`credit()`, `debit()`, `getBalance()`, `transfer()`	Wallet operations — integer-only, ISO 4217, idempotency
`@platform/sdk-audit`	`record()`, `getHistory()`	Structured audit trail — non-blocking, auto-context
`@platform/sdk-ui`	Design system components	Buttons, forms, tables, charts, `<ImageUpload>`, `<EmbedCodeBlock>`
`@platform/sdk-testing`	Mocks, fixtures, test helpers	Unit and integration test utilities for module authors

Dependency rule: sdk-core is a transitive dependency of every other domain SDK. You do not need to install it manually — it is included automatically. Install only the domain SDKs you need.

Architecture

┌─────────────────────────────────────────────────────────┐
│                   Module Code (TypeScript)               │
├────────────┬──────────────┬──────────────┬──────────────┤
│ sdk-auth   │  sdk-data    │  sdk-events  │  sdk-notify  │
├────────────┴──────────────┴──────────────┴──────────────┤
│                     sdk-core                             │
│  HTTP client · RFC 9457 errors · Token management        │
│  BroadcastChannel coordination · Request interceptors    │
└──────────────────────────────────────────────────────────┘
              ↕ REST / gRPC via API Gateway
┌─────────────────────────────────────────────────────────┐
│                 Platform-Kernel Services                 │
│  IAM · Event Bus · Notify · Files · Money · Audit ...   │
└─────────────────────────────────────────────────────────┘

All network traffic from module code goes through the API Gateway. Modules never call backend services directly. The SDK abstracts this boundary entirely — from the developer's perspective, it is just a function call.

Installation

Install only the packages your module needs:

pnpm add @platform/sdk-auth @platform/sdk-data @platform/sdk-events

All @platform/sdk-* packages require Node.js ≥ 20 and TypeScript ≥ 5.0.

Initialization

Every module must call kernel.init() once, at startup, before using any SDK method:

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

await kernel.init({
  apiUrl:      'https://api.septemcore.com/v1',
  tenantId:    process.env.PLATFORM_TENANT_ID!,
  moduleId:    'my-casino-module',
  environment: 'production',   // 'development' | 'staging' | 'production'
});

kernel.init() performs:

Validates moduleId against the Module Registry
Loads and caches the module's manifest (permissions, events, feature flags)
Establishes the WebSocket connection for real-time subscriptions
Primes the feature flag cache from GoFeatureFlag
Sets up the BroadcastChannel for cross-tab token coordination

After kernel.init() resolves, all SDK methods are available. Calling any SDK method before init() completes throws KernelNotInitializedError.

Error Format (RFC 9457)

Every error returned by any platform API follows RFC 9457 (Problem Details for HTTP APIs). The SDK automatically parses these into typed PlatformError objects:

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

try {
  await kernel.money().credit({ ... });
} catch (error) {
  if (error instanceof PlatformError) {
    console.error(error.type);     // "https://api.septemcore.com/problems/insufficient-funds"
    console.error(error.title);    // "Insufficient Funds"
    console.error(error.status);   // 402
    console.error(error.detail);   // Human-readable description
    console.error(error.traceId);  // OpenTelemetry trace ID for debugging
    console.error(error.instance); // "/api/v1/money/debit"
  }
}

Content-Type: application/problem+json is required on all error responses. The SDK throws a raw Error only on network-level failures (no HTTP response received).

Standard Error Fields

Field	Type	Source
`type`	URI string	Identifies the problem type, links to documentation
`title`	string	Short human-readable summary (stable across requests)
`status`	int	HTTP status code
`detail`	string	Human-readable, request-specific explanation
`instance`	string	URI of the specific request that caused the error
`traceId`	string	OpenTelemetry trace ID (for cross-service correlation)
`errors[]`	array	Validation errors only — one entry per failed field

CLI Scaffolding

Create a new module with the platform CLI:

npx @platform/create-module my-casino-module

Generated structure:

my-casino-module/
├── src/
│   ├── engines/          ← business logic
│   ├── pages/            ← UI pages (MFE)
│   ├── api/              ← REST endpoints
│   ├── events/           ← Event Bus subscriptions
│   └── embeds/           ← external site embed widgets (Web Components)
├── module.manifest.json  ← name, version, permissions, embeds
├── federation.config.js  ← Module Federation config
├── tests/
└── docs/

sdk-core — HTTP client, error handling, token management, interceptors
sdk-auth — Authentication hooks, RBAC guards, provider management
sdk-data — Data layer: useQuery, useMutation, useRealtime
sdk-events — Event publishing and subscription
sdk-notify — Notifications and channel adapters
sdk-files — File upload, download, image processing
sdk-money — Wallet operations and balance management
sdk-audit — Audit trail recording and retrieval

Package Ecosystem​

Architecture​

Installation​

Initialization​

Error Format (RFC 9457)​

Standard Error Fields​

CLI Scaffolding​

Related SDK Pages​