@smonn/ids 0.5.0 → 0.7.0

package/dist/fastify.mjs

@@ -0,0 +1,91 @@
+//#region src/fastify.ts
+/**
+* Typed error thrown into Fastify's `setErrorHandler` on validation failure.
+* Inspect `err.reason` and `err.statusCode` in your error handler.
+*/
+var IdParamError = class extends Error {
+	statusCode;
+	reason;
+	constructor(reason, statusCode) {
+		super(`ID validation failed: ${reason}`);
+		this.name = "IdParamError";
+		this.reason = reason;
+		this.statusCode = statusCode;
+	}
+};
+/**
+* Fastify `preHandler` hook factory that validates a named route param against a codec via `safeParse`.
+*
+* **Default (no options):** throws `IdParamError` carrying `statusCode` and `reason` so the app's
+* existing `setErrorHandler` controls rendering. The adapter does not write a response body itself.
+*
+* **`options.onError`:** when provided, the hook calls `onError` and does not throw; the consumer
+* fully owns the response via `reply`.
+*
+* **`options.status`:** remaps the default HTTP status for a reason without a full handler.
+*
+* - **Brand mismatch (`invalid_prefix`) → `reason: "brand_mismatch"`, default 404**
+* - **Malformed or missing ID → `reason: "malformed"`, default 400**
+*
+* On success, stores the canonical `Id<Brand>` in `request.params` under `paramName`.
+*
+* @example
+* ```ts
+* import { idParam, IdParamError } from "@smonn/ids/fastify";
+* import { createTimestampId } from "@smonn/ids";
+*
+* const usr = createTimestampId("usr");
+*
+* // Default: throws IdParamError → setErrorHandler renders it
+* fastify.get("/users/:id", { preHandler: idParam("id", usr) }, (request, reply) => {
+*   const id = request.params.id; // Id<"usr">, canonical
+* });
+*
+* // Error handler receives the typed error
+* fastify.setErrorHandler((err, request, reply) => {
+*   if (err instanceof IdParamError) {
+*     reply.status(err.statusCode).send({ error: err.reason });
+*     return;
+*   }
+*   reply.send(err);
+* });
+*
+* // Override: consumer fully owns the error response
+* fastify.get("/orgs/:id", {
+*   preHandler: idParam("id", org, {
+*     onError: (failure, request, reply) =>
+*       reply.status(failure.status).send({ error: failure.reason }),
+*   }),
+* }, handler);
+*
+* // Or a lightweight status remap without a full handler
+* fastify.get("/things/:id", {
+*   preHandler: idParam("id", thing, { status: { brand_mismatch: 400 } }),
+* }, handler);
+* ```
+*/
+function idParam(paramName, codec, options) {
+	return async (request, reply) => {
+		const raw = request.params[paramName];
+		const result = codec.safeParse(raw);
+		if (!result.ok) {
+			const reason = result.error === "invalid_prefix" ? "brand_mismatch" : "malformed";
+			const defaultStatus = reason === "brand_mismatch" ? 404 : 400;
+			const status = options?.status?.[reason] ?? defaultStatus;
+			const failure = {
+				reason,
+				status
+			};
+			if (options?.onError) {
+				await options.onError(failure, request, reply);
+				return;
+			}
+			throw new IdParamError(reason, status);
+		}
+		request.params[paramName] = result.id;
+	};
+}
+//#endregion
+export { IdParamError, idParam };
+
+//# sourceMappingURL=fastify.mjs.map

package/dist/fastify.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"fastify.mjs","names":[],"sources":["../src/fastify.ts"],"sourcesContent":["import type { FastifyReply, FastifyRequest } from \"fastify\";\nimport type { IdParamFailure } from \"./adapter-types.js\";\nimport type { Id, ParseResult } from \"./types.js\";\n\nexport type { IdParamFailure };\n\ntype IdCodec<Brand extends string> = {\n  safeParse(value: unknown): ParseResult<Brand>;\n};\n\n/**\n * Typed error thrown into Fastify's `setErrorHandler` on validation failure.\n * Inspect `err.reason` and `err.statusCode` in your error handler.\n */\nexport class IdParamError extends Error {\n  readonly statusCode: number;\n  readonly reason: \"brand_mismatch\" | \"malformed\";\n\n  constructor(reason: \"brand_mismatch\" | \"malformed\", statusCode: number) {\n    super(`ID validation failed: ${reason}`);\n    this.name = \"IdParamError\";\n    this.reason = reason;\n    this.statusCode = statusCode;\n  }\n}\n\n/** Options for `idParam`. All fields are optional. */\nexport type IdParamOptions = {\n  /**\n   * Called instead of throwing when provided. The hook owns the response entirely —\n   * the adapter does not throw.\n   */\n  onError?: (\n    failure: IdParamFailure,\n    request: FastifyRequest,\n    reply: FastifyReply,\n  ) => void | Promise<void>;\n  /**\n   * Remap the default HTTP status for a failure reason without a full handler.\n   * e.g. `{ brand_mismatch: 400 }` treats both failure kinds as 400.\n   */\n  status?: { brand_mismatch?: number; malformed?: number };\n};\n\n/**\n * Fastify `preHandler` hook factory that validates a named route param against a codec via `safeParse`.\n *\n * **Default (no options):** throws `IdParamError` carrying `statusCode` and `reason` so the app's\n * existing `setErrorHandler` controls rendering. The adapter does not write a response body itself.\n *\n * **`options.onError`:** when provided, the hook calls `onError` and does not throw; the consumer\n * fully owns the response via `reply`.\n *\n * **`options.status`:** remaps the default HTTP status for a reason without a full handler.\n *\n * - **Brand mismatch (`invalid_prefix`) → `reason: \"brand_mismatch\"`, default 404**\n * - **Malformed or missing ID → `reason: \"malformed\"`, default 400**\n *\n * On success, stores the canonical `Id<Brand>` in `request.params` under `paramName`.\n *\n * @example\n * ```ts\n * import { idParam, IdParamError } from \"@smonn/ids/fastify\";\n * import { createTimestampId } from \"@smonn/ids\";\n *\n * const usr = createTimestampId(\"usr\");\n *\n * // Default: throws IdParamError → setErrorHandler renders it\n * fastify.get(\"/users/:id\", { preHandler: idParam(\"id\", usr) }, (request, reply) => {\n *   const id = request.params.id; // Id<\"usr\">, canonical\n * });\n *\n * // Error handler receives the typed error\n * fastify.setErrorHandler((err, request, reply) => {\n *   if (err instanceof IdParamError) {\n *     reply.status(err.statusCode).send({ error: err.reason });\n *     return;\n *   }\n *   reply.send(err);\n * });\n *\n * // Override: consumer fully owns the error response\n * fastify.get(\"/orgs/:id\", {\n *   preHandler: idParam(\"id\", org, {\n *     onError: (failure, request, reply) =>\n *       reply.status(failure.status).send({ error: failure.reason }),\n *   }),\n * }, handler);\n *\n * // Or a lightweight status remap without a full handler\n * fastify.get(\"/things/:id\", {\n *   preHandler: idParam(\"id\", thing, { status: { brand_mismatch: 400 } }),\n * }, handler);\n * ```\n */\nexport function idParam<ParamKey extends string, Brand extends string>(\n  paramName: ParamKey,\n  codec: IdCodec<Brand>,\n  options?: IdParamOptions,\n): (request: FastifyRequest, reply: FastifyReply) => Promise<void> {\n  return async (request, reply): Promise<void> => {\n    const raw = (request.params as Record<ParamKey, unknown>)[paramName];\n    const result = codec.safeParse(raw);\n    if (!result.ok) {\n      const reason =\n        result.error === \"invalid_prefix\" ? (\"brand_mismatch\" as const) : (\"malformed\" as const);\n      const defaultStatus = reason === \"brand_mismatch\" ? 404 : 400;\n      const status = options?.status?.[reason] ?? defaultStatus;\n      const failure: IdParamFailure = { reason, status };\n      if (options?.onError) {\n        await options.onError(failure, request, reply);\n        return;\n      }\n      throw new IdParamError(reason, status);\n    }\n    (request.params as Record<ParamKey, Id<Brand>>)[paramName] = result.id;\n  };\n}\n"],"mappings":";;;;;AAcA,IAAa,eAAb,cAAkC,MAAM;CACtC;CACA;CAEA,YAAY,QAAwC,YAAoB;EACtE,MAAM,yBAAyB,QAAQ;EACvC,KAAK,OAAO;EACZ,KAAK,SAAS;EACd,KAAK,aAAa;CACpB;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuEA,SAAgB,QACd,WACA,OACA,SACiE;CACjE,OAAO,OAAO,SAAS,UAAyB;EAC9C,MAAM,MAAO,QAAQ,OAAqC;EAC1D,MAAM,SAAS,MAAM,UAAU,GAAG;EAClC,IAAI,CAAC,OAAO,IAAI;GACd,MAAM,SACJ,OAAO,UAAU,mBAAoB,mBAA8B;GACrE,MAAM,gBAAgB,WAAW,mBAAmB,MAAM;GAC1D,MAAM,SAAS,SAAS,SAAS,WAAW;GAC5C,MAAM,UAA0B;IAAE;IAAQ;GAAO;GACjD,IAAI,SAAS,SAAS;IACpB,MAAM,QAAQ,QAAQ,SAAS,SAAS,KAAK;IAC7C;GACF;GACA,MAAM,IAAI,aAAa,QAAQ,MAAM;EACvC;EACA,QAAS,OAAuC,aAAa,OAAO;CACtE;AACF"}

