autotel 3.6.0 → 4.0.0

package/dist/webhook.d.ts

@@ -1,58 +1,23 @@
-import { Link, SpanContext } from '@opentelemetry/api';
-import { T as TraceContext } from './trace-context-DbGKd1Rn.js';
-
-/**
- * Webhook and callback tracing with the "Parking Lot" pattern
- *
- * When initiating async operations that return hours/days later (webhooks,
- * payment callbacks, human approvals), you can't keep a span open. This module
- * provides utilities to "park" trace context and retrieve it when callbacks arrive.
- *
- * @example Stripe payment webhook
- * ```typescript
- * import { createParkingLot, InMemoryTraceContextStore } from 'autotel/webhook';
- *
- * const parkingLot = createParkingLot({
- *   store: new InMemoryTraceContextStore(),
- *   defaultTTLMs: 24 * 60 * 60 * 1000, // 24 hours
- * });
- *
- * // When initiating payment
- * export const initiatePayment = trace(ctx => async (orderId: string) => {
- *   await parkingLot.park(`payment:${orderId}`, { orderId });
- *   await stripeClient.createPaymentIntent({ metadata: { orderId } });
- * });
- *
- * // When Stripe webhook arrives (hours later)
- * export const handleStripeWebhook = parkingLot.traceCallback({
- *   name: 'stripe.webhook.payment_intent.succeeded',
- *   correlationKeyFrom: (event) => `payment:${event.data.object.metadata.orderId}`,
- * })(ctx => async (event: Stripe.Event) => {
- *   // ctx.parkedContext contains the original trace context
- *   // ctx.elapsedMs shows time since payment was initiated
- *   await fulfillOrder(event.data.object);
- * });
- * ```
- *
- * @module
- */
+import { n as TraceContext } from "./trace-context-Cijqoi6e.js";
+import { Link, SpanContext } from "@opentelemetry/api";
 
