@manajemin-dev-cli/sdk 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,4 @@
+Manajemin developer tools
+Copyright 2026 PT Manajemin Aksi Jejaring Usaha
+
+This product includes software developed by PT Manajemin Aksi Jejaring Usaha (https://www.manajemin.com).

package/README.md

@@ -1,3 +1,70 @@
-# Temporary Holding Version
+# @manajemin-dev-cli/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Connect an app to the Manajemin platform: verify what the platform sends you, redeem sign-in codes, acknowledge installs
+and removals, report usage, and keep every database query inside one organisation's workspace. No runtime dependencies.
+Node 20 or later.
+
+```sh
+npm install @manajemin-dev-cli/sdk
+```
+
+The rules it implements are the published contract in `doc/integration/` (`contract.json`, `openapi.yaml`,
+`signature-vectors.json`), not this code. Its tests run every published signature vector.
+
+## Receive a delivery
+
+```ts
+import { receive } from "@manajemin-dev-cli/sdk";
+
+const result = receive({ secret: process.env.MANAJEMIN_WEBHOOK_SECRET!, headers: request.headers, rawBody });
+if (!result.ok) return new Response(result.reason, { status: result.status }); // 401 bad signature, 400 malformed
+const { id, event, body } = result.delivery;
+// Deduplicate on `id`; answer 2xx only after the event is stored.
+```
+
+Pass the **raw** body, never a re-serialised object. While you replace the webhook secret, pass both:
+`secret: [newSecret, oldSecret]`. For 24 hours after a secret changes the platform signs with both.
+
+## Call the platform
+
+```ts
+import { ManajeminClient } from "@manajemin-dev-cli/sdk";
+
+const manajemin = new ManajeminClient({ appKey: process.env.MANAJEMIN_APP_KEY!, appId: "my-tasks", installTokens });
+await manajemin.ack(entityId);                                  // after the workspace exists: activates the install
+await manajemin.uninstallAck(entityId);                         // after the workspace's data is deleted
+await manajemin.ackRemoval({ entityId, memberId, outboxId });   // after the member's data is reassigned or deleted
+const { claims, redirect } = await manajemin.exchange(code, { entityId }); // SSO landing: ?code=…&entity=…
+await manajemin.reportUsage([{ metric: "tasks_created", qty: 1, entity_id: entityId, dedupe_key: taskId }]);
+```
+
+`installTokens` is where you keep per-install tokens if the platform team switches your app to them: `get`, `set` and
+`delete` by entity id. The first `ack` of an install returns the token and the client stores it; every later call for that
+entity sends it. Without per-install tokens, leave it out.
+
+Errors throw `ManajeminApiError` with the platform's public message, the HTTP status and the request id.
+
+## One workspace per organisation (Nile)
+
+```ts
+import { guardTenantTables, withTenant } from "@manajemin-dev-cli/sdk";
+
+// `workspaces` maps the entity id from an event to the live Nile tenant id (see the reference app).
+const tenantId = await liveTenantOf(entityId);
+const tasks = await withTenant(pool, tenantId, (db) => db.query("select * from tasks where tenant_id = $1", [tenantId]));
+
+// Everything that is not a tenant table goes through a guarded handle, so a forgotten withTenant fails loudly.
+const shared = guardTenantTables(pool, ["tasks", "sessions"]);
+```
+
+Do **not** use the entity id as the Nile tenant id. Nile never frees a deleted tenant's id, so an organisation that uninstalls
+your app and installs it again could not get its workspace back. Give each install a fresh tenant id and keep the mapping in
+your own table; `examples/reference-app` shows it, including erasing and reinstalling.
+
+`withTenant` sets the tenant for one transaction only, so a pooled connection never carries one organisation's context into the
+next request. Run every tenant query through it. Nile returns every tenant's rows to a query that runs with no tenant at all, so
+`guardTenantTables` refuses a statement that names a tenant table outside `withTenant`.
+
+## Tests
+
+`npm test` in this folder (Node's built-in test runner).

package/client.d.ts

@@ -0,0 +1,248 @@
+/**
+ * The app -> platform calls of `openapi.yaml` (API version 2026-11-01). Every call carries the app key; a call that names
+ * an entity also carries that install's token when the app is on per-install tokens. Errors throw `ManajeminApiError`
+ * with the platform's public message, never a secret.
+ */
+export declare const DEFAULT_BASE_URL = "https://www.manajemin.com";
+/** Where install tokens live: one per entity, returned once by the install's first ack. Persist it with the workspace. */
+export interface InstallTokenStore {
+    get(entityId: string): Promise<string | null | undefined> | string | null | undefined;
+    set(entityId: string, token: string): Promise<void> | void;
+    delete(entityId: string): Promise<void> | void;
+}
+export interface ClientOptions {
+    /** `<key_prefix>.<secret>`, shown once in the developer portal. Keep it in a secret store, never in source control. */
+    appKey: string;
+    appId: string;
+    /** Defaults to https://www.manajemin.com (the apex redirects, and many clients drop custom headers on a redirect). */
+    baseUrl?: string;
+    installTokens?: InstallTokenStore;
+    fetch?: typeof fetch;
+    /** Per request, milliseconds. */
+    timeoutMs?: number;
+}
+export declare class ManajeminApiError extends Error {
+    readonly status: number;
+    readonly code: string | null;
+    readonly requestId: string | null;
+    constructor(status: number, message: string, code: string | null, requestId: string | null);
+}
+export interface Claims {
+    sub: string;
+    email: string;
+    name?: string;
+    tenant_id: string;
+    entity_id: string;
+    product: string;
+}
+export interface UsageEvent {
+    metric: string;
+    /** A delta, not a level. */
+    qty: number;
+    entity_id: string;
+    /** Makes a retried report a no-op. Derive it from your own event id. */
+    dedupe_key: string;
+}
+export interface Member {
+    member_id: string;
+    user_id: string | null;
+    name: string;
+    email: string;
+    role: string;
+}
+/** An event as delivered to a subscriber (the webhook body) or returned by `pullEvents`. */
+export interface AppEvent {
+    event_id: string;
+    /** `<publisher app id>.<noun>.<verb>.v<N>`. */
+    event: string;
+    /** The publishing app's id. */
+    source: string;
+    entity_id: string;
+    time: string;
+    trace_id: string;
+    /** Only the fields the publisher declared; scalar values. A thin fact: fetch the record with your own permission if you need more. */
+    data: Record<string, string | number | boolean | null>;
+}
+export interface StoredFile {
+    id: string;
+    name: string;
+    contentType: string;
+    sizeBytes: number;
+    createdAt: string;
+}
+export declare class ManajeminClient {
+    readonly appId: string;
+    private readonly appKey;
+    private readonly baseUrl;
+    private readonly tokens;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    constructor(options: ClientOptions);
+    /** Activates an install. Call it after the workspace for the entity exists. Stores the install token if one comes back. */
+    ack(entityId: string): Promise<{
+        installToken: string | null;
+    }>;
+    /** Call only after the workspace's data is deleted. The install token ends with it. */
+    uninstallAck(entityId: string): Promise<void>;
+    /** Call after the member's data is reassigned or deleted. `outboxId` is the event body's `outbox_id`. */
+    ackRemoval(input: {
+        entityId: string;
+        memberId: string;
+        outboxId: string;
+    }): Promise<{
+        completed: boolean;
+    }>;
+    /**
+     * Redeems the one-time SSO code from the landing URL. Pass the landing URL's `entity`: an app on per-install tokens
+     * must, and the token is checked before the code is spent.
+     */
+    exchange(code: string, options?: {
+        entityId?: string;
+    }): Promise<{
+        claims: Claims;
+        redirect: string | null;
+    }>;
+    /** The entity's current plan, limits and features: the repair path after a missed event. */
+    snapshot(entityId: string): Promise<Record<string, unknown>>;
+    /** Reports usage deltas. All events of one call must name the same entity (one install token per call). */
+    reportUsage(events: UsageEvent[]): Promise<{
+        accepted: number;
+        rejected: number;
+        errors: string[];
+    }>;
+    /**
+     * Creates a guest grant: someone outside the organisation who may read (or comment on) what this app shows for the entity. The app
+     * must support guest access. Returns whether it was created; false when a grant already exists for that entity and email.
+     */
+    createGuestGrant(input: {
+        entityId: string;
+        email: string;
+        scope?: "read_only" | "comment";
+    }): Promise<{
+        created: boolean;
+    }>;
+    /** Scope `members:read`. */
+    members(entityId: string): Promise<{
+        members: Member[];
+        truncated: boolean;
+    }>;
+    /** Scope `audit:write`. Stored as `app.activity_recorded` with your event name inside. */
+    audit(input: {
+        entityId: string;
+        event: string;
+        summary?: string;
+        targetType?: string;
+        targetId?: string;
+        memberId?: string;
+        details?: Record<string, string | number | boolean | null>;
+    }): Promise<void>;
+    /**
+     * Scope `telemetry:write`. Reports which of your features were used on a workspace (up to 100 per call). Counts only: a feature name
+     * and, if you like, the member who used it. The platform shows it as adoption under the module `app:<your app id>`.
+     */
+    telemetry(entityId: string, events: Array<{
+        feature: string;
+        memberId?: string;
+        occurredAt?: Date;
+    }>): Promise<{
+        recorded: number;
+    }>;
+    /**
+     * Scope `files:store`. Keeps a file (at most 20 MB) for a workspace in the platform's private storage, counted against the
+     * organisation's storage quota. The bytes go straight to storage on a short-lived link that never sees your app key; the platform
+     * then checks the size before it counts the file.
+     */
+    storeFile(input: {
+        entityId: string;
+        name: string;
+        contentType: string;
+        data: Uint8Array;
+    }): Promise<StoredFile>;
+    /** Scope `files:store`. The app's finished files on a workspace, newest first (up to 100). */
+    listFiles(entityId: string): Promise<StoredFile[]>;
+    /** Scope `files:store`. A fresh link, valid for five minutes, that downloads the file. */
+    fileDownloadUrl(entityId: string, fileId: string): Promise<{
+        file: StoredFile;
+        url: string;
+    }>;
+    /** Scope `files:store`. Removes the file and gives its size back to the quota. */
+    deleteFile(entityId: string, fileId: string): Promise<void>;
+    /** Scope `notify:send`. */
+    notify(input: {
+        entityId: string;
+        memberId: string;
+        subject: string;
+        message: string;
+        actionLabel?: string;
+        actionUrl?: string;
+    }): Promise<void>;
+    /** Scope `ai:invoke`. */
+    ai(input: {
+        entityId: string;
+        memberId: string;
+        messages: {
+            role: "user" | "assistant";
+            content: string;
+        }[];
+        feature?: string;
+        system?: string;
+        maxTokens?: number;
+    }): Promise<{
+        text: string;
+        feature: string;
+        usage: Record<string, unknown>;
+    }>;
+    /**
+     * After `subject.erasure_requested`: say you deleted the person's data on this entity. Call it only once the data is gone. Repeating
+     * it is harmless; `completed` is true on the call that finishes the request (every installed app has now confirmed).
+     */
+    ackSubjectErasure(input: {
+        requestId: string;
+        entityId: string;
+    }): Promise<{
+        completed: boolean;
+    }>;
+    /**
+     * After `app.export_requested`: say where your export of the entity's data is. The link must be https, on your own host, free of
+     * credentials, and stop working within 7 days; the platform shows it to the tenant admin and never holds the data itself.
+     */
+    exportReady(input: {
+        exportId: string;
+        entityId: string;
+        url: string;
+        expiresAt: Date;
+        bytes?: number;
+    }): Promise<void>;
+    /**
+     * Scope `events:publish`. Hands an event your manifest declares to the other apps on this workspace; you are never told who
+     * receives it. Delivery is at least once with a stable `event_id`, so pass an `idempotencyKey` derived from your own record
+     * (a retried publish then returns the first event). Pass `traceId` (32 hex) to continue a trace that began elsewhere.
+     */
+    publishEvent(input: {
+        entityId: string;
+        type: string;
+        data: AppEvent["data"];
+        idempotencyKey?: string;
+        occurredAt?: Date;
+    }, options?: {
+        traceId?: string;
+    }): Promise<{
+        eventId: string;
+        traceId: string;
+        duplicate: boolean;
+    }>;
+    /**
+     * The events your manifest subscribed to, for an entity, oldest first: the catch-up path for an app that was down or cannot
+     * keep up with pushes. Send the returned `next` as `after` next time. Events are kept 7 days.
+     */
+    pullEvents(entityId: string, options?: {
+        after?: number;
+        limit?: number;
+    }): Promise<{
+        events: AppEvent[];
+        next: number;
+    }>;
+    private call;
+}
+/** Only a same-site relative path; anything else is dropped, so a code cannot become an open redirect in your app. */
+export declare function safeRedirect(value: string | null | undefined): string | null;

package/client.js

@@ -0,0 +1,225 @@
+/**
+ * The app -> platform calls of `openapi.yaml` (API version 2026-11-01). Every call carries the app key; a call that names
+ * an entity also carries that install's token when the app is on per-install tokens. Errors throw `ManajeminApiError`
+ * with the platform's public message, never a secret.
+ */
+export const DEFAULT_BASE_URL = "https://www.manajemin.com";
+export class ManajeminApiError extends Error {
+    status;
+    code;
+    requestId;
+    constructor(status, message, code, requestId) {
+        super(message);
+        this.name = "ManajeminApiError";
+        this.status = status;
+        this.code = code;
+        this.requestId = requestId;
+    }
+}
+const toStoredFile = (f) => ({ id: f.id, name: f.name, contentType: f.content_type, sizeBytes: f.size_bytes, createdAt: f.created_at });
+export class ManajeminClient {
+    appId;
+    appKey;
+    baseUrl;
+    tokens;
+    fetchImpl;
+    timeoutMs;
+    constructor(options) {
+        if (!/^[^.\s]+\.[^.\s]+$/.test(options.appKey))
+            throw new Error("appKey must be <key_prefix>.<secret>");
+        this.appKey = options.appKey;
+        this.appId = options.appId;
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+        this.tokens = options.installTokens;
+        this.fetchImpl = options.fetch ?? fetch;
+        this.timeoutMs = options.timeoutMs ?? 10_000;
+    }
+    /** Activates an install. Call it after the workspace for the entity exists. Stores the install token if one comes back. */
+    async ack(entityId) {
+        const body = await this.call("POST", "/api/integration/ack", { entity_id: entityId }, entityId);
+        if (body.install_token)
+            await this.tokens?.set(entityId, body.install_token);
+        return { installToken: body.install_token ?? null };
+    }
+    /** Call only after the workspace's data is deleted. The install token ends with it. */
+    async uninstallAck(entityId) {
+        await this.call("POST", "/api/integration/uninstall-ack", { entity_id: entityId }, entityId);
+        await this.tokens?.delete(entityId);
+    }
+    /** Call after the member's data is reassigned or deleted. `outboxId` is the event body's `outbox_id`. */
+    async ackRemoval(input) {
+        const body = await this.call("POST", "/api/integration/ack-removal", { member_id: input.memberId, outbox_id: input.outboxId }, input.entityId);
+        return { completed: body.completed === true };
+    }
+    /**
+     * Redeems the one-time SSO code from the landing URL. Pass the landing URL's `entity`: an app on per-install tokens
+     * must, and the token is checked before the code is spent.
+     */
+    async exchange(code, options = {}) {
+        const body = await this.call("POST", "/api/integration/exchange", (options.entityId ? { code, entity_id: options.entityId } : { code }), options.entityId ?? null);
+        if (options.entityId && body.claims.entity_id !== options.entityId) {
+            throw new ManajeminApiError(401, "the code belongs to another entity", null, null);
+        }
+        return { claims: body.claims, redirect: safeRedirect(body.redirect) };
+    }
+    /** The entity's current plan, limits and features: the repair path after a missed event. */
+    async snapshot(entityId) {
+        const query = new URLSearchParams({ app_id: this.appId, entity_id: entityId });
+        return this.call("GET", `/api/integration/snapshot?${query}`, undefined, entityId);
+    }
+    /** Reports usage deltas. All events of one call must name the same entity (one install token per call). */
+    async reportUsage(events) {
+        const entities = new Set(events.map((e) => e.entity_id));
+        if (events.length === 0 || entities.size !== 1)
+            throw new Error("reportUsage needs 1 to 500 events for one entity");
+        const body = await this.call("POST", "/api/integration/usage", { events }, events[0].entity_id);
+        return { accepted: body.accepted ?? 0, rejected: body.rejected ?? 0, errors: body.errors ?? [] };
+    }
+    /**
+     * Creates a guest grant: someone outside the organisation who may read (or comment on) what this app shows for the entity. The app
+     * must support guest access. Returns whether it was created; false when a grant already exists for that entity and email.
+     */
+    async createGuestGrant(input) {
+        try {
+            await this.call("POST", "/api/integration/guest-grants", { entityId: input.entityId, email: input.email, scope: input.scope }, input.entityId);
+            return { created: true };
+        }
+        catch (err) {
+            if (err instanceof ManajeminApiError && err.status === 409)
+                return { created: false };
+            throw err;
+        }
+    }
+    /** Scope `members:read`. */
+    async members(entityId) {
+        return this.call("GET", `/api/integration/members?${new URLSearchParams({ entity_id: entityId })}`, undefined, entityId);
+    }
+    /** Scope `audit:write`. Stored as `app.activity_recorded` with your event name inside. */
+    async audit(input) {
+        await this.call("POST", "/api/integration/audit", {
+            entity_id: input.entityId,
+            event: input.event,
+            summary: input.summary,
+            target_type: input.targetType,
+            target_id: input.targetId,
+            member_id: input.memberId,
+            details: input.details,
+        }, input.entityId);
+    }
+    /**
+     * Scope `telemetry:write`. Reports which of your features were used on a workspace (up to 100 per call). Counts only: a feature name
+     * and, if you like, the member who used it. The platform shows it as adoption under the module `app:<your app id>`.
+     */
+    async telemetry(entityId, events) {
+        return this.call("POST", "/api/integration/telemetry", { entity_id: entityId, events: events.map((e) => ({ feature: e.feature, member_id: e.memberId, occurred_at: e.occurredAt?.toISOString() })) }, entityId);
+    }
+    /**
+     * Scope `files:store`. Keeps a file (at most 20 MB) for a workspace in the platform's private storage, counted against the
+     * organisation's storage quota. The bytes go straight to storage on a short-lived link that never sees your app key; the platform
+     * then checks the size before it counts the file.
+     */
+    async storeFile(input) {
+        const started = await this.call("POST", "/api/integration/files", { entity_id: input.entityId, name: input.name, content_type: input.contentType, size_bytes: input.data.byteLength }, input.entityId);
+        // Not through `call`: this goes to the storage host, which must never receive the app key or an install token.
+        const put = await this.fetchImpl(started.upload_url, { method: "PUT", headers: started.upload_headers, body: input.data, redirect: "error", signal: AbortSignal.timeout(this.timeoutMs * 6) });
+        if (!put.ok)
+            throw new ManajeminApiError(put.status, "the storage host refused the upload", null, null);
+        const done = await this.call("POST", `/api/integration/files/${started.file_id}/complete`, { entity_id: input.entityId }, input.entityId);
+        return toStoredFile(done.file);
+    }
+    /** Scope `files:store`. The app's finished files on a workspace, newest first (up to 100). */
+    async listFiles(entityId) {
+        const query = new URLSearchParams({ entity_id: entityId });
+        const body = await this.call("GET", `/api/integration/files?${query}`, undefined, entityId);
+        return body.files.map(toStoredFile);
+    }
+    /** Scope `files:store`. A fresh link, valid for five minutes, that downloads the file. */
+    async fileDownloadUrl(entityId, fileId) {
+        const body = await this.call("GET", `/api/integration/files/${encodeURIComponent(fileId)}?${new URLSearchParams({ entity_id: entityId })}`, undefined, entityId);
+        return { file: toStoredFile(body.file), url: body.download_url };
+    }
+    /** Scope `files:store`. Removes the file and gives its size back to the quota. */
+    async deleteFile(entityId, fileId) {
+        await this.call("DELETE", `/api/integration/files/${encodeURIComponent(fileId)}?${new URLSearchParams({ entity_id: entityId })}`, undefined, entityId);
+    }
+    /** Scope `notify:send`. */
+    async notify(input) {
+        await this.call("POST", "/api/integration/notify", { entity_id: input.entityId, member_id: input.memberId, subject: input.subject, message: input.message, action_label: input.actionLabel, action_url: input.actionUrl }, input.entityId);
+    }
+    /** Scope `ai:invoke`. */
+    async ai(input) {
+        return this.call("POST", "/api/integration/ai", { entity_id: input.entityId, member_id: input.memberId, messages: input.messages, feature: input.feature, system: input.system, max_tokens: input.maxTokens }, input.entityId);
+    }
+    /**
+     * After `subject.erasure_requested`: say you deleted the person's data on this entity. Call it only once the data is gone. Repeating
+     * it is harmless; `completed` is true on the call that finishes the request (every installed app has now confirmed).
+     */
+    async ackSubjectErasure(input) {
+        const body = await this.call("POST", "/api/integration/subject-erasure-ack", { request_id: input.requestId, entity_id: input.entityId }, input.entityId);
+        return { completed: body.completed === true };
+    }
+    /**
+     * After `app.export_requested`: say where your export of the entity's data is. The link must be https, on your own host, free of
+     * credentials, and stop working within 7 days; the platform shows it to the tenant admin and never holds the data itself.
+     */
+    async exportReady(input) {
+        await this.call("POST", "/api/integration/export-ready", { export_id: input.exportId, entity_id: input.entityId, url: input.url, expires_at: input.expiresAt.toISOString(), bytes: input.bytes }, input.entityId);
+    }
+    /**
+     * Scope `events:publish`. Hands an event your manifest declares to the other apps on this workspace; you are never told who
+     * receives it. Delivery is at least once with a stable `event_id`, so pass an `idempotencyKey` derived from your own record
+     * (a retried publish then returns the first event). Pass `traceId` (32 hex) to continue a trace that began elsewhere.
+     */
+    async publishEvent(input, options = {}) {
+        const body = await this.call("POST", "/api/integration/events", { entity_id: input.entityId, type: input.type, data: input.data, idempotency_key: input.idempotencyKey, occurred_at: input.occurredAt?.toISOString() }, input.entityId, options.traceId ? { traceparent: `00-${options.traceId}-${randomSpanId()}-01` } : undefined);
+        return { eventId: body.event_id, traceId: body.trace_id, duplicate: body.duplicate };
+    }
+    /**
+     * The events your manifest subscribed to, for an entity, oldest first: the catch-up path for an app that was down or cannot
+     * keep up with pushes. Send the returned `next` as `after` next time. Events are kept 7 days.
+     */
+    async pullEvents(entityId, options = {}) {
+        const query = new URLSearchParams({ entity_id: entityId, after: String(options.after ?? 0), limit: String(options.limit ?? 50) });
+        return this.call("GET", `/api/integration/events?${query}`, undefined, entityId);
+    }
+    async call(method, path, body, entityId, extraHeaders) {
+        const headers = { "x-manajemin-key": this.appKey, accept: "application/json", ...extraHeaders };
+        if (body !== undefined)
+            headers["content-type"] = "application/json";
+        if (entityId && this.tokens) {
+            const token = await this.tokens.get(entityId);
+            if (token)
+                headers["x-manajemin-install-token"] = token;
+        }
+        const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+            method,
+            headers,
+            body: body === undefined ? undefined : JSON.stringify(body),
+            // A redirect would carry the key to wherever it points.
+            redirect: "error",
+            signal: AbortSignal.timeout(this.timeoutMs),
+        });
+        const text = await response.text();
+        let parsed = null;
+        try {
+            parsed = text ? JSON.parse(text) : null;
+        }
+        catch {
+            parsed = null;
+        }
+        if (!response.ok) {
+            const error = (parsed ?? {});
+            throw new ManajeminApiError(response.status, error.error ?? `HTTP ${response.status}`, error.code ?? null, error.requestId ?? null);
+        }
+        return (parsed ?? {});
+    }
+}
+/** Only a same-site relative path; anything else is dropped, so a code cannot become an open redirect in your app. */
+export function safeRedirect(value) {
+    return value && /^\/(?![/\\])/.test(value) ? value : null;
+}
+function randomSpanId() {
+    const bytes = new Uint8Array(8);
+    crypto.getRandomValues(bytes);
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}

