@classytic/arc 1.1.0 → 2.1.2

package/dist/fields-DyaDVX4J.d.mts

@@ -0,0 +1,110 @@
+//#region src/permissions/fields.d.ts
+/**
+ * Field-Level Permissions
+ *
+ * Control field visibility and writability per role.
+ * Integrated into the response path (read) and sanitization path (write).
+ *
+ * @example
+ * ```typescript
+ * import { fields, defineResource } from '@classytic/arc';
+ *
+ * const userResource = defineResource({
+ *   name: 'user',
+ *   adapter: userAdapter,
+ *   fields: {
+ *     salary: fields.visibleTo(['admin', 'hr']),
+ *     internalNotes: fields.writableBy(['admin']),
+ *     email: fields.redactFor(['viewer']),
+ *     password: fields.hidden(),
+ *   },
+ * });
+ * ```
+ */
+type FieldPermissionType = 'hidden' | 'visibleTo' | 'writableBy' | 'redactFor';
+interface FieldPermission {
+  readonly _type: FieldPermissionType;
+  readonly roles?: readonly string[];
+  readonly redactValue?: unknown;
+}
+type FieldPermissionMap = Record<string, FieldPermission>;
+declare const fields: {
+  /**
+   * Field is never included in responses. Not writable via API.
+   *
+   * @example
+   * ```typescript
+   * fields: { password: fields.hidden() }
+   * ```
+   */
+  hidden(): FieldPermission;
+  /**
+   * Field is only visible to users with specified roles.
+   * Other users don't see the field at all.
+   *
+   * @example
+   * ```typescript
+   * fields: { salary: fields.visibleTo(['admin', 'hr']) }
+   * ```
+   */
+  visibleTo(roles: readonly string[]): FieldPermission;
+  /**
+   * Field is only writable by users with specified roles.
+   * All users can still read the field. Users without the role
+   * have the field silently stripped from write operations.
+   *
+   * @example
+   * ```typescript
+   * fields: { role: fields.writableBy(['admin']) }
+   * ```
+   */
+  writableBy(roles: readonly string[]): FieldPermission;
+  /**
+   * Field is redacted (replaced with a placeholder) for specified roles.
+   * Other users see the real value.
+   *
+   * @param roles - Roles that see the redacted value
+   * @param redactValue - Replacement value (default: '***')
+   *
+   * @example
+   * ```typescript
+   * fields: {
+   *   email: fields.redactFor(['viewer']),
+   *   ssn: fields.redactFor(['basic'], '***-**-****'),
+   * }
+   * ```
+   */
+  redactFor(roles: readonly string[], redactValue?: unknown): FieldPermission;
+};
+/**
+ * Apply field-level READ permissions to a response object.
+ * Strips hidden fields, enforces visibility, and applies redaction.
+ *
+ * @param data - The response object (mutated in place for performance)
+ * @param fieldPermissions - Field permission map from resource config
+ * @param userRoles - Current user's roles (empty array for unauthenticated)
+ * @returns The filtered object
+ */
+declare function applyFieldReadPermissions<T extends Record<string, unknown>>(data: T, fieldPermissions: FieldPermissionMap, userRoles: readonly string[]): T;
+/**
+ * Apply field-level WRITE permissions to request body.
+ * Strips fields that the user doesn't have permission to write.
+ *
+ * @param body - The request body (returns a new filtered copy)
+ * @param fieldPermissions - Field permission map from resource config
+ * @param userRoles - Current user's roles
+ * @returns Filtered body
+ */
+declare function applyFieldWritePermissions<T extends Record<string, unknown>>(body: T, fieldPermissions: FieldPermissionMap, userRoles: readonly string[]): T;
+/**
+ * Resolve effective roles by merging global user roles with org-level roles.
+ *
+ * Global roles come from `req.user.roles` (Better Auth user object).
+ * Org roles come from `req.context.orgRoles` (set by BA adapter's org bridge).
+ *
+ * When no org context exists, returns global roles only — backward compatible.
+ */
+declare function resolveEffectiveRoles(userRoles: readonly string[], orgRoles: readonly string[]): string[];
+//#endregion
+export { applyFieldWritePermissions as a, applyFieldReadPermissions as i, FieldPermissionMap as n, fields as o, FieldPermissionType as r, resolveEffectiveRoles as s, FieldPermission as t };
+//# sourceMappingURL=fields-DyaDVX4J.d.mts.map

package/dist/fields-DyaDVX4J.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fields-DyaDVX4J.d.mts","names":[],"sources":["../src/permissions/fields.ts"],"mappings":";;AAgCA;;;;;AAEA;;;;;;;;;;AAMA;;;;;AAMA;KAdY,mBAAA;AAAA,UAEK,eAAA;EAAA,SACN,KAAA,EAAO,mBAAA;EAAA,SACP,KAAA;EAAA,SACA,WAAA;AAAA;AAAA,KAGC,kBAAA,GAAqB,MAAA,SAAe,eAAA;AAAA,cAMnC,MAAA;;;;;;;;;YASD,eAAA;;;;;;AAgEZ;;;;uCAnDuC,eAAA;EAqDnB;;;;;;;;;;wCAvCoB,eAAA;EAyCrC;;;AAgDH;;;;;;;;;;;;sCAtEoC,WAAA,aAAiC,eAAA;AAAA;;;;;;AA8GrE;;;;iBA5FgB,yBAAA,WAAoC,MAAA,kBAAA,CAClD,IAAA,EAAM,CAAA,EACN,gBAAA,EAAkB,kBAAA,EAClB,SAAA,sBACC,CAAA;;;;;;;;;;iBAgDa,0BAAA,WAAqC,MAAA,kBAAA,CACnD,IAAA,EAAM,CAAA,EACN,gBAAA,EAAkB,kBAAA,EAClB,SAAA,sBACC,CAAA;;;;;;;;;iBAoCa,qBAAA,CACd,SAAA,qBACA,QAAA"}

