@beignet/core 0.0.1 → 0.0.3

package/dist/ports/audit.js

@@ -1,19 +1,108 @@
 import { redactValue } from "./redaction";
+/**
+ * Create an anonymous actor descriptor for unauthenticated activity.
+ *
+ * This helper only creates a normalized context value. It does not perform
+ * authentication.
+ *
+ * @example
+ * ```ts
+ * const actor = createAnonymousActor();
+ * ```
+ *
+ * @param options - Optional display name or metadata to include.
+ * @returns An activity actor with `type: "anonymous"`.
+ */
 export function createAnonymousActor(options = {}) {
     return { type: "anonymous", ...options };
 }
+/**
+ * Create a service actor descriptor for work initiated by another service or
+ * integration.
+ *
+ * This is useful for webhooks, internal service calls, or integration-driven
+ * background jobs.
+ *
+ * @example
+ * ```ts
+ * const actor = createServiceActor("stripe-webhook");
+ * ```
+ *
+ * @param id - Stable service or integration ID.
+ * @param options - Optional display name or metadata to include.
+ * @returns An activity actor with `type: "service"`.
+ */
 export function createServiceActor(id, options = {}) {
     return { type: "service", id, ...options };
 }
+/**
+ * Create a system actor descriptor for framework or app-owned background work.
+ *
+ * Use this for scheduled tasks, scripts, maintenance jobs, and other work that
+ * is not directly caused by a user or external service.
+ *
+ * @example
+ * ```ts
+ * const actor = createSystemActor("nightly-maintenance");
+ * ```
+ *
+ * @param id - Stable system actor ID. Defaults to `"system"`.
+ * @param options - Optional display name or metadata to include.
+ * @returns An activity actor with `type: "system"`.
+ */
 export function createSystemActor(id = "system", options = {}) {
     return { type: "system", id, ...options };
 }
+/**
+ * Create a user actor descriptor for authenticated user activity.
+ *
+ * This helper only normalizes a known user ID for context, authorization,
+ * audit, and diagnostics. It does not verify a session or load a user record.
+ * Resolve authentication first, then call this helper with the authenticated
+ * user ID.
+ *
+ * @example
+ * ```ts
+ * const actor = createUserActor(session.user.id, {
+ *   displayName: session.user.name,
+ * });
+ * ```
+ *
+ * @param id - Stable application user ID.
+ * @param options - Optional display name or metadata to include.
+ * @returns An activity actor with `type: "user"`.
+ */
 export function createUserActor(id, options = {}) {
     return { type: "user", id, ...options };
 }
+/**
+ * Create a tenant/account/workspace descriptor for request or background
+ * context.
+ *
+ * This helper only creates a normalized context value used by audit,
+ * authorization, logs, and diagnostics. It does not create, load, or persist a
+ * tenant record.
+ *
+ * @example
+ * ```ts
+ * const tenant = createTenant(session.organizationId, {
+ *   slug: session.organizationSlug,
+ * });
+ * ```
+ *
+ * @param id - Stable tenant/account/workspace ID.
+ * @param options - Optional slug or metadata to include.
+ * @returns A normalized activity tenant descriptor.
+ */
 export function createTenant(id, options = {}) {
     return { id, ...options };
 }