+//#region src/webhook.d.ts
 /**
  * Stored trace context for parking lot pattern
  */
 interface StoredTraceContext {
-    /** Trace ID from the original span */
-    traceId: string;
-    /** Span ID from the original span */
-    spanId: string;
-    /** Trace flags (sampling decision) */
-    traceFlags: number;
-    /** When the context was parked */
-    parkedAt: number;
-    /** Optional TTL in milliseconds */
-    ttlMs?: number;
-    /** User-provided metadata */
-    metadata?: Record<string, string>;
+  /** Trace ID from the original span */
+  traceId: string;
+  /** Span ID from the original span */
+  spanId: string;
+  /** Trace flags (sampling decision) */
+  traceFlags: number;
+  /** When the context was parked */
+  parkedAt: number;
+  /** Optional TTL in milliseconds */
+  ttlMs?: number;
+  /** User-provided metadata */
+  metadata?: Record<string, string>;
 }
 /**
  * Interface for trace context storage backends
@@ -60,143 +25,143 @@ interface StoredTraceContext {
  * Implement this interface to use different storage backends (Redis, DynamoDB, etc.)
  */
 interface TraceContextStore {
-    /**
-     * Save trace context with a correlation key
-     *
-     * @param key - Unique correlation key (e.g., "payment:order-123")
-     * @param context - The trace context to store
-     */
-    save(key: string, context: StoredTraceContext): Promise<void>;
-    /**
-     * Load trace context by correlation key
-     *
-     * @param key - The correlation key used when parking
-     * @returns The stored context, or null if not found/expired
-     */
-    load(key: string): Promise<StoredTraceContext | null>;
-    /**
-     * Delete trace context by correlation key
-     *
-     * @param key - The correlation key to delete
-     */
-    delete(key: string): Promise<void>;
+  /**
+   * Save trace context with a correlation key
+   *
+   * @param key - Unique correlation key (e.g., "payment:order-123")
+   * @param context - The trace context to store
+   */
+  save(key: string, context: StoredTraceContext): Promise<void>;
+  /**
+   * Load trace context by correlation key
+   *
+   * @param key - The correlation key used when parking
+   * @returns The stored context, or null if not found/expired
+   */
+  load(key: string): Promise<StoredTraceContext | null>;
+  /**
+   * Delete trace context by correlation key
+   *
+   * @param key - The correlation key to delete
+   */
+  delete(key: string): Promise<void>;
 }
 /**
  * Configuration for creating a parking lot
  */
 interface ParkingLotConfig {
-    /** Storage backend for parked contexts */
-    store: TraceContextStore;
-    /** Default TTL in milliseconds (default: 24 hours) */
-    defaultTTLMs?: number;
-    /** Prefix for all correlation keys (default: "parkingLot:") */
-    keyPrefix?: string;
-    /** Whether to auto-delete after retrieval (default: true) */
-    autoDeleteOnRetrieve?: boolean;
-    /** Callback when context expires or is not found */
-    onMiss?: (correlationKey: string) => void;
+  /** Storage backend for parked contexts */
+  store: TraceContextStore;
+  /** Default TTL in milliseconds (default: 24 hours) */
+  defaultTTLMs?: number;
+  /** Prefix for all correlation keys (default: "parkingLot:") */
+  keyPrefix?: string;
+  /** Whether to auto-delete after retrieval (default: true) */
+  autoDeleteOnRetrieve?: boolean;
+  /** Callback when context expires or is not found */
+  onMiss?: (correlationKey: string) => void;
 }
 /**
  * Configuration for traceCallback wrapper
  */
 interface CallbackConfig {
-    /** Span name for the callback handler */
-    name: string;
-    /**
-     * Extract correlation key from callback arguments
-     *
-     * @example
-     * ```typescript
-     * correlationKeyFrom: (event) => `payment:${event.data.orderId}`
-     * ```
-     */
-    correlationKeyFrom: (args: unknown[]) => string;
-    /** Additional span attributes */
-    attributes?: Record<string, string | number | boolean>;
-    /** Whether to fail if parked context is not found (default: false) */
-    requireParkedContext?: boolean;
+  /** Span name for the callback handler */
+  name: string;
+  /**
+   * Extract correlation key from callback arguments
+   *
+   * @example
+   * ```typescript
+   * correlationKeyFrom: (event) => `payment:${event.data.orderId}`
+   * ```
+   */
+  correlationKeyFrom: (args: unknown[]) => string;
+  /** Additional span attributes */
+  attributes?: Record<string, string | number | boolean>;
+  /** Whether to fail if parked context is not found (default: false) */
+  requireParkedContext?: boolean;
 }
 /**
  * Extended context for callback handlers
  */
 interface CallbackContext extends TraceContext {
-    /** The retrieved parked context, if found */
-    parkedContext: StoredTraceContext | null;
-    /** Time elapsed since context was parked (ms), or null if not found */
-    elapsedMs: number | null;
-    /** The correlation key used for retrieval */
-    correlationKey: string;
+  /** The retrieved parked context, if found */
+  parkedContext: StoredTraceContext | null;
+  /** Time elapsed since context was parked (ms), or null if not found */
+  elapsedMs: number | null;
+  /** The correlation key used for retrieval */
+  correlationKey: string;
 }
 /**
  * The parking lot instance
  */
 interface ParkingLot {
-    /**
-     * Park current trace context before initiating async operation
-     *
-     * Call this before sending a webhook, initiating a payment, or starting
-     * any operation that will complete via callback.
-     *
-     * @param correlationKey - Unique key to retrieve context later (e.g., "payment:order-123")
-     * @param metadata - Optional metadata to store with the context
-     * @returns The correlation key (with prefix applied)
-     *
-     * @example
-     * ```typescript
-     * await parkingLot.park(`payment:${orderId}`, {
-     *   customerId: customer.id,
-     *   amount: payment.amount.toString(),
-     * });
-     * ```
-     */
-    park(correlationKey: string, metadata?: Record<string, string>): Promise<string>;
-    /**
-     * Retrieve parked context when callback arrives
-     *
-     * @param correlationKey - The key used when parking
-     * @returns The stored context, or null if not found/expired
-     */
-    retrieve(correlationKey: string): Promise<StoredTraceContext | null>;
-    /**
-     * Wrap a callback handler with automatic context retrieval and linking
-     *
-     * Creates a traced function that:
-     * 1. Extracts correlation key from arguments
-     * 2. Retrieves parked context from storage
-     * 3. Creates a span link to the original trace
-     * 4. Provides elapsed time since parking
-     *
-     * @param config - Callback configuration
-     * @returns Factory function for the callback handler
-     *
-     * @example
-     * ```typescript
-     * export const handleWebhook = parkingLot.traceCallback({
-     *   name: 'webhook.payment.completed',
-     *   correlationKeyFrom: (args) => `payment:${args[0].orderId}`,
-     * })(ctx => async (event) => {
-     *   console.log(`Payment completed after ${ctx.elapsedMs}ms`);
-     *   await processPayment(event);
-     * });
-     * ```
-     */
-    traceCallback<TArgs extends unknown[], TReturn>(config: CallbackConfig): (fnFactory: (ctx: CallbackContext) => (...args: TArgs) => Promise<TReturn>) => (...args: TArgs) => Promise<TReturn>;
-    /**
-     * Manually create a span link from stored context
-     *
-     * Useful when you need more control over span creation.
-     *
-     * @param storedContext - The stored trace context
-     * @returns A span link that can be added to a span
-     */
-    createLink(storedContext: StoredTraceContext): Link;
-    /**
-     * Check if a parked context exists (without retrieving/deleting it)
-     *
-     * @param correlationKey - The key to check
-     * @returns True if context exists and hasn't expired
-     */
-    exists(correlationKey: string): Promise<boolean>;
+  /**
+   * Park current trace context before initiating async operation
+   *
+   * Call this before sending a webhook, initiating a payment, or starting
+   * any operation that will complete via callback.
+   *
+   * @param correlationKey - Unique key to retrieve context later (e.g., "payment:order-123")
+   * @param metadata - Optional metadata to store with the context
+   * @returns The correlation key (with prefix applied)
+   *
+   * @example
+   * ```typescript
+   * await parkingLot.park(`payment:${orderId}`, {
+   *   customerId: customer.id,
+   *   amount: payment.amount.toString(),
+   * });
+   * ```
+   */
+  park(correlationKey: string, metadata?: Record<string, string>): Promise<string>;
+  /**
+   * Retrieve parked context when callback arrives
+   *
+   * @param correlationKey - The key used when parking
+   * @returns The stored context, or null if not found/expired
+   */
+  retrieve(correlationKey: string): Promise<StoredTraceContext | null>;
+  /**
+   * Wrap a callback handler with automatic context retrieval and linking
+   *
+   * Creates a traced function that:
+   * 1. Extracts correlation key from arguments
+   * 2. Retrieves parked context from storage
+   * 3. Creates a span link to the original trace
+   * 4. Provides elapsed time since parking
+   *
+   * @param config - Callback configuration
+   * @returns Factory function for the callback handler
+   *
+   * @example
+   * ```typescript
+   * export const handleWebhook = parkingLot.traceCallback({
+   *   name: 'webhook.payment.completed',
+   *   correlationKeyFrom: (args) => `payment:${args[0].orderId}`,
+   * })(ctx => async (event) => {
+   *   console.log(`Payment completed after ${ctx.elapsedMs}ms`);
+   *   await processPayment(event);
+   * });
+   * ```
+   */
+  traceCallback<TArgs extends unknown[], TReturn>(config: CallbackConfig): (fnFactory: (ctx: CallbackContext) => (...args: TArgs) => Promise<TReturn>) => (...args: TArgs) => Promise<TReturn>;
+  /**
+   * Manually create a span link from stored context
+   *
+   * Useful when you need more control over span creation.
+   *
+   * @param storedContext - The stored trace context
+   * @returns A span link that can be added to a span
+   */
+  createLink(storedContext: StoredTraceContext): Link;
+  /**
+   * Check if a parked context exists (without retrieving/deleting it)
+   *
+   * @param correlationKey - The key to check
+   * @returns True if context exists and hasn't expired
+   */
+  exists(correlationKey: string): Promise<boolean>;
 }
 /**
  * In-memory trace context store
@@ -211,29 +176,28 @@ interface ParkingLot {
  * ```
  */
 declare class InMemoryTraceContextStore implements TraceContextStore {
-    private options;
-    private store;
-    private cleanupInterval;
-    constructor(options?: {
-        /** Cleanup interval in ms (default: 60000) */
-        cleanupIntervalMs?: number;
-    });
-    save(key: string, context: StoredTraceContext): Promise<void>;
-    load(key: string): Promise<StoredTraceContext | null>;
-    delete(key: string): Promise<void>;
-    /**
-     * Get number of stored contexts (for testing)
-     */
-    get size(): number;
-    /**
-     * Clear all stored contexts (for testing)
-     */
-    clear(): void;
-    /**
-     * Stop the cleanup interval
-     */
-    destroy(): void;
-    private cleanup;
+  private options;
+  private store;
+  private cleanupInterval;
+  constructor(options?: {
+    /** Cleanup interval in ms (default: 60000) */cleanupIntervalMs?: number;
+  });
+  save(key: string, context: StoredTraceContext): Promise<void>;
+  load(key: string): Promise<StoredTraceContext | null>;
+  delete(key: string): Promise<void>;
+  /**
+   * Get number of stored contexts (for testing)
+   */
+  get size(): number;
+  /**
+   * Clear all stored contexts (for testing)
+   */
+  clear(): void;
+  /**
+   * Stop the cleanup interval
+   */
+  destroy(): void;
+  private cleanup;
 }
 /**
  * Create a parking lot for trace context storage and retrieval
@@ -295,5 +259,6 @@ declare function createCorrelationKey(...parts: (string | number)[]): string;
  * @returns SpanContext compatible object
  */
 declare function toSpanContext(storedContext: StoredTraceContext): SpanContext;