package/delivery.d.ts

@@ -0,0 +1,96 @@
+import { type HeaderSource, type VerifyFailure, type VerifyInput } from "./signature.ts";
+/** The body shapes of `contract.json`, API version 2026-11-01. Unknown fields are kept: new ones arrive within a version. */
+export interface MemberPayload {
+    member_id: string | null;
+    user_id: string | null;
+    email: string | null;
+    role?: string | null;
+    transfer_to_member_id?: string | null;
+}
+export interface EventBody {
+    api_version: string;
+    event: string;
+    /** The platform's id for the event; `ack-removal` needs it. */
+    outbox_id?: string;
+    tenant_id: string | null;
+    entity_id?: string;
+    /** For member and guest events: who the event is about (contract.json lists the fields per event). */
+    payload?: Record<string, unknown>;
+    /** The entity's current plan, limits and features, on entity events. */
+    snapshot?: Record<string, unknown>;
+    [field: string]: unknown;
+}
+/** The body of an event another app published (plan section 18): `event` is its type, `source` the publishing app. */
+export interface AppEventBody extends EventBody {
+    event_id: string;
+    source: string;
+    time: string;
+    trace_id: string;
+    /** Only the fields the publisher declared, scalar values. */
+    data: Record<string, string | number | boolean | null>;
+}
+/** `subject.erasure_requested` (plan T6): delete this person's data on `entity_id`, then `ackSubjectErasure`. */
+export interface SubjectErasureBody extends EventBody {
+    payload: {
+        request_id: string;
+        email: string | null;
+        user_id: string | null;
+        member_id: string | null;
+        reason: string;
+    };
+}
+/** `app.export_requested` (plan T6): build your export of `entity_id`'s data, then `exportReady`. */
+export interface ExportRequestBody extends EventBody {
+    payload: {
+        export_id: string;
+        reason: "tenant_request" | "tenant_exit";
+    };
+}
+export interface ToolCallBody {
+    api_version: string;
+    tool: string;
+    call_id: string;
+    arguments: Record<string, unknown>;
+    confirmed?: true;
+    context: {
+        tenant_id: string;
+        entity_id: string;
+        member: {
+            id: string;
+            user_id: string | null;
+            name: string;
+            email: string;
+            role: string;
+        };
+        initiated_by: "jemi";
+    };
+}
+export interface Delivery<B = EventBody> {
+    /** X-Manajemin-Delivery: the idempotency key. The same delivery can arrive more than once. */
+    id: string;
+    event: string;
+    tenantId: string | null;
+    entityId: string | null;
+    apiVersion: string | null;
+    /** The W3C trace id from `traceparent` when the delivery belongs to a traced flow (an app event): log it with everything you do for it. */
+    traceId: string | null;
+    body: B;
+}
+export type ReceiveResult<B> = {
+    ok: true;
+    delivery: Delivery<B>;
+}
+/** `status` is what to answer: 401 for a signature failure, 400 for a body that is not the contract's. */
+ | {
+    ok: false;
+    status: 400 | 401;
+    reason: VerifyFailure | "malformed";
+};
+/**
+ * Verifies, then parses. Never reads the body before the signature is checked. Answer 2xx only after the event is
+ * stored, and deduplicate on `delivery.id`.
+ */
+export declare function receive<B = EventBody>(input: VerifyInput): ReceiveResult<B>;
+/** The member a member event is about, or null when the delivery carries none. */
+export declare function memberOf(body: EventBody): MemberPayload | null;
+export type { HeaderSource };

