@agentuity/server 1.0.21 → 1.0.23

package/dist/api/webhook/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/api/webhook/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB;;;;;;;;;GASG;AACH,eAAO,MAAM,4BAA4B;;EAAkB,CAAC;AAE5D;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAMlF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,2BAA2B;;;;EAA2C,CAAC;AAEpF;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAMhF;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa;;;;;;;;iBAexB,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAEpD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;iBAenC,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB;;;;;;iBAW/B,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;iBAmBhC,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAMpE;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IACjC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAMD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,0BAA0B;;;iBAKrC,CAAC;AAEH,2CAA2C;AAC3C,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,0BAA0B;;;iBAKrC,CAAC;AAEH,2CAA2C;AAC3C,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qCAAqC;;;;;iBAKhD,CAAC;AAEH,uDAAuD;AACvD,MAAM,MAAM,+BAA+B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qCAAqC,CAAC,CAAC;AAEpG;;;;;;;;;GASG;AACH,eAAO,MAAM,qCAAqC;;iBAGhD,CAAC;AAEH,uDAAuD;AACvD,MAAM,MAAM,+BAA+B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qCAAqC,CAAC,CAAC;AAEpG,eAAO,MAAM,uBAAuB;;;iBAGlC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE,eAAO,MAAM,yBAAyB;;;iBAA0B,CAAC;AAEjE,yCAAyC;AACzC,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,eAAO,MAAM,gCAAgC;;;iBAA0B,CAAC;AAExE,iDAAiD;AACjD,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gCAAgC,CAAC,CAAC;AAE1F,eAAO,MAAM,kCAAkC;;;iBAA0B,CAAC;AAE1E,mDAAmD;AACnD,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kCAAkC,CAAC,CAAC"}

package/dist/api/webhook/types.js

