@sovecom/module-sdk 1.0.0-rc.1

package/README.md

@@ -0,0 +1,63 @@
+# @sovecom/module-sdk
+
+The public, author-facing SDK for building [SovEcom](../../README.md) modules.
+
+> **Status:** stub. This package is `private` and consumed in-repo via the pnpm workspace; it is
+> not yet published to npm. This README is a placeholder — the full author guide is forthcoming.
+
+## What it is
+
+This package is the **single source of truth** for the SovEcom module contract: the capability
+interfaces the core broker enforces, the data-transfer types it returns, the manifest validators, and
+the author ergonomics. The core runtime (`apps/api`) imports these same definitions, so the published
+contract can never drift from what the broker actually enforces.
+
+It is a **contract package, not a code-execution surface**. All permission / tenant / refusal
+enforcement lives in the core-side broker; nothing here can disable or weaken it.
+
+## Authoring a module
+
+```ts
+import { defineModule, defineSlots, createNamespacedTable } from '@sovecom/module-sdk';
+
+export default defineModule({
+  async activate(sdk) {
+    // `sdk` is the capability object: store, admin, tables, events, http, serve.
+    const products = await sdk.store.products.list({ limit: 20 });
+
+    await sdk.events.on('order.paid', async (payload) => {
+      // react to a core event
+    });
+
+    sdk.serve((req) => ({ status: 200, body: JSON.stringify({ ok: true }) }));
+  },
+});
+
+// Declarative slot metadata for the manifest (NOT a runtime call):
+export const slots = defineSlots([{ slot: 'product-page', component: 'my-widget' }]);
+
+// DDL/migration helper — enforces the `mod_<name>_` table prefix:
+const itemsTable = createNamespacedTable('my-module', 'items'); // → 'mod_my-module_items'
+```
+
+## Exports
+
+- `defineModule(config)` — wraps your `activate(sdk)` body into the `{ activate }` object the
+  worker loader expects.
+- `defineSlots(entries)` — typed, validated builder for the manifest's declarative `slots` array.
+- `createNamespacedTable(name, suffix)` — DDL identifier helper enforcing the `mod_<name>_` prefix
+  (it returns a table NAME; it is not a live query builder).
+- Capability types: `ModuleSdk`, `StoreClient`, `AdminClient`, `HttpClient`, `TablesClient`,
+  `EventsClient`.
+- DTOs: `ModuleProductDto`, `ModuleCategoryDto`, `ModuleOrderDto`, `ModuleCustomerDto`,
+  `ListQuery`, `ListResult`.
+- HTTP contract: `ModuleHttpRequest`, `ModuleHttpResponse`, `ModuleHttpHandler`,
+  `ModuleHttpSurface`.
+- Manifest types + validators: `ModuleManifest`, `ModuleSlotEntry`, `ModulePermission`,
+  `MODULE_PERMISSION_ALLOWLIST`, `moduleManifestSchema`, `parseAndVerifyManifest`,
+  `assertCoreCompatible`, `CORE_API_VERSION`.
+- `RpcErrorCode` — stable broker error codes for author error-handling.
+
+## License
+
+AGPL-3.0 (core). See the repository root.

package/dist/capabilities.d.ts

