@stratum-hq/sdk 0.2.3 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christian Crank
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,77 @@
+# @stratum-hq/sdk
+
+HTTP client, LRU cache, and Express/Fastify middleware for the [Stratum](https://github.com/stratum-hq/Stratum) control plane. Resolves tenant context from incoming requests and attaches it to the request object.
+
+## Installation
+
+```bash
+npm install @stratum-hq/sdk @stratum-hq/core
+```
+
+## Quick Start
+
+```typescript
+import { stratum } from "@stratum-hq/sdk";
+
+const s = stratum({
+  controlPlaneUrl: "http://localhost:3001",
+  apiKey: "sk_live_your_key",
+});
+
+// Express
+app.use(s.middleware({ jwtClaimPath: "tenant_id" }));
+
+// Fastify
+app.register(s.plugin({ jwtClaimPath: "tenant_id" }));
+
+// Direct client access
+const ctx = await s.client.resolveTenant("tenant-uuid");
+```
+
+Prefer the pieces individually? Import them directly:
+
+```typescript
+import { StratumClient, expressMiddleware } from "@stratum-hq/sdk";
+
+const client = new StratumClient({
+  controlPlaneUrl: "http://localhost:3001",
+  apiKey: "sk_live_your_key",
+  cache: { enabled: true, ttlMs: 60000, maxSize: 100 },
+});
+
+app.use(expressMiddleware(client, {
+  jwtClaimPath: "tenant_id",
+  jwtSecret: process.env.JWT_SECRET,
+  headerName: "X-Tenant-ID",
+}));
+
+app.get("/data", (req, res) => {
+  res.json({ tenantId: req.tenant.tenant_id, config: req.tenant.resolved_config });
+});
+```
+
+## Features
+
+- **`StratumClient`** — HTTP client for the control plane API (`resolveTenant`, `getTenantTree`, `createTenant`, `createWebhook`, `listRegions`, …) with a built-in LRU cache that auto-invalidates on mutations.
+- **`expressMiddleware` / `fastifyPlugin`** — resolve the tenant from a JWT claim, `X-Tenant-ID` header, or custom resolvers (tried in that order), then populate `req.tenant`.
+- **AsyncLocalStorage context** — `getTenantContext()` and `runWithTenantContext()` make the resolved context available to services that never see the request object.
+- **Custom resolvers** — supply async functions (e.g. subdomain- or query-based) via the `resolvers` option.
+
+JWT resolution activates only when `jwtSecret` or `jwtVerify` is provided; otherwise Bearer tokens are ignored. If no tenant is found, the middleware returns `400 MISSING_TENANT`.
+
+## Error Handling
+
+The SDK throws typed errors from `@stratum-hq/core`:
+
+```typescript
+import { TenantNotFoundError, UnauthorizedError } from "@stratum-hq/core";
+```
+
+## Links
+
+- Documentation: https://docs.stratum-hq.org/packages/sdk/
+- GitHub: https://github.com/stratum-hq/Stratum
+
+## License
+
+MIT © Christian Crank

package/package.json

@@ -1,7 +1,20 @@
 {
   "name": "@stratum-hq/sdk",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Stratum Node.js SDK for multi-tenant context propagation",
+  "keywords": [
+    "multi-tenancy",
+    "multi-tenant",
+    "saas",
+    "tenant",
+    "context-propagation",
+    "middleware",
+    "node",
+    "typescript",
+    "express",
+    "fastify",
+    "stratum"
+  ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -35,5 +48,10 @@
     "fastify": "^5.3.2",
     "typescript": "^5.4.0",
     "vitest": "^1.6.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/stratum-hq/Stratum.git",
+    "directory": "packages/sdk"
   }
 }