package/delivery.js

@@ -0,0 +1,41 @@
+import { header, verifySignature } from "./signature.js";
+/**
+ * Verifies, then parses. Never reads the body before the signature is checked. Answer 2xx only after the event is
+ * stored, and deduplicate on `delivery.id`.
+ */
+export function receive(input) {
+    const verified = verifySignature(input);
+    if (!verified.ok)
+        return { ok: false, status: 401, reason: verified.reason };
+    const text = typeof input.rawBody === "string" ? input.rawBody : new TextDecoder().decode(input.rawBody);
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        return { ok: false, status: 400, reason: "malformed" };
+    }
+    const id = header(input.headers, "x-manajemin-delivery");
+    const event = header(input.headers, "x-manajemin-event");
+    if (!id || !event || typeof body !== "object" || body === null)
+        return { ok: false, status: 400, reason: "malformed" };
+    return {
+        ok: true,
+        delivery: {
+            id,
+            event,
+            tenantId: header(input.headers, "x-manajemin-tenant") ?? null,
+            entityId: header(input.headers, "x-manajemin-entity") ?? null,
+            apiVersion: header(input.headers, "x-manajemin-api-version") ?? null,
+            traceId: /^00-([0-9a-f]{32})-[0-9a-f]{16}-[0-9a-f]{2}$/.exec(header(input.headers, "traceparent") ?? "")?.[1] ?? null,
+            body: body,
+        },
+    };
+}
+/** The member a member event is about, or null when the delivery carries none. */
+export function memberOf(body) {
+    const payload = body.payload;
+    if (!payload || typeof payload !== "object" || !("member_id" in payload || "user_id" in payload))
+        return null;
+    return payload;
+}