@@ -0,0 +1,125 @@
+/**
+ * the {@link ModuleSdk} capability contract, EXTRACTED here
+ * as the single source of truth (was `apps/api/src/modules/runtime/worker-sdk.ts`). These are
+ * PURE TYPES: no `RpcPeer`, no runtime, no DB/pg handle. The capability object is what core hands
+ * a module's `activate(sdk)`; each method maps 1:1 onto ONE gated broker RPC. ALL permission /
+ * tenant / refusal enforcement lives in the core-side broker — a module cannot weaken it.
+ *
+ * apps/api's in-tree `createModuleSdk(peer)` IMPLEMENTS this interface and a compile-time
+ * conformance check (`*.type-test.ts`) guards that the broker never drifts from this contract.
+ */
+import type { ListQuery, ListResult, ModuleProductDto, ModuleCategoryDto, ModuleOrderDto, ModuleCustomerDto } from './dto.js';
+import type { ModuleHttpHandler } from './http.js';
+import type { ModuleEmailMessage, ModuleCustomerEmailMessage, ModuleEmailSendResult } from './email.js';
+/** Storefront-facing read surface (catalog). Gated by `read:products` / `read:categories`. */
+export interface StoreClient {
+    products: {
+        list(query?: Partial<ListQuery>): Promise<ListResult<ModuleProductDto>>;
+        get(id: string): Promise<ModuleProductDto | null>;
+    };
+    categories: {
+        list(query?: Partial<ListQuery>): Promise<ListResult<ModuleCategoryDto>>;
+        get(id: string): Promise<ModuleCategoryDto | null>;
+    };
+}
+/** Admin-facing read surface. Gated by `read:orders` / `read:customers` (customer = field-limited). */
+export interface AdminClient {
+    orders: {
+        list(query?: Partial<ListQuery>): Promise<ListResult<ModuleOrderDto>>;
+        get(id: string): Promise<ModuleOrderDto | null>;
+    };
+    customers: {
+        list(query?: Partial<ListQuery>): Promise<ListResult<ModuleCustomerDto>>;
+        get(id: string): Promise<ModuleCustomerDto | null>;
+    };
+}
+/**
+ * Narrow commerce read surface (follow-up B1). Gated by the EXISTING `read:orders` permission
+ * (default-deny: FORBIDDEN without it). It deliberately returns ONLY a boolean verdict — never order
+ * rows — so a module can ASK "did this customer buy this product?" without being handed any order
+ * details (least-privilege). The query is tenant-scoped from the broker context (never module
+ * input) and runs against paid/fulfilled orders only.
+ */
+export interface CommerceClient {
+    /**
+     * @returns `true` iff the tenant has a paid (or later: fulfilled/shipped/…) order for
+     *          `customerId` that contains `productId`. Both ids are opaque, bound params. A bare
+     *          boolean — no order data crosses the boundary.
+     */
+    hasPurchased(customerId: string, productId: string): Promise<boolean>;
+}
+/** Outbound HTTP (gated by `http:outbound`; mediated + SSRF-guarded in core). */
+export interface HttpClient {
+    fetch(request: {
+        url: string;
+        method?: string;
+        headers?: Record<string, string>;
+        body?: string;
+    }): Promise<{
+        status: number;
+        headers: Record<string, string>;
+        body: string;
+    }>;
+}
+/** Module's OWN tables (gated by `write:own_tables`). Parameterized SQL against its own schema. */
+export interface TablesClient {
+    /** Run a SELECT (or any returning statement); resolves the rows. */
+    query<T = Record<string, unknown>>(sql: string, params?: ReadonlyArray<string | number | boolean | null>): Promise<{
+        rows: T[];
+        rowCount: number;
+    }>;
+    /** Run a mutation; resolves the affected/returned rows + count. */
+    exec(sql: string, params?: ReadonlyArray<string | number | boolean | null>): Promise<{
+        rows: Array<Record<string, unknown>>;
+        rowCount: number;
+    }>;
+}
+/**
+ * Outbound email (gated by `email:send`; 3.10-i). The module supplies its own subject + body and
+ * NEVER sees SMTP credentials or core's transactional templates. Core validates the recipient +
+ * subject (header-injection-safe), rate-limits per module, audits every send, and QUEUES the
+ * message through core's MailService scoped to the module's tenant. Resolves `{ queued: true }`
+ * on success; rejects with `RATE_LIMITED` over the cap or `FORBIDDEN` without the grant.
+ *
+ * `sendToCustomer` (follow-up B3) is the PRIVACY-PRESERVING variant: the module names a customer by
+ * its opaque `customerId` ONLY — it supplies no address and NEVER receives one. Core resolves the
+ * recipient from the (broker-context tenant, customerId) composite, honours marketing CONSENT
+ * (`accepts_marketing`) and RGPD erasure (`deleted_at`/`anonymized_at`), and either sends or
+ * SUPPRESSES. It resolves `{ queued: true }` when sent or `{ queued: false }` when suppressed — and
+ * the module CANNOT learn WHY a send was suppressed (no consent/existence oracle). It shares the
+ * EXISTING `email:send` grant + per-module rate limit (it is strictly more privacy-preserving than
+ * `send`, which already lets a module email any address it supplies).
+ */
+export interface EmailClient {
+    send(message: ModuleEmailMessage): Promise<ModuleEmailSendResult>;
+    sendToCustomer(message: ModuleCustomerEmailMessage): Promise<ModuleEmailSendResult>;
+}
+/** Domain events (gated by `subscribe:events` / `emit:events`). */
+export interface EventsClient {
+    /**
+     * Subscribe to an event and register a handler. Re-sends the full subscription set to core, so
+     * call all `on(...)` during `activate`. Events: curated core names (`order.paid`, `product.*`,
+     * …) or another module's `mod.<name>.*`.
+     */
+    on(event: string, handler: (payload: unknown) => void | Promise<void>): Promise<void>;
+    /** Emit a module event (delivered as `mod.<thisModule>.<event>` to other subscribed modules). */
+    emit(event: string, payload?: unknown): Promise<void>;
+}
+/** The capability object handed to a module's `activate(sdk)` — its ONLY channel to core. */
+export interface ModuleSdk {
+    readonly store: StoreClient;
+    readonly admin: AdminClient;
+    /** Narrow commerce reads (gated by `read:orders`; boolean-only — see {@link CommerceClient}). */
+    readonly commerce: CommerceClient;
+    readonly http: HttpClient;
+    readonly tables: TablesClient;
+    readonly events: EventsClient;
+    /** Outbound email via core's MailService (gated by `email:send`; 3.10-i). */
+    readonly email: EmailClient;
+    /**
+     * Register the module's HTTP handler. Core proxies requests on the module's mounted routes
+     * (`/{store,admin}/v1/modules/<name>/*`) to it. At most one handler; the last call wins.
+     */
+    serve(handler: ModuleHttpHandler): void;
+}
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"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"}

