@01.software/sdk 0.31.0 → 0.32.0

package/dist/webhook.d.ts

@@ -1,12 +1,60 @@
-import { C as Collection } from './const-BGCP-OJL.js';
-import { C as CollectionType } from './types-CVA10VC-.js';
-import './payload-types-Wa4-eC6x.js';
+import { C as Collection } from './const-DcY2_z9O.js';
+import { C as CollectionType } from './types-DUPC7Xn6.js';
+import './payload-types-DVK1QCeU.js';
 
 type WebhookOperation = string;
+/**
+ * Semantic event type for manual Admin Panel ordering changes.
+ *
+ * Order-change webhooks remain `operation: "update"` events for compatibility.
+ * Do not filter on or emit `operation: "reorder"`; use this event type with
+ * `isOrderChangedWebhookEvent()` to distinguish ordering from normal content
+ * updates.
+ */
+declare const ORDER_CHANGED_EVENT_TYPE: "collection.orderChanged";
+/** Collection webhook operations emitted for tenant collection writes. */
+type CollectionWebhookOperation = 'create' | 'update';
+/** Describes the ordered area affected by an order-change webhook. */
+type WebhookOrderScope = {
+    kind: 'collection';
+    collection: string;
+} | {
+    kind: 'join';
+    collection: string;
+    field: string;
+    id: string | number;
+};
+/** Identifies the public moved document for the ordered scope. */
+type WebhookOrderMoved = {
+    collection: string;
+    id: string | number;
+    relatedCollection?: string;
+    relatedId?: string | number;
+};
+/** Metadata attached to `collection.orderChanged` webhook events. */
+type WebhookOrderChange = {
+    type: 'order';
+    source: 'payload-orderable';
+    /**
+     * Diagnostic Payload order field name.
+     *
+     * This may contain hidden implementation field names. Application routing
+     * should use `change.scope` and `change.moved` instead.
+     */
+    orderableFieldName?: string;
+    previousOrder?: string | null;
+    nextOrder?: string | null;
+    scope: WebhookOrderScope;
+    moved: WebhookOrderMoved;
+};
+/** Known semantic webhook change metadata. */
+type WebhookChange = WebhookOrderChange;
 interface WebhookEvent<T extends Collection | string = Collection, TData = T extends Collection ? CollectionType<T> : Record<string, unknown>> {
     collection: T;
     operation: WebhookOperation;
     data: TData;
+    eventType?: string;
+    change?: unknown;
     timestamp?: string;
     deliveryId?: string;
 }
@@ -17,7 +65,28 @@ interface WebhookOptions {
     toleranceSeconds?: number;
 }
 declare function isValidWebhookEvent(data: unknown): data is WebhookEvent;
+/** Webhook event emitted when manual Admin Panel ordering changes. */
+type OrderChangedWebhookEvent<T extends Collection | string = Collection, TData = T extends Collection ? CollectionType<T> : Record<string, unknown>> = WebhookEvent<T, TData> & {
+    operation: 'update';
+    eventType: typeof ORDER_CHANGED_EVENT_TYPE;
+    change: WebhookOrderChange;
+};
+/**
+ * Returns true for semantic order-change webhooks emitted as update events.
+ *
+ * Use this guard with `ORDER_CHANGED_EVENT_TYPE` instead of filtering on
+ * `operation: "reorder"`. Tenant order-change webhooks intentionally keep
+ * `operation: "update"` for compatibility with existing webhook handlers.
+ */
+declare function isOrderChangedWebhookEvent(event: unknown): event is OrderChangedWebhookEvent<string, unknown>;
+/** Narrows a webhook event to a specific collection. */
+declare function isWebhookCollection<TCollection extends string>(event: unknown, collection: TCollection): event is WebhookEvent<TCollection, unknown>;
+/** Narrows a webhook event to a specific operation. */
+declare function isWebhookOperation<TOperation extends string>(event: unknown, operation: TOperation): event is WebhookEvent<string, unknown> & {
+    operation: TOperation;
+};
 declare const CUSTOMER_PASSWORD_RESET_OPERATION: "password-reset";