package/generated/api.d.ts

@@ -0,0 +1,123 @@
+export declare const API_VERSION = "2026-11-01";
+/** Every operation the document describes, as `METHOD /path`. */
+export declare const OPERATIONS: readonly ["POST /api/integration/ack", "POST /api/integration/uninstall-ack", "POST /api/integration/exchange", "POST /api/integration/usage", "POST /api/integration/ack-removal", "GET /api/integration/snapshot", "POST /api/integration/guest-grants", "GET /api/integration/members", "POST /api/integration/audit", "POST /api/integration/telemetry", "GET /api/integration/files", "POST /api/integration/files", "POST /api/integration/files/{fileId}/complete", "GET /api/integration/files/{fileId}", "DELETE /api/integration/files/{fileId}", "POST /api/integration/notify", "POST /api/integration/subject-erasure-ack", "POST /api/integration/export-ready", "GET /api/integration/events", "POST /api/integration/events", "POST /api/integration/ai"];
+export type Operation = (typeof OPERATIONS)[number];
+/** The JSON body an operation takes, where it takes one. */
+export interface ApiBodies {
+    "POST /api/integration/ack": {
+        entity_id: string;
+    };
+    "POST /api/integration/uninstall-ack": {
+        entity_id: string;
+    };
+    "POST /api/integration/exchange": {
+        code: string;
+        entity_id?: string;
+    };
+    "POST /api/integration/usage": {
+        events: Array<{
+            metric: string;
+            qty: number;
+            entity_id: string;
+            dedupe_key: string;
+        }>;
+    };
+    "POST /api/integration/ack-removal": {
+        member_id: string;
+        outbox_id: string;
+    };
+    "POST /api/integration/guest-grants": {
+        entityId: string;
+        email: string;
+        scope?: "read_only" | "comment";
+    };
+    "POST /api/integration/audit": {
+        entity_id: string;
+        event: string;
+        summary?: string;
+        target_type?: string;
+        target_id?: string;
+        member_id?: string;
+        details?: Record<string, unknown>;
+    };
+    "POST /api/integration/telemetry": {
+        entity_id: string;
+        events: Array<{
+            feature: string;
+            member_id?: string;
+            occurred_at?: string;
+        }>;
+    };
+    "POST /api/integration/files": {
+        entity_id: string;
+        name: string;
+        content_type: string;
+        size_bytes: number;
+    };
+    "POST /api/integration/files/{fileId}/complete": {
+        entity_id: string;
+    };
+    "POST /api/integration/notify": {
+        entity_id: string;
+        member_id: string;
+        subject: string;
+        message: string;
+        action_label?: string;
+        action_url?: string;
+    };
+    "POST /api/integration/subject-erasure-ack": {
+        request_id: string;
+        entity_id: string;
+    };
+    "POST /api/integration/export-ready": {
+        export_id: string;
+        entity_id: string;
+        url: string;
+        expires_at: string;
+        bytes?: number;
+    };
+    "POST /api/integration/events": {
+        entity_id: string;
+        type: string;
+        data: Record<string, unknown>;
+        idempotency_key?: string;
+        occurred_at?: string;
+    };
+    "POST /api/integration/ai": {
+        entity_id: string;
+        member_id: string;
+        feature?: string;
+        system?: string;
+        messages: Array<{
+            role: "user" | "assistant";
+            content: string;
+        }>;
+        max_tokens?: number;
+    };
+}
+/** The query parameters an operation takes, where it takes any. */
+export interface ApiQueries {
+    "GET /api/integration/snapshot": {
+        app_id: string;
+        entity_id: string;
+    };
+    "GET /api/integration/members": {
+        entity_id: string;
+    };
+    "GET /api/integration/files": {
+        entity_id: string;
+    };
+    "GET /api/integration/files/{fileId}": {
+        entity_id: string;
+    };
+    "DELETE /api/integration/files/{fileId}": {
+        entity_id: string;
+    };
+    "GET /api/integration/events": {
+        entity_id: string;
+        after?: number;
+        limit?: number;
+    };
+}
+export type ApiBody<K extends keyof ApiBodies> = ApiBodies[K];
+export type ApiQuery<K extends keyof ApiQueries> = ApiQueries[K];