package/dist/capabilities.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=capabilities.js.map

package/dist/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":""}

package/dist/core-version.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The module-API contract version, EXTRACTED here (was
+ * `apps/api/src/modules/core-version.ts`) so the SDK's `assertCoreCompatible` and apps/api's
+ * runtime gate share ONE constant. apps/api now re-exports this from `@sovecom/module-sdk`.
+ *
+ * This is the version a module's `compatibleCore` range is checked against — the stable
+ * contract between core and modules. It is INTENTIONALLY decoupled from the API package's own
+ * `package.json` version (pre-1.0): module authors target a stable `^1.0.0` while the package
+ * version churns through 0.x. Bumping the MAJOR here means modules pinned to an older major
+ * refuse to load.
+ */
+export declare const CORE_API_VERSION = "1.0.0";
+//# sourceMappingURL=core-version.d.ts.map

package/dist/core-version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core-version.d.ts","sourceRoot":"","sources":["../src/core-version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,UAAU,CAAC"}

package/dist/core-version.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CORE_API_VERSION = void 0;
+/**
+ * The module-API contract version, EXTRACTED here (was
+ * `apps/api/src/modules/core-version.ts`) so the SDK's `assertCoreCompatible` and apps/api's
+ * runtime gate share ONE constant. apps/api now re-exports this from `@sovecom/module-sdk`.
+ *
+ * This is the version a module's `compatibleCore` range is checked against — the stable
+ * contract between core and modules. It is INTENTIONALLY decoupled from the API package's own
+ * `package.json` version (pre-1.0): module authors target a stable `^1.0.0` while the package
+ * version churns through 0.x. Bumping the MAJOR here means modules pinned to an older major
+ * refuse to load.
+ */
+exports.CORE_API_VERSION = '1.0.0';
+//# sourceMappingURL=core-version.js.map

package/dist/core-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core-version.js","sourceRoot":"","sources":["../src/core-version.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;GAUG;AACU,QAAA,gBAAgB,GAAG,OAAO,CAAC"}

package/dist/dto.d.ts

