@s3p/sdk

Browser SDK for the S3-Native App Platform. Apps import this module; it hides the Cognito OIDC → Cognito Identity Pool → STS handshake and exposes a typed data-shaped surface (collection, log, doc, view, fn, transaction, plus admin facades for Cognito users and IAM roles).

Substrate-agnostic data primitives (lists, logs, rollups, envelope-encryption adapter) live in ../s3db/ and are re-exported here. The SDK is a thin composer of s3db + Cognito + IAM.

Public entries

| Entry | Purpose | |---|---| | @s3p/sdk | The main connect() + app.* surface for app code. | | @s3p/sdk/raw | Raw @aws-sdk/client-s3 clients + commands. Visible escape hatch. | | @s3p/sdk/functions | Server-function runtime types + helpers (used by /server). | | @s3p/sdk/conventions | Bucket naming, ARN parsing, callback URL composition. Importable from Node by the CLI. | | @s3p/sdk/policy-templates | IAM policy renderers. Used by both the CLI and app.roleAdmin. |

The split keeps Node-importable convention/policy code out of the browser SDK bundle, while letting both consumers share one source of truth.

Connect

import { connect } from "@s3p/sdk";

const app = await connect();      // reads /s3p.config.json
if (!app.signedIn) return app.signIn();

connect() discovers s3p.config.json from /, runs the Cognito OIDC handshake (Auth Code + PKCE), exchanges the ID token at the Identity Pool for STS credentials, and returns a fully configured app object.

Switching between client and server tabs is automatic — the SDK picks the {slug}-spa vs {slug}-server Cognito client based on URL (/server* paths route through the server client).

App surface

// Identity
app.me                // { sub, username, email, groups[], role, raw }
app.signedIn
app.signIn()
app.signOut()

// Data primitives
app.collection<T>(name, opts?)    // keyed JSON, mutable, indexes, subscribe, optimistic update
app.log<T>(name, opts?)            // ULID-keyed append-only, partition: "author"
app.doc<T>(pathTemplate)           // single named blob, {sub} substitution
app.view(def)                      // DuckDB-WASM over Parquet rollups

// RPC + transactions
app.fn(name)(input)                // invoke a server function
app.transaction([...steps])        // best-effort sequential, NOT ACID

// Secrets (server-role only)
app.secrets.put(name, value)
app.secrets.get(name)

// Admin facades (IAM-gated)
app.users.list/invite/addToGroup/removeFromGroup/disable/enable
app.roleAdmin.list/diff/sync

// Dev guards (raise on accidental large scans)
app.setDevGuards({ warn: 100, throw: 1000 })

// Raw escape (separate import)
import { rawS3Client } from "@s3p/sdk/raw";
const s3 = await rawS3Client(app);

See ../../DATA.md for the full primitive surface and access-control model, ../../SCOPE.md for the trust topology.

Why bundle to a single file

The platform pitch is "apps need no build step." Each app is a static bundle that imports the SDK from a URL. To make that fast and reliable, the SDK ships as one bundled dist/index.js (+ source map + .d.ts), with the AWS SDK kept external as a jsDelivr URL so it's CDN-cached across apps.

Layout

src/
  index.ts                public entry — re-exports the supported surface
  client.ts               connect() + app composer
  oidc.ts                 Cognito Auth Code + PKCE
  sts.ts                  Cognito Identity Pool → STS exchange
  me.ts                   identity + role derivation from cognito:groups
  collection.ts           app.collection<T>
  log.ts (via s3db)       app.log<T>
  doc.ts                  app.doc<T>
  view.ts (via s3db)      app.view(def)
  functions.ts            server-function runtime (inbox/outputs/claims)
  runtime.ts              startRuntime(...) for /server boot
  users.ts                Cognito User admin facade
  roles-module.ts         IAM/Identity Pool role admin facade
  cognito-admin.ts        thin Cognito client wrapper
  iam-admin.ts            thin IAM client wrapper
  identity-pool-admin.ts  thin Identity Pool client wrapper
  secrets.ts              SSE-KMS secrets helper
  transaction.ts          best-effort sequential
  dev-guards.ts           cost guards for collection/log scans
  events.ts               event bus
  conventions.ts          bucket naming, ARN parsing
  policy-templates.ts     IAM policy renderers
  raw.ts                  re-export raw @aws-sdk/client-s3
  types/cdn.d.ts          ambient module for the AWS SDK CDN URL

Dev loop

From the workspace root:

npm install
npm run -ws build
npm test --workspace=@s3p/sdk

Or per-package, from packages/sdk/:

npm run build       # tsup → dist/
npm run dev         # tsup --watch
npm test            # vitest run
npm run typecheck
npm run lint

After changing SDK sources, run npm run build and refresh the consumer app — apps fetch the SDK as a plain ES module at runtime, so no app rebuild is needed.

Tests

Vitest suite covers OIDC flow, STS exchange, group → role derivation, collection/log behavior with mock S3, envelope encryption recipient-set permutations, function-registry dispatch, and surface contract tests.