package/generated/api.js

@@ -0,0 +1,26 @@
+// Generated by scripts/gen-sdk-api.mjs from doc/integration/openapi.yaml. Do not edit by hand: change the document and run `npm run sdk:generate`.
+export const API_VERSION = "2026-11-01";
+/** Every operation the document describes, as `METHOD /path`. */
+export const OPERATIONS = [
+    "POST /api/integration/ack",
+    "POST /api/integration/uninstall-ack",
+    "POST /api/integration/exchange",
+    "POST /api/integration/usage",
+    "POST /api/integration/ack-removal",
+    "GET /api/integration/snapshot",
+    "POST /api/integration/guest-grants",
+    "GET /api/integration/members",
+    "POST /api/integration/audit",
+    "POST /api/integration/telemetry",
+    "GET /api/integration/files",
+    "POST /api/integration/files",
+    "POST /api/integration/files/{fileId}/complete",
+    "GET /api/integration/files/{fileId}",
+    "DELETE /api/integration/files/{fileId}",
+    "POST /api/integration/notify",
+    "POST /api/integration/subject-erasure-ack",
+    "POST /api/integration/export-ready",
+    "GET /api/integration/events",
+    "POST /api/integration/events",
+    "POST /api/integration/ai"
+];

package/index.d.ts