package/dist/fields-iagOozy0.mjs

@@ -0,0 +1,115 @@
+//#region src/permissions/fields.ts
+/**
+* Field-Level Permissions
+*
+* Control field visibility and writability per role.
+* Integrated into the response path (read) and sanitization path (write).
+*
+* @example
+* ```typescript
+* import { fields, defineResource } from '@classytic/arc';
+*
+* const userResource = defineResource({
+*   name: 'user',
+*   adapter: userAdapter,
+*   fields: {
+*     salary: fields.visibleTo(['admin', 'hr']),
+*     internalNotes: fields.writableBy(['admin']),
+*     email: fields.redactFor(['viewer']),
+*     password: fields.hidden(),
+*   },
+* });
+* ```
+*/
+/** Type guard for Mongoose-like documents with toObject() */
+function isMongooseDoc(obj) {
+	return !!obj && typeof obj === "object" && "toObject" in obj && typeof obj.toObject === "function";
+}
+const fields = {
+	hidden() {
+		return { _type: "hidden" };
+	},
+	visibleTo(roles) {
+		return {
+			_type: "visibleTo",
+			roles
+		};
+	},
+	writableBy(roles) {
+		return {
+			_type: "writableBy",
+			roles
+		};
+	},
+	redactFor(roles, redactValue = "***") {
+		return {
+			_type: "redactFor",
+			roles,
+			redactValue
+		};
+	}
+};
+/**
+* Apply field-level READ permissions to a response object.
+* Strips hidden fields, enforces visibility, and applies redaction.
+*
+* @param data - The response object (mutated in place for performance)
+* @param fieldPermissions - Field permission map from resource config
+* @param userRoles - Current user's roles (empty array for unauthenticated)
+* @returns The filtered object
+*/
+function applyFieldReadPermissions(data, fieldPermissions, userRoles) {
+	if (!data || typeof data !== "object") return data;
+	const result = { ...isMongooseDoc(data) ? data.toObject() : data };
+	for (const [field, perm] of Object.entries(fieldPermissions)) switch (perm._type) {
+		case "hidden":
+			delete result[field];
+			break;
+		case "visibleTo":
+			if (!perm.roles?.some((r) => userRoles.includes(r))) delete result[field];
+			break;
+		case "redactFor":
+			if (perm.roles?.some((r) => userRoles.includes(r))) result[field] = perm.redactValue ?? "***";
+			break;
+		case "writableBy": break;
+	}
+	return result;
+}
+/**
+* Apply field-level WRITE permissions to request body.
+* Strips fields that the user doesn't have permission to write.
+*
+* @param body - The request body (returns a new filtered copy)
+* @param fieldPermissions - Field permission map from resource config
+* @param userRoles - Current user's roles
+* @returns Filtered body
+*/
+function applyFieldWritePermissions(body, fieldPermissions, userRoles) {
+	const result = { ...body };
+	for (const [field, perm] of Object.entries(fieldPermissions)) switch (perm._type) {
+		case "hidden":
+			delete result[field];
+			break;
+		case "writableBy":
+			if (field in result && !perm.roles?.some((r) => userRoles.includes(r))) delete result[field];
+			break;
+	}
+	return result;
+}
+/**
+* Resolve effective roles by merging global user roles with org-level roles.
+*
+* Global roles come from `req.user.roles` (Better Auth user object).
+* Org roles come from `req.context.orgRoles` (set by BA adapter's org bridge).
+*
+* When no org context exists, returns global roles only — backward compatible.
+*/
+function resolveEffectiveRoles(userRoles, orgRoles) {
+	if (orgRoles.length === 0) return [...userRoles];
+	if (userRoles.length === 0) return [...orgRoles];
+	return [...new Set([...userRoles, ...orgRoles])];
+}
+
+//#endregion
+export { resolveEffectiveRoles as i, applyFieldWritePermissions as n, fields as r, applyFieldReadPermissions as t };
+//# sourceMappingURL=fields-iagOozy0.mjs.map