@@ -0,0 +1,64 @@
+/**
+ * the broker read-port DTOs, EXTRACTED here as the single
+ * source of truth. These were defined in `apps/api/src/modules/runtime/broker-ports.ts`; the
+ * dependency direction is now reversed (apps/api imports them from this package), so the
+ * published SDK contract can never drift from what the core broker returns.
+ *
+ * The DTO TYPES are the privacy boundary: e.g. {@link ModuleCustomerDto} has no email/phone/
+ * address/VAT fields, so `read:customers` is field-limited by construction.
+ */
+/** Cursor/limit list query a module may pass (the broker validates + bounds it). */
+export interface ListQuery {
+    readonly limit: number;
+    readonly cursor?: string;
+}
+export interface ListResult<T> {
+    readonly items: readonly T[];
+    readonly nextCursor?: string;
+}
+/**
+ * READ-ONLY product→category metadata on {@link ModuleProductDto} (follow-up B1). A product's
+ * PRIMARY category (the lowest-`position`, id-tiebroken row of its `product_categories` links),
+ * projected to the same `{ id, slug, name }` shape as {@link ModuleCategoryDto}. It rides the
+ * EXISTING `read:products` grant (no new permission — it is catalog metadata, never PII) and is
+ * `undefined` when the product has no category. Lets a module filter/exclude by category without a
+ * separate product→category port.
+ */
+export interface ModuleProductCategory {
+    readonly id: string;
+    readonly slug: string;
+    readonly name: string;
+}
+export interface ModuleProductDto {
+    readonly id: string;
+    readonly slug: string;
+    readonly title: string;
+    readonly status: string;
+    /** The product's primary category (read-only; omitted/undefined when it has none). */
+    readonly category?: ModuleProductCategory;
+}
+export interface ModuleCategoryDto {
+    readonly id: string;
+    readonly slug: string;
+    readonly name: string;
+}
+export interface ModuleOrderDto {
+    readonly id: string;
+    readonly number: string;
+    readonly status: string;
+    readonly totalMinor: number;
+    readonly currency: string;
+    readonly createdAt: string;
+}
+/**
+ * FIELD-LIMITED customer projection. Deliberately carries NO email, phone,
+ * address, or VAT — `read:customers` must not hand modules raw PII. Widening requires a future
+ * explicit PII sub-permission with its own DTO/port.
+ */
+export interface ModuleCustomerDto {
+    readonly id: string;
+    readonly displayName: string;
+    readonly locale: string | null;
+    readonly createdAt: string;
+}
+//# sourceMappingURL=dto.d.ts.map

package/dist/dto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dto.d.ts","sourceRoot":"","sources":["../src/dto.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,oFAAoF;AACpF,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,sFAAsF;IACtF,QAAQ,CAAC,QAAQ,CAAC,EAAE,qBAAqB,CAAC;CAC3C;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B"}

package/dist/dto.js