@@ -0,0 +1,8 @@
+export { DEFAULT_TOLERANCE_SECONDS, SIGNATURE_HEADER, TIMESTAMP_HEADER, sign, verifySignature } from "./signature.ts";
+export type { HeaderSource, VerifyFailure, VerifyInput, VerifyResult } from "./signature.ts";
+export { memberOf, receive } from "./delivery.ts";
+export type { AppEventBody, Delivery, EventBody, ExportRequestBody, MemberPayload, ReceiveResult, SubjectErasureBody, ToolCallBody } from "./delivery.ts";
+export { DEFAULT_BASE_URL, ManajeminApiError, ManajeminClient, safeRedirect } from "./client.ts";
+export type { AppEvent, Claims, ClientOptions, InstallTokenStore, Member, StoredFile, UsageEvent } from "./client.ts";
+export { guardTenantTables, TenantContextError, withTenant } from "./tenant.ts";
+export type { TenantPool, TenantPoolClient, TenantQueryable } from "./tenant.ts";

package/index.js

@@ -0,0 +1,4 @@
+export { DEFAULT_TOLERANCE_SECONDS, SIGNATURE_HEADER, TIMESTAMP_HEADER, sign, verifySignature } from "./signature.js";
+export { memberOf, receive } from "./delivery.js";
+export { DEFAULT_BASE_URL, ManajeminApiError, ManajeminClient, safeRedirect } from "./client.js";
+export { guardTenantTables, TenantContextError, withTenant } from "./tenant.js";

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "@manajemin-dev-cli/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Connect an app to the Manajemin platform: verify deliveries, redeem SSO codes, acknowledge installs, report usage.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "manajemin",
+    "sdk",
+    "webhook",
+    "sso"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/signature.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Webhook and tool-call verification, the part developers most often get wrong. The rules are the published contract
+ * (`contract.json`, `signature-vectors.json`), not this file: the tests run every published vector.
+ *
+ * X-Manajemin-Signature: t=<unix seconds>,v1=<hex>[,v1=<hex>]  (one v1 per secret during a webhook secret rotation)
+ * X-Manajemin-Timestamp: the same <unix seconds>
+ * hex = HMAC-SHA256(webhook secret, "<t>.<raw body>")
+ */
+export declare const SIGNATURE_HEADER = "x-manajemin-signature";
+export declare const TIMESTAMP_HEADER = "x-manajemin-timestamp";
+export declare const DEFAULT_TOLERANCE_SECONDS = 300;
+export type HeaderSource = Headers | Record<string, string | string[] | undefined>;
+export type VerifyFailure = "missing" | "stale" | "mismatched";
+export type VerifyResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: VerifyFailure;
+};
+export interface VerifyInput {
+    /** The webhook secret, or several while you deploy a new one: the delivery is valid if any of them matches. */
+    secret: string | readonly string[];
+    headers: HeaderSource;
+    /** The body exactly as received. Never a re-serialised object: one changed byte breaks the signature. */
+    rawBody: string | Uint8Array;
+    /** Unix seconds; defaults to the clock. */
+    now?: number;
+    toleranceSeconds?: number;
+}
+export declare function header(headers: HeaderSource, name: string): string | undefined;
+export declare function sign(secret: string, timestamp: number | string, rawBody: string | Uint8Array): string;
+/** Order: missing or malformed headers, then age, then the MAC in constant time. */
+export declare function verifySignature(input: VerifyInput): VerifyResult;