@@ -0,0 +1,221 @@
+import { z } from 'zod';
+// ============================================================================
+// Webhook Destination Types
+// ============================================================================
+/**
+ * Webhook destination type schema.
+ *
+ * Currently only 'url' destinations are supported.
+ *
+ * @example
+ * ```typescript
+ * const destType = WebhookDestinationTypeSchema.parse('url');
+ * ```
+ */
+export const WebhookDestinationTypeSchema = z.enum(['url']);
+// ============================================================================
+// Webhook Delivery Status
+// ============================================================================
+/**
+ * Webhook delivery status schema.
+ *
+ * - `pending`: Delivery is queued and waiting to be sent.
+ * - `success`: Delivery was completed successfully.
+ * - `failed`: Delivery failed after all retry attempts.
+ *
+ * @example
+ * ```typescript
+ * const status = WebhookDeliveryStatusSchema.parse('success');
+ * ```
+ */
+export const WebhookDeliveryStatusSchema = z.enum(['pending', 'success', 'failed']);
+// ============================================================================
+// Core Schemas
+// ============================================================================
+/**
+ * Webhook schema representing a webhook endpoint.
+ *
+ * @example
+ * ```typescript
+ * const webhook = await getWebhook(client, 'wh_abc123');
+ * console.log(`Webhook: ${webhook.name} (${webhook.id})`);
+ * ```
+ */
+export const WebhookSchema = z.object({
+    /** Unique identifier for the webhook (prefixed with wh_). */
+    id: z.string(),
+    /** ISO 8601 timestamp when the webhook was created. */
+    created_at: z.string(),
+    /** ISO 8601 timestamp when the webhook was last updated. */
+    updated_at: z.string(),
+    /** ID of the user who created the webhook. */
+    created_by: z.string(),
+    /** Human-readable webhook name. */
+    name: z.string(),
+    /** Optional description of the webhook's purpose. */
+    description: z.string().nullable().optional(),
+    /** Fully-qualified ingest URL for sending events to this webhook. Only present on create. */
+    url: z.string().optional(),
+});
+/**
+ * Webhook destination schema representing a delivery target for webhook events.
+ *
+ * Destinations define where incoming webhook payloads are forwarded to.
+ *
+ * @example
+ * ```typescript
+ * const destinations = await listWebhookDestinations(client, 'wh_abc123');
+ * for (const dest of destinations) {
+ *   console.log(`Destination ${dest.id}: type=${dest.type}`);
+ * }
+ * ```
+ */
+export const WebhookDestinationSchema = z.object({
+    /** Unique identifier for the destination (prefixed with whds_). */
+    id: z.string(),
+    /** ISO 8601 timestamp when the destination was created. */
+    created_at: z.string(),
+    /** ISO 8601 timestamp when the destination was last updated. */
+    updated_at: z.string(),
+    /** ID of the user who created the destination. */
+    created_by: z.string(),
+    /** ID of the webhook this destination belongs to. */
+    webhook_id: z.string(),
+    /** Type of destination (currently only 'url'). */
+    type: WebhookDestinationTypeSchema,
+    /** Configuration object for the destination (e.g., URL, headers). */
+    config: z.record(z.string(), z.unknown()),
+});
+/**
+ * Webhook receipt schema representing an incoming webhook payload that was received.
+ *
+ * Receipts capture the raw payload and headers of each incoming webhook request.
+ *
+ * @example
+ * ```typescript
+ * const receipt = await getWebhookReceipt(client, 'wh_abc123', 'whrc_def456');
+ * console.log(`Receipt ${receipt.id}: received at ${receipt.date}`);
+ * ```
+ */
+export const WebhookReceiptSchema = z.object({
+    /** Unique identifier for the receipt (prefixed with whrc_). */
+    id: z.string(),
+    /** ISO 8601 timestamp when the receipt was recorded. */
+    date: z.string(),
+    /** ID of the webhook this receipt belongs to. */
+    webhook_id: z.string(),
+    /** HTTP headers from the incoming webhook request. */
+    headers: z.record(z.string(), z.unknown()),
+    /** Raw payload from the incoming webhook request (can be any type). */
+    payload: z.unknown(),
+});
+/**
+ * Webhook delivery schema representing a delivery attempt to a destination.
+ *
+ * Deliveries track the status and result of forwarding a received webhook
+ * payload to a configured destination.
+ *
+ * @example
+ * ```typescript
+ * const deliveries = await listWebhookDeliveries(client, 'wh_abc123');
+ * for (const delivery of deliveries) {
+ *   console.log(`Delivery ${delivery.id}: ${delivery.status}`);
+ * }
+ * ```
+ */
+export const WebhookDeliverySchema = z.object({
+    /** Unique identifier for the delivery (prefixed with whdv_). */
+    id: z.string(),
+    /** ISO 8601 timestamp when the delivery was attempted. */
+    date: z.string(),
+    /** ID of the webhook this delivery belongs to. */
+    webhook_id: z.string(),
+    /** ID of the destination this delivery was sent to. */
+    webhook_destination_id: z.string(),
+    /** ID of the receipt that triggered this delivery. */
+    webhook_receipt_id: z.string(),
+    /** Current status of the delivery. */
+    status: WebhookDeliveryStatusSchema,
+    /** Number of retry attempts made. */
+    retries: z.number(),
+    /** Error message if the delivery failed. */
+    error: z.string().nullable().optional(),
+    /** Response data from the destination (if available). */
+    response: z.record(z.string(), z.unknown()).nullable().optional(),
+});
+// ============================================================================
+// Request Schemas
+// ============================================================================
+/**
+ * Request schema for creating a new webhook.
+ *
+ * @example
+ * ```typescript
+ * const request: CreateWebhookRequest = {
+ *   name: 'github-events',
+ *   description: 'Receives GitHub webhook events',
+ * };
+ * ```
+ */
+export const CreateWebhookRequestSchema = z.object({
+    /** Human-readable name for the webhook. */
+    name: z.string(),
+    /** Optional description of the webhook's purpose. */
+    description: z.string().optional(),
+});
+/**
+ * Request schema for updating an existing webhook.
+ *
+ * @example
+ * ```typescript
+ * const request: UpdateWebhookRequest = {
+ *   name: 'github-events-v2',
+ *   description: 'Updated description',
+ * };
+ * ```
+ */
+export const UpdateWebhookRequestSchema = z.object({
+    /** New name for the webhook. */
+    name: z.string(),
+    /** New description for the webhook. */
+    description: z.string().optional(),
+});
+/**
+ * Request schema for creating a webhook destination.
+ *
+ * @example
+ * ```typescript
+ * const request: CreateWebhookDestinationRequest = {
+ *   type: 'url',
+ *   config: { url: 'https://api.example.com/webhook' },
+ * };
+ * ```
+ */
+export const CreateWebhookDestinationRequestSchema = z.object({
+    /** Type of destination to create. */
+    type: WebhookDestinationTypeSchema,
+    /** Configuration object for the destination. */
+    config: z.record(z.string(), z.unknown()),
+});
+/**
+ * Request schema for updating a webhook destination.
+ *
+ * @example
+ * ```typescript
+ * const request: UpdateWebhookDestinationRequest = {
+ *   config: { url: 'https://api.example.com/webhook/v2' },
+ * };
+ * ```
+ */
+export const UpdateWebhookDestinationRequestSchema = z.object({
+    /** Updated configuration object for the destination. */
+    config: z.record(z.string(), z.unknown()).optional(),
+});
+export const PaginationRequestSchema = z.object({
+    limit: z.number().optional(),
+    offset: z.number().optional(),
+});
+export const ListWebhooksRequestSchema = PaginationRequestSchema;
+export const ListWebhookReceiptsRequestSchema = PaginationRequestSchema;
+export const ListWebhookDeliveriesRequestSchema = PaginationRequestSchema;
+//# sourceMappingURL=types.js.map