@@ -0,0 +1,12 @@
+"use strict";
+/**
+ * the broker read-port DTOs, EXTRACTED here as the single
+ * source of truth. These were defined in `apps/api/src/modules/runtime/broker-ports.ts`; the
+ * dependency direction is now reversed (apps/api imports them from this package), so the
+ * published SDK contract can never drift from what the core broker returns.
+ *
+ * The DTO TYPES are the privacy boundary: e.g. {@link ModuleCustomerDto} has no email/phone/
+ * address/VAT fields, so `read:customers` is field-limited by construction.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=dto.js.map

package/dist/dto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dto.js","sourceRoot":"","sources":["../src/dto.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG"}

package/dist/email.d.ts

@@ -0,0 +1,85 @@
+/**
+ * the module `email:send` capability message DTO.
+ *
+ * A PURE type: the shape a module passes to `sdk.email.send(...)`. ALL enforcement — the
+ * `email:send` permission gate, strict param validation (header-injection-safe recipient/subject),
+ * the per-module rate limit, the audit record, and tenant scoping — lives in the CORE broker
+ * (`apps/api/.../module-broker.ts` + `module-mail.port.ts`). Nothing here can weaken it.
+ *
+ * The module supplies its OWN subject + plaintext body; it gets NO access to core's transactional
+ * templates and NO SMTP/transport credentials. Core routes the message through the existing
+ * `MailService` as a module-originated email.
+ *
+ * TENANT SCOPING (v1): "tenant-scoped" here means the send is ATTRIBUTED to the module's tenant for
+ * AUDIT and RATE-LIMIT purposes (both keyed by the worker's tenant + module identity, never module
+ * input). It is NOT transport-level isolation — single-tenant v1 uses one shared mail transport.
+ *
+ * BOUNDS (mirrored exactly by the broker's Zod schema — the single source of truth is the broker;
+ * these constants document the contract for authors and let the SDK package self-check):
+ *   - `to`     — a single, syntactically-valid email, ≤ {@link EMAIL_TO_MAX} chars, NO CR/LF/comma/
+ *                semicolon (header-injection guard — a module may never address multiple recipients
+ *                or smuggle a header);
+ *   - `subject`— ≤ {@link EMAIL_SUBJECT_MAX} chars, NO CR/LF (header-injection guard);
+ *   - `text`   — required plaintext body, ≤ {@link EMAIL_TEXT_MAX} chars;
+ *   - `html`   — OPTIONAL html body, ≤ {@link EMAIL_HTML_MAX} chars (escaping/CSP is whatever the
+ *                core mail layer already applies — the module gains no new injection surface).
+ * Unknown keys are REJECTED (`.strict()` in the broker) — a module cannot smuggle `from`, `to`
+ * arrays, `cc`/`bcc`, `tenantId`, or transport options.
+ */
+/** Max length of the `to` recipient address. */
+export declare const EMAIL_TO_MAX = 254;
+/** Max length of the `subject` line. */
+export declare const EMAIL_SUBJECT_MAX = 200;
+/** Max length of the plaintext `text` body. */
+export declare const EMAIL_TEXT_MAX = 50000;
+/** Max length of the optional `html` body. */
+export declare const EMAIL_HTML_MAX = 100000;
+/** The message a module supplies to {@link EmailClient.send}. */
+export interface ModuleEmailMessage {
+    /** A single, syntactically-valid recipient email. No CR/LF/comma/semicolon. */
+    readonly to: string;
+    /** The subject line. No CR/LF. */
+    readonly subject: string;
+    /** Plain-text body (required). */
+    readonly text: string;
+    /** Optional HTML body. */
+    readonly html?: string;
+}
+/**
+ * The message a module supplies to {@link EmailClient.sendToCustomer}.
+ *
+ * PRIVACY-PRESERVING module→customer email: the module addresses a customer it holds only an
+ * opaque `customerId` for — it supplies NO email address and NEVER receives one. Core resolves the
+ * recipient by the (broker-context tenant, customerId) composite, honours marketing CONSENT
+ * (`accepts_marketing`) and RGPD erasure (`deleted_at` / `anonymized_at`), and either sends or
+ * SUPPRESSES the message. The module cannot tell WHY a send was suppressed (no consent/existence
+ * oracle) — it only learns whether it was {@link ModuleEmailSendResult.queued}.
+ *
+ * `subject`/`text`/`html` carry the SAME header-injection rules + length bounds as
+ * {@link ModuleEmailMessage} (validated in the core broker — the single source of truth). There is
+ * NO `to` field by construction.
+ */
+export interface ModuleCustomerEmailMessage {
+    /** The opaque customer id (a uuid). Core resolves the recipient; the module never sees it. */
+    readonly customerId: string;
+    /** The subject line. No CR/LF (header-injection guard). */
+    readonly subject: string;
+    /** Plain-text body (required). */
+    readonly text: string;
+    /** Optional HTML body. */
+    readonly html?: string;
+}
+/**
+ * The result of an attempted send — handed back to the module.
+ *
+ * - `{@link send}` always resolves `{ queued: true }` (the module supplied the address; on success
+ *   the message is queued, else it rejects).
+ * - `{@link sendToCustomer}` resolves `{ queued: true }` when core sent, or `{ queued: false }` when
+ *   core SUPPRESSED it (recipient missing / erased / not marketing-consented). `queued:false` is a
+ *   DELIBERATELY OPAQUE outcome — it leaks no reason, so the module gains no consent/existence
+ *   oracle over the customer base.
+ */
+export interface ModuleEmailSendResult {
+    readonly queued: boolean;
+}
+//# sourceMappingURL=email.d.ts.map

package/dist/email.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"email.d.ts","sourceRoot":"","sources":["../src/email.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,gDAAgD;AAChD,eAAO,MAAM,YAAY,MAAM,CAAC;AAChC,wCAAwC;AACxC,eAAO,MAAM,iBAAiB,MAAM,CAAC;AACrC,+CAA+C;AAC/C,eAAO,MAAM,cAAc,QAAS,CAAC;AACrC,8CAA8C;AAC9C,eAAO,MAAM,cAAc,SAAU,CAAC;AAEtC,iEAAiE;AACjE,MAAM,WAAW,kBAAkB;IACjC,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,kCAAkC;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kCAAkC;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0BAA0B;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,0BAA0B;IACzC,8FAA8F;IAC9F,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kCAAkC;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0BAA0B;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B"}