+/**
+ * Fill default audit fields for an input entry.
+ *
+ * @param entry - Partial audit entry accepted by `AuditLogPort.record(...)`.
+ * @returns A complete audit entry with `occurredAt` and `outcome` populated.
+ */
 export function normalizeAuditLogEntry(entry) {
     return {
         ...entry,
@@ -21,6 +110,15 @@ export function normalizeAuditLogEntry(entry) {
         outcome: entry.outcome ?? "success",
     };
 }
+/**
+ * Redact metadata on an already-normalized audit entry.
+ *
+ * This redacts metadata values on the entry, actor, tenant, and resource using
+ * the default redaction rules from `redactValue(...)`.
+ *
+ * @param entry - Audit entry to redact.
+ * @returns A shallow copy with redacted metadata fields.
+ */
 export function redactAuditLogEntry(entry) {
     return {
         ...entry,
@@ -49,6 +147,16 @@ export function redactAuditLogEntry(entry) {
         metadata: entry.metadata ? redactValue(entry.metadata) : entry.metadata,
     };
 }
+/**
+ * Wrap an audit log port with default audit metadata redaction.
+ *
+ * Use this around durable adapters so application code can record entries
+ * without each call site remembering to redact metadata.
+ *
+ * @param audit - Underlying audit log port to write to after redaction.
+ * @param options - Optional final redaction/customization hook.
+ * @returns An audit log port that normalizes and redacts before writing.
+ */
 export function createRedactedAuditLog(audit, options = {}) {
     return {
         record(entry) {
@@ -60,6 +168,26 @@ export function createRedactedAuditLog(audit, options = {}) {
         },
     };
 }
+/**
+ * Create an in-memory audit log for tests and local examples.
+ *
+ * Entries are normalized and redacted before being pushed into the shared
+ * `entries` array.
+ *
+ * @example
+ * ```ts
+ * const audit = createMemoryAuditLog();
+ * await audit.record({
+ *   action: "posts.publish",
+ *   actor: createUserActor("user_1"),
+ * });
+ * expect(audit.entries).toHaveLength(1);
+ * ```
+ *
+ * @param entries - Optional backing array, useful when tests need shared state.
+ * @param options - Optional final redaction/customization hook.
+ * @returns An in-memory audit log port with captured `entries`.
+ */
 export function createMemoryAuditLog(entries = [], options = {}) {
     return {
         entries,

package/dist/ports/audit.js.map

@@ -1 +1 @@
-{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../src/ports/audit.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../src/ports/audit.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAuN1C;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,oBAAoB,CAClC,UAAuC,EAAE;IAEzC,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,OAAO,EAAE,CAAC;AAC3C,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,kBAAkB,CAChC,EAAU,EACV,UAA8C,EAAE;IAEhD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,GAAG,OAAO,EAAE,CAAC;AAC7C,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,iBAAiB,CAC/B,EAAE,GAAG,QAAQ,EACb,UAA8C,EAAE;IAEhD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,GAAG,OAAO,EAAE,CAAC;AAC5C,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,eAAe,CAC7B,EAAU,EACV,UAA8C,EAAE;IAEhD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,GAAG,OAAO,EAAE,CAAC;AAC1C,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,YAAY,CAC1B,EAAU,EACV,UAAsC,EAAE;IAExC,OAAO,EAAE,EAAE,EAAE,GAAG,OAAO,EAAE,CAAC;AAC5B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CACpC,KAAyB;IAEzB,OAAO;QACL,GAAG,KAAK;QACR,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,IAAI,IAAI,EAAE;QAC1C,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,SAAS;KACpC,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAoB;IACtD,OAAO;QACL,GAAG,KAAK;QACR,KAAK,EAAE;YACL,GAAG,KAAK,CAAC,KAAK;YACd,QAAQ,EAAE,KAAK,CAAC,KAAK,CAAC,QAAQ;gBAC5B,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC;gBACnC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ;SACzB;QACD,MAAM,EAAE,KAAK,CAAC,MAAM;YAClB,CAAC,CAAC;gBACE,GAAG,KAAK,CAAC,MAAM;gBACf,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,QAAQ;oBAC7B,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC;oBACpC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ;aAC1B;YACH,CAAC,CAAC,KAAK,CAAC,MAAM;QAChB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACtB,CAAC,CAAC;gBACE,GAAG,KAAK,CAAC,QAAQ;gBACjB,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC,QAAQ;oBAC/B,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC;oBACtC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,QAAQ;aAC5B;YACH,CAAC,CAAC,KAAK,CAAC,QAAQ;QAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ;KACxE,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,sBAAsB,CACpC,KAAmB,EACnB,UAA2B,EAAE;IAE7B,OAAO;QACL,MAAM,CAAC,KAAK;YACV,MAAM,UAAU,GAAG,sBAAsB,CAAC,KAAK,CAAC,CAAC;YACjD,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM;gBAC7B,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,mBAAmB,CAAC,UAAU,CAAC,CAAC;gBACjD,CAAC,CAAC,mBAAmB,CAAC,UAAU,CAAC,CAAC;YACpC,OAAO,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAChC,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,oBAAoB,CAClC,UAA2B,EAAE,EAC7B,UAA2B,EAAE;IAE7B,OAAO;QACL,OAAO;QACP,MAAM,CAAC,KAAK;YACV,MAAM,UAAU,GAAG,sBAAsB,CAAC,KAAK,CAAC,CAAC;YACjD,OAAO,CAAC,IAAI,CACV,OAAO,CAAC,MAAM;gBACZ,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,mBAAmB,CAAC,UAAU,CAAC,CAAC;gBACjD,CAAC,CAAC,mBAAmB,CAAC,UAAU,CAAC,CACpC,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/ports/auth.d.ts

@@ -1,23 +1,93 @@
+/**
+ * Minimal request shape consumed by Beignet auth ports.
+ *
+ * Framework adapters can pass richer request objects, but auth providers should
+ * only rely on headers and the optional raw platform request unless they
+ * declare a more specific `RequestLike` type.
+ */
 export interface AuthRequestLike {
+    /**
+     * Request headers used for cookies, bearer tokens, API keys, or provider
+     * specific auth data.
+     */
     headers: Headers;
+    /**
+     * Raw platform request, when the runtime has one available.
+     */
     raw?: Request;
 }
+/**
+ * Normalized authenticated session returned by an `AuthPort`.
+ *
+ * `user` is the app/provider user object. `session` can carry provider-specific
+ * session state such as cookie session metadata or token claims.
+ */
 export interface AuthSession<User = unknown, Session = unknown> {
     user: User;
     session?: Session;
 }
+/**
+ * Error thrown by auth helpers when a route or workflow requires a user but no
+ * authenticated user is available.
+ */
 export declare class AuthUnauthorizedError extends Error {
     readonly code = "UNAUTHORIZED";
     constructor(message?: string);
 }
+/**
+ * App-facing authentication port.
+ *
+ * Implement this with a provider adapter such as Better Auth, a custom session
+ * lookup, or a test fake. The port identifies the current user; it does not
+ * decide whether that user may perform a business action. Keep authorization in
+ * policies or use cases.
+ */
 export interface AuthPort<User = unknown, Session = unknown, RequestLike extends AuthRequestLike = AuthRequestLike> {
+    /**
+     * Return the current session, or `null` when the request is unauthenticated.
+     */
     getSession(req: RequestLike): Promise<AuthSession<User, Session> | null>;
+    /**
+     * Return the current user, or `null` when unauthenticated.
+     */
     getUser(req: RequestLike): Promise<User | null>;
+    /**
+     * Return the current user or throw `AuthUnauthorizedError`.
+     */
     requireUser(req: RequestLike): Promise<User>;
 }
 type MaybePromise<T> = T | Promise<T>;
+/**
+ * Request-aware factory for a static auth session.
+ */
 export type StaticAuthSessionFactory<User, Session, RequestLike extends AuthRequestLike> = (req: RequestLike) => MaybePromise<AuthSession<User, Session> | null>;
+/**
+ * Create an auth port from a fixed session or request-aware session factory.
+ *
+ * This is useful for tests, examples, and simple apps. Production apps usually
+ * use a provider-backed auth port that verifies cookies, tokens, or sessions.
+ *
+ * @example
+ * ```ts
+ * const auth = createStaticAuth({
+ *   user: { id: "user_1", name: "Ada" },
+ * });
+ * ```
+ *
+ * @param session - Fixed session, `null`, or a function that resolves a session
+ * from the request.
+ * @returns An `AuthPort` implementation backed by the provided session source.
+ */
 export declare function createStaticAuth<User, Session = unknown, RequestLike extends AuthRequestLike = AuthRequestLike>(session: AuthSession<User, Session> | null | StaticAuthSessionFactory<User, Session, RequestLike>): AuthPort<User, Session, RequestLike>;
+/**
+ * Create an auth port that always treats requests as unauthenticated.
+ *
+ * Use this in tests or examples where auth is intentionally absent. It is not a
+ * security boundary; it simply returns `null` from `getSession`/`getUser` and
+ * throws from `requireUser`.
+ *
+ * @returns An `AuthPort` with no active session.
+ */
 export declare function createAnonymousAuth<User = unknown, Session = unknown, RequestLike extends AuthRequestLike = AuthRequestLike>(): AuthPort<User, Session, RequestLike>;
 export {};
 //# sourceMappingURL=auth.d.ts.map

package/dist/ports/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/ports/auth.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,WAAW,CAAC,IAAI,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO;IAC5D,IAAI,EAAE,IAAI,CAAC;IACX,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,IAAI,kBAAkB;gBAEnB,OAAO,SAAiB;CAIrC;AAED,MAAM,WAAW,QAAQ,CACvB,IAAI,GAAG,OAAO,EACd,OAAO,GAAG,OAAO,EACjB,WAAW,SAAS,eAAe,GAAG,eAAe;IAErD,UAAU,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;IACzE,OAAO,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;IAChD,WAAW,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9C;AAED,KAAK,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAEtC,MAAM,MAAM,wBAAwB,CAClC,IAAI,EACJ,OAAO,EACP,WAAW,SAAS,eAAe,IACjC,CAAC,GAAG,EAAE,WAAW,KAAK,YAAY,CAAC,WAAW,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;AAE1E,wBAAgB,gBAAgB,CAC9B,IAAI,EACJ,OAAO,GAAG,OAAO,EACjB,WAAW,SAAS,eAAe,GAAG,eAAe,EAErD,OAAO,EACH,WAAW,CAAC,IAAI,EAAE,OAAO,CAAC,GAC1B,IAAI,GACJ,wBAAwB,CAAC,IAAI,EAAE,OAAO,EAAE,WAAW,CAAC,GACvD,QAAQ,CAAC,IAAI,EAAE,OAAO,EAAE,WAAW,CAAC,CAqBtC;AAED,wBAAgB,mBAAmB,CACjC,IAAI,GAAG,OAAO,EACd,OAAO,GAAG,OAAO,EACjB,WAAW,SAAS,eAAe,GAAG,eAAe,KAClD,QAAQ,CAAC,IAAI,EAAE,OAAO,EAAE,WAAW,CAAC,CAExC"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/ports/auth.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB;;OAEG;IACH,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW,CAAC,IAAI,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO;IAC5D,IAAI,EAAE,IAAI,CAAC;IACX,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;GAGG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,IAAI,kBAAkB;gBAEnB,OAAO,SAAiB;CAIrC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,QAAQ,CACvB,IAAI,GAAG,OAAO,EACd,OAAO,GAAG,OAAO,EACjB,WAAW,SAAS,eAAe,GAAG,eAAe;IAErD;;OAEG;IACH,UAAU,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;IACzE;;OAEG;IACH,OAAO,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;IAChD;;OAEG;IACH,WAAW,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9C;AAED,KAAK,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAEtC;;GAEG;AACH,MAAM,MAAM,wBAAwB,CAClC,IAAI,EACJ,OAAO,EACP,WAAW,SAAS,eAAe,IACjC,CAAC,GAAG,EAAE,WAAW,KAAK,YAAY,CAAC,WAAW,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;AAE1E;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EACJ,OAAO,GAAG,OAAO,EACjB,WAAW,SAAS,eAAe,GAAG,eAAe,EAErD,OAAO,EACH,WAAW,CAAC,IAAI,EAAE,OAAO,CAAC,GAC1B,IAAI,GACJ,wBAAwB,CAAC,IAAI,EAAE,OAAO,EAAE,WAAW,CAAC,GACvD,QAAQ,CAAC,IAAI,EAAE,OAAO,EAAE,WAAW,CAAC,CAqBtC;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,GAAG,OAAO,EACd,OAAO,GAAG,OAAO,EACjB,WAAW,SAAS,eAAe,GAAG,eAAe,KAClD,QAAQ,CAAC,IAAI,EAAE,OAAO,EAAE,WAAW,CAAC,CAExC"}

package/dist/ports/auth.js

@@ -1,3 +1,7 @@
+/**
+ * Error thrown by auth helpers when a route or workflow requires a user but no
+ * authenticated user is available.
+ */
 export class AuthUnauthorizedError extends Error {
     code = "UNAUTHORIZED";
     constructor(message = "Unauthorized") {
@@ -5,6 +9,23 @@ export class AuthUnauthorizedError extends Error {
         this.name = "AuthUnauthorizedError";
     }
 }
+/**
+ * Create an auth port from a fixed session or request-aware session factory.
+ *
+ * This is useful for tests, examples, and simple apps. Production apps usually
+ * use a provider-backed auth port that verifies cookies, tokens, or sessions.
+ *
+ * @example
+ * ```ts
+ * const auth = createStaticAuth({
+ *   user: { id: "user_1", name: "Ada" },
+ * });
+ * ```
+ *
+ * @param session - Fixed session, `null`, or a function that resolves a session
+ * from the request.
+ * @returns An `AuthPort` implementation backed by the provided session source.
+ */
 export function createStaticAuth(session) {
     async function resolveSession(req) {
         return typeof session === "function" ? session(req) : session;
@@ -25,6 +46,15 @@ export function createStaticAuth(session) {
         },
     };
 }
+/**
+ * Create an auth port that always treats requests as unauthenticated.
+ *
+ * Use this in tests or examples where auth is intentionally absent. It is not a
+ * security boundary; it simply returns `null` from `getSession`/`getUser` and
+ * throws from `requireUser`.
+ *
+ * @returns An `AuthPort` with no active session.
+ */
 export function createAnonymousAuth() {
     return createStaticAuth(null);
 }

package/dist/ports/auth.js.map

@@ -1 +1 @@
-{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/ports/auth.ts"],"names":[],"mappings":"AAUA,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IACrC,IAAI,GAAG,cAAc,CAAC;IAE/B,YAAY,OAAO,GAAG,cAAc;QAClC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAoBD,MAAM,UAAU,gBAAgB,CAK9B,OAGwD;IAExD,KAAK,UAAU,cAAc,CAAC,GAAgB;QAC5C,OAAO,OAAO,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;IAChE,CAAC;IAED,OAAO;QACL,KAAK,CAAC,UAAU,CAAC,GAAG;YAClB,OAAO,cAAc,CAAC,GAAG,CAAC,CAAC;QAC7B,CAAC;QACD,KAAK,CAAC,OAAO,CAAC,GAAG;YACf,OAAO,CAAC,MAAM,cAAc,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,IAAI,IAAI,CAAC;QACnD,CAAC;QACD,KAAK,CAAC,WAAW,CAAC,GAAG;YACnB,MAAM,IAAI,GAAG,CAAC,MAAM,cAAc,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,IAAI,IAAI,CAAC;YACvD,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,MAAM,IAAI,qBAAqB,EAAE,CAAC;YACpC,CAAC;YAED,OAAO,IAAI,CAAC;QACd,CAAC;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,mBAAmB;IAKjC,OAAO,gBAAgB,CAA6B,IAAI,CAAC,CAAC;AAC5D,CAAC"}
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/ports/auth.ts"],"names":[],"mappings":"AA8BA;;;GAGG;AACH,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IACrC,IAAI,GAAG,cAAc,CAAC;IAE/B,YAAY,OAAO,GAAG,cAAc;QAClC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAwCD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,gBAAgB,CAK9B,OAGwD;IAExD,KAAK,UAAU,cAAc,CAAC,GAAgB;QAC5C,OAAO,OAAO,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;IAChE,CAAC;IAED,OAAO;QACL,KAAK,CAAC,UAAU,CAAC,GAAG;YAClB,OAAO,cAAc,CAAC,GAAG,CAAC,CAAC;QAC7B,CAAC;QACD,KAAK,CAAC,OAAO,CAAC,GAAG;YACf,OAAO,CAAC,MAAM,cAAc,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,IAAI,IAAI,CAAC;QACnD,CAAC;QACD,KAAK,CAAC,WAAW,CAAC,GAAG;YACnB,MAAM,IAAI,GAAG,CAAC,MAAM,cAAc,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,IAAI,IAAI,CAAC;YACvD,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,MAAM,IAAI,qBAAqB,EAAE,CAAC;YACpC,CAAC;YAED,OAAO,IAAI,CAAC;QACd,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB;IAKjC,OAAO,gBAAgB,CAA6B,IAAI,CAAC,CAAC;AAC5D,CAAC"}

package/dist/ports/cache.d.ts

@@ -1,15 +1,56 @@
+/**
+ * Options for storing a cache value.
+ */
 export interface CacheSetOptions {
     /**
      * Time-to-live in seconds. Omit this for a value that does not expire.
      */
     ttlSeconds?: number;
 }
+/**
+ * App-facing string cache port.
+ *
+ * Values are intentionally strings so adapters can map cleanly to Redis,
+ * Upstash, and other key/value stores. Serialize structured values at the app
+ * boundary.
+ */
 export interface CachePort {
+    /**
+     * Return a fresh value for `key`, or `null` when missing or expired.
+     */
     get(key: string): Promise<string | null>;
+    /**
+     * Store a string value.
+     */
     set(key: string, value: string, options?: CacheSetOptions): Promise<void>;
+    /**
+     * Delete a cache key.
+     *
+     * @returns `true` when the key existed.
+     */
     delete(key: string): Promise<boolean>;
+    /**
+     * Return whether a fresh value exists for `key`.
+     */
     has(key: string): Promise<boolean>;
+    /**
+     * Return a cached value or compute, store, and return a new value.
+     *
+     * Implementations are not required to provide single-flight behavior. If
+     * concurrent cache fills matter, choose an adapter that documents that
+     * guarantee or protect the factory at the application layer.
+     */
     remember(key: string, factory: () => Promise<string>, options?: CacheSetOptions): Promise<string>;
 }
+/**
+ * Create an in-memory cache for tests, examples, and single-process
+ * development.
+ *
+ * This adapter is not durable or distributed. Values are lost when the process
+ * exits and are not shared across workers, regions, or serverless invocations.
+ *
+ * @param initialValues - Optional initial string values without TTL.
+ * @returns A cache port backed by a local `Map`.
+ */
 export declare function createMemoryCache(initialValues?: Record<string, string>): CachePort;
 //# sourceMappingURL=cache.d.ts.map

package/dist/ports/cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/ports/cache.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,SAAS;IACxB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACzC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1E,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACnC,QAAQ,CACN,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,EAC9B,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,MAAM,CAAC,CAAC;CACpB;AAuBD,wBAAgB,iBAAiB,CAC/B,aAAa,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GACzC,SAAS,CAmDX"}
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/ports/cache.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACxB;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACzC;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1E;;;;OAIG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtC;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACnC;;;;;;OAMG;IACH,QAAQ,CACN,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,EAC9B,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,MAAM,CAAC,CAAC;CACpB;AAuBD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,aAAa,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GACzC,SAAS,CAmDX"}

package/dist/ports/cache.js

@@ -10,6 +10,16 @@ function resolveExpiresAt(options) {
 function isExpired(entry) {
     return entry.expiresAt != null && entry.expiresAt <= Date.now();
 }
+/**
+ * Create an in-memory cache for tests, examples, and single-process
+ * development.
+ *
+ * This adapter is not durable or distributed. Values are lost when the process
+ * exits and are not shared across workers, regions, or serverless invocations.
+ *
+ * @param initialValues - Optional initial string values without TTL.
+ * @returns A cache port backed by a local `Map`.
+ */
 export function createMemoryCache(initialValues = {}) {
     const values = new Map(Object.entries(initialValues).map(([key, value]) => [
         key,

package/dist/ports/cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/ports/cache.ts"],"names":[],"mappings":"AAwBA,SAAS,gBAAgB,CAAC,OAAoC;IAC5D,IAAI,OAAO,EAAE,UAAU,IAAI,IAAI,EAAE,CAAC;QAChC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,OAAO,CAAC,UAAU,IAAI,CAAC,EAAE,CAAC;QAC5B,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC;IACpB,CAAC;IAED,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;AAChD,CAAC;AAED,SAAS,SAAS,CAAC,KAAuB;IACxC,OAAO,KAAK,CAAC,SAAS,IAAI,IAAI,IAAI,KAAK,CAAC,SAAS,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;AAClE,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,gBAAwC,EAAE;IAE1C,MAAM,MAAM,GAAG,IAAI,GAAG,CACpB,MAAM,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC;QAClD,GAAG;QACH,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE;KAC3B,CAAC,CACH,CAAC;IAEF,KAAK,UAAU,aAAa,CAAC,GAAW;QACtC,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,IAAI,CAAC;QACd,CAAC;QAED,IAAI,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;YACrB,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACnB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,KAAK,GAAc;QACvB,KAAK,CAAC,GAAG,CAAC,GAAG;YACX,OAAO,CAAC,MAAM,aAAa,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,IAAI,IAAI,CAAC;QACnD,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,OAAO;YAC3B,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE;gBACd,KAAK;gBACL,SAAS,EAAE,gBAAgB,CAAC,OAAO,CAAC;aACrC,CAAC,CAAC;QACL,CAAC;QACD,KAAK,CAAC,MAAM,CAAC,GAAG;YACd,OAAO,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC5B,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,GAAG;YACX,OAAO,CAAC,MAAM,aAAa,CAAC,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC;QAC5C,CAAC;QACD,KAAK,CAAC,QAAQ,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO;YAClC,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACpC,IAAI,MAAM,IAAI,IAAI,EAAE,CAAC;gBACnB,OAAO,MAAM,CAAC;YAChB,CAAC;YAED,MAAM,KAAK,GAAG,MAAM,OAAO,EAAE,CAAC;YAC9B,MAAM,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;YACrC,OAAO,KAAK,CAAC;QACf,CAAC;KACF,CAAC;IAEF,OAAO,KAAK,CAAC;AACf,CAAC"}
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/ports/cache.ts"],"names":[],"mappings":"AAuDA,SAAS,gBAAgB,CAAC,OAAoC;IAC5D,IAAI,OAAO,EAAE,UAAU,IAAI,IAAI,EAAE,CAAC;QAChC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,OAAO,CAAC,UAAU,IAAI,CAAC,EAAE,CAAC;QAC5B,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC;IACpB,CAAC;IAED,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;AAChD,CAAC;AAED,SAAS,SAAS,CAAC,KAAuB;IACxC,OAAO,KAAK,CAAC,SAAS,IAAI,IAAI,IAAI,KAAK,CAAC,SAAS,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;AAClE,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAC/B,gBAAwC,EAAE;IAE1C,MAAM,MAAM,GAAG,IAAI,GAAG,CACpB,MAAM,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC;QAClD,GAAG;QACH,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE;KAC3B,CAAC,CACH,CAAC;IAEF,KAAK,UAAU,aAAa,CAAC,GAAW;QACtC,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,IAAI,CAAC;QACd,CAAC;QAED,IAAI,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;YACrB,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACnB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,KAAK,GAAc;QACvB,KAAK,CAAC,GAAG,CAAC,GAAG;YACX,OAAO,CAAC,MAAM,aAAa,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,IAAI,IAAI,CAAC;QACnD,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,OAAO;YAC3B,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE;gBACd,KAAK;gBACL,SAAS,EAAE,gBAAgB,CAAC,OAAO,CAAC;aACrC,CAAC,CAAC;QACL,CAAC;QACD,KAAK,CAAC,MAAM,CAAC,GAAG;YACd,OAAO,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC5B,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,GAAG;YACX,OAAO,CAAC,MAAM,aAAa,CAAC,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC;QAC5C,CAAC;QACD,KAAK,CAAC,QAAQ,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO;YAClC,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACpC,IAAI,MAAM,IAAI,IAAI,EAAE,CAAC;gBACnB,OAAO,MAAM,CAAC;YAChB,CAAC;YAED,MAAM,KAAK,GAAG,MAAM,OAAO,EAAE,CAAC;YAC9B,MAAM,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;YACrC,OAAO,KAAK,CAAC;QACf,CAAC;KACF,CAAC;IAEF,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/ports/clock.d.ts

@@ -1,10 +1,48 @@
+/**
+ * App-facing time source.
+ *
+ * Use this port anywhere deterministic time matters, such as use-case tests,
+ * scheduled work, idempotency windows, or audit timestamps.
+ */
 export interface ClockPort {
+    /**
+     * Return the current time according to this clock.
+     */
     now(): Date;
 }
+/**
+ * Mutable clock implementation used by tests.
+ */
 export interface FrozenClockPort extends ClockPort {
+    /**
+     * Replace the current time.
+     */
     setNow(value: Date | string | number): void;
+    /**
+     * Move the current time forward by the given number of milliseconds.
+     */
     advance(milliseconds: number): void;
 }
+/**
+ * Create a clock backed by `new Date()`.
+ *
+ * Use this as the default production `ClockPort` when the app does not need a
+ * provider-specific time source.
+ *
+ * @returns A clock that reads the current system time.
+ */
 export declare function createSystemClock(): ClockPort;
+/**
+ * Create a mutable clock for deterministic tests.
+ *
+ * @example
+ * ```ts
+ * const clock = createFrozenClock("2026-01-01T00:00:00.000Z");
+ * clock.advance(1000);
+ * ```
+ *
+ * @param initial - Initial time for the clock. Defaults to Unix epoch.
+ * @returns A clock whose time can be replaced or advanced.
+ */
 export declare function createFrozenClock(initial?: Date | string | number): FrozenClockPort;
 //# sourceMappingURL=clock.d.ts.map

package/dist/ports/clock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"clock.d.ts","sourceRoot":"","sources":["../../src/ports/clock.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,SAAS;IACxB,GAAG,IAAI,IAAI,CAAC;CACb;AAED,MAAM,WAAW,eAAgB,SAAQ,SAAS;IAChD,MAAM,CAAC,KAAK,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC5C,OAAO,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC;AAMD,wBAAgB,iBAAiB,IAAI,SAAS,CAI7C;AAED,wBAAgB,iBAAiB,CAC/B,OAAO,GAAE,IAAI,GAAG,MAAM,GAAG,MAAoB,GAC5C,eAAe,CAYjB"}
+{"version":3,"file":"clock.d.ts","sourceRoot":"","sources":["../../src/ports/clock.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB;;OAEG;IACH,GAAG,IAAI,IAAI,CAAC;CACb;AAED;;GAEG;AACH,MAAM,WAAW,eAAgB,SAAQ,SAAS;IAChD;;OAEG;IACH,MAAM,CAAC,KAAK,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC5C;;OAEG;IACH,OAAO,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC;AAMD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,IAAI,SAAS,CAI7C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,GAAE,IAAI,GAAG,MAAM,GAAG,MAAoB,GAC5C,eAAe,CAYjB"}

package/dist/ports/clock.js

@@ -1,11 +1,31 @@
 function toDate(value) {
     return value instanceof Date ? new Date(value.getTime()) : new Date(value);
 }
+/**
+ * Create a clock backed by `new Date()`.
+ *
+ * Use this as the default production `ClockPort` when the app does not need a
+ * provider-specific time source.
+ *
+ * @returns A clock that reads the current system time.
+ */
 export function createSystemClock() {
     return {
         now: () => new Date(),
     };
 }
+/**
+ * Create a mutable clock for deterministic tests.
+ *
+ * @example
+ * ```ts
+ * const clock = createFrozenClock("2026-01-01T00:00:00.000Z");
+ * clock.advance(1000);
+ * ```
+ *
+ * @param initial - Initial time for the clock. Defaults to Unix epoch.
+ * @returns A clock whose time can be replaced or advanced.
+ */
 export function createFrozenClock(initial = new Date(0)) {
     let current = toDate(initial);
     return {

package/dist/ports/clock.js.map

@@ -1 +1 @@
-{"version":3,"file":"clock.js","sourceRoot":"","sources":["../../src/ports/clock.ts"],"names":[],"mappings":"AASA,SAAS,MAAM,CAAC,KAA6B;IAC3C,OAAO,KAAK,YAAY,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC;AAC7E,CAAC;AAED,MAAM,UAAU,iBAAiB;IAC/B,OAAO;QACL,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE;KACtB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,UAAkC,IAAI,IAAI,CAAC,CAAC,CAAC;IAE7C,IAAI,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IAE9B,OAAO;QACL,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;QACtC,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE;YAChB,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAC1B,CAAC;QACD,OAAO,EAAE,CAAC,YAAY,EAAE,EAAE;YACxB,OAAO,GAAG,IAAI,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,YAAY,CAAC,CAAC;QACvD,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"clock.js","sourceRoot":"","sources":["../../src/ports/clock.ts"],"names":[],"mappings":"AA2BA,SAAS,MAAM,CAAC,KAA6B;IAC3C,OAAO,KAAK,YAAY,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC;AAC7E,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO;QACL,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE;KACtB,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iBAAiB,CAC/B,UAAkC,IAAI,IAAI,CAAC,CAAC,CAAC;IAE7C,IAAI,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IAE9B,OAAO;QACL,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;QACtC,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE;YAChB,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAC1B,CAAC;QACD,OAAO,EAAE,CAAC,YAAY,EAAE,EAAE;YACxB,OAAO,GAAG,IAAI,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,YAAY,CAAC,CAAC;QACvD,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/ports/id-generator.d.ts

@@ -1,10 +1,47 @@
+/**
+ * App-facing ID generation port.
+ *
+ * Use this when deterministic IDs matter in use-case tests or when production
+ * infrastructure owns ID generation.
+ */
 export interface IdGeneratorPort {
+    /**
+     * Return the next ID.
+     */
     nextId(): string;
 }
+/**
+ * Mutable sequential ID generator used by tests and simple examples.
+ */
 export interface SequenceIdGeneratorPort extends IdGeneratorPort {
+    /**
+     * Reset the next sequence value.
+     */
     reset(next?: number): void;
 }
+/**
+ * Create an ID generator backed by `globalThis.crypto.randomUUID()`.
+ *
+ * The factory itself does not read from `crypto`; the returned generator's
+ * `nextId()` method throws if the current runtime does not expose
+ * `globalThis.crypto.randomUUID()`.
+ *
+ * @returns An ID generator that returns UUID strings from `nextId()`.
+ */
 export declare function createUuidIdGenerator(): IdGeneratorPort;
+/**
+ * Create a deterministic sequence ID generator for tests and examples.
+ *
+ * @example
+ * ```ts
+ * const ids = createSequenceIdGenerator({ prefix: "post", start: 10 });
+ * ids.nextId(); // "post_10"
+ * ids.nextId(); // "post_11"
+ * ```
+ *
+ * @param options - Optional ID prefix and starting sequence number.
+ * @returns A mutable sequence ID generator.
+ */
 export declare function createSequenceIdGenerator(options?: {
     prefix?: string;
     start?: number;

package/dist/ports/id-generator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"id-generator.d.ts","sourceRoot":"","sources":["../../src/ports/id-generator.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe;IAC9B,MAAM,IAAI,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,uBAAwB,SAAQ,eAAe;IAC9D,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,wBAAgB,qBAAqB,IAAI,eAAe,CAYvD;AAED,wBAAgB,yBAAyB,CACvC,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAChD,uBAAuB,CAWzB"}
+{"version":3,"file":"id-generator.d.ts","sourceRoot":"","sources":["../../src/ports/id-generator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,MAAM,IAAI,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAwB,SAAQ,eAAe;IAC9D;;OAEG;IACH,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,IAAI,eAAe,CAYvD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAChD,uBAAuB,CAWzB"}

package/dist/ports/id-generator.js

@@ -1,3 +1,12 @@
+/**
+ * Create an ID generator backed by `globalThis.crypto.randomUUID()`.
+ *
+ * The factory itself does not read from `crypto`; the returned generator's
+ * `nextId()` method throws if the current runtime does not expose
+ * `globalThis.crypto.randomUUID()`.
+ *
+ * @returns An ID generator that returns UUID strings from `nextId()`.
+ */
 export function createUuidIdGenerator() {
     return {
         nextId: () => {
@@ -8,6 +17,19 @@ export function createUuidIdGenerator() {
         },
     };
 }
+/**
+ * Create a deterministic sequence ID generator for tests and examples.
+ *
+ * @example
+ * ```ts
+ * const ids = createSequenceIdGenerator({ prefix: "post", start: 10 });
+ * ids.nextId(); // "post_10"
+ * ids.nextId(); // "post_11"
+ * ```
+ *
+ * @param options - Optional ID prefix and starting sequence number.
+ * @returns A mutable sequence ID generator.
+ */
 export function createSequenceIdGenerator(options = {}) {
     const prefix = options.prefix ?? "id";
     const start = options.start ?? 1;

package/dist/ports/id-generator.js.map

@@ -1 +1 @@
-{"version":3,"file":"id-generator.js","sourceRoot":"","sources":["../../src/ports/id-generator.ts"],"names":[],"mappings":"AAQA,MAAM,UAAU,qBAAqB;IACnC,OAAO;QACL,MAAM,EAAE,GAAG,EAAE;YACX,IAAI,OAAO,UAAU,CAAC,MAAM,EAAE,UAAU,KAAK,UAAU,EAAE,CAAC;gBACxD,MAAM,IAAI,KAAK,CACb,kHAAkH,CACnH,CAAC;YACJ,CAAC;YAED,OAAO,UAAU,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;QACxC,CAAC;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,yBAAyB,CACvC,UAA+C,EAAE;IAEjD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC;IACtC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC;IACjC,IAAI,IAAI,GAAG,KAAK,CAAC;IAEjB,OAAO;QACL,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,MAAM,IAAI,IAAI,EAAE,EAAE;QACnC,KAAK,EAAE,CAAC,KAAK,GAAG,KAAK,EAAE,EAAE;YACvB,IAAI,GAAG,KAAK,CAAC;QACf,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"id-generator.js","sourceRoot":"","sources":["../../src/ports/id-generator.ts"],"names":[],"mappings":"AAuBA;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB;IACnC,OAAO;QACL,MAAM,EAAE,GAAG,EAAE;YACX,IAAI,OAAO,UAAU,CAAC,MAAM,EAAE,UAAU,KAAK,UAAU,EAAE,CAAC;gBACxD,MAAM,IAAI,KAAK,CACb,kHAAkH,CACnH,CAAC;YACJ,CAAC;YAED,OAAO,UAAU,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;QACxC,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,yBAAyB,CACvC,UAA+C,EAAE;IAEjD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC;IACtC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC;IACjC,IAAI,IAAI,GAAG,KAAK,CAAC;IAEjB,OAAO;QACL,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,MAAM,IAAI,IAAI,EAAE,EAAE;QACnC,KAAK,EAAE,CAAC,KAAK,GAAG,KAAK,EAAE,EAAE;YACvB,IAAI,GAAG,KAAK,CAAC;QACf,CAAC;KACF,CAAC;AACJ,CAAC"}