@agentuity/core 1.0.32 → 1.0.34

package/src/services/{webhook.ts → webhook/service.ts}

@@ -1,6 +1,15 @@
-import { FetchAdapter } from './adapter.ts';
-import { buildUrl, toServiceException } from './_util.ts';
-import { StructuredError } from '../error.ts';
+import { FetchAdapter } from '../adapter.ts';
+import { buildUrl, toServiceException } from '../_util.ts';
+import { StructuredError } from '../../error.ts';
+import type {
+	CreateWebhookDestinationRequest,
+	CreateWebhookRequest,
+	UpdateWebhookRequest,
+	Webhook,
+	WebhookDelivery,
+	WebhookDestination,
+	WebhookReceipt,
+} from './types.ts';
 
 /**
  * Creates an {@link AbortSignal} that will abort after the specified timeout.
@@ -24,259 +33,106 @@ function createTimeoutSignal(ms = 30_000): AbortSignal {
 	return controller.signal;
 }
 
-/**
- * A webhook endpoint that can receive HTTP requests. Each webhook has a unique
- * ingest URL and can forward received payloads to configured destinations.
- */
-export interface Webhook {
-	/** Unique identifier for the webhook. */
-	id: string;
-
-	/** ISO 8601 timestamp when the webhook was created. */
-	created_at: string;
-
-	/** ISO 8601 timestamp when the webhook was last modified. */
-	updated_at: string;
-
-	/** ID of the user who created the webhook. */
-	created_by: string;
-
-	/** Human-readable name for the webhook. */
-	name: string;
-
-	/** Optional description of the webhook's purpose. */
-	description: string | null;
-
-	/**
-	 * The fully-qualified ingest URL where HTTP requests should be sent.
-	 *
-	 * @remarks Format: `https://<catalyst-url>/webhook/<orgId>-<webhookId>`
-	 */
-	url: string;
-}
-
-/**
- * A delivery target for a webhook. When an HTTP request is received at the
- * webhook's ingest URL, the payload is forwarded to each of its destinations.
- */
-export interface WebhookDestination {
-	/** Unique identifier for the destination. */
-	id: string;
-
-	/** The ID of the parent webhook. */
-	webhook_id: string;
-
-	/** ISO 8601 timestamp when the destination was created. */
-	created_at: string;
-
-	/** ISO 8601 timestamp when the destination was last modified. */
-	updated_at: string;
-
-	/** ID of the user who created the destination. */
-	created_by: string;
-
-	/**
-	 * The destination type.
-	 *
-	 * @remarks Currently only `'url'` is supported.
-	 */
-	type: string;
-
-	/**
-	 * Destination-specific configuration.
-	 *
-	 * @remarks For `'url'` type: `{ url: string, headers?: Record<string, string> }`.
-	 * The URL must use http or https.
-	 */
-	config: Record<string, unknown>;
-}
-
-/**
- * A record of an HTTP request received at a webhook's ingest URL. Each receipt
- * captures the request headers and payload for auditing and replay.
- */
-export interface WebhookReceipt {
-	/** Unique identifier for the receipt. */
-	id: string;
-
-	/** ISO 8601 timestamp when the request was received. */
-	date: string;
-
-	/** The ID of the webhook that received the request. */
-	webhook_id: string;
-
-	/** HTTP headers from the incoming request. */
-	headers: Record<string, string>;
-
-	/** The request body/payload, preserved in its original form. */
-	payload: unknown;
-}
-
-/**
- * A record of a delivery attempt from a webhook receipt to a destination.
- * Tracks the forwarding status and supports retries for failed deliveries.
- */
-export interface WebhookDelivery {
-	/** Unique identifier for the delivery attempt. */
-	id: string;
-
-	/** ISO 8601 timestamp when the delivery was attempted. */
-	date: string;
-
-	/** The ID of the parent webhook. */
-	webhook_id: string;
-
-	/** The ID of the destination this delivery was sent to. */
-	webhook_destination_id: string;
-
-	/** The ID of the receipt that triggered this delivery. */
-	webhook_receipt_id: string;
-
-	/**
-	 * Delivery status.
-	 *
-	 * - `'pending'` — Queued for delivery.
-	 * - `'success'` — Successfully delivered.
-	 * - `'failed'` — Delivery error occurred.
-	 */
-	status: 'pending' | 'success' | 'failed';
-
-	/** Number of retry attempts made. */
-	retries: number;
-
-	/** Error message if delivery failed, `null` on success. */
-	error: string | null;
-
-	/** The response received from the destination endpoint, or `null`. */
-	response: Record<string, unknown> | null;
-}
-
 /**
  * Parameters for creating a new webhook.
  */