package/dist/api/webhook/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/api/webhook/types.ts"],"names":[],"mappings":"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"}

package/dist/api/webhook/util.d.ts

@@ -0,0 +1,202 @@
+/**
+ * General webhook operation error.
+ *
+ * Thrown when a webhook operation fails for reasons other than not-found.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await createWebhook(client, { name: 'my-webhook' });
+ * } catch (error) {
+ *   if (error instanceof WebhookError) {
+ *     console.error(`Webhook operation failed: ${error.message}`);
+ *   }
+ * }
+ * ```
+ */
+export declare const WebhookError: {
+    new (args?: ({
+        webhookId?: string;
+    } & {
+        message?: string;
+        cause?: unknown;
+    }) | undefined): import("@agentuity/core").RichError & {
+        readonly _tag: "WebhookError";
+    } & Readonly<{
+        webhookId?: string;
+    }>;
+    readonly defaultMessage?: string;
+};
+/**
+ * Error thrown when a webhook is not found.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await getWebhook(client, 'wh_nonexistent');
+ * } catch (error) {
+ *   if (error instanceof WebhookNotFoundError) {
+ *     console.error(`Webhook not found: ${error.webhookId}`);
+ *   }
+ * }
+ * ```
+ */
+export declare const WebhookNotFoundError: {
+    new (args?: ({
+        webhookId: string;
+    } & {
+        message?: string;
+        cause?: unknown;
+    }) | undefined): import("@agentuity/core").RichError & {
+        readonly _tag: "WebhookNotFoundError";
+    } & Readonly<{
+        webhookId: string;
+    }>;
+    readonly defaultMessage?: string;
+};
+/**
+ * Error thrown when a webhook destination is not found.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await deleteWebhookDestination(client, 'wh_abc', 'whds_nonexistent');
+ * } catch (error) {
+ *   if (error instanceof WebhookDestinationNotFoundError) {
+ *     console.error(`Destination ${error.destinationId} not found`);
+ *   }
+ * }
+ * ```
+ */
+export declare const WebhookDestinationNotFoundError: {
+    new (args?: ({
+        webhookId: string;
+        destinationId: string;
+    } & {
+        message?: string;
+        cause?: unknown;
+    }) | undefined): import("@agentuity/core").RichError & {
+        readonly _tag: "WebhookDestinationNotFoundError";
+    } & Readonly<{
+        webhookId: string;
+        destinationId: string;
+    }>;
+    readonly defaultMessage?: string;
+};
+/**
+ * Error thrown when a webhook receipt is not found.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await getWebhookReceipt(client, 'wh_abc', 'whrc_nonexistent');
+ * } catch (error) {
+ *   if (error instanceof WebhookReceiptNotFoundError) {
+ *     console.error(`Receipt ${error.receiptId} not found`);
+ *   }
+ * }
+ * ```
+ */
+export declare const WebhookReceiptNotFoundError: {
+    new (args?: ({
+        webhookId: string;
+        receiptId: string;
+    } & {
+        message?: string;
+        cause?: unknown;
+    }) | undefined): import("@agentuity/core").RichError & {
+        readonly _tag: "WebhookReceiptNotFoundError";
+    } & Readonly<{
+        webhookId: string;
+        receiptId: string;
+    }>;
+    readonly defaultMessage?: string;
+};
+/**
+ * Error thrown when a webhook delivery is not found.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await retryWebhookDelivery(client, 'wh_abc', 'whdv_nonexistent');
+ * } catch (error) {
+ *   if (error instanceof WebhookDeliveryNotFoundError) {
+ *     console.error(`Delivery ${error.deliveryId} not found`);
+ *   }
+ * }
+ * ```
+ */
+export declare const WebhookDeliveryNotFoundError: {
+    new (args?: ({
+        webhookId: string;
+        deliveryId: string;
+    } & {
+        message?: string;
+        cause?: unknown;
+    }) | undefined): import("@agentuity/core").RichError & {
+        readonly _tag: "WebhookDeliveryNotFoundError";
+    } & Readonly<{
+        webhookId: string;
+        deliveryId: string;
+    }>;
+    readonly defaultMessage?: string;
+};
+/**
+ * Constructs a full API path for webhook operations.
+ *
+ * Pattern: `/webhook/${VERSION}/${verb}/${segments.join('/')}`
+ * Each verb is unique to avoid route conflicts with the Go mux.
+ *
+ * @param verb - The action verb (e.g., 'create', 'list', 'get', 'destination-list')
+ * @param segments - Additional path segments (e.g., webhook ID, sub-resource ID)
+ * @returns The full API path with version and verb prefix
+ *
+ * @internal
+ */
+export declare function webhookApiPath(verb: string, ...segments: string[]): string;
+/**
+ * Constructs a full API path for webhook operations with query string.
+ *
+ * @param verb - The action verb
+ * @param queryString - Query string to append (without leading ?)
+ * @param segments - Additional path segments
+ * @returns The full API path with version, verb, and query string
+ *
+ * @internal
+ */
+export declare function webhookApiPathWithQuery(verb: string, queryString: string | undefined, ...segments: string[]): string;
+/**
+ * Constructs the public ingest URL for a webhook.
+ *
+ * Pattern: `/webhook/{orgId}-{webhookId}` (non-versioned, public)
+ *
+ * @param orgId - The organization ID
+ * @param webhookId - The webhook ID (prefixed with wh_)
+ * @returns The public ingest URL
+ *
+ * @internal
+ */
+export declare function webhookIngestPath(orgId: string, webhookId: string): string;
+/**
+ * Builds headers for webhook API requests.
+ *
+ * @param orgId - Optional organization ID for CLI authentication
+ * @returns Headers object to pass to API client
+ *
+ * @internal
+ */
+export declare function buildWebhookHeaders(orgId?: string): Record<string, string> | undefined;
+/**
+ * Wraps an API call and translates APIError with HTTP status codes to domain-specific webhook errors.
+ *
+ * - 404 → WebhookNotFoundError / WebhookDestinationNotFoundError / WebhookReceiptNotFoundError / WebhookDeliveryNotFoundError
+ *
+ * @internal
+ */
+export declare function withWebhookErrorHandling<T>(apiCall: () => Promise<T>, context: {
+    webhookId?: string;
+    destinationId?: string;
+    receiptId?: string;
+    deliveryId?: string;
+}): Promise<T>;
+//# sourceMappingURL=util.d.ts.map

