@voyant-travel/core 0.109.0

package/dist/events.js

@@ -0,0 +1,169 @@
+/** Stable, unique event id for envelope metadata / outbox dedup. */
+export function generateEventId() {
+    return `evt_${crypto.randomUUID()}`;
+}
+const DEFAULT_HANDLER_TIMEOUT_MS = 15_000;
+/**
+ * Create an in-process event bus.
+ *
+ * Handlers run **in parallel** — they are independent observers by
+ * contract, so one slow subscriber doesn't serialize behind another.
+ * Errors thrown by a handler are caught and logged and never affect the
+ * emitter or sibling handlers ("subscribers are fire-and-forget").
+ * Each handler is bounded by {@link EventBusOptions.handlerTimeoutMs}.
+ *
+ * When the emitter passes {@link EmitOptions.schedule}, handlers not
+ * marked `inline` are handed to the scheduler as one promise and
+ * `emit()` resolves without waiting for them — this is how the HTTP
+ * runtime moves subscriber work (third-party syncs, notifications)
+ * after the response.
+ */
+export function createEventBus(options = {}) {
+    const handlers = new Map();
+    const timeoutMs = options.handlerTimeoutMs ?? DEFAULT_HANDLER_TIMEOUT_MS;
+    /**
+     * Runs one handler; never rejects. Returns the error message when the
+     * handler threw or timed out, `null` on success. Errors are always
+     * logged here so non-durable emits keep today's observability.
+     */
+    async function runHandler(event, handler, envelope) {
+        try {
+            if (timeoutMs === false) {
+                await handler(envelope);
+                return null;
+            }
+            let timer = null;
+            const timedOut = new Promise((resolve) => {
+                timer = setTimeout(() => resolve("timeout"), timeoutMs);
+            });
+            try {
+                const result = await Promise.race([
+                    Promise.resolve(handler(envelope)).then(() => "done"),
+                    timedOut,
+                ]);
+                if (result === "timeout") {
+                    // The handler keeps running detached — we just stop waiting.
+                    // Counted as a failure for durable delivery: the retry relies
+                    // on subscriber idempotency.
+                    const message = `subscriber for "${event}" exceeded ${timeoutMs}ms; not awaited`;
+                    console.error(`[events] ${message}`);
+                    return message;
+                }
+                return null;
+            }
+            finally {
+                if (timer !== null)
+                    clearTimeout(timer);
+            }
+        }
+        catch (err) {
+            // Subscribers are fire-and-forget — log and continue.
+            console.error(`[events] subscriber error for "${event}":`, err);
+            return err instanceof Error ? err.message : String(err);
+        }
+    }
+    /** Runs a batch in parallel; resolves with the error messages. */
+    function runBatch(event, batch, envelope) {
+        return Promise.all(batch.map((h) => runHandler(event, h, envelope))).then((results) => results.filter((r) => r !== null));
+    }
+    function partition(event) {
+        const inline = [];
+        const deferrable = [];
+        const registered = handlers.get(event);
+        if (registered) {
+            for (const [handler, meta] of registered) {
+                ;
+                (meta.inline ? inline : deferrable).push(handler);
+            }
+        }
+        return { inline, deferrable };
+    }
+    function ensureEventId(metadata) {
+        if (metadata && typeof metadata.eventId === "string" && metadata.eventId.length > 0) {
+            return metadata;
+        }
+        return { ...(metadata ?? {}), eventId: generateEventId() };
+    }
+    return {
+        async emit(event, data, metadata, emitOptions) {
+            const store = emitOptions?.store;
+            const registered = handlers.get(event);
+            if (!store && (!registered || registered.size === 0))
+                return;
+            const envelope = {
+                name: event,
+                data,
+                emittedAt: new Date().toISOString(),
+                // Durable capture and downstream dedup (workflow forwarder) both
+                // key on a stable event id — stamp one when the caller didn't.
+                ...(() => {
+                    const withId = ensureEventId(metadata);
+                    return withId === undefined ? {} : { metadata: withId };
+                })(),
+            };
+            const { inline, deferrable } = partition(event);
+            const run = (batch) => runBatch(event, batch, envelope);
+            if (!store) {
+                if (emitOptions?.schedule && deferrable.length > 0) {
+                    emitOptions.schedule(run(deferrable));
+                    if (inline.length > 0)
+                        await run(inline);
+                    return;
+                }
+                await run([...inline, ...deferrable]);
+                return;
+            }
+            // ---- Durable (outbox) path ----
+            // Persist BEFORE any handler runs: a crash mid-delivery leaves a
+            // pending row the drain redelivers, instead of a lost event.
+            const record = await store.insert(envelope);
+            if (record === null) {
+                // Duplicate eventId — already captured; the original owns delivery.
+                return;
+            }
+            const settle = async (errors) => {
+                try {
+                    if (errors.length === 0)
+                        await store.complete(record.id);
+                    else
+                        await store.fail(record.id, errors.join("; "));
+                }
+                catch (err) {
+                    // Best-effort bookkeeping: a failed `complete` leaves the row
+                    // pending and the drain redelivers (at-least-once, idempotent
+                    // subscribers). Never surface to the emitter.
+                    console.error(`[events] outbox bookkeeping failed for "${event}":`, err);
+                }
+            };
+            if (emitOptions.schedule && deferrable.length > 0) {
+                const inlineErrors = inline.length > 0 ? await run(inline) : [];
+                emitOptions.schedule(run(deferrable).then((deferredErrors) => settle([...inlineErrors, ...deferredErrors])));
+                return;
+            }
+            const errors = await run([...inline, ...deferrable]);
+            await settle(errors);
+        },
+        async deliver(envelope) {
+            const { inline, deferrable } = partition(envelope.name);
+            const all = [...inline, ...deferrable];
+            if (all.length === 0)
+                return { attempted: 0, failed: 0, errors: [] };
+            const errors = await runBatch(envelope.name, all, envelope);
+            return { attempted: all.length, failed: errors.length, errors };
+        },
+        subscribe(event, handler, subscribeOptions) {
+            let registered = handlers.get(event);
+            if (!registered) {
+                registered = new Map();
+                handlers.set(event, registered);
+            }
+            registered.set(handler, { inline: subscribeOptions?.inline ?? false });
+            return {
+                unsubscribe() {
+                    registered?.delete(handler);
+                },
+            };
+        },
+    };
+}
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

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