-export interface CreateWebhookParams {
-	/** Human-readable name for the webhook (required). */
-	name: string;
-
-	/** Optional description of the webhook's purpose. */
-	description?: string;
-}
+export type CreateWebhookParams = CreateWebhookRequest;
 
 /**
- * Parameters for updating a webhook. Only provided fields are modified.
+ * Parameters for updating a webhook.
  */
-export interface UpdateWebhookParams {
-	/** Updated name. */
-	name?: string;
-
-	/** Updated description. */
-	description?: string;
-}
+export type UpdateWebhookParams = UpdateWebhookRequest;
 
 /**
  * Parameters for creating a new webhook destination.
  */
-export interface CreateWebhookDestinationParams {
-	/**
-	 * The destination type.
-	 *
-	 * @remarks Currently only `'url'` is supported.
-	 */
-	type: string;
-
-	/**
-	 * Type-specific configuration.
-	 *
-	 * @remarks For `'url'` type: `{ url: string, headers?: Record<string, string> }`.
-	 */
-	config: Record<string, unknown>;
-}
+export type CreateWebhookDestinationParams = CreateWebhookDestinationRequest;
 
 /**
  * Paginated list of webhooks.
  */
-export interface WebhookListResult {
+export type WebhookListResult = {
 	/** Array of webhooks. */
 	webhooks: Webhook[];
 
 	/** Total number of webhooks. */
 	total: number;
-}
+};
 
 /**
  * Result of fetching a single webhook, including its configured destinations.
  */
-export interface WebhookGetResult {
+export type WebhookGetResult = {
 	/** The requested webhook. */
 	webhook: Webhook;
 
 	/** Array of destinations configured for this webhook. */
 	destinations: WebhookDestination[];
-}
+};
 
 /**
  * Result of creating a webhook.
  */
-export interface WebhookCreateResult {
+export type WebhookCreateResult = {
 	/** The newly created webhook. */
 	webhook: Webhook;
-}
+};
 
 /**
  * Result of updating a webhook.
  */
-export interface UpdateWebhookResult {
+export type UpdateWebhookResult = {
 	/** The updated webhook. */
 	webhook: Webhook;
-}
+};
 
 /**
  * Result of creating a webhook destination.
  */
-export interface CreateDestinationResult {
+export type CreateDestinationResult = {
 	/** The newly created destination. */
 	destination: WebhookDestination;
-}
+};
 
 /**
  * List of destinations for a webhook.
  */
-export interface ListDestinationsResult {
+export type ListDestinationsResult = {
 	/** Array of destinations. */
 	destinations: WebhookDestination[];
-}
+};
 
 /**
  * List of receipts (incoming requests) for a webhook.
  */
-export interface WebhookReceiptListResult {
+export type WebhookReceiptListResult = {
 	/** Array of receipt records. */
 	receipts: WebhookReceipt[];
-}
+};
 
 /**
  * List of delivery attempts for a webhook.
  */
-export interface WebhookDeliveryListResult {
+export type WebhookDeliveryListResult = {
 	/** Array of delivery records. */
 	deliveries: WebhookDelivery[];
-}
+};
 
 /**
  * Internal API success response envelope for webhook operations.
  */
-interface WebhookSuccessResponse<T> {
+type WebhookSuccessResponse<T> = {
 	success: true;
 	data: T;
-}
+};
 
 /**
  * Internal API error response envelope for webhook operations.
  */