package/dist/hono.d.mts

@@ -0,0 +1,68 @@
+import { i as ParseResult, t as Id } from "./types-g7CiQDyE.mjs";
+import { t as IdParamFailure } from "./adapter-types-oHCCSgOO.mjs";
+import { Context, MiddlewareHandler } from "hono";
+
+//#region src/hono.d.ts
+type IdCodec<Brand extends string> = {
+  safeParse(value: unknown): ParseResult<Brand>;
+};
+/** Options for `idParam`. All fields are optional. */
+type IdParamOptions = {
+  /**
+  * Called instead of throwing when provided. The hook owns the response entirely —
+  * the adapter neither throws nor writes a body.
+  */
+  onError?: (failure: IdParamFailure, c: Context) => Response | Promise<Response>;
+  /**
+  * Remap the default HTTP status for a failure reason without a full handler.
+  * e.g. `{ brand_mismatch: 400 }` treats both failure kinds as 400.
+  */
+  status?: {
+    brand_mismatch?: number;
+    malformed?: number;
+  };
+};
+/**
+* Hono middleware that validates a named route param against a codec via `safeParse`.
+*
+* **Default (no options):** throws `HTTPException(status)` so the app's existing `onError` handler
+* controls rendering and content negotiation. The adapter does not write a response body itself.
+*
+* **`options.onError`:** when provided, the hook owns the response entirely — the adapter neither
+* throws nor writes a response.
+*
+* **`options.status`:** remaps the default HTTP status for a reason without a full handler.
+*
+* - **Brand mismatch (`invalid_prefix`) → `reason: "brand_mismatch"`, default 404**
+* - **Malformed or missing ID → `reason: "malformed"`, default 400**
+*
+* On success, stores the canonical `Id<Brand>` in the Hono context under `paramName`
+* and calls `next()`.
+*
+* @example
+* ```ts
+* import { idParam } from "@smonn/ids/hono";
+* import { createTimestampId } from "@smonn/ids";
+*
+* const usr = createTimestampId("usr");
+*
+* // Default: throws HTTPException → app.onError renders it
+* app.get("/users/:id", idParam("id", usr), (c) => {
+*   const id = c.get("id"); // Id<"usr">, canonical
+* });
+*
+* // Override: consumer fully owns the response
+* app.get("/orgs/:id", idParam("id", org, {
+*   onError: (failure, c) => c.json({ error: failure.reason }, failure.status),
+* }), handler);
+*
+* // Or a lightweight status remap without a full handler
+* app.get("/things/:id", idParam("id", thing, { status: { brand_mismatch: 400 } }), handler);
+* ```
+*/
+declare function idParam<ParamKey extends string, Brand extends string>(paramName: ParamKey, codec: IdCodec<Brand>, options?: IdParamOptions): MiddlewareHandler<{
+  Variables: Record<ParamKey, Id<Brand>>;
+}>;
+//#endregion
+export { type IdParamFailure, IdParamOptions, idParam };
+//# sourceMappingURL=hono.d.mts.map

package/dist/hono.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hono.d.mts","names":[],"sources":["../src/hono.ts"],"mappings":";;;;;KAOK,OAAA;EACH,SAAA,CAAU,KAAA,YAAiB,WAAA,CAAY,KAAA;AAAA;;KAI7B,cAAA;;;;;EAKV,OAAA,IAAW,OAAA,EAAS,cAAA,EAAgB,CAAA,EAAG,OAAA,KAAY,QAAA,GAAW,OAAA,CAAQ,QAAA;EAT/B;AAAA;AAIzC;;EAUE,MAAA;IAAW,cAAA;IAAyB,SAAA;EAAA;AAAA;;;;;;;;;;;;;;;;AAAA;AAyCtC;;;;;;;;;;;;;;;;;;;;;;iBAAgB,OAAA,gDACd,SAAA,EAAW,QAAA,EACX,KAAA,EAAO,OAAA,CAAQ,KAAA,GACf,OAAA,GAAU,cAAA,GACT,iBAAA;EAAoB,SAAA,EAAW,MAAA,CAAO,QAAA,EAAU,EAAA,CAAG,KAAA;AAAA"}

package/dist/hono.mjs

@@ -0,0 +1,63 @@
+import { HTTPException } from "hono/http-exception";
+//#region src/hono.ts
+/**
+* Hono middleware that validates a named route param against a codec via `safeParse`.
+*
+* **Default (no options):** throws `HTTPException(status)` so the app's existing `onError` handler
+* controls rendering and content negotiation. The adapter does not write a response body itself.
+*
+* **`options.onError`:** when provided, the hook owns the response entirely — the adapter neither
+* throws nor writes a response.
+*
+* **`options.status`:** remaps the default HTTP status for a reason without a full handler.
+*
+* - **Brand mismatch (`invalid_prefix`) → `reason: "brand_mismatch"`, default 404**
+* - **Malformed or missing ID → `reason: "malformed"`, default 400**
+*
+* On success, stores the canonical `Id<Brand>` in the Hono context under `paramName`
+* and calls `next()`.
+*
+* @example
+* ```ts
+* import { idParam } from "@smonn/ids/hono";
+* import { createTimestampId } from "@smonn/ids";
+*
+* const usr = createTimestampId("usr");
+*
+* // Default: throws HTTPException → app.onError renders it
+* app.get("/users/:id", idParam("id", usr), (c) => {
+*   const id = c.get("id"); // Id<"usr">, canonical
+* });
+*
+* // Override: consumer fully owns the response
+* app.get("/orgs/:id", idParam("id", org, {
+*   onError: (failure, c) => c.json({ error: failure.reason }, failure.status),
+* }), handler);
+*
+* // Or a lightweight status remap without a full handler
+* app.get("/things/:id", idParam("id", thing, { status: { brand_mismatch: 400 } }), handler);
+* ```
+*/
+function idParam(paramName, codec, options) {
+	return async (c, next) => {
+		const raw = c.req.param(paramName);
+		const result = codec.safeParse(raw);
+		if (!result.ok) {
+			const reason = result.error === "invalid_prefix" ? "brand_mismatch" : "malformed";
+			const defaultStatus = reason === "brand_mismatch" ? 404 : 400;
+			const status = options?.status?.[reason] ?? defaultStatus;
+			const failure = {
+				reason,
+				status
+			};
+			if (options?.onError) return options.onError(failure, c);
+			throw new HTTPException(status);
+		}
+		c.set(paramName, result.id);
+		await next();
+	};
+}
+//#endregion
+export { idParam };
+
+//# sourceMappingURL=hono.mjs.map