package/dist/api/webhook/util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.d.ts","sourceRoot":"","sources":["../../../src/api/webhook/util.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,YAAY;;oBAAiD,MAAM;;;;;;;oBAAN,MAAM;;;CAAK,CAAC;AAEtF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,oBAAoB;;mBACrB,MAAM;;;;;;;mBAAN,MAAM;;;CACd,CAAC;AAEL;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,+BAA+B;;mBAChC,MAAM;uBACF,MAAM;;;;;;;mBADV,MAAM;uBACF,MAAM;;;CAClB,CAAC;AAEL;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,2BAA2B;;mBAC5B,MAAM;mBACN,MAAM;;;;;;;mBADN,MAAM;mBACN,MAAM;;;CACd,CAAC;AAEL;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,4BAA4B;;mBAC7B,MAAM;oBACL,MAAM;;;;;;;mBADP,MAAM;oBACL,MAAM;;;CACf,CAAC;AASL;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAM1E;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACtC,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,GAAG,QAAQ,EAAE,MAAM,EAAE,GACnB,MAAM,CAGR;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAE1E;AAMD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAKtF;AAMD;;;;;;GAMG;AACH,wBAAsB,wBAAwB,CAAC,CAAC,EAC/C,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACzB,OAAO,EAAE;IACR,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB,GACC,OAAO,CAAC,CAAC,CAAC,CAqCZ"}