-interface WebhookErrorResponse {
+type WebhookErrorResponse = {
 	success: false;
 	message: string;
-}
+};
 
 /**
  * Discriminated union of API success and error responses for webhook operations.
@@ -371,7 +227,7 @@ export class WebhookService {
 	 * ```
 	 */
 	async create(params: CreateWebhookParams): Promise<WebhookCreateResult> {
-		const url = buildUrl(this.#baseUrl, '/webhook/2026-02-24/create');
+		const url = buildUrl(this.#baseUrl, '/webhook/create');
 		const signal = createTimeoutSignal();
 		const res = await this.#adapter.invoke<WebhookResponse<Webhook>>(url, {
 			method: 'POST',
@@ -421,9 +277,7 @@ export class WebhookService {
 			qs.set('offset', String(params.offset));
 		}
 
-		const path = qs.toString()
-			? `/webhook/2026-02-24/list?${qs.toString()}`
-			: '/webhook/2026-02-24/list';
+		const path = qs.toString() ? `/webhook/list?${qs.toString()}` : '/webhook/list';
 		const url = buildUrl(this.#baseUrl, path);
 		const signal = createTimeoutSignal();
 		const res = await this.#adapter.invoke<WebhookResponse<Webhook[]>>(url, {
@@ -469,10 +323,7 @@ export class WebhookService {
 	 * ```
 	 */
 	async get(webhookId: string): Promise<WebhookGetResult> {
-		const url = buildUrl(
-			this.#baseUrl,
-			`/webhook/2026-02-24/get/${encodeURIComponent(webhookId)}`
-		);
+		const url = buildUrl(this.#baseUrl, `/webhook/get/${encodeURIComponent(webhookId)}`);
 		const signal = createTimeoutSignal();
 		const res = await this.#adapter.invoke<WebhookResponse<Webhook>>(url, {
 			method: 'GET',
@@ -514,10 +365,7 @@ export class WebhookService {
 	 * ```
 	 */
 	async update(webhookId: string, params: UpdateWebhookParams): Promise<UpdateWebhookResult> {
-		const url = buildUrl(
-			this.#baseUrl,
-			`/webhook/2026-02-24/update/${encodeURIComponent(webhookId)}`
-		);
+		const url = buildUrl(this.#baseUrl, `/webhook/update/${encodeURIComponent(webhookId)}`);
 		const signal = createTimeoutSignal();
 		const res = await this.#adapter.invoke<WebhookResponse<Webhook>>(url, {
 			method: 'PUT',
@@ -555,10 +403,7 @@ export class WebhookService {
 	 * ```
 	 */
 	async delete(webhookId: string): Promise<void> {
-		const url = buildUrl(
-			this.#baseUrl,
-			`/webhook/2026-02-24/delete/${encodeURIComponent(webhookId)}`
-		);
+		const url = buildUrl(this.#baseUrl, `/webhook/delete/${encodeURIComponent(webhookId)}`);
 		const signal = createTimeoutSignal();
 		const res = await this.#adapter.invoke<WebhookResponse<null>>(url, {
 			method: 'DELETE',
@@ -611,7 +456,7 @@ export class WebhookService {
 	): Promise<CreateDestinationResult> {
 		const url = buildUrl(
 			this.#baseUrl,
-			`/webhook/2026-02-24/destination-create/${encodeURIComponent(webhookId)}`
+			`/webhook/destination-create/${encodeURIComponent(webhookId)}`
 		);
 		const signal = createTimeoutSignal();
 		const res = await this.#adapter.invoke<WebhookResponse<WebhookDestination>>(url, {
@@ -656,7 +501,7 @@ export class WebhookService {
 	async listDestinations(webhookId: string): Promise<ListDestinationsResult> {
 		const url = buildUrl(
 			this.#baseUrl,
-			`/webhook/2026-02-24/destination-list/${encodeURIComponent(webhookId)}`
+			`/webhook/destination-list/${encodeURIComponent(webhookId)}`
 		);
 		const signal = createTimeoutSignal();
 		const res = await this.#adapter.invoke<WebhookResponse<WebhookDestination[]>>(url, {
@@ -696,7 +541,7 @@ export class WebhookService {
 	async deleteDestination(webhookId: string, destinationId: string): Promise<void> {
 		const url = buildUrl(
 			this.#baseUrl,
-			`/webhook/2026-02-24/destination-delete/${encodeURIComponent(webhookId)}/${encodeURIComponent(destinationId)}`
+			`/webhook/destination-delete/${encodeURIComponent(webhookId)}/${encodeURIComponent(destinationId)}`
 		);
 		const signal = createTimeoutSignal();
 		const res = await this.#adapter.invoke<WebhookResponse<null>>(url, {
@@ -754,7 +599,7 @@ export class WebhookService {
 			qs.set('offset', String(params.offset));
 		}
 
-		const basePath = `/webhook/2026-02-24/receipt-list/${encodeURIComponent(webhookId)}`;
+		const basePath = `/webhook/receipt-list/${encodeURIComponent(webhookId)}`;
 		const path = qs.toString() ? `${basePath}?${qs.toString()}` : basePath;
 		const url = buildUrl(this.#baseUrl, path);
 		const signal = createTimeoutSignal();
@@ -799,7 +644,7 @@ export class WebhookService {
 	async getReceipt(webhookId: string, receiptId: string): Promise<WebhookReceipt> {
 		const url = buildUrl(
 			this.#baseUrl,
-			`/webhook/2026-02-24/receipt-get/${encodeURIComponent(webhookId)}/${encodeURIComponent(receiptId)}`
+			`/webhook/receipt-get/${encodeURIComponent(webhookId)}/${encodeURIComponent(receiptId)}`
 		);
 		const signal = createTimeoutSignal();
 		const res = await this.#adapter.invoke<WebhookResponse<WebhookReceipt>>(url, {
@@ -852,7 +697,7 @@ export class WebhookService {
 			qs.set('offset', String(params.offset));
 		}
 
-		const basePath = `/webhook/2026-02-24/delivery-list/${encodeURIComponent(webhookId)}`;
+		const basePath = `/webhook/delivery-list/${encodeURIComponent(webhookId)}`;
 		const path = qs.toString() ? `${basePath}?${qs.toString()}` : basePath;
 		const url = buildUrl(this.#baseUrl, path);
 		const signal = createTimeoutSignal();
@@ -901,7 +746,7 @@ export class WebhookService {
 	async retryDelivery(webhookId: string, deliveryId: string): Promise<void> {
 		const url = buildUrl(
 			this.#baseUrl,
-			`/webhook/2026-02-24/delivery-retry/${encodeURIComponent(webhookId)}/${encodeURIComponent(deliveryId)}`
+			`/webhook/delivery-retry/${encodeURIComponent(webhookId)}/${encodeURIComponent(deliveryId)}`
 		);
 		const signal = createTimeoutSignal();
 		const res = await this.#adapter.invoke<WebhookResponse<null>>(url, {

package/src/services/webhook/types.ts

@@ -0,0 +1,185 @@
+import { z } from 'zod';
+
+// ============================================================================
+// Webhook Destination Types
+// ============================================================================
+
+export const WebhookDestinationTypeSchema = z
+	.enum(['url'])
+	.describe('Webhook destination type. Currently only url destinations are supported');
+
+export type WebhookDestinationType = z.infer<typeof WebhookDestinationTypeSchema>;
+
+// ============================================================================
+// Webhook Delivery Status
+// ============================================================================
+
+export const WebhookDeliveryStatusSchema = z
+	.enum(['pending', 'success', 'failed'])
+	.describe(
+		'Webhook delivery status. pending: queued and waiting to be sent. success: completed successfully. failed: failed after all retry attempts'
+	);
+
+export type WebhookDeliveryStatus = z.infer<typeof WebhookDeliveryStatusSchema>;
+
+// ============================================================================
+// Core Schemas
+// ============================================================================
+
+export const WebhookSchema = z
+	.object({
+		id: z.string().describe('Unique identifier for the webhook (prefixed with wh_)'),
+		created_at: z.string().describe('ISO 8601 timestamp when the webhook was created'),
+		updated_at: z.string().describe('ISO 8601 timestamp when the webhook was last updated'),
+		created_by: z.string().describe('ID of the user who created the webhook'),
+		name: z.string().describe('Human-readable webhook name'),
+		description: z.string().nullable().describe("Optional description of the webhook's purpose"),
+		url: z
+			.string()
+			.optional()
+			.describe(
+				'Fully-qualified ingest URL for sending events to this webhook. Only present on create'
+			),
+	})
+	.describe('Webhook endpoint configuration');
+
+export type Webhook = z.infer<typeof WebhookSchema>;
+
+export const WebhookDestinationSchema = z
+	.object({
+		id: z.string().describe('Unique identifier for the destination (prefixed with whds_)'),
+		created_at: z.string().describe('ISO 8601 timestamp when the destination was created'),
+		updated_at: z.string().describe('ISO 8601 timestamp when the destination was last updated'),
+		created_by: z.string().describe('ID of the user who created the destination'),
+		webhook_id: z.string().describe('ID of the webhook this destination belongs to'),
+		type: WebhookDestinationTypeSchema.describe("Type of destination (currently only 'url')"),
+		config: z
+			.record(z.string(), z.unknown())
+			.describe('Configuration object for the destination (e.g., URL, headers)'),
+	})
+	.describe('Webhook destination representing a delivery target for webhook events');
+
+export type WebhookDestination = z.infer<typeof WebhookDestinationSchema>;
+
+export const WebhookReceiptSchema = z
+	.object({
+		id: z.string().describe('Unique identifier for the receipt (prefixed with whrc_)'),
+		date: z.string().describe('ISO 8601 timestamp when the receipt was recorded'),
+		webhook_id: z.string().describe('ID of the webhook this receipt belongs to'),
+		headers: z
+			.record(z.string(), z.string())
+			.describe('HTTP headers from the incoming webhook request'),
+		payload: z
+			.unknown()
+			.describe('Raw payload from the incoming webhook request (can be any type)'),
+	})
+	.describe('Webhook receipt representing an incoming webhook payload that was received');
+
+export type WebhookReceipt = z.infer<typeof WebhookReceiptSchema>;
+
+export const WebhookDeliverySchema = z
+	.object({
+		id: z.string().describe('Unique identifier for the delivery (prefixed with whdv_)'),
+		date: z.string().describe('ISO 8601 timestamp when the delivery was attempted'),
+		webhook_id: z.string().describe('ID of the webhook this delivery belongs to'),
+		webhook_destination_id: z
+			.string()
+			.describe('ID of the destination this delivery was sent to'),
+		webhook_receipt_id: z.string().describe('ID of the receipt that triggered this delivery'),
+		status: WebhookDeliveryStatusSchema.describe('Current status of the delivery'),
+		retries: z.number().describe('Number of retry attempts made'),
+		error: z.string().nullable().describe('Error message if the delivery failed'),
+		response: z
+			.record(z.string(), z.unknown())
+			.nullable()
+			.describe('Response data from the destination (if available)'),
+	})
+	.describe('Webhook delivery representing a delivery attempt to a destination');
+
+export type WebhookDelivery = z.infer<typeof WebhookDeliverySchema>;
+
+// ============================================================================
+// API Options
+// ============================================================================
+
+export const WebhookApiOptionsSchema = z
+	.object({
+		orgId: z
+			.string()
+			.optional()
+			.describe('Organization ID for CLI-authenticated requests without embedded org context'),
+	})
+	.describe('Common options for webhook API calls');
+
+export type WebhookApiOptions = z.infer<typeof WebhookApiOptionsSchema>;
+
+// ============================================================================
+// Request Schemas
+// ============================================================================
+
+export const CreateWebhookRequestSchema = z
+	.object({
+		name: z.string().describe('Human-readable name for the webhook'),
+		description: z.string().optional().describe("Optional description of the webhook's purpose"),
+	})
+	.describe('Request for creating a new webhook');
+
+export type CreateWebhookRequest = z.infer<typeof CreateWebhookRequestSchema>;
+
+export const UpdateWebhookRequestSchema = z
+	.object({
+		name: z.string().describe('New name for the webhook'),
+		description: z.string().optional().describe('New description for the webhook'),
+	})
+	.describe('Request for updating an existing webhook');
+
+export type UpdateWebhookRequest = z.infer<typeof UpdateWebhookRequestSchema>;
+
+export const CreateWebhookDestinationRequestSchema = z
+	.object({
+		type: WebhookDestinationTypeSchema.describe('Type of destination to create'),
+		config: z
+			.record(z.string(), z.unknown())
+			.describe('Configuration object for the destination'),
+	})
+	.describe('Request for creating a webhook destination');
+
+export type CreateWebhookDestinationRequest = z.infer<typeof CreateWebhookDestinationRequestSchema>;
+
+export const UpdateWebhookDestinationRequestSchema = z
+	.object({
+		config: z
+			.record(z.string(), z.unknown())
+			.optional()
+			.describe('Updated configuration object for the destination'),
+	})
+	.describe('Request for updating a webhook destination');
+
+export type UpdateWebhookDestinationRequest = z.infer<typeof UpdateWebhookDestinationRequestSchema>;
+
+export const PaginationRequestSchema = z
+	.object({
+		limit: z.number().optional().describe('Maximum number of items to return'),
+		offset: z.number().optional().describe('Number of items to skip for pagination'),
+	})
+	.describe('Pagination options for list requests');
+
+export type PaginationRequest = z.infer<typeof PaginationRequestSchema>;
+
+export const ListWebhooksRequestSchema = PaginationRequestSchema.describe(
+	'Request for listing webhooks'
+);
+
+export type ListWebhooksRequest = z.infer<typeof ListWebhooksRequestSchema>;
+
+export const ListWebhookReceiptsRequestSchema = PaginationRequestSchema.describe(
+	'Request for listing webhook receipts'
+);
+
+export type ListWebhookReceiptsRequest = z.infer<typeof ListWebhookReceiptsRequestSchema>;
+
+export const ListWebhookDeliveriesRequestSchema = PaginationRequestSchema.describe(
+	'Request for listing webhook deliveries'
+);
+
+export type ListWebhookDeliveriesRequest = z.infer<typeof ListWebhookDeliveriesRequestSchema>;