package/dist/hooks.d.ts

@@ -0,0 +1,19 @@
+type HookHandler = (...args: unknown[]) => Promise<void> | void;
+/**
+ * Simple typed event emitter for module lifecycle hooks.
+ *
+ * Events are namespaced by convention: "module.event"
+ * (e.g., "contacts.beforeCreate", "bookings.afterConfirm")
+ */
+declare class HookSystem {
+    private handlers;
+    /** Register a handler for an event */
+    on(event: string, handler: HookHandler): void;
+    /** Remove a handler for an event */
+    off(event: string, handler: HookHandler): void;
+    /** Emit an event, calling all registered handlers sequentially */
+    emit(event: string, ...args: unknown[]): Promise<void>;
+}
+export declare const hooks: HookSystem;
+export {};
+//# sourceMappingURL=hooks.d.ts.map

package/dist/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAAA,KAAK,WAAW,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;AAE/D;;;;;GAKG;AACH,cAAM,UAAU;IACd,OAAO,CAAC,QAAQ,CAAsC;IAEtD,sCAAsC;IACtC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI;IAS7C,oCAAoC;IACpC,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI;IAI9C,kEAAkE;IAC5D,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAO7D;AAED,eAAO,MAAM,KAAK,YAAmB,CAAA"}

package/dist/hooks.js

@@ -0,0 +1,33 @@
+/**
+ * Simple typed event emitter for module lifecycle hooks.
+ *
+ * Events are namespaced by convention: "module.event"
+ * (e.g., "contacts.beforeCreate", "bookings.afterConfirm")
+ */
+class HookSystem {
+    handlers = new Map();
+    /** Register a handler for an event */
+    on(event, handler) {
+        let set = this.handlers.get(event);
+        if (!set) {
+            set = new Set();
+            this.handlers.set(event, set);
+        }
+        set.add(handler);
+    }
+    /** Remove a handler for an event */
+    off(event, handler) {
+        this.handlers.get(event)?.delete(handler);
+    }
+    /** Emit an event, calling all registered handlers sequentially */
+    async emit(event, ...args) {
+        const set = this.handlers.get(event);
+        if (!set)
+            return;
+        for (const handler of set) {
+            await handler(...args);
+        }
+    }
+}
+export const hooks = new HookSystem();
+//# sourceMappingURL=hooks.js.map