package/dist/hono.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"hono.mjs","names":[],"sources":["../src/hono.ts"],"sourcesContent":["import { HTTPException } from \"hono/http-exception\";\nimport type { Context, MiddlewareHandler } from \"hono\";\nimport type { IdParamFailure } from \"./adapter-types.js\";\nimport type { Id, ParseResult } from \"./types.js\";\n\nexport type { IdParamFailure };\n\ntype IdCodec<Brand extends string> = {\n  safeParse(value: unknown): ParseResult<Brand>;\n};\n\n/** Options for `idParam`. All fields are optional. */\nexport type IdParamOptions = {\n  /**\n   * Called instead of throwing when provided. The hook owns the response entirely —\n   * the adapter neither throws nor writes a body.\n   */\n  onError?: (failure: IdParamFailure, c: Context) => Response | Promise<Response>;\n  /**\n   * Remap the default HTTP status for a failure reason without a full handler.\n   * e.g. `{ brand_mismatch: 400 }` treats both failure kinds as 400.\n   */\n  status?: { brand_mismatch?: number; malformed?: number };\n};\n\n/**\n * Hono middleware that validates a named route param against a codec via `safeParse`.\n *\n * **Default (no options):** throws `HTTPException(status)` so the app's existing `onError` handler\n * controls rendering and content negotiation. The adapter does not write a response body itself.\n *\n * **`options.onError`:** when provided, the hook owns the response entirely — the adapter neither\n * throws nor writes a response.\n *\n * **`options.status`:** remaps the default HTTP status for a reason without a full handler.\n *\n * - **Brand mismatch (`invalid_prefix`) → `reason: \"brand_mismatch\"`, default 404**\n * - **Malformed or missing ID → `reason: \"malformed\"`, default 400**\n *\n * On success, stores the canonical `Id<Brand>` in the Hono context under `paramName`\n * and calls `next()`.\n *\n * @example\n * ```ts\n * import { idParam } from \"@smonn/ids/hono\";\n * import { createTimestampId } from \"@smonn/ids\";\n *\n * const usr = createTimestampId(\"usr\");\n *\n * // Default: throws HTTPException → app.onError renders it\n * app.get(\"/users/:id\", idParam(\"id\", usr), (c) => {\n *   const id = c.get(\"id\"); // Id<\"usr\">, canonical\n * });\n *\n * // Override: consumer fully owns the response\n * app.get(\"/orgs/:id\", idParam(\"id\", org, {\n *   onError: (failure, c) => c.json({ error: failure.reason }, failure.status),\n * }), handler);\n *\n * // Or a lightweight status remap without a full handler\n * app.get(\"/things/:id\", idParam(\"id\", thing, { status: { brand_mismatch: 400 } }), handler);\n * ```\n */\nexport function idParam<ParamKey extends string, Brand extends string>(\n  paramName: ParamKey,\n  codec: IdCodec<Brand>,\n  options?: IdParamOptions,\n): MiddlewareHandler<{ Variables: Record<ParamKey, Id<Brand>> }> {\n  return async (c, next) => {\n    const raw = c.req.param(paramName);\n    const result = codec.safeParse(raw);\n    if (!result.ok) {\n      const reason =\n        result.error === \"invalid_prefix\" ? (\"brand_mismatch\" as const) : (\"malformed\" as const);\n      const defaultStatus = reason === \"brand_mismatch\" ? 404 : 400;\n      const status = options?.status?.[reason] ?? defaultStatus;\n      const failure: IdParamFailure = { reason, status };\n      if (options?.onError) {\n        return options.onError(failure, c);\n      }\n      throw new HTTPException(status as ConstructorParameters<typeof HTTPException>[0]);\n    }\n    c.set(paramName, result.id);\n    await next();\n    return;\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+DA,SAAgB,QACd,WACA,OACA,SAC+D;CAC/D,OAAO,OAAO,GAAG,SAAS;EACxB,MAAM,MAAM,EAAE,IAAI,MAAM,SAAS;EACjC,MAAM,SAAS,MAAM,UAAU,GAAG;EAClC,IAAI,CAAC,OAAO,IAAI;GACd,MAAM,SACJ,OAAO,UAAU,mBAAoB,mBAA8B;GACrE,MAAM,gBAAgB,WAAW,mBAAmB,MAAM;GAC1D,MAAM,SAAS,SAAS,SAAS,WAAW;GAC5C,MAAM,UAA0B;IAAE;IAAQ;GAAO;GACjD,IAAI,SAAS,SACX,OAAO,QAAQ,QAAQ,SAAS,CAAC;GAEnC,MAAM,IAAI,cAAc,MAAwD;EAClF;EACA,EAAE,IAAI,WAAW,OAAO,EAAE;EAC1B,MAAM,KAAK;CAEb;AACF"}

package/dist/index.d.mts

@@ -1,3 +1,4 @@
+import { n as IdsErrorCode, r as isIdsError, t as IdsError } from "./error-DTr4i6Ic.mjs";
 import { a as StandardSchemaProps, i as ParseResult, n as JsonSchema, r as ParseError, t as Id } from "./types-g7CiQDyE.mjs";
 
 //#region src/timestamp.d.ts