package/dist/api/webhook/util.js

@@ -0,0 +1,201 @@
+import { StructuredError } from '@agentuity/core';
+import { APIError } from "../api.js";
+// ============================================================================
+// Error Types
+// ============================================================================
+/**
+ * General webhook operation error.
+ *
+ * Thrown when a webhook operation fails for reasons other than not-found.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await createWebhook(client, { name: 'my-webhook' });
+ * } catch (error) {
+ *   if (error instanceof WebhookError) {
+ *     console.error(`Webhook operation failed: ${error.message}`);
+ *   }
+ * }
+ * ```
+ */
+export const WebhookError = StructuredError('WebhookError')();
+/**
+ * Error thrown when a webhook is not found.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await getWebhook(client, 'wh_nonexistent');
+ * } catch (error) {
+ *   if (error instanceof WebhookNotFoundError) {
+ *     console.error(`Webhook not found: ${error.webhookId}`);
+ *   }
+ * }
+ * ```
+ */
+export const WebhookNotFoundError = StructuredError('WebhookNotFoundError')();
+/**
+ * Error thrown when a webhook destination is not found.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await deleteWebhookDestination(client, 'wh_abc', 'whds_nonexistent');
+ * } catch (error) {
+ *   if (error instanceof WebhookDestinationNotFoundError) {
+ *     console.error(`Destination ${error.destinationId} not found`);
+ *   }
+ * }
+ * ```
+ */
+export const WebhookDestinationNotFoundError = StructuredError('WebhookDestinationNotFoundError')();
+/**
+ * Error thrown when a webhook receipt is not found.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await getWebhookReceipt(client, 'wh_abc', 'whrc_nonexistent');
+ * } catch (error) {
+ *   if (error instanceof WebhookReceiptNotFoundError) {
+ *     console.error(`Receipt ${error.receiptId} not found`);
+ *   }
+ * }
+ * ```
+ */
+export const WebhookReceiptNotFoundError = StructuredError('WebhookReceiptNotFoundError')();
+/**
+ * Error thrown when a webhook delivery is not found.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await retryWebhookDelivery(client, 'wh_abc', 'whdv_nonexistent');
+ * } catch (error) {
+ *   if (error instanceof WebhookDeliveryNotFoundError) {
+ *     console.error(`Delivery ${error.deliveryId} not found`);
+ *   }
+ * }
+ * ```
+ */
+export const WebhookDeliveryNotFoundError = StructuredError('WebhookDeliveryNotFoundError')();
+// ============================================================================
+// API Path Helpers
+// ============================================================================
+/** Current Webhook API version. */
+const WEBHOOK_API_VERSION = '2026-02-24';
+/**
+ * Constructs a full API path for webhook operations.
+ *
+ * Pattern: `/webhook/${VERSION}/${verb}/${segments.join('/')}`
+ * Each verb is unique to avoid route conflicts with the Go mux.
+ *
+ * @param verb - The action verb (e.g., 'create', 'list', 'get', 'destination-list')
+ * @param segments - Additional path segments (e.g., webhook ID, sub-resource ID)
+ * @returns The full API path with version and verb prefix
+ *
+ * @internal
+ */
+export function webhookApiPath(verb, ...segments) {
+    const encoded = segments.map((s) => encodeURIComponent(s)).join('/');
+    if (encoded) {
+        return `/webhook/${WEBHOOK_API_VERSION}/${verb}/${encoded}`;
+    }
+    return `/webhook/${WEBHOOK_API_VERSION}/${verb}`;
+}
+/**
+ * Constructs a full API path for webhook operations with query string.
+ *
+ * @param verb - The action verb
+ * @param queryString - Query string to append (without leading ?)
+ * @param segments - Additional path segments
+ * @returns The full API path with version, verb, and query string
+ *
+ * @internal
+ */
+export function webhookApiPathWithQuery(verb, queryString, ...segments) {
+    const basePath = webhookApiPath(verb, ...segments);
+    return queryString ? `${basePath}?${queryString}` : basePath;
+}
+/**
+ * Constructs the public ingest URL for a webhook.
+ *
+ * Pattern: `/webhook/{orgId}-{webhookId}` (non-versioned, public)
+ *
+ * @param orgId - The organization ID
+ * @param webhookId - The webhook ID (prefixed with wh_)
+ * @returns The public ingest URL
+ *
+ * @internal
+ */
+export function webhookIngestPath(orgId, webhookId) {
+    return `/webhook/${encodeURIComponent(orgId)}-${encodeURIComponent(webhookId)}`;
+}
+// ============================================================================
+// Header Builder
+// ============================================================================
+/**
+ * Builds headers for webhook API requests.
+ *
+ * @param orgId - Optional organization ID for CLI authentication
+ * @returns Headers object to pass to API client
+ *
+ * @internal
+ */
+export function buildWebhookHeaders(orgId) {
+    if (orgId) {
+        return { 'x-agentuity-orgid': orgId };
+    }
+    return undefined;
+}
+// ============================================================================
+// Error Handling
+// ============================================================================
+/**
+ * Wraps an API call and translates APIError with HTTP status codes to domain-specific webhook errors.
+ *
+ * - 404 → WebhookNotFoundError / WebhookDestinationNotFoundError / WebhookReceiptNotFoundError / WebhookDeliveryNotFoundError
+ *
+ * @internal
+ */
+export async function withWebhookErrorHandling(apiCall, context) {
+    try {
+        return await apiCall();
+    }
+    catch (error) {
+        if (error instanceof APIError) {
+            if (error.status === 404) {
+                if (context.deliveryId && context.webhookId) {
+                    throw new WebhookDeliveryNotFoundError({
+                        webhookId: context.webhookId,
+                        deliveryId: context.deliveryId,
+                        message: error.message,
+                    });
+                }
+                if (context.receiptId && context.webhookId) {
+                    throw new WebhookReceiptNotFoundError({
+                        webhookId: context.webhookId,
+                        receiptId: context.receiptId,
+                        message: error.message,
+                    });
+                }
+                if (context.destinationId && context.webhookId) {
+                    throw new WebhookDestinationNotFoundError({
+                        webhookId: context.webhookId,
+                        destinationId: context.destinationId,
+                        message: error.message,
+                    });
+                }
+                if (context.webhookId) {
+                    throw new WebhookNotFoundError({
+                        webhookId: context.webhookId,
+                        message: error.message,
+                    });
+                }
+            }
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=util.js.map

package/dist/api/webhook/util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.js","sourceRoot":"","sources":["../../../src/api/webhook/util.ts"],"names":[],"mappings":"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"}