package/dist/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,UAAU;IACN,QAAQ,GAAG,IAAI,GAAG,EAA4B,CAAA;IAEtD,sCAAsC;IACtC,EAAE,CAAC,KAAa,EAAE,OAAoB;QACpC,IAAI,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;QAClC,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,GAAG,GAAG,IAAI,GAAG,EAAE,CAAA;YACf,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAA;QAC/B,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;IAClB,CAAC;IAED,oCAAoC;IACpC,GAAG,CAAC,KAAa,EAAE,OAAoB;QACrC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC,CAAA;IAC3C,CAAC;IAED,kEAAkE;IAClE,KAAK,CAAC,IAAI,CAAC,KAAa,EAAE,GAAG,IAAe;QAC1C,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;QACpC,IAAI,CAAC,GAAG;YAAE,OAAM;QAChB,KAAK,MAAM,OAAO,IAAI,GAAG,EAAE,CAAC;YAC1B,MAAM,OAAO,CAAC,GAAG,IAAI,CAAC,CAAA;QACxB,CAAC;IACH,CAAC;CACF;AAED,MAAM,CAAC,MAAM,KAAK,GAAG,IAAI,UAAU,EAAE,CAAA"}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+export type { AdminConfig, AdminRoutesConfig, ConfigValidationIssue, ConfigValidationResult, DeploymentTarget, ModuleEntry, PluginEntry, ProjectConfig, VoyantConfig, } from "./config.js";
+export { defineVoyantConfig, resolveEntry, validateVoyantConfig } from "./config.js";
+export type { ModuleContainer } from "./container.js";
+export { createContainer } from "./container.js";
+export type { Actor, VoyantAuthContext, VoyantCallerType, VoyantPermission, VoyantVariables, } from "./env.js";
+export type { DeliveryResult, EmitOptions, EventBus, EventBusOptions, EventCategory, EventEnvelope, EventHandler, EventMetadata, EventSource, OutboxEventStore, SubscribeOptions, Subscription, } from "./events.js";
+export { createEventBus, generateEventId } from "./events.js";
+export { hooks } from "./hooks.js";
+export type { LinkableDefinition, LinkCardinality, LinkDefinition, LinkDefinitionOptions, LinkKeyRecord, LinkListFilter, LinkRow, LinkService, LinkSide, LinkSideInput, LinkSpec, LinkTableSql, ResolvedLinkSpec, } from "./links.js";
+export { defineLink, generateLinkTableSql, resolveLinkFromSpec } from "./links.js";
+export type { ExclusiveExecutionResult, ExecutionLockManager, } from "./locking.js";
+export { createInMemoryExecutionLockManager } from "./locking.js";
+export type { BootstrapContext, BootstrapHandler, EventFilterDescriptor, Extension, Module, WorkflowDescriptor, } from "./module.js";
+export type { JobOptions, JobRunner } from "./orchestration.js";
+export type { Plugin, RegisteredPlugins, RegisterPluginsOptions, Subscriber, } from "./plugin.js";
+export { definePlugin, registerPlugins } from "./plugin.js";
+export type { EntityFetcher, EntityFetcherArgs, EntityRecord, QueryContextValue, QueryFilters, QueryGraphConfig, QueryGraphContext, QueryGraphResult, QueryPagination, QueryRunner, } from "./query.js";
+export { createQueryContext, createQueryRunner, queryGraph } from "./query.js";
+export type { RegistryOptions } from "./registry.js";
+export { createRegistry } from "./registry.js";
+export type { StepBuilder, StepCompensateFn, StepDefinition, StepRunFn, WorkflowContext, WorkflowDefinition, WorkflowResult, WorkflowRunOptions, } from "./workflows.js";
+export { createWorkflow, step, WorkflowError } from "./workflows.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,WAAW,EACX,iBAAiB,EACjB,qBAAqB,EACrB,sBAAsB,EACtB,gBAAgB,EAChB,WAAW,EACX,WAAW,EACX,aAAa,EACb,YAAY,GACb,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AACpF,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAChD,YAAY,EACV,KAAK,EACL,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,GAChB,MAAM,UAAU,CAAA;AACjB,YAAY,EACV,cAAc,EACd,WAAW,EACX,QAAQ,EACR,eAAe,EACf,aAAa,EACb,aAAa,EACb,YAAY,EACZ,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,GACb,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAC7D,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,YAAY,EACV,kBAAkB,EAClB,eAAe,EACf,cAAc,EACd,qBAAqB,EACrB,aAAa,EACb,cAAc,EACd,OAAO,EACP,WAAW,EACX,QAAQ,EACR,aAAa,EACb,QAAQ,EACR,YAAY,EACZ,gBAAgB,GACjB,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,UAAU,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAClF,YAAY,EACV,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,cAAc,CAAA;AACrB,OAAO,EAAE,kCAAkC,EAAE,MAAM,cAAc,CAAA;AACjE,YAAY,EACV,gBAAgB,EAChB,gBAAgB,EAChB,qBAAqB,EACrB,SAAS,EACT,MAAM,EACN,kBAAkB,GACnB,MAAM,aAAa,CAAA;AACpB,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAC/D,YAAY,EACV,MAAM,EACN,iBAAiB,EACjB,sBAAsB,EACtB,UAAU,GACX,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAC3D,YAAY,EACV,aAAa,EACb,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EACf,WAAW,GACZ,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAC9E,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAC9C,YAAY,EACV,WAAW,EACX,gBAAgB,EAChB,cAAc,EACd,SAAS,EACT,eAAe,EACf,kBAAkB,EAClB,cAAc,EACd,kBAAkB,GACnB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA"}