package/dist/fields-iagOozy0.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"fields-iagOozy0.mjs","names":[],"sources":["../src/permissions/fields.ts"],"sourcesContent":["/**\n * Field-Level Permissions\n *\n * Control field visibility and writability per role.\n * Integrated into the response path (read) and sanitization path (write).\n *\n * @example\n * ```typescript\n * import { fields, defineResource } from '@classytic/arc';\n *\n * const userResource = defineResource({\n *   name: 'user',\n *   adapter: userAdapter,\n *   fields: {\n *     salary: fields.visibleTo(['admin', 'hr']),\n *     internalNotes: fields.writableBy(['admin']),\n *     email: fields.redactFor(['viewer']),\n *     password: fields.hidden(),\n *   },\n * });\n * ```\n */\n\n/** Type guard for Mongoose-like documents with toObject() */\nfunction isMongooseDoc(obj: unknown): obj is { toObject(): Record<string, unknown> } {\n  return !!obj && typeof obj === 'object' && 'toObject' in obj && typeof (obj as Record<string, unknown>).toObject === 'function';\n}\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\nexport type FieldPermissionType = 'hidden' | 'visibleTo' | 'writableBy' | 'redactFor';\n\nexport interface FieldPermission {\n  readonly _type: FieldPermissionType;\n  readonly roles?: readonly string[];\n  readonly redactValue?: unknown;\n}\n\nexport type FieldPermissionMap = Record<string, FieldPermission>;\n\n// ---------------------------------------------------------------------------\n// Field Permission Helpers\n// ---------------------------------------------------------------------------\n\nexport const fields = {\n  /**\n   * Field is never included in responses. Not writable via API.\n   *\n   * @example\n   * ```typescript\n   * fields: { password: fields.hidden() }\n   * ```\n   */\n  hidden(): FieldPermission {\n    return { _type: 'hidden' };\n  },\n\n  /**\n   * Field is only visible to users with specified roles.\n   * Other users don't see the field at all.\n   *\n   * @example\n   * ```typescript\n   * fields: { salary: fields.visibleTo(['admin', 'hr']) }\n   * ```\n   */\n  visibleTo(roles: readonly string[]): FieldPermission {\n    return { _type: 'visibleTo', roles };\n  },\n\n  /**\n   * Field is only writable by users with specified roles.\n   * All users can still read the field. Users without the role\n   * have the field silently stripped from write operations.\n   *\n   * @example\n   * ```typescript\n   * fields: { role: fields.writableBy(['admin']) }\n   * ```\n   */\n  writableBy(roles: readonly string[]): FieldPermission {\n    return { _type: 'writableBy', roles };\n  },\n\n  /**\n   * Field is redacted (replaced with a placeholder) for specified roles.\n   * Other users see the real value.\n   *\n   * @param roles - Roles that see the redacted value\n   * @param redactValue - Replacement value (default: '***')\n   *\n   * @example\n   * ```typescript\n   * fields: {\n   *   email: fields.redactFor(['viewer']),\n   *   ssn: fields.redactFor(['basic'], '***-**-****'),\n   * }\n   * ```\n   */\n  redactFor(roles: readonly string[], redactValue: unknown = '***'): FieldPermission {\n    return { _type: 'redactFor', roles, redactValue };\n  },\n};\n\n// ---------------------------------------------------------------------------\n// Application Functions\n// ---------------------------------------------------------------------------\n\n/**\n * Apply field-level READ permissions to a response object.\n * Strips hidden fields, enforces visibility, and applies redaction.\n *\n * @param data - The response object (mutated in place for performance)\n * @param fieldPermissions - Field permission map from resource config\n * @param userRoles - Current user's roles (empty array for unauthenticated)\n * @returns The filtered object\n */\nexport function applyFieldReadPermissions<T extends Record<string, unknown>>(\n  data: T,\n  fieldPermissions: FieldPermissionMap,\n  userRoles: readonly string[],\n): T {\n  if (!data || typeof data !== 'object') return data;\n\n  // Normalize Mongoose documents to plain objects before spreading.\n  // HydratedDocument's spread gives internal properties ($__, $isNew, etc.),\n  // not the actual document fields — toObject() returns a proper plain object.\n  const plain = isMongooseDoc(data) ? data.toObject() as T : data;\n  const result = { ...plain };\n\n  for (const [field, perm] of Object.entries(fieldPermissions)) {\n    switch (perm._type) {\n      case 'hidden':\n        // Always strip\n        delete result[field];\n        break;\n\n      case 'visibleTo':\n        // Strip if user doesn't have any of the required roles\n        if (!perm.roles?.some((r) => userRoles.includes(r))) {\n          delete result[field];\n        }\n        break;\n\n      case 'redactFor':\n        // Redact if user HAS any of the specified roles\n        if (perm.roles?.some((r) => userRoles.includes(r))) {\n          (result as Record<string, unknown>)[field] = perm.redactValue ?? '***';\n        }\n        break;\n\n      case 'writableBy':\n        // Write-only permission — no effect on reads\n        break;\n    }\n  }\n\n  return result;\n}\n\n/**\n * Apply field-level WRITE permissions to request body.\n * Strips fields that the user doesn't have permission to write.\n *\n * @param body - The request body (returns a new filtered copy)\n * @param fieldPermissions - Field permission map from resource config\n * @param userRoles - Current user's roles\n * @returns Filtered body\n */\nexport function applyFieldWritePermissions<T extends Record<string, unknown>>(\n  body: T,\n  fieldPermissions: FieldPermissionMap,\n  userRoles: readonly string[],\n): T {\n  const result = { ...body };\n\n  for (const [field, perm] of Object.entries(fieldPermissions)) {\n    switch (perm._type) {\n      case 'hidden':\n        // Hidden fields can never be written\n        delete result[field];\n        break;\n\n      case 'writableBy':\n        // Only writable by specific roles — strip if user lacks them\n        if (field in result && !perm.roles?.some((r) => userRoles.includes(r))) {\n          delete result[field];\n        }\n        break;\n\n      // visibleTo and redactFor don't affect writes\n    }\n  }\n\n  return result;\n}\n\n// ---------------------------------------------------------------------------\n// Role Resolution\n// ---------------------------------------------------------------------------\n\n/**\n * Resolve effective roles by merging global user roles with org-level roles.\n *\n * Global roles come from `req.user.roles` (Better Auth user object).\n * Org roles come from `req.context.orgRoles` (set by BA adapter's org bridge).\n *\n * When no org context exists, returns global roles only — backward compatible.\n */\nexport function resolveEffectiveRoles(\n  userRoles: readonly string[],\n  orgRoles: readonly string[],\n): string[] {\n  if (orgRoles.length === 0) return [...userRoles];\n  if (userRoles.length === 0) return [...orgRoles];\n  return [...new Set([...userRoles, ...orgRoles])];\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAwBA,SAAS,cAAc,KAA8D;AACnF,QAAO,CAAC,CAAC,OAAO,OAAO,QAAQ,YAAY,cAAc,OAAO,OAAQ,IAAgC,aAAa;;AAqBvH,MAAa,SAAS;CASpB,SAA0B;AACxB,SAAO,EAAE,OAAO,UAAU;;CAY5B,UAAU,OAA2C;AACnD,SAAO;GAAE,OAAO;GAAa;GAAO;;CAatC,WAAW,OAA2C;AACpD,SAAO;GAAE,OAAO;GAAc;GAAO;;CAkBvC,UAAU,OAA0B,cAAuB,OAAwB;AACjF,SAAO;GAAE,OAAO;GAAa;GAAO;GAAa;;CAEpD;;;;;;;;;;AAeD,SAAgB,0BACd,MACA,kBACA,WACG;AACH,KAAI,CAAC,QAAQ,OAAO,SAAS,SAAU,QAAO;CAM9C,MAAM,SAAS,EAAE,GADH,cAAc,KAAK,GAAG,KAAK,UAAU,GAAQ,MAChC;AAE3B,MAAK,MAAM,CAAC,OAAO,SAAS,OAAO,QAAQ,iBAAiB,CAC1D,SAAQ,KAAK,OAAb;EACE,KAAK;AAEH,UAAO,OAAO;AACd;EAEF,KAAK;AAEH,OAAI,CAAC,KAAK,OAAO,MAAM,MAAM,UAAU,SAAS,EAAE,CAAC,CACjD,QAAO,OAAO;AAEhB;EAEF,KAAK;AAEH,OAAI,KAAK,OAAO,MAAM,MAAM,UAAU,SAAS,EAAE,CAAC,CAChD,CAAC,OAAmC,SAAS,KAAK,eAAe;AAEnE;EAEF,KAAK,aAEH;;AAIN,QAAO;;;;;;;;;;;AAYT,SAAgB,2BACd,MACA,kBACA,WACG;CACH,MAAM,SAAS,EAAE,GAAG,MAAM;AAE1B,MAAK,MAAM,CAAC,OAAO,SAAS,OAAO,QAAQ,iBAAiB,CAC1D,SAAQ,KAAK,OAAb;EACE,KAAK;AAEH,UAAO,OAAO;AACd;EAEF,KAAK;AAEH,OAAI,SAAS,UAAU,CAAC,KAAK,OAAO,MAAM,MAAM,UAAU,SAAS,EAAE,CAAC,CACpE,QAAO,OAAO;AAEhB;;AAMN,QAAO;;;;;;;;;;AAeT,SAAgB,sBACd,WACA,UACU;AACV,KAAI,SAAS,WAAW,EAAG,QAAO,CAAC,GAAG,UAAU;AAChD,KAAI,UAAU,WAAW,EAAG,QAAO,CAAC,GAAG,SAAS;AAChD,QAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,WAAW,GAAG,SAAS,CAAC,CAAC"}