package/dist/email.js

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * the module `email:send` capability message DTO.
+ *
+ * A PURE type: the shape a module passes to `sdk.email.send(...)`. ALL enforcement — the
+ * `email:send` permission gate, strict param validation (header-injection-safe recipient/subject),
+ * the per-module rate limit, the audit record, and tenant scoping — lives in the CORE broker
+ * (`apps/api/.../module-broker.ts` + `module-mail.port.ts`). Nothing here can weaken it.
+ *
+ * The module supplies its OWN subject + plaintext body; it gets NO access to core's transactional
+ * templates and NO SMTP/transport credentials. Core routes the message through the existing
+ * `MailService` as a module-originated email.
+ *
+ * TENANT SCOPING (v1): "tenant-scoped" here means the send is ATTRIBUTED to the module's tenant for
+ * AUDIT and RATE-LIMIT purposes (both keyed by the worker's tenant + module identity, never module
+ * input). It is NOT transport-level isolation — single-tenant v1 uses one shared mail transport.
+ *
+ * BOUNDS (mirrored exactly by the broker's Zod schema — the single source of truth is the broker;
+ * these constants document the contract for authors and let the SDK package self-check):
+ *   - `to`     — a single, syntactically-valid email, ≤ {@link EMAIL_TO_MAX} chars, NO CR/LF/comma/
+ *                semicolon (header-injection guard — a module may never address multiple recipients
+ *                or smuggle a header);
+ *   - `subject`— ≤ {@link EMAIL_SUBJECT_MAX} chars, NO CR/LF (header-injection guard);
+ *   - `text`   — required plaintext body, ≤ {@link EMAIL_TEXT_MAX} chars;
+ *   - `html`   — OPTIONAL html body, ≤ {@link EMAIL_HTML_MAX} chars (escaping/CSP is whatever the
+ *                core mail layer already applies — the module gains no new injection surface).
+ * Unknown keys are REJECTED (`.strict()` in the broker) — a module cannot smuggle `from`, `to`
+ * arrays, `cc`/`bcc`, `tenantId`, or transport options.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EMAIL_HTML_MAX = exports.EMAIL_TEXT_MAX = exports.EMAIL_SUBJECT_MAX = exports.EMAIL_TO_MAX = void 0;
+/** Max length of the `to` recipient address. */
+exports.EMAIL_TO_MAX = 254;
+/** Max length of the `subject` line. */
+exports.EMAIL_SUBJECT_MAX = 200;
+/** Max length of the plaintext `text` body. */
+exports.EMAIL_TEXT_MAX = 50_000;
+/** Max length of the optional `html` body. */
+exports.EMAIL_HTML_MAX = 100_000;
+//# sourceMappingURL=email.js.map