+type WebhookKnownOperation = CollectionWebhookOperation | typeof CUSTOMER_PASSWORD_RESET_OPERATION;
 interface CustomerPasswordResetWebhookData {
     customerId: string | number;
     email: string;
@@ -39,4 +108,4 @@ declare function createCustomerAuthWebhookHandler(handlers: CustomerAuthWebhookH
 declare function handleWebhook<T extends Collection | string = Collection, TData = T extends Collection ? CollectionType<T> : Record<string, unknown>>(request: Request, handler: WebhookHandler<T, TData>, options?: WebhookOptions): Promise<Response>;
 declare function createTypedWebhookHandler<T extends Collection>(collection: T, handler: (event: WebhookEvent<T>) => Promise<void> | void): WebhookHandler<T>;
 
-export { CUSTOMER_PASSWORD_RESET_OPERATION, type CustomerAuthWebhookEvent, type CustomerAuthWebhookHandlers, type CustomerPasswordResetWebhookData, type CustomerPasswordResetWebhookEvent, type WebhookEvent, type WebhookHandler, type WebhookOperation, type WebhookOptions, createCustomerAuthWebhookHandler, createTypedWebhookHandler, handleWebhook, isCustomerPasswordResetWebhookEvent, isValidWebhookEvent };
+export { CUSTOMER_PASSWORD_RESET_OPERATION, type CollectionWebhookOperation, type CustomerAuthWebhookEvent, type CustomerAuthWebhookHandlers, type CustomerPasswordResetWebhookData, type CustomerPasswordResetWebhookEvent, ORDER_CHANGED_EVENT_TYPE, type OrderChangedWebhookEvent, type WebhookChange, type WebhookEvent, type WebhookHandler, type WebhookKnownOperation, type WebhookOperation, type WebhookOptions, type WebhookOrderChange, type WebhookOrderMoved, type WebhookOrderScope, createCustomerAuthWebhookHandler, createTypedWebhookHandler, handleWebhook, isCustomerPasswordResetWebhookEvent, isOrderChangedWebhookEvent, isValidWebhookEvent, isWebhookCollection, isWebhookOperation };

package/dist/webhook.js

@@ -1,9 +1,52 @@
 // src/core/webhook/index.ts
+var ORDER_CHANGED_EVENT_TYPE = "collection.orderChanged";
 function isValidWebhookEvent(data) {
   if (typeof data !== "object" || data === null) return false;
   const obj = data;
   return typeof obj.collection === "string" && typeof obj.operation === "string" && obj.operation.length > 0 && typeof obj.data === "object" && obj.data !== null;
 }
+function isStringOrNumber(value) {
+  return typeof value === "string" || typeof value === "number";
+}
+function isWebhookOrderScope(value) {
+  if (!isRecord(value)) return false;
+  if (value.kind === "collection") {
+    return typeof value.collection === "string";
+  }
+  if (value.kind === "join") {
+    return typeof value.collection === "string" && typeof value.field === "string" && isStringOrNumber(value.id);
+  }
+  return false;
+}
+function isWebhookOrderMoved(value) {
+  if (!isRecord(value)) return false;
+  return typeof value.collection === "string" && isStringOrNumber(value.id) && (value.relatedCollection === void 0 || typeof value.relatedCollection === "string") && (value.relatedId === void 0 || isStringOrNumber(value.relatedId));
+}
+function hasOptionalOrderValue(value, key) {
+  return value[key] === void 0 || value[key] === null || typeof value[key] === "string";
+}
+function isWebhookOrderChange(value) {
+  if (!isRecord(value)) return false;
+  return value.type === "order" && value.source === "payload-orderable" && (value.orderableFieldName === void 0 || typeof value.orderableFieldName === "string") && hasOptionalOrderValue(value, "previousOrder") && hasOptionalOrderValue(value, "nextOrder") && isWebhookOrderScope(value.scope) && isWebhookOrderMoved(value.moved);
+}
+function isOrderChangedWebhookEvent(event) {
+  if (!isValidWebhookEvent(event) || event.operation !== "update" || event.eventType !== ORDER_CHANGED_EVENT_TYPE || !isWebhookOrderChange(event.change)) {
+    return false;
+  }
+  if (event.collection !== event.change.scope.collection) {
+    return false;
+  }
+  if (event.change.scope.kind === "collection" && event.change.moved.collection !== event.change.scope.collection) {
+    return false;
+  }
+  return true;
+}
+function isWebhookCollection(event, collection) {
+  return isValidWebhookEvent(event) && event.collection === collection;
+}
+function isWebhookOperation(event, operation) {
+  return isValidWebhookEvent(event) && event.operation === operation;
+}
 var CUSTOMER_PASSWORD_RESET_OPERATION = "password-reset";
 function isRecord(value) {
   return typeof value === "object" && value !== null;
@@ -116,10 +159,14 @@ function createTypedWebhookHandler(collection, handler) {
 }
 export {
   CUSTOMER_PASSWORD_RESET_OPERATION,
+  ORDER_CHANGED_EVENT_TYPE,
   createCustomerAuthWebhookHandler,
   createTypedWebhookHandler,
   handleWebhook,
   isCustomerPasswordResetWebhookEvent,
-  isValidWebhookEvent
+  isOrderChangedWebhookEvent,
+  isValidWebhookEvent,
+  isWebhookCollection,
+  isWebhookOperation
 };
 //# sourceMappingURL=webhook.js.map

package/dist/webhook.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/core/webhook/index.ts"],"sourcesContent":["import type { Collection } from '../client/types'\nimport type { CollectionType } from '../collection/types'\n\nexport type WebhookOperation = string\n\nexport interface WebhookEvent<\n  T extends Collection | string = Collection,\n  TData = T extends Collection ? CollectionType<T> : Record<string, unknown>,\n> {\n  collection: T\n  operation: WebhookOperation\n  data: TData\n  timestamp?: string\n  deliveryId?: string\n}\n\nexport type WebhookHandler<\n  T extends Collection | string = Collection,\n  TData = T extends Collection ? CollectionType<T> : Record<string, unknown>,\n> = (\n  event: WebhookEvent<T, TData>,\n) => Promise<void> | void\n\nexport interface WebhookOptions {\n  secret?: string\n  /** Max accepted skew for signed webhook delivery timestamps. Default: 300s. */\n  toleranceSeconds?: number\n}\n\nexport function isValidWebhookEvent(data: unknown): data is WebhookEvent {\n  if (typeof data !== 'object' || data === null) return false\n  const obj = data as Record<string, unknown>\n  return (\n    typeof obj.collection === 'string' &&\n    typeof obj.operation === 'string' &&\n    obj.operation.length > 0 &&\n    typeof obj.data === 'object' &&\n    obj.data !== null\n  )\n}\n\nexport const CUSTOMER_PASSWORD_RESET_OPERATION = 'password-reset' as const\n\nexport interface CustomerPasswordResetWebhookData {\n  customerId: string | number\n  email: string\n  name: string\n  resetPasswordToken: string\n  resetPasswordExpiresAt: string\n}\n\nexport type CustomerPasswordResetWebhookEvent = WebhookEvent<\n  'customers',\n  CustomerPasswordResetWebhookData\n> & {\n  operation: typeof CUSTOMER_PASSWORD_RESET_OPERATION\n}\n\nexport type CustomerAuthWebhookEvent = CustomerPasswordResetWebhookEvent\n\ntype MaybePromise<T> = T | Promise<T>\n\nexport interface CustomerAuthWebhookHandlers {\n  passwordReset?: (\n    data: CustomerPasswordResetWebhookData,\n    event: CustomerPasswordResetWebhookEvent,\n  ) => MaybePromise<void>\n  unhandled?: (event: WebhookEvent<string, unknown>) => MaybePromise<void>\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null\n}\n\nfunction hasString(value: Record<string, unknown>, key: string): boolean {\n  return typeof value[key] === 'string'\n}\n\nfunction hasStringOrNumber(\n  value: Record<string, unknown>,\n  key: string,\n): boolean {\n  return typeof value[key] === 'string' || typeof value[key] === 'number'\n}\n\nexport function isCustomerPasswordResetWebhookEvent(\n  event: WebhookEvent<string, unknown>,\n): event is CustomerPasswordResetWebhookEvent {\n  if (\n    event.collection !== 'customers' ||\n    event.operation !== CUSTOMER_PASSWORD_RESET_OPERATION ||\n    !isRecord(event.data)\n  ) {\n    return false\n  }\n\n  return (\n    hasStringOrNumber(event.data, 'customerId') &&\n    hasString(event.data, 'email') &&\n    hasString(event.data, 'name') &&\n    hasString(event.data, 'resetPasswordToken') &&\n    hasString(event.data, 'resetPasswordExpiresAt')\n  )\n}\n\nexport function createCustomerAuthWebhookHandler(\n  handlers: CustomerAuthWebhookHandlers,\n): WebhookHandler<string, unknown> {\n  return async (event) => {\n    if (isCustomerPasswordResetWebhookEvent(event) && handlers.passwordReset) {\n      await handlers.passwordReset(event.data, event)\n      return\n    }\n\n    await handlers.unhandled?.(event)\n  }\n}\n\nasync function verifySignature(\n  payload: string,\n  secret: string,\n  signature: string,\n  timestamp: string,\n  deliveryId: string,\n): Promise<boolean> {\n  const encoder = new TextEncoder()\n  const key = await crypto.subtle.importKey(\n    'raw',\n    encoder.encode(secret),\n    { name: 'HMAC', hash: 'SHA-256' },\n    false,\n    ['verify'],\n  )\n  // Validate and convert hex signature to Uint8Array\n  if (signature.length % 2 !== 0 || !/^[0-9a-fA-F]*$/.test(signature)) {\n    return false\n  }\n  const sigBytes = new Uint8Array(\n    (signature.match(/.{2}/g) ?? []).map((byte) => parseInt(byte, 16)),\n  )\n  // crypto.subtle.verify performs constant-time comparison internally\n  return crypto.subtle.verify(\n    'HMAC',\n    key,\n    sigBytes,\n    encoder.encode(`${timestamp}.${deliveryId}.${payload}`),\n  )\n}\n\nfunction timestampIsFresh(timestamp: string, toleranceSeconds: number): boolean {\n  if (!/^\\d+$/.test(timestamp)) return false\n  const timestampMs = Number(timestamp)\n  if (!Number.isFinite(timestampMs)) return false\n  const skewMs = Math.abs(Date.now() - timestampMs)\n  return skewMs <= toleranceSeconds * 1000\n}\n\nexport async function handleWebhook<\n  T extends Collection | string = Collection,\n  TData = T extends Collection ? CollectionType<T> : Record<string, unknown>,\n>(\n  request: Request,\n  handler: WebhookHandler<T, TData>,\n  options?: WebhookOptions,\n): Promise<Response> {\n  try {\n    const rawBody = await request.text()\n\n    if (options?.secret) {\n      const signature = request.headers.get('x-webhook-signature') || ''\n      const timestamp = request.headers.get('x-webhook-timestamp') || ''\n      const deliveryId = request.headers.get('x-webhook-delivery-id') || ''\n      const toleranceSeconds = options.toleranceSeconds ?? 300\n      const valid = Boolean(timestamp && deliveryId) &&\n        timestampIsFresh(timestamp, toleranceSeconds) &&\n        (await verifySignature(\n          rawBody,\n          options.secret,\n          signature,\n          timestamp,\n          deliveryId,\n        ))\n      if (!valid) {\n        return new Response(\n          JSON.stringify({ error: 'Invalid webhook signature' }),\n          { status: 401, headers: { 'Content-Type': 'application/json' } },\n        )\n      }\n    } else {\n      console.warn(\n        '[@01.software/sdk] Webhook signature verification is disabled. ' +\n          'Set { secret } in handleWebhook() options to enable HMAC-SHA256 verification.',\n      )\n    }\n\n    const body = JSON.parse(rawBody)\n\n    if (!isValidWebhookEvent(body)) {\n      return new Response(\n        JSON.stringify({ error: 'Invalid webhook event format' }),\n        { status: 400, headers: { 'Content-Type': 'application/json' } },\n      )\n    }\n\n    await handler(body as WebhookEvent<T, TData>)\n\n    return new Response(\n      JSON.stringify({ success: true, message: 'Webhook processed' }),\n      { status: 200, headers: { 'Content-Type': 'application/json' } },\n    )\n  } catch (error) {\n    console.error('Webhook processing error:', error)\n\n    return new Response(JSON.stringify({ error: 'Internal server error' }), {\n      status: 500,\n      headers: { 'Content-Type': 'application/json' },\n    })\n  }\n}\n\nexport function createTypedWebhookHandler<T extends Collection>(\n  collection: T,\n  handler: (event: WebhookEvent<T>) => Promise<void> | void,\n): WebhookHandler<T> {\n  return async (event: WebhookEvent<T>) => {\n    if (event.collection !== collection) {\n      throw new Error(\n        `Expected collection \"${collection}\", got \"${event.collection}\"`,\n      )\n    }\n    return handler(event)\n  }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/core/webhook/index.ts"],"sourcesContent":["import type { Collection } from '../client/types'\nimport type { CollectionType } from '../collection/types'\n\nexport type WebhookOperation = string\n\n/**\n * Semantic event type for manual Admin Panel ordering changes.\n *\n * Order-change webhooks remain `operation: \"update\"` events for compatibility.\n * Do not filter on or emit `operation: \"reorder\"`; use this event type with\n * `isOrderChangedWebhookEvent()` to distinguish ordering from normal content\n * updates.\n */\nexport const ORDER_CHANGED_EVENT_TYPE = 'collection.orderChanged' as const\n\n/** Collection webhook operations emitted for tenant collection writes. */\nexport type CollectionWebhookOperation = 'create' | 'update'\n\n/** Describes the ordered area affected by an order-change webhook. */\nexport type WebhookOrderScope =\n  | { kind: 'collection'; collection: string }\n  | { kind: 'join'; collection: string; field: string; id: string | number }\n\n/** Identifies the public moved document for the ordered scope. */\nexport type WebhookOrderMoved = {\n  collection: string\n  id: string | number\n  relatedCollection?: string\n  relatedId?: string | number\n}\n\n/** Metadata attached to `collection.orderChanged` webhook events. */\nexport type WebhookOrderChange = {\n  type: 'order'\n  source: 'payload-orderable'\n  /**\n   * Diagnostic Payload order field name.\n   *\n   * This may contain hidden implementation field names. Application routing\n   * should use `change.scope` and `change.moved` instead.\n   */\n  orderableFieldName?: string\n  previousOrder?: string | null\n  nextOrder?: string | null\n  scope: WebhookOrderScope\n  moved: WebhookOrderMoved\n}\n\n/** Known semantic webhook change metadata. */\nexport type WebhookChange = WebhookOrderChange\n\nexport interface WebhookEvent<\n  T extends Collection | string = Collection,\n  TData = T extends Collection ? CollectionType<T> : Record<string, unknown>,\n> {\n  collection: T\n  operation: WebhookOperation\n  data: TData\n  eventType?: string\n  change?: unknown\n  timestamp?: string\n  deliveryId?: string\n}\n\nexport type WebhookHandler<\n  T extends Collection | string = Collection,\n  TData = T extends Collection ? CollectionType<T> : Record<string, unknown>,\n> = (event: WebhookEvent<T, TData>) => Promise<void> | void\n\nexport interface WebhookOptions {\n  secret?: string\n  /** Max accepted skew for signed webhook delivery timestamps. Default: 300s. */\n  toleranceSeconds?: number\n}\n\nexport function isValidWebhookEvent(data: unknown): data is WebhookEvent {\n  if (typeof data !== 'object' || data === null) return false\n  const obj = data as Record<string, unknown>\n  return (\n    typeof obj.collection === 'string' &&\n    typeof obj.operation === 'string' &&\n    obj.operation.length > 0 &&\n    typeof obj.data === 'object' &&\n    obj.data !== null\n  )\n}\n\n/** Webhook event emitted when manual Admin Panel ordering changes. */\nexport type OrderChangedWebhookEvent<\n  T extends Collection | string = Collection,\n  TData = T extends Collection ? CollectionType<T> : Record<string, unknown>,\n> = WebhookEvent<T, TData> & {\n  operation: 'update'\n  eventType: typeof ORDER_CHANGED_EVENT_TYPE\n  change: WebhookOrderChange\n}\n\nfunction isStringOrNumber(value: unknown): value is string | number {\n  return typeof value === 'string' || typeof value === 'number'\n}\n\nfunction isWebhookOrderScope(value: unknown): value is WebhookOrderScope {\n  if (!isRecord(value)) return false\n\n  if (value.kind === 'collection') {\n    return typeof value.collection === 'string'\n  }\n\n  if (value.kind === 'join') {\n    return (\n      typeof value.collection === 'string' &&\n      typeof value.field === 'string' &&\n      isStringOrNumber(value.id)\n    )\n  }\n\n  return false\n}\n\nfunction isWebhookOrderMoved(value: unknown): value is WebhookOrderMoved {\n  if (!isRecord(value)) return false\n\n  return (\n    typeof value.collection === 'string' &&\n    isStringOrNumber(value.id) &&\n    (value.relatedCollection === undefined ||\n      typeof value.relatedCollection === 'string') &&\n    (value.relatedId === undefined || isStringOrNumber(value.relatedId))\n  )\n}\n\nfunction hasOptionalOrderValue(\n  value: Record<string, unknown>,\n  key: string,\n): boolean {\n  return (\n    value[key] === undefined ||\n    value[key] === null ||\n    typeof value[key] === 'string'\n  )\n}\n\nfunction isWebhookOrderChange(value: unknown): value is WebhookOrderChange {\n  if (!isRecord(value)) return false\n\n  return (\n    value.type === 'order' &&\n    value.source === 'payload-orderable' &&\n    (value.orderableFieldName === undefined ||\n      typeof value.orderableFieldName === 'string') &&\n    hasOptionalOrderValue(value, 'previousOrder') &&\n    hasOptionalOrderValue(value, 'nextOrder') &&\n    isWebhookOrderScope(value.scope) &&\n    isWebhookOrderMoved(value.moved)\n  )\n}\n\n/**\n * Returns true for semantic order-change webhooks emitted as update events.\n *\n * Use this guard with `ORDER_CHANGED_EVENT_TYPE` instead of filtering on\n * `operation: \"reorder\"`. Tenant order-change webhooks intentionally keep\n * `operation: \"update\"` for compatibility with existing webhook handlers.\n */\nexport function isOrderChangedWebhookEvent(\n  event: unknown,\n): event is OrderChangedWebhookEvent<string, unknown> {\n  if (\n    !isValidWebhookEvent(event) ||\n    event.operation !== 'update' ||\n    event.eventType !== ORDER_CHANGED_EVENT_TYPE ||\n    !isWebhookOrderChange(event.change)\n  ) {\n    return false\n  }\n\n  if (event.collection !== event.change.scope.collection) {\n    return false\n  }\n\n  if (\n    event.change.scope.kind === 'collection' &&\n    event.change.moved.collection !== event.change.scope.collection\n  ) {\n    return false\n  }\n\n  return true\n}\n\n/** Narrows a webhook event to a specific collection. */\nexport function isWebhookCollection<TCollection extends string>(\n  event: unknown,\n  collection: TCollection,\n): event is WebhookEvent<TCollection, unknown> {\n  return isValidWebhookEvent(event) && event.collection === collection\n}\n\n/** Narrows a webhook event to a specific operation. */\nexport function isWebhookOperation<TOperation extends string>(\n  event: unknown,\n  operation: TOperation,\n): event is WebhookEvent<string, unknown> & { operation: TOperation } {\n  return isValidWebhookEvent(event) && event.operation === operation\n}\n\nexport const CUSTOMER_PASSWORD_RESET_OPERATION = 'password-reset' as const\n\nexport type WebhookKnownOperation =\n  | CollectionWebhookOperation\n  | typeof CUSTOMER_PASSWORD_RESET_OPERATION\n\nexport interface CustomerPasswordResetWebhookData {\n  customerId: string | number\n  email: string\n  name: string\n  resetPasswordToken: string\n  resetPasswordExpiresAt: string\n}\n\nexport type CustomerPasswordResetWebhookEvent = WebhookEvent<\n  'customers',\n  CustomerPasswordResetWebhookData\n> & {\n  operation: typeof CUSTOMER_PASSWORD_RESET_OPERATION\n}\n\nexport type CustomerAuthWebhookEvent = CustomerPasswordResetWebhookEvent\n\ntype MaybePromise<T> = T | Promise<T>\n\nexport interface CustomerAuthWebhookHandlers {\n  passwordReset?: (\n    data: CustomerPasswordResetWebhookData,\n    event: CustomerPasswordResetWebhookEvent,\n  ) => MaybePromise<void>\n  unhandled?: (event: WebhookEvent<string, unknown>) => MaybePromise<void>\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null\n}\n\nfunction hasString(value: Record<string, unknown>, key: string): boolean {\n  return typeof value[key] === 'string'\n}\n\nfunction hasStringOrNumber(\n  value: Record<string, unknown>,\n  key: string,\n): boolean {\n  return typeof value[key] === 'string' || typeof value[key] === 'number'\n}\n\nexport function isCustomerPasswordResetWebhookEvent(\n  event: WebhookEvent<string, unknown>,\n): event is CustomerPasswordResetWebhookEvent {\n  if (\n    event.collection !== 'customers' ||\n    event.operation !== CUSTOMER_PASSWORD_RESET_OPERATION ||\n    !isRecord(event.data)\n  ) {\n    return false\n  }\n\n  return (\n    hasStringOrNumber(event.data, 'customerId') &&\n    hasString(event.data, 'email') &&\n    hasString(event.data, 'name') &&\n    hasString(event.data, 'resetPasswordToken') &&\n    hasString(event.data, 'resetPasswordExpiresAt')\n  )\n}\n\nexport function createCustomerAuthWebhookHandler(\n  handlers: CustomerAuthWebhookHandlers,\n): WebhookHandler<string, unknown> {\n  return async (event) => {\n    if (isCustomerPasswordResetWebhookEvent(event) && handlers.passwordReset) {\n      await handlers.passwordReset(event.data, event)\n      return\n    }\n\n    await handlers.unhandled?.(event)\n  }\n}\n\nasync function verifySignature(\n  payload: string,\n  secret: string,\n  signature: string,\n  timestamp: string,\n  deliveryId: string,\n): Promise<boolean> {\n  const encoder = new TextEncoder()\n  const key = await crypto.subtle.importKey(\n    'raw',\n    encoder.encode(secret),\n    { name: 'HMAC', hash: 'SHA-256' },\n    false,\n    ['verify'],\n  )\n  // Validate and convert hex signature to Uint8Array\n  if (signature.length % 2 !== 0 || !/^[0-9a-fA-F]*$/.test(signature)) {\n    return false\n  }\n  const sigBytes = new Uint8Array(\n    (signature.match(/.{2}/g) ?? []).map((byte) => parseInt(byte, 16)),\n  )\n  // crypto.subtle.verify performs constant-time comparison internally\n  return crypto.subtle.verify(\n    'HMAC',\n    key,\n    sigBytes,\n    encoder.encode(`${timestamp}.${deliveryId}.${payload}`),\n  )\n}\n\nfunction timestampIsFresh(\n  timestamp: string,\n  toleranceSeconds: number,\n): boolean {\n  if (!/^\\d+$/.test(timestamp)) return false\n  const timestampMs = Number(timestamp)\n  if (!Number.isFinite(timestampMs)) return false\n  const skewMs = Math.abs(Date.now() - timestampMs)\n  return skewMs <= toleranceSeconds * 1000\n}\n\nexport async function handleWebhook<\n  T extends Collection | string = Collection,\n  TData = T extends Collection ? CollectionType<T> : Record<string, unknown>,\n>(\n  request: Request,\n  handler: WebhookHandler<T, TData>,\n  options?: WebhookOptions,\n): Promise<Response> {\n  try {\n    const rawBody = await request.text()\n\n    if (options?.secret) {\n      const signature = request.headers.get('x-webhook-signature') || ''\n      const timestamp = request.headers.get('x-webhook-timestamp') || ''\n      const deliveryId = request.headers.get('x-webhook-delivery-id') || ''\n      const toleranceSeconds = options.toleranceSeconds ?? 300\n      const valid =\n        Boolean(timestamp && deliveryId) &&\n        timestampIsFresh(timestamp, toleranceSeconds) &&\n        (await verifySignature(\n          rawBody,\n          options.secret,\n          signature,\n          timestamp,\n          deliveryId,\n        ))\n      if (!valid) {\n        return new Response(\n          JSON.stringify({ error: 'Invalid webhook signature' }),\n          { status: 401, headers: { 'Content-Type': 'application/json' } },\n        )\n      }\n    } else {\n      console.warn(\n        '[@01.software/sdk] Webhook signature verification is disabled. ' +\n          'Set { secret } in handleWebhook() options to enable HMAC-SHA256 verification.',\n      )\n    }\n\n    const body = JSON.parse(rawBody)\n\n    if (!isValidWebhookEvent(body)) {\n      return new Response(\n        JSON.stringify({ error: 'Invalid webhook event format' }),\n        { status: 400, headers: { 'Content-Type': 'application/json' } },\n      )\n    }\n\n    await handler(body as WebhookEvent<T, TData>)\n\n    return new Response(\n      JSON.stringify({ success: true, message: 'Webhook processed' }),\n      { status: 200, headers: { 'Content-Type': 'application/json' } },\n    )\n  } catch (error) {\n    console.error('Webhook processing error:', error)\n\n    return new Response(JSON.stringify({ error: 'Internal server error' }), {\n      status: 500,\n      headers: { 'Content-Type': 'application/json' },\n    })\n  }\n}\n\nexport function createTypedWebhookHandler<T extends Collection>(\n  collection: T,\n  handler: (event: WebhookEvent<T>) => Promise<void> | void,\n): WebhookHandler<T> {\n  return async (event: WebhookEvent<T>) => {\n    if (event.collection !== collection) {\n      throw new Error(\n        `Expected collection \"${collection}\", got \"${event.collection}\"`,\n      )\n    }\n    return handler(event)\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@01.software/sdk",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "01.software SDK",
   "author": "<office@01.works>",
   "repository": {
@@ -211,8 +211,8 @@
     "tsup": "^8.5.1",
     "typescript": "5.7.3",
     "vitest": "3.2.3",
-    "@repo/eslint-config": "0.0.0",
-    "@repo/typescript-config": "0.0.0"
+    "@repo/typescript-config": "0.0.0",
+    "@repo/eslint-config": "0.0.0"
   },
   "dependencies": {
     "qs-esm": "^8.0.1"