package/signature.js

@@ -0,0 +1,55 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+/**
+ * Webhook and tool-call verification, the part developers most often get wrong. The rules are the published contract
+ * (`contract.json`, `signature-vectors.json`), not this file: the tests run every published vector.
+ *
+ * X-Manajemin-Signature: t=<unix seconds>,v1=<hex>[,v1=<hex>]  (one v1 per secret during a webhook secret rotation)
+ * X-Manajemin-Timestamp: the same <unix seconds>
+ * hex = HMAC-SHA256(webhook secret, "<t>.<raw body>")
+ */
+export const SIGNATURE_HEADER = "x-manajemin-signature";
+export const TIMESTAMP_HEADER = "x-manajemin-timestamp";
+export const DEFAULT_TOLERANCE_SECONDS = 300;
+/** More than this many v1 entries is not something the platform sends; refusing bounds the work per request. */
+const MAX_SIGNATURES = 8;
+export function header(headers, name) {
+    if (typeof headers.get === "function")
+        return headers.get(name) ?? undefined;
+    const record = headers;
+    const key = Object.keys(record).find((k) => k.toLowerCase() === name);
+    const value = key === undefined ? undefined : record[key];
+    return Array.isArray(value) ? value[0] : value;
+}
+export function sign(secret, timestamp, rawBody) {
+    return createHmac("sha256", secret).update(`${timestamp}.`).update(rawBody).digest("hex");
+}
+/** Order: missing or malformed headers, then age, then the MAC in constant time. */
+export function verifySignature(input) {
+    const timestamp = header(input.headers, TIMESTAMP_HEADER);
+    const signature = header(input.headers, SIGNATURE_HEADER);
+    if (!timestamp || !/^\d+$/.test(timestamp) || !signature)
+        return { ok: false, reason: "missing" };
+    const match = /^t=(\d+)((?:,v1=[0-9a-f]{64})+)$/.exec(signature.trim());
+    if (!match)
+        return { ok: false, reason: "missing" };
+    const candidates = match[2].slice(1).split(",").map((entry) => entry.slice(3));
+    if (candidates.length > MAX_SIGNATURES)
+        return { ok: false, reason: "missing" };
+    const now = input.now ?? Math.floor(Date.now() / 1000);
+    if (Math.abs(now - Number(timestamp)) > (input.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS)) {
+        return { ok: false, reason: "stale" };
+    }
+    // The age was read from the timestamp header and the MAC covers the signature's own t: they must agree, or an old
+    // captured signature could be replayed behind a fresh timestamp header.
+    if (match[1] !== timestamp)
+        return { ok: false, reason: "mismatched" };
+    const secrets = typeof input.secret === "string" ? [input.secret] : input.secret;
+    for (const secret of secrets) {
+        const expected = Buffer.from(sign(secret, timestamp, input.rawBody), "hex");
+        for (const candidate of candidates) {
+            if (timingSafeEqual(expected, Buffer.from(candidate, "hex")))
+                return { ok: true };
+        }
+    }
+    return { ok: false, reason: "mismatched" };
+}

package/tenant.d.ts