package/dist/hooks/index.d.mts

@@ -0,0 +1,4 @@
+import "../elevation-B_2dRLVP.mjs";
+import { $ as beforeUpdate, B as DefineHookOptions, G as HookRegistration, H as HookHandler, J as afterCreate, K as HookSystem, Q as beforeDelete, U as HookOperation, V as HookContext, W as HookPhase, X as afterUpdate, Y as afterDelete, Z as beforeCreate, et as createHookSystem, q as HookSystemOptions, tt as defineHook } from "../interface-Ch8HU9uM.mjs";
+import "../types-aYB4V7uN.mjs";
+export { type DefineHookOptions, type HookContext, type HookHandler, type HookOperation, type HookPhase, type HookRegistration, HookSystem, type HookSystemOptions, afterCreate, afterDelete, afterUpdate, beforeCreate, beforeDelete, beforeUpdate, createHookSystem, defineHook };

package/dist/hooks/index.mjs

@@ -0,0 +1,3 @@
+import { a as beforeCreate, c as createHookSystem, i as afterUpdate, l as defineHook, n as afterCreate, o as beforeDelete, r as afterDelete, s as beforeUpdate, t as HookSystem } from "../HookSystem-BsGV-j2l.mjs";
+
+export { HookSystem, afterCreate, afterDelete, afterUpdate, beforeCreate, beforeDelete, beforeUpdate, createHookSystem, defineHook };