package/dist/email.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"email.js","sourceRoot":"","sources":["../src/email.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;;;AAEH,gDAAgD;AACnC,QAAA,YAAY,GAAG,GAAG,CAAC;AAChC,wCAAwC;AAC3B,QAAA,iBAAiB,GAAG,GAAG,CAAC;AACrC,+CAA+C;AAClC,QAAA,cAAc,GAAG,MAAM,CAAC;AACrC,8CAA8C;AACjC,QAAA,cAAc,GAAG,OAAO,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,40 @@
+/**
+ * the stable RPC error codes carried on a broker response,
+ * EXTRACTED here so module authors can branch on failures (e.g. distinguish `forbidden` from
+ * `timeout`) without string-matching. Was defined in
+ * `apps/api/src/modules/runtime/ipc-protocol.ts`; apps/api now imports it from here.
+ *
+ * This is the ONLY runtime-value half of the error contract the SDK exposes. The IPC envelope,
+ * frame Zod schemas, and `RpcError` class stay core-side (transport/enforcement, not contract).
+ */
+/** Stable error codes carried on a response frame. */
+export declare const RpcErrorCode: {
+    /** The peer did not register a handler for the requested method. */
+    readonly UNKNOWN_METHOD: "unknown_method";
+    /** The request timed out waiting for a response. */
+    readonly TIMEOUT: "timeout";
+    /** The handler threw. */
+    readonly HANDLER_ERROR: "handler_error";
+    /** The channel closed before a response arrived. */
+    readonly CHANNEL_CLOSED: "channel_closed";
+    /** Params/result failed validation, or a frame was malformed. */
+    readonly PROTOCOL: "protocol";
+    /** The broker refused the call (permission / tenant / transactional-path). */
+    readonly FORBIDDEN: "forbidden";
+    /** The capability exists in the manifest vocabulary but is not implemented yet. */
+    readonly NOT_AVAILABLE: "not_available";
+    /**
+     * The worker's inbound RPC concurrency cap was exceeded (DoS hardening).
+     * The caller should back off and retry rather than queuing indefinitely in core.
+     */
+    readonly BUSY: "busy";
+    /**
+     * A per-module capability rate limit was exceeded (e.g. `email:send`). The call was
+     * REFUSED, not queued; the caller should back off until the limit window rolls over. Distinct
+     * from {@link BUSY} (transient concurrency) — this is a sustained-volume cap on a side-effecting
+     * capability, surfaced to the module as a clean refusal rather than a thrown crash.
+     */
+    readonly RATE_LIMITED: "rate_limited";
+};
+export type RpcErrorCode = (typeof RpcErrorCode)[keyof typeof RpcErrorCode];
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,sDAAsD;AACtD,eAAO,MAAM,YAAY;IACvB,oEAAoE;;IAEpE,oDAAoD;;IAEpD,yBAAyB;;IAEzB,oDAAoD;;IAEpD,iEAAiE;;IAEjE,8EAA8E;;IAE9E,mFAAmF;;IAEnF;;;OAGG;;IAEH;;;;;OAKG;;CAEK,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC"}

package/dist/errors.js

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * the stable RPC error codes carried on a broker response,
+ * EXTRACTED here so module authors can branch on failures (e.g. distinguish `forbidden` from
+ * `timeout`) without string-matching. Was defined in
+ * `apps/api/src/modules/runtime/ipc-protocol.ts`; apps/api now imports it from here.
+ *
+ * This is the ONLY runtime-value half of the error contract the SDK exposes. The IPC envelope,
+ * frame Zod schemas, and `RpcError` class stay core-side (transport/enforcement, not contract).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RpcErrorCode = void 0;
+/** Stable error codes carried on a response frame. */
+exports.RpcErrorCode = {
+    /** The peer did not register a handler for the requested method. */
+    UNKNOWN_METHOD: 'unknown_method',
+    /** The request timed out waiting for a response. */
+    TIMEOUT: 'timeout',
+    /** The handler threw. */
+    HANDLER_ERROR: 'handler_error',
+    /** The channel closed before a response arrived. */
+    CHANNEL_CLOSED: 'channel_closed',
+    /** Params/result failed validation, or a frame was malformed. */
+    PROTOCOL: 'protocol',
+    /** The broker refused the call (permission / tenant / transactional-path). */
+    FORBIDDEN: 'forbidden',
+    /** The capability exists in the manifest vocabulary but is not implemented yet. */
+    NOT_AVAILABLE: 'not_available',
+    /**
+     * The worker's inbound RPC concurrency cap was exceeded (DoS hardening).
+     * The caller should back off and retry rather than queuing indefinitely in core.
+     */
+    BUSY: 'busy',
+    /**
+     * A per-module capability rate limit was exceeded (e.g. `email:send`). The call was
+     * REFUSED, not queued; the caller should back off until the limit window rolls over. Distinct
+     * from {@link BUSY} (transient concurrency) — this is a sustained-volume cap on a side-effecting
+     * capability, surfaced to the module as a clean refusal rather than a thrown crash.
+     */
+    RATE_LIMITED: 'rate_limited',
+};
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AAEH,sDAAsD;AACzC,QAAA,YAAY,GAAG;IAC1B,oEAAoE;IACpE,cAAc,EAAE,gBAAgB;IAChC,oDAAoD;IACpD,OAAO,EAAE,SAAS;IAClB,yBAAyB;IACzB,aAAa,EAAE,eAAe;IAC9B,oDAAoD;IACpD,cAAc,EAAE,gBAAgB;IAChC,iEAAiE;IACjE,QAAQ,EAAE,UAAU;IACpB,8EAA8E;IAC9E,SAAS,EAAE,WAAW;IACtB,mFAAmF;IACnF,aAAa,EAAE,eAAe;IAC9B;;;OAGG;IACH,IAAI,EAAE,MAAM;IACZ;;;;;OAKG;IACH,YAAY,EAAE,cAAc;CACpB,CAAC"}

package/dist/events.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Follow-up B2 — the MODULE-FACING payload contracts for the two OBSERVATIONAL commerce events a
+ * module may subscribe to (`product.price_changed`, `product.stock_changed`). These are the EXACT
+ * shapes core fans to a subscribed worker's event handler, so they are part of the published SDK
+ * contract: a change here is a contract change. `apps/api` (the core runtime) imports these FROM
+ * here, so what the broker delivers can never drift from what a module author types against.
+ *
+ * Both are deliberately minimal, NON-PII projections. Modules only OBSERVE these signals — emitting
+ * them stays entirely inside core's transactional/admin paths (a module never enters them).
+ */
+/**
+ * `eventId` — an opaque, core-assigned identifier that is UNIQUE PER EMIT. Two genuinely distinct
+ * events (e.g. a flash-sale cycle that drops a variant to the SAME price TWICE) carry DIFFERENT
+ * `eventId`s, so a module can use it as an idempotency key that dedupes only redelivery/reprocessing
+ * of the SAME event — never two real events that happen to share the same {old,new} values. (Core
+ * delivery is at-most-once today, but a module persisting a dedup ledger must key on this, not on
+ * the collision-prone value tuple.) Treat it as opaque — do not parse it.
+ */
+/**
+ * `product.price_changed` — a variant's price ACTUALLY changed (old !== new). Prices are PUBLIC
+ * catalog data, so carrying BOTH the old and new minor-unit price is safe and is exactly what a
+ * module needs to detect a drop without a second read. NEVER delivered on a no-op price update.
+ */
+export interface ProductPriceChangedPayload {
+    /** Opaque, core-assigned, unique-per-emit id — the correct module-side idempotency key. */
+    readonly eventId: string;
+    readonly productId: string;
+    readonly variantId: string;
+    readonly oldPriceMinor: number;
+    readonly newPriceMinor: number;
+    readonly currency: string;
+}
+/**
+ * `product.stock_changed` — a variant's AVAILABILITY flipped across the zero boundary. Carries a
+ * back-in-stock BOOLEAN ONLY: `available: true` on an out-of-stock → in-stock (0 → positive)
+ * transition, `false` on in-stock → out-of-stock. It NEVER carries the exact stock level / quantity
+ * — exposing precise inventory to a sandboxed module is a competitive-information leak, and the
+ * boolean is all a back-in-stock notifier needs. `available` reflects PHYSICAL stock crossing zero
+ * (NOT stock-minus-active-reservations).
+ */
+export interface ProductStockChangedPayload {
+    /** Opaque, core-assigned, unique-per-emit id — the correct module-side idempotency key. */
+    readonly eventId: string;
+    readonly productId: string;
+    readonly variantId: string;
+    readonly available: boolean;
+}
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;;;GAOG;AAEH;;;;GAIG;AACH,MAAM,WAAW,0BAA0B;IACzC,2FAA2F;IAC3F,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,0BAA0B;IACzC,2FAA2F;IAC3F,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B"}

package/dist/events.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * Follow-up B2 — the MODULE-FACING payload contracts for the two OBSERVATIONAL commerce events a
+ * module may subscribe to (`product.price_changed`, `product.stock_changed`). These are the EXACT
+ * shapes core fans to a subscribed worker's event handler, so they are part of the published SDK
+ * contract: a change here is a contract change. `apps/api` (the core runtime) imports these FROM
+ * here, so what the broker delivers can never drift from what a module author types against.
+ *
+ * Both are deliberately minimal, NON-PII projections. Modules only OBSERVE these signals — emitting
+ * them stays entirely inside core's transactional/admin paths (a module never enters them).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG"}