@@ -51,5 +52,5 @@ type TimestampCodec<Brand extends string> = {
 */
 declare function createTimestampId<Brand extends string>(brand: Brand, opts?: TimestampOptions): TimestampCodec<Brand>;
 //#endregion
-export { type Id, type JsonSchema, type ParseError, type ParseResult, type TimestampCodec, type TimestampOptions, createTimestampId };
+export { type Id, IdsError, type IdsErrorCode, type JsonSchema, type ParseError, type ParseResult, type TimestampCodec, type TimestampOptions, createTimestampId, isIdsError };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/timestamp.ts"],"mappings":";;;;;AASA;KAAY,gBAAA;+EAEV,GAAA;EAEA,GAAA,IAAO,MAAA,EAAQ,UAAA;EAEf,mBAAA;AAAA;;AAAA;AAeF;;;;;;;KAAY,cAAA;uEAEV,QAAA,IAAY,EAAA,CAAG,KAAA;EAEf,UAAA,CAAW,IAAA,EAAM,IAAA,GAAO,EAAA,CAAG,KAAA;;;;;EAK3B,EAAA,CAAG,KAAA,YAAiB,KAAA,IAAS,EAAA,CAAG,KAAA;;;;EAIhC,KAAA,CAAM,KAAA,YAAiB,EAAA,CAAG,KAAA;;;;EAI1B,SAAA,CAAU,KAAA,YAAiB,WAAA,CAAY,KAAA;;;;EAIvC,gBAAA,CAAiB,EAAA,EAAI,EAAA,CAAG,KAAA,IAAS,IAAA;EAEjC,YAAA,CAAa,IAAA,EAAM,IAAA,GAAO,EAAA,CAAG,KAAA;EAE7B,YAAA,CAAa,IAAA,EAAM,IAAA,GAAO,EAAA,CAAG,KAAA;EAE7B,YAAA,IAAgB,UAAA;WAEP,WAAA,EAAa,mBAAA,CAAoB,KAAA;AAAA;;;;;;;iBAiD5B,iBAAA,uBACd,KAAA,EAAO,KAAA,EACP,IAAA,GAAM,gBAAA,GACL,cAAA,CAAe,KAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/timestamp.ts"],"mappings":";;;;;;;KASY,gBAAA;EAAA,6EAEV,GAAA,iBAEe;EAAf,GAAA,IAAO,MAAA,EAAQ,UAAA;EAEf,mBAAA;AAAA;;;AAAA;AAeF;;;;;;KAAY,cAAA;uEAEV,QAAA,IAAY,EAAA,CAAG,KAAA;EAEf,UAAA,CAAW,IAAA,EAAM,IAAA,GAAO,EAAA,CAAG,KAAA;;;;;EAK3B,EAAA,CAAG,KAAA,YAAiB,KAAA,IAAS,EAAA,CAAG,KAAA;;;;EAIhC,KAAA,CAAM,KAAA,YAAiB,EAAA,CAAG,KAAA;;;;EAI1B,SAAA,CAAU,KAAA,YAAiB,WAAA,CAAY,KAAA;;;;EAIvC,gBAAA,CAAiB,EAAA,EAAI,EAAA,CAAG,KAAA,IAAS,IAAA;EAEjC,YAAA,CAAa,IAAA,EAAM,IAAA,GAAO,EAAA,CAAG,KAAA;EAE7B,YAAA,CAAa,IAAA,EAAM,IAAA,GAAO,EAAA,CAAG,KAAA;EAE7B,YAAA,IAAgB,UAAA;WAEP,WAAA,EAAa,mBAAA,CAAoB,KAAA;AAAA;;;;;;;iBAiD5B,iBAAA,uBACd,KAAA,EAAO,KAAA,EACP,IAAA,GAAM,gBAAA,GACL,cAAA,CAAe,KAAA"}

package/dist/index.mjs

@@ -1,2 +1,3 @@
-import { t as createTimestampId } from "./timestamp-Bgzxx8bE.mjs";
-export { createTimestampId };
+import { n as isIdsError, t as IdsError } from "./error-Cp5qYZcv.mjs";
+import { t as createTimestampId } from "./timestamp-B5_UCzc6.mjs";
+export { IdsError, createTimestampId, isIdsError };

package/dist/kysely.d.mts

@@ -0,0 +1,56 @@
+import { n as IdsErrorCode, r as isIdsError, t as IdsError } from "./error-DTr4i6Ic.mjs";
+import { t as Id } from "./types-g7CiQDyE.mjs";
+import { t as IdColumnCodec } from "./drizzle-CeSni5PB.mjs";
+import { ColumnType } from "kysely";
+
+//#region src/kysely.d.ts
+/**
+* Kysely column type mapping for `Id<Brand>`.
+*
+* Use this in your Kysely `Database` interface to type a column as `Id<Brand>` at
+* the TypeScript level. Pair it with `idColumn(codec)` for runtime read/write
+* transformation.
+*
+* @example
+* ```ts
+* import type { IdColumnType } from "@smonn/ids/kysely";
+* import type { Id } from "@smonn/ids";
+*
+* interface Database {
+*   users: { id: IdColumnType<"usr"> };
+* }
+* ```
+*/
+type IdColumnType<Brand extends string> = ColumnType<Id<Brand>, Id<Brand>, Id<Brand>>;
+/**
+* Kysely column adapter bound to a codec.
+*
+* Returns an object with `fromDriver` / `toDriver` helpers that mirror the read/write
+* contract of the Drizzle adapter — same error message, same strictness (safeParse on
+* read, identity on write).
+*
+* **Write path:** passes the `Id<Brand>` directly to the driver — it is already
+* the canonical string form.
+*
+* **Read path:** normalises the raw DB string via `codec.safeParse()`. Throws if
+* the value does not parse as a valid `Id<Brand>`.
+*
+* @example
+* ```ts
+* import { idColumn } from "@smonn/ids/kysely";
+* import { createTimestampId } from "@smonn/ids";
+*
+* const usr = createTimestampId("usr");
+* const usrCol = idColumn(usr);
+*
+* // In a query result handler:
+* const id = usrCol.fromDriver(row.id);
+* ```
+*/
+declare function idColumn<Brand extends string>(codec: IdColumnCodec<Brand>): {
+  toDriver(value: Id<Brand>): string;
+  fromDriver(value: string): Id<Brand>;
+};
+//#endregion
+export { type IdColumnCodec, IdColumnType, IdsError, type IdsErrorCode, idColumn, isIdsError };
+//# sourceMappingURL=kysely.d.mts.map

package/dist/kysely.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kysely.d.mts","names":[],"sources":["../src/kysely.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;KA0BY,YAAA,yBAAqC,UAAA,CAAW,EAAA,CAAG,KAAA,GAAQ,EAAA,CAAG,KAAA,GAAQ,EAAA,CAAG,KAAA;;;AAAA;AA2BrF;;;;;;;;;;;;;;;;;;;;;;iBAAgB,QAAA,uBACd,KAAA,EAAO,aAAA,CAAc,KAAA;EAErB,QAAA,CAAS,KAAA,EAAO,EAAA,CAAG,KAAA;EACnB,UAAA,CAAW,KAAA,WAAgB,EAAA,CAAG,KAAA;AAAA"}

package/dist/kysely.mjs

@@ -0,0 +1,43 @@
+import { n as isIdsError, t as IdsError } from "./error-Cp5qYZcv.mjs";
+//#region src/kysely.ts
+/**
+* Kysely column adapter bound to a codec.
+*
+* Returns an object with `fromDriver` / `toDriver` helpers that mirror the read/write
+* contract of the Drizzle adapter — same error message, same strictness (safeParse on
+* read, identity on write).
+*
+* **Write path:** passes the `Id<Brand>` directly to the driver — it is already
+* the canonical string form.
+*
+* **Read path:** normalises the raw DB string via `codec.safeParse()`. Throws if
+* the value does not parse as a valid `Id<Brand>`.
+*
+* @example
+* ```ts
+* import { idColumn } from "@smonn/ids/kysely";
+* import { createTimestampId } from "@smonn/ids";
+*
+* const usr = createTimestampId("usr");
+* const usrCol = idColumn(usr);
+*
+* // In a query result handler:
+* const id = usrCol.fromDriver(row.id);
+* ```
+*/
+function idColumn(codec) {
+	return {
+		toDriver(value) {
+			return value;
+		},
+		fromDriver(value) {
+			const result = codec.safeParse(value);
+			if (!result.ok) throw new IdsError("invalid_id", `invalid ID from database: ${result.error}`, { cause: result.error });
+			return result.id;
+		}
+	};
+}
+//#endregion
+export { IdsError, idColumn, isIdsError };
+
+//# sourceMappingURL=kysely.mjs.map

package/dist/kysely.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"kysely.mjs","names":[],"sources":["../src/kysely.ts"],"sourcesContent":["import type { ColumnType } from \"kysely\";\nimport { IdsError, isIdsError, type IdsErrorCode } from \"./error.js\";\nimport type { IdColumnCodec } from \"./drizzle.js\";\nimport type { Id } from \"./types.js\";\n\nexport type { IdColumnCodec } from \"./drizzle.js\";\n/** {@link IdsError} class, {@link isIdsError} type guard, and {@link IdsErrorCode} union — re-exported from `\"@smonn/ids\"` for convenience. */\nexport { IdsError, isIdsError, type IdsErrorCode };\n\n/**\n * Kysely column type mapping for `Id<Brand>`.\n *\n * Use this in your Kysely `Database` interface to type a column as `Id<Brand>` at\n * the TypeScript level. Pair it with `idColumn(codec)` for runtime read/write\n * transformation.\n *\n * @example\n * ```ts\n * import type { IdColumnType } from \"@smonn/ids/kysely\";\n * import type { Id } from \"@smonn/ids\";\n *\n * interface Database {\n *   users: { id: IdColumnType<\"usr\"> };\n * }\n * ```\n */\nexport type IdColumnType<Brand extends string> = ColumnType<Id<Brand>, Id<Brand>, Id<Brand>>;\n\n/**\n * Kysely column adapter bound to a codec.\n *\n * Returns an object with `fromDriver` / `toDriver` helpers that mirror the read/write\n * contract of the Drizzle adapter — same error message, same strictness (safeParse on\n * read, identity on write).\n *\n * **Write path:** passes the `Id<Brand>` directly to the driver — it is already\n * the canonical string form.\n *\n * **Read path:** normalises the raw DB string via `codec.safeParse()`. Throws if\n * the value does not parse as a valid `Id<Brand>`.\n *\n * @example\n * ```ts\n * import { idColumn } from \"@smonn/ids/kysely\";\n * import { createTimestampId } from \"@smonn/ids\";\n *\n * const usr = createTimestampId(\"usr\");\n * const usrCol = idColumn(usr);\n *\n * // In a query result handler:\n * const id = usrCol.fromDriver(row.id);\n * ```\n */\nexport function idColumn<Brand extends string>(\n  codec: IdColumnCodec<Brand>,\n): {\n  toDriver(value: Id<Brand>): string;\n  fromDriver(value: string): Id<Brand>;\n} {\n  return {\n    toDriver(value: Id<Brand>): string {\n      return value;\n    },\n    fromDriver(value: string): Id<Brand> {\n      const result = codec.safeParse(value);\n      if (!result.ok) {\n        throw new IdsError(\"invalid_id\", `invalid ID from database: ${result.error}`, {\n          cause: result.error,\n        });\n      }\n      return result.id;\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AAqDA,SAAgB,SACd,OAIA;CACA,OAAO;EACL,SAAS,OAA0B;GACjC,OAAO;EACT;EACA,WAAW,OAA0B;GACnC,MAAM,SAAS,MAAM,UAAU,KAAK;GACpC,IAAI,CAAC,OAAO,IACV,MAAM,IAAI,SAAS,cAAc,6BAA6B,OAAO,SAAS,EAC5E,OAAO,OAAO,MAChB,CAAC;GAEH,OAAO,OAAO;EAChB;CACF;AACF"}

package/dist/{opaque-B4ps7Pqk.mjs → opaque-uvjOFY_0.mjs}

@@ -1,5 +1,6 @@
-import { a as toWireId, i as payloadBytesFromId, n as registerBrand, r as payloadBase32Length, s as validateBrand, t as wireMethods } from "./codec-shell-dWpxoFmy.mjs";
-import { r as writeTimestamp, t as readTimestampMs } from "./timestamp-bytes-B57RM7Ho.mjs";
+import { t as IdsError } from "./error-Cp5qYZcv.mjs";
+import { a as toWireId, i as payloadBytesFromId, n as registerBrand, r as payloadBase32Length, s as validateBrand, t as wireMethods } from "./codec-shell-DH-UO4UR.mjs";
+import { r as writeTimestamp, t as readTimestampMs } from "./timestamp-bytes-BBY7JI33.mjs";
 import { i as encodeHex, n as decodeHex, r as encodeBase64Url, t as decodeBase64Url } from "./bytes-lhzKVaBV.mjs";
 //#region src/layouts/opaque.ts
 const zeroIv = new Uint8Array(16);
@@ -59,6 +60,29 @@ const validAesKeyByteLengths = new Set([
 	24,
 	32
 ]);
+const opaqueKeyInternals = /* @__PURE__ */ new WeakMap();
+/**
+* Imports raw AES key bytes into an {@link OpaqueKey} handle for the Opaque
+* Timestamp codec.
+*
+* Accepts 16, 24, or 32 bytes (AES-128 / AES-192 / AES-256 strength).
+* To store or transport key material, use {@link encodeOpaqueKey} /
+* {@link decodeOpaqueKey} (`"hex"` or `"base64url"` — not Crockford base32).
+*
+* @param bytes - 16, 24, or 32 raw key bytes.
+*/
+async function importOpaqueKey(bytes) {
+	assertValidAesKeyByteLength(bytes.length);
+	const cryptoKey = await crypto.subtle.importKey("raw", bytes, "AES-CBC", false, ["encrypt", "decrypt"]);
+	const key = Object.freeze({});
+	opaqueKeyInternals.set(key, cryptoKey);
+	return key;
+}
+function getOpaqueKeyCryptoKey(key) {
+	const cryptoKey = opaqueKeyInternals.get(key);
+	if (cryptoKey === void 0) throw new Error("invalid opaque key");
+	return cryptoKey;
+}
 /**
 * Encodes raw AES key bytes for storage in env vars or secret managers.
 *
@@ -81,22 +105,22 @@ function decodeOpaqueKey(encoded, format) {
 	assertOpaqueKeyFormat(format);
 	let bytes;
 	if (format === "hex") {
-		if (encoded.length === 0 || encoded.length % 2 !== 0) throw new Error("invalid hex key: length must be a positive even number of characters");
-		if (!/^[0-9a-fA-F]+$/.test(encoded)) throw new Error("invalid hex key: expected [0-9a-fA-F] only");
+		if (encoded.length === 0 || encoded.length % 2 !== 0) throw new IdsError("invalid_key_encoding", "invalid hex key: length must be a positive even number of characters");
+		if (!/^[0-9a-fA-F]+$/.test(encoded)) throw new IdsError("invalid_key_encoding", "invalid hex key: expected [0-9a-fA-F] only");
 		bytes = decodeHex(encoded);
 	} else try {
 		bytes = decodeBase64Url(encoded);
 	} catch {
-		throw new Error("invalid base64url key");
+		throw new IdsError("invalid_key_encoding", "invalid base64url key");
 	}
 	assertValidAesKeyByteLength(bytes.length);
 	return bytes;
 }
 function assertValidAesKeyByteLength(byteLength) {
-	if (!validAesKeyByteLengths.has(byteLength)) throw new Error(`invalid AES key length: expected 16, 24, or 32 bytes, got ${byteLength}`);
+	if (!validAesKeyByteLengths.has(byteLength)) throw new IdsError("invalid_key_length", `invalid AES key length: expected 16, 24, or 32 bytes, got ${byteLength}`);
 }
 function assertOpaqueKeyFormat(format) {
-	if (format !== "hex" && format !== "base64url") throw new Error(`invalid opaque key format: expected hex or base64url, got '${formatForError(format)}'`);
+	if (format !== "hex" && format !== "base64url") throw new IdsError("invalid_key_format", `invalid opaque key format: expected hex or base64url, got '${formatForError(format)}'`);
 }
 function formatForError(value) {
 	try {
@@ -111,28 +135,21 @@ function defaultRng(target) {
 	crypto.getRandomValues(target);
 }
 /**
-* Imports a raw AES key for use with the Opaque Timestamp codec.
-*
-* @param bytes - Raw key bytes (16, 24, or 32 bytes for AES-128/192/256).
-*/
-function importOpaqueKey(bytes) {
-	return crypto.subtle.importKey("raw", bytes, "AES-CBC", false, ["encrypt", "decrypt"]);
-}
-/**
 * Creates an Opaque Timestamp codec for `brand` (three lowercase a–z characters).
 *
 * @param brand - Entity type brand validated once at construction.
-* @param opts - Required `key` plus optional `now`, `rng`, and `allowDuplicateBrand` overrides.
+* @param opts - Required `key` (an {@link OpaqueKey} from {@link importOpaqueKey}) plus
+*   optional `now`, `rng`, and `allowDuplicateBrand` overrides.
 */
 function createOpaqueTimestampId(brand, opts) {
 	validateBrand(brand);
 	registerBrand(brand, opts.allowDuplicateBrand);
-	const key = opts.key;
+	const cryptoKey = getOpaqueKeyCryptoKey(opts.key);
 	const now = opts.now ?? Date.now;
 	const rng = opts.rng ?? defaultRng;
 	const prefix = `${brand}_`;
 	const wire = wireMethods(prefix);
-	const layout = createOpaqueLayoutOps(prefix, key, rng);
+	const layout = createOpaqueLayoutOps(prefix, cryptoKey, rng);
 	return {
 		generate: () => layout.generateAt(now()),
 		generateAt: (date) => layout.generateAt(date.getTime()),
@@ -145,6 +162,6 @@ function createOpaqueTimestampId(brand, opts) {
 	};
 }
 //#endregion
-export { encodeOpaqueKey as i, importOpaqueKey as n, decodeOpaqueKey as r, createOpaqueTimestampId as t };
+export { importOpaqueKey as i, decodeOpaqueKey as n, encodeOpaqueKey as r, createOpaqueTimestampId as t };
 
-//# sourceMappingURL=opaque-B4ps7Pqk.mjs.map
+//# sourceMappingURL=opaque-uvjOFY_0.mjs.map

package/dist/opaque-uvjOFY_0.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"opaque-uvjOFY_0.mjs","names":[],"sources":["../src/layouts/opaque.ts","../src/opaque-key.ts","../src/opaque.ts"],"sourcesContent":["import type { Id, Prefix } from \"../types.js\";\nimport { payloadBytesFromId, toWireId } from \"../wire/envelope.js\";\nimport { payloadBase32Length, payloadByteLength } from \"../wire/invariants.js\";\nimport { readTimestampMs, timestampByteLength, writeTimestamp } from \"../wire/timestamp-bytes.js\";\n\nconst zeroIv = new Uint8Array(payloadByteLength);\nconst pkcsPad = 0x10;\n\nfunction buildPlaintext(ms: number, rng: (target: Uint8Array) => void): Uint8Array {\n  const plaintext = new Uint8Array(payloadByteLength);\n  writeTimestamp(ms, plaintext);\n  rng(plaintext.subarray(timestampByteLength, payloadByteLength));\n  return plaintext;\n}\n\nasync function encryptPayload(key: CryptoKey, plaintext: Uint8Array): Promise<Uint8Array> {\n  const encrypted = new Uint8Array(\n    await crypto.subtle.encrypt(\n      { name: \"AES-CBC\", iv: zeroIv },\n      key,\n      plaintext as Uint8Array<ArrayBuffer>,\n    ),\n  );\n  return encrypted.subarray(0, payloadByteLength);\n}\n\n// AES-CBC strip-and-reconstruct decrypt (ADR-0004). The wire carries only C1\n// (16 bytes); C2 = AES_K(P2 XOR C1) where P2 is the PKCS#7 pad block (0x10×16).\n// Recompute C2 via CBC encrypt of (P2 XOR C1) with IV=0, then decrypt C1‖C2.\nasync function decryptPayload(key: CryptoKey, c1: Uint8Array): Promise<Uint8Array> {\n  const c2Input = new Uint8Array(payloadByteLength);\n  for (let i = 0; i < payloadByteLength; i++) c2Input[i] = pkcsPad ^ c1[i]!;\n  const c2Encrypted = new Uint8Array(\n    await crypto.subtle.encrypt(\n      { name: \"AES-CBC\", iv: zeroIv },\n      key,\n      c2Input as Uint8Array<ArrayBuffer>,\n    ),\n  );\n  const ciphertext = new Uint8Array(payloadByteLength * 2);\n  ciphertext.set(c1, 0);\n  ciphertext.set(c2Encrypted.subarray(0, payloadByteLength), payloadByteLength);\n  return new Uint8Array(\n    await crypto.subtle.decrypt(\n      { name: \"AES-CBC\", iv: zeroIv },\n      key,\n      ciphertext as Uint8Array<ArrayBuffer>,\n    ),\n  );\n}\n\nasync function extractTimestampFromId<Brand extends string>(\n  prefix: Prefix<Brand>,\n  key: CryptoKey,\n  id: Id<Brand>,\n): Promise<Date> {\n  const plaintext = await decryptPayload(key, payloadBytesFromId(prefix, id));\n  return new Date(readTimestampMs(plaintext));\n}\n\n/** Produces a canonical encrypted wire ID. Per-call plaintext/ciphertext buffers —\n * subtle dominates this path; reuse would be safe but not worth pinning to spec detail. */\nasync function generateWireId<Brand extends string>(\n  prefix: Prefix<Brand>,\n  key: CryptoKey,\n  rng: (target: Uint8Array) => void,\n  ms: number,\n): Promise<Id<Brand>> {\n  const plaintext = buildPlaintext(ms, rng);\n  const encrypted = await encryptPayload(key, plaintext);\n  return toWireId(prefix, encrypted);\n}\n\n/** Structural placeholder for JSON Schema (encrypt is async). */\nfunction schemaExample<Brand extends string>(prefix: Prefix<Brand>): string {\n  return prefix + \"0\".repeat(payloadBase32Length);\n}\n\n/** Layout ops binder for the Opaque Timestamp variant. `extractTimestampFromId` is module-private; the binder exposes `extractTimestamp` for the codec constructor. */\nexport function createOpaqueLayoutOps<Brand extends string>(\n  prefix: Prefix<Brand>,\n  key: CryptoKey,\n  rng: (target: Uint8Array) => void,\n) {\n  return {\n    generateAt: (ms: number): Promise<Id<Brand>> => generateWireId(prefix, key, rng, ms),\n    extractTimestamp: (id: Id<Brand>): Promise<Date> => extractTimestampFromId(prefix, key, id),\n    exampleWireId: (): Id<Brand> => schemaExample(prefix) as Id<Brand>,\n  };\n}\n","import { decodeBase64Url, decodeHex, encodeBase64Url, encodeHex } from \"./bytes.js\";\nimport { IdsError } from \"./error.js\";\n\n/** Wire encoding for opaque AES key material (not Crockford base32). */\nexport type OpaqueKeyFormat = \"hex\" | \"base64url\";\n\nconst validAesKeyByteLengths = new Set([16, 24, 32]);\n\ndeclare const opaqueKeyBrand: unique symbol;\n\n/**\n * Opaque imported handle for one AES key used by the Opaque Timestamp codec.\n *\n * Holds the underlying `CryptoKey` internally; callers never access it directly.\n * Obtain handles via {@link importOpaqueKey} and pass them to\n * `createOpaqueTimestampId` as the `key` option.\n *\n * Distinct from the `WrappingKey` used by `@smonn/ids/wrapped` — one raw\n * secret must not silently serve both codecs without an explicit import.\n */\nexport type OpaqueKey = {\n  readonly [opaqueKeyBrand]: \"OpaqueKey\";\n};\n\nconst opaqueKeyInternals = new WeakMap<OpaqueKey, CryptoKey>();\n\n/**\n * Imports raw AES key bytes into an {@link OpaqueKey} handle for the Opaque\n * Timestamp codec.\n *\n * Accepts 16, 24, or 32 bytes (AES-128 / AES-192 / AES-256 strength).\n * To store or transport key material, use {@link encodeOpaqueKey} /\n * {@link decodeOpaqueKey} (`\"hex\"` or `\"base64url\"` — not Crockford base32).\n *\n * @param bytes - 16, 24, or 32 raw key bytes.\n */\nexport async function importOpaqueKey(bytes: Uint8Array): Promise<OpaqueKey> {\n  assertValidAesKeyByteLength(bytes.length);\n  const cryptoKey = await crypto.subtle.importKey(\n    \"raw\",\n    bytes as Uint8Array<ArrayBuffer>,\n    \"AES-CBC\",\n    false,\n    [\"encrypt\", \"decrypt\"],\n  );\n  const key = Object.freeze({}) as OpaqueKey;\n  opaqueKeyInternals.set(key, cryptoKey);\n  return key;\n}\n\nexport function getOpaqueKeyCryptoKey(key: OpaqueKey): CryptoKey {\n  const cryptoKey = opaqueKeyInternals.get(key);\n  if (cryptoKey === undefined) {\n    throw new Error(\"invalid opaque key\");\n  }\n  return cryptoKey;\n}\n\n/**\n * Encodes raw AES key bytes for storage in env vars or secret managers.\n *\n * @param bytes - 16, 24, or 32 raw key bytes (AES-128/192/256).\n * @param format - `hex` (lowercase) or `base64url`.\n */\nexport function encodeOpaqueKey(bytes: Uint8Array, format: OpaqueKeyFormat): string {\n  assertOpaqueKeyFormat(format);\n  assertValidAesKeyByteLength(bytes.length);\n  if (format === \"hex\") return encodeHex(bytes);\n  return encodeBase64Url(bytes);\n}\n\n/**\n * Decodes key material emitted by `encodeOpaqueKey` (or `ids keygen`) back to raw bytes.\n *\n * @param encoded - Hex or base64url string.\n * @param format - Must match how the string was encoded.\n */\nexport function decodeOpaqueKey(encoded: string, format: OpaqueKeyFormat): Uint8Array {\n  assertOpaqueKeyFormat(format);\n  let bytes: Uint8Array;\n  if (format === \"hex\") {\n    if (encoded.length === 0 || encoded.length % 2 !== 0) {\n      throw new IdsError(\n        \"invalid_key_encoding\",\n        \"invalid hex key: length must be a positive even number of characters\",\n      );\n    }\n    if (!/^[0-9a-fA-F]+$/.test(encoded)) {\n      throw new IdsError(\"invalid_key_encoding\", \"invalid hex key: expected [0-9a-fA-F] only\");\n    }\n    bytes = decodeHex(encoded);\n  } else {\n    try {\n      bytes = decodeBase64Url(encoded);\n    } catch {\n      throw new IdsError(\"invalid_key_encoding\", \"invalid base64url key\");\n    }\n  }\n  assertValidAesKeyByteLength(bytes.length);\n  return bytes;\n}\n\nfunction assertValidAesKeyByteLength(byteLength: number): void {\n  if (!validAesKeyByteLengths.has(byteLength)) {\n    throw new IdsError(\n      \"invalid_key_length\",\n      `invalid AES key length: expected 16, 24, or 32 bytes, got ${byteLength}`,\n    );\n  }\n}\n\nfunction assertOpaqueKeyFormat(format: unknown): asserts format is OpaqueKeyFormat {\n  if (format !== \"hex\" && format !== \"base64url\") {\n    throw new IdsError(\n      \"invalid_key_format\",\n      `invalid opaque key format: expected hex or base64url, got '${formatForError(format)}'`,\n    );\n  }\n}\n\nfunction formatForError(value: unknown): string {\n  try {\n    return String(value);\n  } catch {\n    return \"[unprintable]\";\n  }\n}\n","import { validateBrand } from \"./brand.js\";\nimport { createOpaqueLayoutOps } from \"./layouts/opaque.js\";\nimport { getOpaqueKeyCryptoKey, type OpaqueKey } from \"./opaque-key.js\";\nimport { registerBrand } from \"./registry.js\";\nimport type { Id, JsonSchema, ParseResult, Prefix, StandardSchemaProps } from \"./types.js\";\nimport { wireMethods } from \"./wire/codec-shell.js\";\n\n/** {@link IdsError} class, {@link isIdsError} type guard, and {@link IdsErrorCode} union — re-exported from `\"@smonn/ids\"` for convenience. */\nexport { IdsError, isIdsError, type IdsErrorCode } from \"./error.js\";\nexport {\n  decodeOpaqueKey,\n  encodeOpaqueKey,\n  importOpaqueKey,\n  type OpaqueKey,\n  type OpaqueKeyFormat,\n} from \"./opaque-key.js\";\n\n/**\n * Configuration options for an Opaque Timestamp codec instance.\n */\nexport type OpaqueTimestampOptions = {\n  /**\n   * {@link OpaqueKey} handle for AES-CBC encryption and decryption.\n   * Obtain via {@link importOpaqueKey}.\n   */\n  key: OpaqueKey;\n  /** Returns the current timestamp in milliseconds. Defaults to `Date.now`. */\n  now?: () => number;\n  /** Writes random bytes into `target` for ID generation. Defaults to `crypto.getRandomValues`. */\n  rng?: (target: Uint8Array) => void;\n  /** If true, silences the duplicate-brand warning in non-production environments. */\n  allowDuplicateBrand?: boolean;\n};\n\n/**\n * A brand-scoped codec for generating and validating Opaque Timestamp IDs.\n *\n * Same wire shape as the Timestamp codec (`{brand}_` + 26 base32 chars) but the\n * payload is AES-CBC encrypted. `generate`, `generateAt`, and `extractTimestamp`\n * are async; parsing methods are sync. No `minIdForTime` / `maxIdForTime` —\n * encrypted payloads do not sort by creation time.\n */\nexport type OpaqueTimestampCodec<Brand extends string> = {\n  /** Produces a new canonical encrypted ID using the codec's `now` and `rng`. */\n  generate(): Promise<Id<Brand>>;\n  /** Produces a new canonical encrypted ID with timestamp bytes from `date`. Throws on invalid dates. */\n  generateAt(date: Date): Promise<Id<Brand>>;\n  /**\n   * Strict type guard: `true` only for already-canonical strings for this brand.\n   * For untrusted input, use `safeParse()` or `parse()` instead. See ADR-0003.\n   */\n  is(value: unknown): value is Id<Brand>;\n  /**\n   * Lenient parse: normalises case and Crockford aliases, returns canonical `Id<Brand>`, or throws.\n   */\n  parse(value: unknown): Id<Brand>;\n  /**\n   * Lenient parse without throwing: normalises to canonical form, or returns `{ ok: false, error }`.\n   */\n  safeParse(value: unknown): ParseResult<Brand>;\n  /**\n   * Decrypts and decodes the creation `Date` from an `Id<Brand>`. Trusts the type — use `safeParse()` at boundaries first. See ADR-0002.\n   */\n  extractTimestamp(id: Id<Brand>): Promise<Date>;\n  /** JSON Schema for the canonical wire form (`example` is a structural placeholder). */\n  toJsonSchema(): JsonSchema;\n  /** Standard Schema validate entry point. */\n  readonly \"~standard\": StandardSchemaProps<Brand>;\n};\n\nfunction defaultRng(target: Uint8Array): void {\n  crypto.getRandomValues(target as Uint8Array<ArrayBuffer>);\n}\n\n/**\n * Creates an Opaque Timestamp codec for `brand` (three lowercase a–z characters).\n *\n * @param brand - Entity type brand validated once at construction.\n * @param opts - Required `key` (an {@link OpaqueKey} from {@link importOpaqueKey}) plus\n *   optional `now`, `rng`, and `allowDuplicateBrand` overrides.\n */\nexport function createOpaqueTimestampId<Brand extends string>(\n  brand: Brand,\n  opts: OpaqueTimestampOptions,\n): OpaqueTimestampCodec<Brand> {\n  validateBrand(brand);\n  registerBrand(brand, opts.allowDuplicateBrand);\n\n  const cryptoKey = getOpaqueKeyCryptoKey(opts.key);\n  const now = opts.now ?? Date.now;\n  const rng = opts.rng ?? defaultRng;\n  const prefix: Prefix<Brand> = `${brand}_`;\n  const wire = wireMethods(prefix);\n  const layout = createOpaqueLayoutOps(prefix, cryptoKey, rng);\n\n  return {\n    generate: () => layout.generateAt(now()),\n    generateAt: (date: Date) => layout.generateAt(date.getTime()),\n    is: wire.is,\n    parse: wire.parse,\n    safeParse: wire.safeParse,\n    extractTimestamp: layout.extractTimestamp,\n    toJsonSchema: () => wire.toJsonSchema(brand, layout.exampleWireId()),\n    \"~standard\": wire[\"~standard\"],\n  };\n}\n"],"mappings":"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"}

package/dist/opaque.d.mts

@@ -1,8 +1,34 @@
+import { n as IdsErrorCode, r as isIdsError, t as IdsError } from "./error-DTr4i6Ic.mjs";
 import { a as StandardSchemaProps, i as ParseResult, n as JsonSchema, t as Id } from "./types-g7CiQDyE.mjs";
 
 //#region src/opaque-key.d.ts
 /** Wire encoding for opaque AES key material (not Crockford base32). */
 type OpaqueKeyFormat = "hex" | "base64url";
+declare const opaqueKeyBrand: unique symbol;
+/**
+* Opaque imported handle for one AES key used by the Opaque Timestamp codec.
+*
+* Holds the underlying `CryptoKey` internally; callers never access it directly.
+* Obtain handles via {@link importOpaqueKey} and pass them to
+* `createOpaqueTimestampId` as the `key` option.
+*
+* Distinct from the `WrappingKey` used by `@smonn/ids/wrapped` — one raw
+* secret must not silently serve both codecs without an explicit import.
+*/
+type OpaqueKey = {
+  readonly [opaqueKeyBrand]: "OpaqueKey";
+};
+/**
+* Imports raw AES key bytes into an {@link OpaqueKey} handle for the Opaque
+* Timestamp codec.
+*
+* Accepts 16, 24, or 32 bytes (AES-128 / AES-192 / AES-256 strength).
+* To store or transport key material, use {@link encodeOpaqueKey} /
+* {@link decodeOpaqueKey} (`"hex"` or `"base64url"` — not Crockford base32).
+*
+* @param bytes - 16, 24, or 32 raw key bytes.
+*/
+declare function importOpaqueKey(bytes: Uint8Array): Promise<OpaqueKey>;
 /**
 * Encodes raw AES key bytes for storage in env vars or secret managers.
 *
@@ -23,7 +49,11 @@ declare function decodeOpaqueKey(encoded: string, format: OpaqueKeyFormat): Uint
 * Configuration options for an Opaque Timestamp codec instance.
 */
 type OpaqueTimestampOptions = {
-  /** AES-CBC key used for encryption and decryption. */key: CryptoKey; /** Returns the current timestamp in milliseconds. Defaults to `Date.now`. */
+  /**
+  * {@link OpaqueKey} handle for AES-CBC encryption and decryption.
+  * Obtain via {@link importOpaqueKey}.
+  */
+  key: OpaqueKey; /** Returns the current timestamp in milliseconds. Defaults to `Date.now`. */
   now?: () => number; /** Writes random bytes into `target` for ID generation. Defaults to `crypto.getRandomValues`. */
   rng?: (target: Uint8Array) => void; /** If true, silences the duplicate-brand warning in non-production environments. */
   allowDuplicateBrand?: boolean;
@@ -60,18 +90,13 @@ type OpaqueTimestampCodec<Brand extends string> = {
   readonly "~standard": StandardSchemaProps<Brand>;
 };
 /**
-* Imports a raw AES key for use with the Opaque Timestamp codec.
-*
-* @param bytes - Raw key bytes (16, 24, or 32 bytes for AES-128/192/256).
-*/
-declare function importOpaqueKey(bytes: Uint8Array): Promise<CryptoKey>;
-/**
 * Creates an Opaque Timestamp codec for `brand` (three lowercase a–z characters).
 *
 * @param brand - Entity type brand validated once at construction.
-* @param opts - Required `key` plus optional `now`, `rng`, and `allowDuplicateBrand` overrides.
+* @param opts - Required `key` (an {@link OpaqueKey} from {@link importOpaqueKey}) plus
+*   optional `now`, `rng`, and `allowDuplicateBrand` overrides.
 */
 declare function createOpaqueTimestampId<Brand extends string>(brand: Brand, opts: OpaqueTimestampOptions): OpaqueTimestampCodec<Brand>;
 //#endregion
-export { type OpaqueKeyFormat, OpaqueTimestampCodec, OpaqueTimestampOptions, createOpaqueTimestampId, decodeOpaqueKey, encodeOpaqueKey, importOpaqueKey };
+export { IdsError, type IdsErrorCode, type OpaqueKey, type OpaqueKeyFormat, OpaqueTimestampCodec, OpaqueTimestampOptions, createOpaqueTimestampId, decodeOpaqueKey, encodeOpaqueKey, importOpaqueKey, isIdsError };
 //# sourceMappingURL=opaque.d.mts.map

package/dist/opaque.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"opaque.d.mts","names":[],"sources":["../src/opaque-key.ts","../src/opaque.ts"],"mappings":";;;;KAGY,eAAA;;AAAZ;;;;AAAY;iBAUI,eAAA,CAAgB,KAAA,EAAO,UAAA,EAAY,MAAA,EAAQ,eAAA;;;;;;;iBAa3C,eAAA,CAAgB,OAAA,UAAiB,MAAA,EAAQ,eAAA,GAAkB,UAAA;;;;AAvB3E;;KCQY,sBAAA;EDRA,sDCUV,GAAA,EAAK,SAAA,EDAP;ECEE,GAAA;EAEA,GAAA,IAAO,MAAA,EAAQ,UAAA;EAEf,mBAAA;AAAA;;;ADNyD;AAa3D;;;;;KCIY,oBAAA;iFAEV,QAAA,IAAY,OAAA,CAAQ,EAAA,CAAG,KAAA,IDNkD;ECQzE,UAAA,CAAW,IAAA,EAAM,IAAA,GAAO,OAAA,CAAQ,EAAA,CAAG,KAAA;;;;AAvBrC;EA4BE,EAAA,CAAG,KAAA,YAAiB,KAAA,IAAS,EAAA,CAAG,KAAA;;;;EAIhC,KAAA,CAAM,KAAA,YAAiB,EAAA,CAAG,KAAA;;;;EAI1B,SAAA,CAAU,KAAA,YAAiB,WAAA,CAAY,KAAA;;;AA5BvC;EAgCA,gBAAA,CAAiB,EAAA,EAAI,EAAA,CAAG,KAAA,IAAS,OAAA,CAAQ,IAAA,GArB/B;EAuBV,YAAA,IAAgB,UAAA;WAEP,WAAA,EAAa,mBAAA,CAAoB,KAAA;AAAA;;;;;;iBAY5B,eAAA,CAAgB,KAAA,EAAO,UAAA,GAAa,OAAA,CAAQ,SAAA;;;;;;;iBAa5C,uBAAA,uBACd,KAAA,EAAO,KAAA,EACP,IAAA,EAAM,sBAAA,GACL,oBAAA,CAAqB,KAAA"}
+{"version":3,"file":"opaque.d.mts","names":[],"sources":["../src/opaque-key.ts","../src/opaque.ts"],"mappings":";;;;;KAIY,eAAA;AAAA,cAIE,cAAA;;AAJd;;;;AAAY;AAA0B;;;;KAgB1B,SAAA;EAAA,UACA,cAAA;AAAA;;;AAAA;AAeZ;;;;;;;iBAAsB,eAAA,CAAgB,KAAA,EAAO,UAAA,GAAa,OAAA,CAAQ,SAAA;;;;;AAAA;AA4BlE;iBAAgB,eAAA,CAAgB,KAAA,EAAO,UAAA,EAAY,MAAA,EAAQ,eAAA;;;;;;;iBAa3C,eAAA,CAAgB,OAAA,UAAiB,MAAA,EAAQ,eAAA,GAAkB,UAAA;;;;;;KCzD/D,sBAAA;EDhB0B;;;;ECqBpC,GAAA,EAAK,SAAA,EDLP;ECOE,GAAA;EAEA,GAAA,IAAO,MAAA,EAAQ,UAAA,WDRL;ECUV,mBAAA;AAAA;;;;;;;;;KAWU,oBAAA;iFAEV,QAAA,IAAY,OAAA,CAAQ,EAAA,CAAG,KAAA,IDRyC;ECUhE,UAAA,CAAW,IAAA,EAAM,IAAA,GAAO,OAAA,CAAQ,EAAA,CAAG,KAAA;EDkBrB;;;;ECbd,EAAA,CAAG,KAAA,YAAiB,KAAA,IAAS,EAAA,CAAG,KAAA;;;;EAIhC,KAAA,CAAM,KAAA,YAAiB,EAAA,CAAG,KAAA;EDsB5B;;;EClBE,SAAA,CAAU,KAAA,YAAiB,WAAA,CAAY,KAAA;;;;EAIvC,gBAAA,CAAiB,EAAA,EAAI,EAAA,CAAG,KAAA,IAAS,OAAA,CAAQ,IAAA,GDcgC;ECZzE,YAAA,IAAgB,UAAA;WAEP,WAAA,EAAa,mBAAA,CAAoB,KAAA;AAAA;AA/C5C;;;;;;;AAAA,iBA6DgB,uBAAA,uBACd,KAAA,EAAO,KAAA,EACP,IAAA,EAAM,sBAAA,GACL,oBAAA,CAAqB,KAAA"}

package/dist/opaque.mjs

@@ -1,2 +1,3 @@
-import { i as encodeOpaqueKey, n as importOpaqueKey, r as decodeOpaqueKey, t as createOpaqueTimestampId } from "./opaque-B4ps7Pqk.mjs";
-export { createOpaqueTimestampId, decodeOpaqueKey, encodeOpaqueKey, importOpaqueKey };
+import { n as isIdsError, t as IdsError } from "./error-Cp5qYZcv.mjs";
+import { i as importOpaqueKey, n as decodeOpaqueKey, r as encodeOpaqueKey, t as createOpaqueTimestampId } from "./opaque-uvjOFY_0.mjs";
+export { IdsError, createOpaqueTimestampId, decodeOpaqueKey, encodeOpaqueKey, importOpaqueKey, isIdsError };