package/dist/idempotency/index.d.mts

@@ -0,0 +1,97 @@
+import { i as createIdempotencyResult, n as IdempotencyResult, r as IdempotencyStore, t as IdempotencyLock } from "../interface-B01JvPVc.mjs";
+import { r as RedisIdempotencyStoreOptions, t as RedisClient } from "../redis-D-JAeLtm.mjs";
+import { n as MongoIdempotencyStoreOptions } from "../mongodb-JN-9JA7K.mjs";
+import { FastifyPluginAsync } from "fastify";
+
+//#region src/idempotency/idempotencyPlugin.d.ts
+interface IdempotencyPluginOptions {
+  /** Enable idempotency (default: false) */
+  enabled?: boolean;
+  /** Header name for idempotency key (default: 'idempotency-key') */
+  headerName?: string;
+  /** TTL for cached responses in ms (default: 86400000 = 24h) */
+  ttlMs?: number;
+  /** Lock timeout in ms (default: 30000 = 30s) */
+  lockTimeoutMs?: number;
+  /** HTTP methods to apply idempotency to (default: ['POST', 'PUT', 'PATCH']) */
+  methods?: string[];
+  /** URL patterns to include (regex). If set, only matching URLs use idempotency */
+  include?: RegExp[];
+  /** URL patterns to exclude (regex). Excluded patterns take precedence */
+  exclude?: RegExp[];
+  /** Custom store (default: MemoryIdempotencyStore) */
+  store?: IdempotencyStore;
+  /** Retry-After header value in seconds when request is in-flight (default: 1) */
+  retryAfterSeconds?: number;
+}
+declare module 'fastify' {
+  interface FastifyRequest {
+    /** The idempotency key for this request (if present) */
+    idempotencyKey?: string;
+    /** Whether this response was replayed from cache */
+    idempotencyReplayed?: boolean;
+    /** @internal Full key with fingerprint for store lookups */
+    _idempotencyFullKey?: string;
+  }
+  interface FastifyInstance {
+    /** Idempotency utilities */
+    idempotency: {
+      /** Manually invalidate an idempotency key */invalidate: (key: string) => Promise<void>; /** Check if a key has a cached response */
+      has: (key: string) => Promise<boolean>;
+      /**
+       * Route-level preHandler for idempotency check + lock.
+       * Wire AFTER authenticate in the preHandler chain so that
+       * `request.user` is populated before the fingerprint is computed.
+       *
+       * `createCrudRouter` injects this automatically for mutation routes.
+       * For custom routes, add it manually:
+       * ```typescript
+       * fastify.post('/orders', {
+       *   preHandler: [fastify.authenticate, fastify.idempotency.middleware],
+       * }, handler);
+       * ```
+       */
+      middleware: (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+    };
+  }
+}
+declare const idempotencyPlugin: FastifyPluginAsync<IdempotencyPluginOptions>;
+declare const _default: FastifyPluginAsync<IdempotencyPluginOptions>;
+//#endregion
+//#region src/idempotency/stores/memory.d.ts
+interface MemoryIdempotencyStoreOptions {
+  /** Default TTL in milliseconds (default: 86400000 = 24h) */
+  ttlMs?: number;
+  /** Cleanup interval in milliseconds (default: 60000 = 1 min) */
+  cleanupIntervalMs?: number;
+  /** Maximum entries before oldest are evicted (default: 10000) */
+  maxEntries?: number;
+}
+declare class MemoryIdempotencyStore implements IdempotencyStore {
+  readonly name = "memory";
+  private results;
+  private locks;
+  private ttlMs;
+  private maxEntries;
+  private cleanupInterval;
+  constructor(options?: MemoryIdempotencyStoreOptions);
+  get(key: string): Promise<IdempotencyResult | undefined>;
+  set(key: string, result: Omit<IdempotencyResult, 'key'>): Promise<void>;
+  tryLock(key: string, requestId: string, ttlMs: number): Promise<boolean>;
+  unlock(key: string, requestId: string): Promise<void>;
+  isLocked(key: string): Promise<boolean>;
+  delete(key: string): Promise<void>;
+  deleteByPrefix(prefix: string): Promise<number>;
+  findByPrefix(prefix: string): Promise<IdempotencyResult | undefined>;
+  close(): Promise<void>;
+  /** Get current stats (for debugging/monitoring) */
+  getStats(): {
+    results: number;
+    locks: number;
+  };
+  private cleanup;
+  private evictOldest;
+}
+//#endregion
+export { type IdempotencyLock, type IdempotencyPluginOptions, type IdempotencyResult, type IdempotencyStore, MemoryIdempotencyStore, type MemoryIdempotencyStoreOptions, type MongoIdempotencyStoreOptions, type RedisClient, type RedisIdempotencyStoreOptions, createIdempotencyResult, _default as idempotencyPlugin, idempotencyPlugin as idempotencyPluginFn };
+//# sourceMappingURL=index.d.mts.map

package/dist/idempotency/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/idempotency/idempotencyPlugin.ts","../../src/idempotency/stores/memory.ts"],"mappings":";;;;;;UA6CiB,wBAAA;EA0Bb;EAxBF,OAAA;EA6BU;EA3BV,UAAA;EA+BI;EA7BJ,KAAA;EA6BiC;EA3BjC,aAAA;EA6BU;EA3BV,OAAA;EAyCI;EAvCJ,OAAA,GAAU,MAAA;EAuCO;EArCjB,OAAA,GAAU,MAAA;EAqCgC;EAnC1C,KAAA,GAAQ,gBAAA;EAmCiE;EAjCzE,iBAAA;AAAA;AAAA;EAAA,UAIU,cAAA;IAqCgC;IAnCxC,cAAA;IAmCgE;IAjChE,mBAAA;;IAEA,mBAAA;EAAA;EAAA,UAGQ,eAAA;;IAER,WAAA;mDAEE,UAAA,GAAa,GAAA,aAAgB,OAAA,QCjEW;MDmExC,GAAA,GAAM,GAAA,aAAgB,OAAA;MCnEkB;;;;;;AAS9C;;;;;;;MDwEM,UAAA,GAAa,OAAA,EAAS,cAAA,EAAgB,KAAA,EAAO,YAAA,KAAiB,OAAA;IAAA;EAAA;AAAA;AAAA,cAQ9D,iBAAA,EAAmB,kBAAA,CAAmB,wBAAA;AAAA,cAAwB,QAAA;;;UCzFnD,6BAAA;EDgCf;EC9BA,KAAA;EDkCA;EChCA,iBAAA;EDoCA;EClCA,UAAA;AAAA;AAAA,cAGW,sBAAA,YAAkC,gBAAA;EAAA,SACpC,IAAA;EAAA,QACD,OAAA;EAAA,QACA,KAAA;EAAA,QACA,KAAA;EAAA,QACA,UAAA;EAAA,QACA,eAAA;cAEI,OAAA,GAAS,6BAAA;EAgBf,GAAA,CAAI,GAAA,WAAc,OAAA,CAAQ,iBAAA;EAa1B,GAAA,CAAI,GAAA,UAAa,MAAA,EAAQ,IAAA,CAAK,iBAAA,WAA4B,OAAA;EAS1D,OAAA,CAAQ,GAAA,UAAa,SAAA,UAAmB,KAAA,WAAgB,OAAA;EAwBxD,MAAA,CAAO,GAAA,UAAa,SAAA,WAAoB,OAAA;EAOxC,QAAA,CAAS,GAAA,WAAc,OAAA;EAavB,MAAA,CAAO,GAAA,WAAc,OAAA;EAKrB,cAAA,CAAe,MAAA,WAAiB,OAAA;EAgBhC,YAAA,CAAa,MAAA,WAAiB,OAAA,CAAQ,iBAAA;EActC,KAAA,CAAA,GAAS,OAAA;EDlFL;EC4FV,QAAA,CAAA;IAAc,OAAA;IAAiB,KAAA;EAAA;EAAA,QAOvB,OAAA;EAAA,QAgBA,WAAA;AAAA"}

package/dist/idempotency/index.mjs

@@ -0,0 +1,320 @@
+import fp from "fastify-plugin";
+import { createHash } from "crypto";
+
+//#region src/idempotency/stores/interface.ts
+/**
+* Helper to create a result object
+*/
+function createIdempotencyResult(statusCode, body, headers, ttlMs) {
+	const now = /* @__PURE__ */ new Date();
+	return {
+		statusCode,
+		headers,
+		body,
+		createdAt: now,
+		expiresAt: new Date(now.getTime() + ttlMs)
+	};
+}
+
+//#endregion
+//#region src/idempotency/stores/memory.ts
+var MemoryIdempotencyStore = class {
+	name = "memory";
+	results = /* @__PURE__ */ new Map();
+	locks = /* @__PURE__ */ new Map();
+	ttlMs;
+	maxEntries;
+	cleanupInterval = null;
+	constructor(options = {}) {
+		this.ttlMs = options.ttlMs ?? 864e5;
+		this.maxEntries = options.maxEntries ?? 1e4;
+		const cleanupIntervalMs = options.cleanupIntervalMs ?? 6e4;
+		this.cleanupInterval = setInterval(() => {
+			this.cleanup();
+		}, cleanupIntervalMs);
+		if (this.cleanupInterval.unref) this.cleanupInterval.unref();
+	}
+	async get(key) {
+		const result = this.results.get(key);
+		if (!result) return void 0;
+		if (/* @__PURE__ */ new Date() > result.expiresAt) {
+			this.results.delete(key);
+			return;
+		}
+		return result;
+	}
+	async set(key, result) {
+		if (this.results.size >= this.maxEntries) this.evictOldest();
+		this.results.set(key, {
+			...result,
+			key
+		});
+	}
+	async tryLock(key, requestId, ttlMs) {
+		const existing = this.locks.get(key);
+		if (existing) if (/* @__PURE__ */ new Date() > existing.expiresAt) this.locks.delete(key);
+		else return false;
+		this.locks.set(key, {
+			key,
+			requestId,
+			lockedAt: /* @__PURE__ */ new Date(),
+			expiresAt: new Date(Date.now() + ttlMs)
+		});
+		return true;
+	}
+	async unlock(key, requestId) {
+		const lock = this.locks.get(key);
+		if (lock && lock.requestId === requestId) this.locks.delete(key);
+	}
+	async isLocked(key) {
+		const lock = this.locks.get(key);
+		if (!lock) return false;
+		if (/* @__PURE__ */ new Date() > lock.expiresAt) {
+			this.locks.delete(key);
+			return false;
+		}
+		return true;
+	}
+	async delete(key) {
+		this.results.delete(key);
+		this.locks.delete(key);
+	}
+	async deleteByPrefix(prefix) {
+		let count = 0;
+		for (const key of this.results.keys()) if (key.startsWith(prefix)) {
+			this.results.delete(key);
+			count++;
+		}
+		for (const key of this.locks.keys()) if (key.startsWith(prefix)) this.locks.delete(key);
+		return count;
+	}
+	async findByPrefix(prefix) {
+		const now = /* @__PURE__ */ new Date();
+		for (const [key, result] of this.results) if (key.startsWith(prefix)) {
+			if (now > result.expiresAt) {
+				this.results.delete(key);
+				continue;
+			}
+			return result;
+		}
+	}
+	async close() {
+		if (this.cleanupInterval) {
+			clearInterval(this.cleanupInterval);
+			this.cleanupInterval = null;
+		}
+		this.results.clear();
+		this.locks.clear();
+	}
+	/** Get current stats (for debugging/monitoring) */
+	getStats() {
+		return {
+			results: this.results.size,
+			locks: this.locks.size
+		};
+	}
+	cleanup() {
+		const now = /* @__PURE__ */ new Date();
+		for (const [key, result] of this.results) if (now > result.expiresAt) this.results.delete(key);
+		for (const [key, lock] of this.locks) if (now > lock.expiresAt) this.locks.delete(key);
+	}
+	evictOldest() {
+		const entries = Array.from(this.results.entries()).sort((a, b) => a[1].createdAt.getTime() - b[1].createdAt.getTime());
+		const toRemove = Math.max(1, Math.floor(entries.length * .1));
+		for (let i = 0; i < toRemove; i++) {
+			const entry = entries[i];
+			if (entry) this.results.delete(entry[0]);
+		}
+	}
+};
+
+//#endregion
+//#region src/idempotency/idempotencyPlugin.ts
+/**
+* Idempotency Plugin
+*
+* Duplicate request protection for mutating operations.
+* Uses idempotency keys to ensure safe retries.
+*
+* ## Auth Safety
+*
+* The idempotency check runs as a **route-level middleware**
+* (`idempotency.middleware`) that must be wired AFTER authentication in the
+* preHandler chain. This ensures the fingerprint includes the real caller
+* identity, preventing cross-user replay attacks.
+*
+* Arc's `createCrudRouter` does this automatically for mutation routes.
+* For custom routes, wire it manually:
+*
+* ```typescript
+* fastify.post('/orders', {
+*   preHandler: [fastify.authenticate, fastify.idempotency.middleware],
+* }, handler);
+* ```
+*
+* @example
+* import { idempotencyPlugin } from '@classytic/arc/idempotency';
+*
+* await fastify.register(idempotencyPlugin, {
+*   enabled: true,
+*   headerName: 'idempotency-key',
+*   ttlMs: 86400000, // 24 hours
+* });
+*
+* // Client sends:
+* // POST /api/orders
+* // Idempotency-Key: order-123-abc
+*
+* // If same key sent again within TTL, returns cached response
+*/
+const HEADER_IDEMPOTENCY_REPLAYED = "x-idempotency-replayed";
+const HEADER_IDEMPOTENCY_KEY = "x-idempotency-key";
+const idempotencyPlugin = async (fastify, opts = {}) => {
+	const { enabled = false, headerName = "idempotency-key", ttlMs = 864e5, lockTimeoutMs = 3e4, methods = [
+		"POST",
+		"PUT",
+		"PATCH"
+	], include, exclude, store = new MemoryIdempotencyStore({ ttlMs }), retryAfterSeconds = 1 } = opts;
+	if (!enabled) {
+		fastify.decorate("idempotency", {
+			invalidate: async () => {},
+			has: async () => false,
+			middleware: async () => {}
+		});
+		fastify.decorateRequest("idempotencyKey", void 0);
+		fastify.decorateRequest("idempotencyReplayed", false);
+		fastify.log?.debug?.("Idempotency plugin disabled");
+		return;
+	}
+	const methodSet = new Set(methods.map((m) => m.toUpperCase()));
+	fastify.decorateRequest("idempotencyKey", void 0);
+	fastify.decorateRequest("idempotencyReplayed", false);
+	/**
+	* Check if this request should use idempotency
+	*/
+	function shouldApplyIdempotency(request) {
+		if (!methodSet.has(request.method)) return false;
+		const url = request.url;
+		if (exclude?.some((pattern) => pattern.test(url))) return false;
+		if (include && !include.some((pattern) => pattern.test(url))) return false;
+		return true;
+	}
+	/**
+	* Normalize body for consistent hashing (sort keys recursively)
+	*/
+	function normalizeBody(obj) {
+		if (obj === null || typeof obj !== "object") return obj;
+		if (Array.isArray(obj)) return obj.map(normalizeBody);
+		const sorted = {};
+		const keys = Object.keys(obj).sort();
+		for (const key of keys) sorted[key] = normalizeBody(obj[key]);
+		return sorted;
+	}
+	/**
+	* Generate a fingerprint for the request (for key generation).
+	* Includes caller identity so the same idempotency key from different
+	* users doesn't replay one user's response to another.
+	*
+	* IMPORTANT: This must be called AFTER auth has populated request.user,
+	* otherwise userId falls back to 'anon' and cross-user replay is possible.
+	*/
+	function getRequestFingerprint(request) {
+		let bodyHash = "nobody";
+		if (request.body && typeof request.body === "object") {
+			const normalized = normalizeBody(request.body);
+			const bodyString = JSON.stringify(normalized);
+			bodyHash = createHash("sha256").update(bodyString).digest("hex").substring(0, 16);
+			if (request.log && request.log.debug) request.log.debug({ bodyHash }, "Generated body hash");
+		}
+		const user = request.user;
+		const userId = user?.id ?? user?._id ?? "anon";
+		return `${request.method}:${request.url}:${bodyHash}:u=${userId}`;
+	}
+	const idempotencyMiddleware = async (request, reply) => {
+		if (!shouldApplyIdempotency(request)) return;
+		const keyHeader = request.headers[headerName.toLowerCase()];
+		const idempotencyKey = typeof keyHeader === "string" ? keyHeader.trim() : void 0;
+		if (!idempotencyKey) return;
+		request.idempotencyKey = idempotencyKey;
+		const fullKey = `${idempotencyKey}:${getRequestFingerprint(request)}`;
+		const cached = await store.get(fullKey);
+		if (cached) {
+			request.idempotencyReplayed = true;
+			reply.header(HEADER_IDEMPOTENCY_REPLAYED, "true");
+			reply.header(HEADER_IDEMPOTENCY_KEY, idempotencyKey);
+			for (const [key, value] of Object.entries(cached.headers)) if (!key.startsWith("x-idempotency")) reply.header(key, value);
+			reply.code(cached.statusCode).send(cached.body);
+			return;
+		}
+		if (!await store.tryLock(fullKey, request.id, lockTimeoutMs)) {
+			reply.code(409).header("Retry-After", retryAfterSeconds.toString()).send({
+				error: "Request with this idempotency key is already in progress",
+				code: "IDEMPOTENCY_CONFLICT",
+				retryAfter: retryAfterSeconds
+			});
+			return;
+		}
+		request._idempotencyFullKey = fullKey;
+	};
+	fastify.decorate("idempotency", {
+		invalidate: async (key) => {
+			await store.deleteByPrefix(`${key}:`);
+		},
+		has: async (key) => {
+			return !!await store.findByPrefix(`${key}:`);
+		},
+		middleware: idempotencyMiddleware
+	});
+	fastify.addHook("onSend", async (request, reply, payload) => {
+		if (request.idempotencyReplayed) return payload;
+		const fullKey = request._idempotencyFullKey;
+		if (!fullKey) return payload;
+		const statusCode = reply.statusCode;
+		if (statusCode < 200 || statusCode >= 300) {
+			await store.unlock(fullKey, request.id);
+			return payload;
+		}
+		const headersToCache = {};
+		const excludeHeaders = new Set([
+			"content-length",
+			"transfer-encoding",
+			"connection",
+			"keep-alive",
+			"date",
+			"set-cookie"
+		]);
+		const rawHeaders = reply.getHeaders();
+		for (const [key, value] of Object.entries(rawHeaders)) if (!excludeHeaders.has(key.toLowerCase()) && typeof value === "string") headersToCache[key] = value;
+		let body;
+		try {
+			body = typeof payload === "string" ? JSON.parse(payload) : payload;
+		} catch {
+			body = payload;
+		}
+		const result = createIdempotencyResult(statusCode, body, headersToCache, ttlMs);
+		await store.set(fullKey, result);
+		await store.unlock(fullKey, request.id);
+		reply.header(HEADER_IDEMPOTENCY_KEY, request.idempotencyKey);
+		return payload;
+	});
+	fastify.addHook("onError", async (request) => {
+		const fullKey = request._idempotencyFullKey;
+		if (fullKey) await store.unlock(fullKey, request.id);
+	});
+	fastify.addHook("onClose", async () => {
+		await store.close?.();
+	});
+	fastify.log?.debug?.({
+		headerName,
+		ttlMs,
+		methods
+	}, "Idempotency plugin enabled");
+};
+var idempotencyPlugin_default = fp(idempotencyPlugin, {
+	name: "arc-idempotency",
+	fastify: "5.x"
+});
+
+//#endregion
+export { MemoryIdempotencyStore, createIdempotencyResult, idempotencyPlugin_default as idempotencyPlugin, idempotencyPlugin as idempotencyPluginFn };
+//# sourceMappingURL=index.mjs.map