package/dist/index.js

@@ -0,0 +1,11 @@
+export { defineVoyantConfig, resolveEntry, validateVoyantConfig } from "./config.js";
+export { createContainer } from "./container.js";
+export { createEventBus, generateEventId } from "./events.js";
+export { hooks } from "./hooks.js";
+export { defineLink, generateLinkTableSql, resolveLinkFromSpec } from "./links.js";
+export { createInMemoryExecutionLockManager } from "./locking.js";
+export { definePlugin, registerPlugins } from "./plugin.js";
+export { createQueryContext, createQueryRunner, queryGraph } from "./query.js";
+export { createRegistry } from "./registry.js";
+export { createWorkflow, step, WorkflowError } from "./workflows.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AAEpF,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAsBhD,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAC7D,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAgBlC,OAAO,EAAE,UAAU,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAKlF,OAAO,EAAE,kCAAkC,EAAE,MAAM,cAAc,CAAA;AAgBjE,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAa3D,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE9E,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAW9C,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA"}

package/dist/links.d.ts

@@ -0,0 +1,201 @@
+/**
+ * Module Links — cross-module associations that live in "neutral territory"
+ * outside any specific module's schema.
+ *
+ * Each link defines a pivot table that contains only ID pairs. There are no
+ * DB-level foreign key constraints, so modules remain independently
+ * swappable, and templates can introduce new cross-module references
+ * without modifying any module package.
+ */
+/**
+ * Metadata describing a linkable entity — the entity kind that can participate
+ * in a link from another module.
+ *
+ * Each module exposes one {@link LinkableDefinition} per entity it wants to
+ * expose to other modules (e.g. a CRM module exposes `person` and
+ * `organization`).
+ */
+export interface LinkableDefinition {
+    /** Owning module name (e.g. "crm"). */
+    module: string;
+    /** Entity name within the module (e.g. "person"). Used to build the join-column name. */
+    entity: string;
+    /** Underlying DB table name (informational; used by codegen / diagnostics). */
+    table: string;
+    /** Primary-key column name on the entity's table. Defaults to "id". */
+    primaryKey?: string;
+    /** TypeID prefix for IDs of this entity (informational). */
+    idPrefix?: string;
+}
+/**
+ * One side of a link. `isList: true` means that, from the opposite side,
+ * this entity appears as a list.
+ */
+export interface LinkSide {
+    linkable: LinkableDefinition;
+    isList?: boolean;
+}
+export type LinkSideInput = LinkableDefinition | LinkSide;
+export interface LinkDefinitionOptions {
+    /**
+     * When true, deleting the link row should cascade-delete the target side
+     * (enforced by the link service, not the database).
+     */
+    deleteCascade?: boolean;
+    database?: {
+        /** Override the auto-generated pivot table name. */
+        tableName?: string;
+        /** Override the auto-generated left-side ID column name. */
+        leftColumn?: string;
+        /** Override the auto-generated right-side ID column name. */
+        rightColumn?: string;
+    };
+    /**
+     * Mark the link as externally-owned and non-materialized.
+     *
+     * Read-only links participate in cross-module query traversal, but they do
+     * not create a neutral-territory pivot table and cannot be mutated through
+     * the runtime link service.
+     */
+    readOnly?: {
+        list(filter?: {
+            leftId?: string;
+            rightId?: string;
+        }): Promise<LinkRow[]>;
+    };
+}
+export type LinkCardinality = "one-to-one" | "one-to-many" | "many-to-one" | "many-to-many";
+/**
+ * A fully-resolved link definition. Produced by {@link defineLink} and
+ * consumed by codegen (`generateLinkTableSql`) and the runtime link service.
+ */
+export interface LinkDefinition {
+    left: LinkSide;
+    right: LinkSide;
+    /** Generated pivot table name (e.g. "crm_person_products_product"). */
+    tableName: string;
+    /** Left-side ID column name in the pivot table (e.g. "crm_person_id"). */
+    leftColumn: string;
+    /** Right-side ID column name in the pivot table (e.g. "products_product_id"). */
+    rightColumn: string;
+    /** Inferred cardinality from the `isList` flags on each side. */
+    cardinality: LinkCardinality;
+    deleteCascade: boolean;
+    /**
+     * Read-only links are resolved from an externally-owned relation instead of
+     * a generated pivot table.
+     */
+    readOnly?: {
+        list(filter?: {
+            leftId?: string;
+            rightId?: string;
+        }): Promise<LinkRow[]>;
+    };
+}
+/**
+ * Declare a link between two linkable entities.
+ *
+ * @example
+ * ```ts
+ * // one-to-one
+ * defineLink(crm.linkable.person, products.linkable.product)
+ *
+ * // one-to-many (each person has many products)
+ * defineLink(
+ *   crm.linkable.person,
+ *   { linkable: products.linkable.product, isList: true },
+ * )
+ *
+ * // many-to-many
+ * defineLink(
+ *   { linkable: crm.linkable.person, isList: true },
+ *   { linkable: products.linkable.product, isList: true },
+ * )
+ * ```
+ */
+export declare function defineLink(left: LinkSideInput, right: LinkSideInput, options?: LinkDefinitionOptions): LinkDefinition;
+/**
+ * SQL DDL for materializing a link's pivot table.
+ */
+export interface LinkTableSql {
+    /** `CREATE TABLE IF NOT EXISTS …` statement. */
+    createTable: string;
+    /** `CREATE [UNIQUE] INDEX IF NOT EXISTS …` statements. */
+    indexes: string[];
+}
+export declare function generateLinkTableSql(def: LinkDefinition): LinkTableSql;
+/**
+ * Medusa-style link spec keyed by module name, then by join-column name.
+ *
+ * @example
+ * ```ts
+ * {
+ *   crm: { person_id: "pers_abc" },
+ *   products: { product_id: "prod_xyz" },
+ * }
+ * ```
+ */
+export type LinkKeyRecord = Record<string, string>;
+export type LinkSpec = Record<string, LinkKeyRecord>;
+export interface ResolvedLinkSpec {
+    definition: LinkDefinition;
+    leftId: string;
+    rightId: string;
+}
+/**
+ * Match a {@link LinkSpec} to a {@link LinkDefinition} from the provided list,
+ * returning the matched definition along with the resolved left/right IDs
+ * (in the order the definition declares).
+ *
+ * Throws when the spec doesn't match exactly one definition.
+ */
+export declare function resolveLinkFromSpec(spec: LinkSpec, defs: LinkDefinition[]): ResolvedLinkSpec;
+/**
+ * A row in a link's pivot table.
+ */
+export interface LinkRow {
+    id: string;
+    leftId: string;
+    rightId: string;
+    createdAt: Date;
+    updatedAt: Date;
+    deletedAt: Date | null;
+}
+/**
+ * Filter for {@link LinkService.list}. All provided fields are ANDed.
+ *
+ * The plural fields (`leftIds`/`rightIds`) match any of the given IDs in a
+ * single batched lookup — implementations MUST resolve them with one
+ * query/roundtrip, not one per ID. An empty array can never match and
+ * short-circuits to `[]`. Singular and plural fields for the same side
+ * combine by intersection.
+ */
+export interface LinkListFilter {
+    /** Match a single left-side ID. */
+    leftId?: string;
+    /** Match a single right-side ID. */
+    rightId?: string;
+    /** Match any of the given left-side IDs (one batched query). */
+    leftIds?: string[];
+    /** Match any of the given right-side IDs (one batched query). */
+    rightIds?: string[];
+}
+/**
+ * Runtime service for manipulating link rows. Templates register an
+ * implementation in the module container under `"link"`.
+ */
+export interface LinkService {
+    /** Create a link between two entity IDs. Idempotent on the unique pair. */
+    create(linkKey: string, leftId: string, rightId: string): Promise<LinkRow>;
+    /** Create using a Medusa-style module-keyed spec. */
+    create(spec: LinkSpec): Promise<LinkRow>;
+    /** Soft-delete a link (sets `deleted_at`). */
+    dismiss(linkKey: string, leftId: string, rightId: string): Promise<void>;
+    dismiss(spec: LinkSpec): Promise<void>;
+    /** Hard-delete a link row. */
+    delete(linkKey: string, leftId: string, rightId: string): Promise<void>;
+    delete(spec: LinkSpec): Promise<void>;
+    /** List link rows matching the given filter (non-soft-deleted only). */
+    list(linkKey: string, filter?: LinkListFilter): Promise<LinkRow[]>;
+}
+//# sourceMappingURL=links.d.ts.map