-
-export { type CallbackConfig, type CallbackContext, InMemoryTraceContextStore, type ParkingLot, type ParkingLotConfig, type StoredTraceContext, type TraceContextStore, createCorrelationKey, createParkingLot, toSpanContext };
+//#endregion
+export { CallbackConfig, CallbackContext, InMemoryTraceContextStore, ParkingLot, ParkingLotConfig, StoredTraceContext, TraceContextStore, createCorrelationKey, createParkingLot, toSpanContext };
+//# sourceMappingURL=webhook.d.ts.map

package/dist/webhook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.d.ts","names":[],"sources":["../src/webhook.ts"],"mappings":";;;;;;;UAkDiB,kBAAA;EAqDA;EAnDf,OAAA;;EAGA,MAAA;EAkDA;EA/CA,UAAA;EAkDA;EA/CA,QAAA;EAqDA;EAlDA,KAAA;EAqDU;EAlDV,QAAA,GAAW,MAAM;AAAA;AAwDnB;;;;;AAAA,UAhDiB,iBAAA;EA4DM;;;;;AAMD;EA3DpB,IAAA,CAAK,GAAA,UAAa,OAAA,EAAS,kBAAA,GAAqB,OAAA;EAiEjB;;;;;;EAzD/B,IAAA,CAAK,GAAA,WAAc,OAAA,CAAQ,kBAAA;EAiE3B;;AAAc;AAMhB;;EAhEE,MAAA,CAAO,GAAA,WAAc,OAAA;AAAA;;;;UAMN,gBAAA;EAoHI;EAlHnB,KAAA,EAAO,iBAAiB;EAkH2C;EA/GnE,YAAA;EAgHe;EA7Gf,SAAA;EA6GyB;EA1GzB,oBAAA;EAoH+C;EAjH/C,MAAA,IAAU,cAAA;AAAA;;;;UAMK,cAAA;EA2Db;EAzDF,IAAA;EAkEA;;;;;;;;EAxDA,kBAAA,GAAqB,IAAA;EAoFF;EAjFnB,UAAA,GAAa,MAAM;EAiFwB;EA9E3C,oBAAA;AAAA;;;;UAMe,eAAA,SAAwB,YAAY;EAyE1B;EAvEzB,aAAA,EAAe,kBAAA;EAiFf;EA9EA,SAAA;EA8EW;EA3EX,cAAA;AAAA;;;;UAMe,UAAA;EAgGJ;;;;;;;;;;;;;;;;;;EA7EX,IAAA,CACE,cAAA,UACA,QAAA,GAAW,MAAA,mBACV,OAAA;EA+FQ;;;;;;EAvFX,QAAA,CAAS,cAAA,WAAyB,OAAA,CAAQ,kBAAA;EA2FT;;;;;;;;;AA8ClB;AAwDjB;;;;;;;;AAAsE;AA2OtE;;;;EAnZE,aAAA,mCACE,MAAA,EAAQ,cAAA,IAER,SAAA,GAAY,GAAA,EAAK,eAAA,SAAwB,IAAA,EAAM,KAAA,KAAU,OAAA,CAAQ,OAAA,UAC1D,IAAA,EAAM,KAAA,KAAU,OAAA,CAAQ,OAAA;EAyZnB;;;;;;;;EA/Yd,UAAA,CAAW,aAAA,EAAe,kBAAA,GAAqB,IAAA;;;;;;;EAQ/C,MAAA,CAAO,cAAA,WAAyB,OAAA;AAAA;;;;;;;;;;;;;cAmBrB,yBAAA,YAAqC,iBAAA;EAAA,QAKtC,OAAA;EAAA,QAJF,KAAA;EAAA,QACA,eAAA;cAGE,OAAA;kDAEN,iBAAA;EAAA;EAcE,IAAA,CAAK,GAAA,UAAa,OAAA,EAAS,kBAAA,GAAqB,OAAA;EAIhD,IAAA,CAAK,GAAA,WAAc,OAAA,CAAQ,kBAAA;EAkB3B,MAAA,CAAO,GAAA,WAAc,OAAA;;;;MAOvB,IAAA;;;;EAOJ,KAAA;;;;EAOA,OAAA;EAAA,QAOQ,OAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAwDM,gBAAA,CAAiB,MAAA,EAAQ,gBAAA,GAAmB,UAAU;;;;;;;;;;;;;iBA2OtD,oBAAA,IAAwB,KAAK;;;;;;;iBAU7B,aAAA,CAAc,aAAA,EAAe,kBAAA,GAAqB,WAAW"}