@@ -0,0 +1,44 @@
+/**
+ * One live Nile tenant per Manajemin entity (plan D5, as amended 2026-10-25). Nile never frees a deleted tenant's id, so an
+ * app must NOT use the entity id as the tenant id: it keeps its own entity-to-tenant table and gives each install a fresh
+ * tenant id (the reference app's `workspaces` table shows how). `withTenant` runs a unit of work inside one tenant's context
+ * and nowhere else, so the short path is the safe path (plan §15.3: "no query runs outside withTenant").
+ *
+ * The context is set with `SET LOCAL nile.tenant_id`, local to one transaction, so a pooled connection never carries
+ * one entity's context into the next request. Checked against real Nile on 2026-10-22: it accepts `SET LOCAL` right
+ * after BEGIN and refuses `select set_config('nile.tenant_id', ..., true)` there ("changing nile.tenant_id within a
+ * transaction is only allowed before any queries"). A plain session `SET` also works but outlives the request on a
+ * pooled connection, so it is never used here. Any pg-compatible pool works (node-postgres `Pool`); the SDK itself has
+ * no database dependency.
+ *
+ * What this does NOT give: Nile still returns every tenant's rows to a query that runs with no context at all (writes
+ * without one are refused). The protection is therefore in the app, in three layers: no tenant-table query runs outside
+ * `withTenant`; the pool the rest of the code gets is wrapped by `guardTenantTables`, which refuses a statement that names
+ * a tenant table; and a test in the app fails if its source reaches for the raw pool (the reference app has all three).
+ */
+export interface TenantQueryable {
+    query<R = Record<string, unknown>>(text: string, values?: unknown[]): Promise<{
+        rows: R[];
+    }>;
+}
+export interface TenantPoolClient extends TenantQueryable {
+    /** node-postgres: passing an error destroys the connection instead of returning it to the pool. */
+    release(err?: Error | boolean): void;
+}
+export interface TenantPool {
+    connect(): Promise<TenantPoolClient>;
+}
+export declare function withTenant<T>(pool: TenantPool, tenantId: string, work: (db: TenantQueryable) => Promise<T>): Promise<T>;
+/** Thrown by `guardTenantTables` for a statement that names a tenant table outside `withTenant`. */
+export declare class TenantContextError extends Error {
+    readonly table: string;
+    constructor(table: string);
+}
+/**
+ * Wraps the plain pool the rest of the app queries through, for the tables that are NOT tenant tables. A statement that names
+ * one of `tenantTables` is refused before it is sent, so a forgotten `withTenant` fails loudly in development and in tests
+ * instead of quietly reading every tenant's rows on Nile (backlog -114). It is a guard against the realistic mistake, not a
+ * proof: dynamic SQL built elsewhere, a view or a function can still reach a tenant table, which is why the app's own test
+ * also scans its source.
+ */
+export declare function guardTenantTables(db: TenantQueryable, tenantTables: readonly string[]): TenantQueryable;

package/tenant.js

@@ -0,0 +1,75 @@
+/**
+ * One live Nile tenant per Manajemin entity (plan D5, as amended 2026-10-25). Nile never frees a deleted tenant's id, so an
+ * app must NOT use the entity id as the tenant id: it keeps its own entity-to-tenant table and gives each install a fresh
+ * tenant id (the reference app's `workspaces` table shows how). `withTenant` runs a unit of work inside one tenant's context
+ * and nowhere else, so the short path is the safe path (plan §15.3: "no query runs outside withTenant").
+ *
+ * The context is set with `SET LOCAL nile.tenant_id`, local to one transaction, so a pooled connection never carries
+ * one entity's context into the next request. Checked against real Nile on 2026-10-22: it accepts `SET LOCAL` right
+ * after BEGIN and refuses `select set_config('nile.tenant_id', ..., true)` there ("changing nile.tenant_id within a
+ * transaction is only allowed before any queries"). A plain session `SET` also works but outlives the request on a
+ * pooled connection, so it is never used here. Any pg-compatible pool works (node-postgres `Pool`); the SDK itself has
+ * no database dependency.
+ *
+ * What this does NOT give: Nile still returns every tenant's rows to a query that runs with no context at all (writes
+ * without one are refused). The protection is therefore in the app, in three layers: no tenant-table query runs outside
+ * `withTenant`; the pool the rest of the code gets is wrapped by `guardTenantTables`, which refuses a statement that names
+ * a tenant table; and a test in the app fails if its source reaches for the raw pool (the reference app has all three).
+ */
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export async function withTenant(pool, tenantId, work) {
+    // Validated before any connection: a malformed id must not become "no tenant context" by accident.
+    if (!UUID.test(tenantId))
+        throw new Error("withTenant needs the tenant id (a UUID) of the workspace");
+    const client = await pool.connect();
+    try {
+        // `SET` takes no bind parameters, so the id is part of the SQL text: the UUID check above is what makes that safe.
+        // BEGIN and the context go in one message (one network round trip fewer; about 200 ms from Jakarta to Frankfurt).
+        await client.query(`BEGIN; SET LOCAL nile.tenant_id = '${tenantId}'`);
+        const result = await work(client);
+        await client.query("COMMIT");
+        client.release();
+        return result;
+    }
+    catch (err) {
+        await client.query("ROLLBACK").catch(() => undefined);
+        client.release(err instanceof Error ? err : true);
+        throw err;
+    }
+}
+/** Thrown by `guardTenantTables` for a statement that names a tenant table outside `withTenant`. */
+export class TenantContextError extends Error {
+    table;
+    constructor(table) {
+        super(`this statement names the tenant table "${table}" outside withTenant(); run it inside withTenant(tenantId, ...)`);
+        this.name = "TenantContextError";
+        this.table = table;
+    }
+}
+/**
+ * Removes string literals and comments in ONE left-to-right pass, so each is recognised where it starts: a `--` inside a string is part
+ * of the string and a quote inside a comment is part of the comment. Two ordered replacements cannot do this (`select '--' from tasks`
+ * would lose the table name to the comment rule), which would let the very statement the guard exists to refuse through.
+ */
+function stripLiteralsAndComments(sql) {
+    return sql.replace(/'(?:[^']|'')*'|--[^\n]*|\/\*[\s\S]*?\*\//g, (match) => (match.startsWith("'") ? "''" : " "));
+}
+/**
+ * Wraps the plain pool the rest of the app queries through, for the tables that are NOT tenant tables. A statement that names
+ * one of `tenantTables` is refused before it is sent, so a forgotten `withTenant` fails loudly in development and in tests
+ * instead of quietly reading every tenant's rows on Nile (backlog -114). It is a guard against the realistic mistake, not a
+ * proof: dynamic SQL built elsewhere, a view or a function can still reach a tenant table, which is why the app's own test
+ * also scans its source.
+ */
+export function guardTenantTables(db, tenantTables) {
+    const patterns = tenantTables.map((table) => ({ table, re: new RegExp(`(?<![A-Za-z0-9_])"?${table.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}"?(?![A-Za-z0-9_])`, "i") }));
+    return {
+        async query(text, values) {
+            const sql = stripLiteralsAndComments(text);
+            for (const { table, re } of patterns)
+                if (re.test(sql))
+                    throw new TenantContextError(table);
+            return db.query(text, values);
+        },
+    };
+}