package/dist/links.d.ts.map

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

package/dist/links.js

@@ -0,0 +1,159 @@
+/**
+ * Module Links — cross-module associations that live in "neutral territory"
+ * outside any specific module's schema.
+ *
+ * Each link defines a pivot table that contains only ID pairs. There are no
+ * DB-level foreign key constraints, so modules remain independently
+ * swappable, and templates can introduce new cross-module references
+ * without modifying any module package.
+ */
+/**
+ * Declare a link between two linkable entities.
+ *
+ * @example
+ * ```ts
+ * // one-to-one
+ * defineLink(crm.linkable.person, products.linkable.product)
+ *
+ * // one-to-many (each person has many products)
+ * defineLink(
+ *   crm.linkable.person,
+ *   { linkable: products.linkable.product, isList: true },
+ * )
+ *
+ * // many-to-many
+ * defineLink(
+ *   { linkable: crm.linkable.person, isList: true },
+ *   { linkable: products.linkable.product, isList: true },
+ * )
+ * ```
+ */
+export function defineLink(left, right, options) {
+    const leftSide = normalizeSide(left);
+    const rightSide = normalizeSide(right);
+    const tableName = options?.database?.tableName ?? defaultLinkTableName(leftSide, rightSide);
+    const leftColumn = options?.database?.leftColumn ?? defaultColumnName(leftSide);
+    const rightColumn = options?.database?.rightColumn ?? defaultColumnName(rightSide);
+    if (leftColumn === rightColumn) {
+        throw new Error(`defineLink: left and right column names would collide ("${leftColumn}"). ` +
+            `Provide distinct database.leftColumn / database.rightColumn overrides.`);
+    }
+    return {
+        left: leftSide,
+        right: rightSide,
+        tableName,
+        leftColumn,
+        rightColumn,
+        cardinality: cardinalityFor(leftSide, rightSide),
+        deleteCascade: options?.deleteCascade ?? false,
+        readOnly: options?.readOnly,
+    };
+}
+function normalizeSide(input) {
+    if ("linkable" in input) {
+        return { linkable: input.linkable, isList: input.isList ?? false };
+    }
+    return { linkable: input, isList: false };
+}
+function defaultLinkTableName(left, right) {
+    return `${left.linkable.module}_${left.linkable.entity}_${right.linkable.module}_${right.linkable.entity}`;
+}
+function defaultColumnName(side) {
+    return `${side.linkable.module}_${side.linkable.entity}_id`;
+}
+function cardinalityFor(left, right) {
+    if (!left.isList && !right.isList)
+        return "one-to-one";
+    if (!left.isList && right.isList)
+        return "one-to-many";
+    if (left.isList && !right.isList)
+        return "many-to-one";
+    return "many-to-many";
+}
+/**
+ * Generate the SQL needed to materialize a link's pivot table.
+ *
+ * Quote a SQL identifier, escaping embedded double quotes by doubling them.
+ *
+ * Defense in depth: link identifiers are developer-authored (never HTTP
+ * input), but routing them through a quoting helper guarantees the emitted
+ * DDL stays well-formed even for hostile or accidental quote-containing
+ * names (see security assessment L6).
+ */
+function quoteIdent(identifier) {
+    return `"${identifier.replaceAll('"', '""')}"`;
+}
+export function generateLinkTableSql(def) {
+    if (def.readOnly) {
+        throw new Error(`generateLinkTableSql: read-only link "${def.tableName}" is externally owned and does not materialize a pivot table`);
+    }
+    const { tableName, leftColumn, rightColumn } = def;
+    const table = quoteIdent(tableName);
+    const left = quoteIdent(leftColumn);
+    const right = quoteIdent(rightColumn);
+    const createTable = [
+        `CREATE TABLE IF NOT EXISTS ${table} (`,
+        `  "id" text PRIMARY KEY NOT NULL,`,
+        `  ${left} text NOT NULL,`,
+        `  ${right} text NOT NULL,`,
+        `  "created_at" timestamp with time zone DEFAULT now() NOT NULL,`,
+        `  "updated_at" timestamp with time zone DEFAULT now() NOT NULL,`,
+        `  "deleted_at" timestamp with time zone`,
+        `)`,
+    ].join("\n");
+    // Postgres truncates identifiers at 63 chars; keep index suffixes short.
+    const indexes = [];
+    // Dedupe the pair (ignoring soft-deleted rows).
+    indexes.push(`CREATE UNIQUE INDEX IF NOT EXISTS ${quoteIdent(`${tableName}_pair_idx`)} ON ${table} (${left}, ${right}) WHERE "deleted_at" IS NULL`);
+    // !right.isList → each left has ≤1 right → left_id must be unique.
+    if (!def.right.isList) {
+        indexes.push(`CREATE UNIQUE INDEX IF NOT EXISTS ${quoteIdent(`${tableName}_l_uniq`)} ON ${table} (${left}) WHERE "deleted_at" IS NULL`);
+    }
+    else {
+        indexes.push(`CREATE INDEX IF NOT EXISTS ${quoteIdent(`${tableName}_l_idx`)} ON ${table} (${left}) WHERE "deleted_at" IS NULL`);
+    }
+    // !left.isList → each right has ≤1 left → right_id must be unique.
+    if (!def.left.isList) {
+        indexes.push(`CREATE UNIQUE INDEX IF NOT EXISTS ${quoteIdent(`${tableName}_r_uniq`)} ON ${table} (${right}) WHERE "deleted_at" IS NULL`);
+    }
+    else {
+        indexes.push(`CREATE INDEX IF NOT EXISTS ${quoteIdent(`${tableName}_r_idx`)} ON ${table} (${right}) WHERE "deleted_at" IS NULL`);
+    }
+    return { createTable, indexes };
+}
+/**
+ * Match a {@link LinkSpec} to a {@link LinkDefinition} from the provided list,
+ * returning the matched definition along with the resolved left/right IDs
+ * (in the order the definition declares).
+ *
+ * Throws when the spec doesn't match exactly one definition.
+ */
+export function resolveLinkFromSpec(spec, defs) {
+    const entries = Object.entries(spec);
+    if (entries.length !== 2) {
+        throw new Error(`resolveLinkFromSpec: expected exactly 2 module keys, got ${entries.length}`);
+    }
+    const [first, second] = entries;
+    for (const def of defs) {
+        const leftModule = def.left.linkable.module;
+        const rightModule = def.right.linkable.module;
+        const leftKey = `${def.left.linkable.entity}_id`;
+        const rightKey = `${def.right.linkable.entity}_id`;
+        // Spec order matches definition order.
+        if (first[0] === leftModule && second[0] === rightModule) {
+            const leftId = first[1][leftKey];
+            const rightId = second[1][rightKey];
+            if (leftId && rightId)
+                return { definition: def, leftId, rightId };
+        }
+        // Spec order is reversed.
+        if (second[0] === leftModule && first[0] === rightModule) {
+            const leftId = second[1][leftKey];
+            const rightId = first[1][rightKey];
+            if (leftId && rightId)
+                return { definition: def, leftId, rightId };
+        }
+    }
+    throw new Error(`resolveLinkFromSpec: no LinkDefinition matches spec keys [${first[0]}, ${second[0]}]`);
+}
+//# sourceMappingURL=links.js.map