@timeback/webhooks 0.1.1-beta.20260219190739

package/dist/index.d.ts

@@ -0,0 +1,532 @@
+import * as _timeback_internal_client_infra from '@timeback/internal-client-infra';
+import { BaseTransportConfig, WebhookPaths, ClientConfig, TransportOnlyConfig, RequestOptions, ProviderClientConfig, ProviderRegistry, TimebackProvider, AuthCheckResult, BaseTransport } from '@timeback/internal-client-infra';
+export { AuthCheckResult, EnvAuth, Environment, ExplicitAuth } from '@timeback/internal-client-infra';
+
+type input<T> = T extends {
+    _zod: {
+        input: any;
+    };
+} ? T["_zod"]["input"] : unknown;
+
+/**
+ * Webhook Schemas
+ *
+ * Zod schemas for webhook and webhook filter inputs.
+ */
+
+
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// WEBHOOK INPUTS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+declare const WebhookCreateInput = z
+	.object({
+		name: z.string().min(1, 'name must be a non-empty string'),
+		targetUrl: z.url('targetUrl must be a valid URL'),
+		secret: z.string().min(1, 'secret must be a non-empty string'),
+		active: z.boolean(),
+		sensor: z.string().nullable().optional(),
+		description: z.string().nullable().optional(),
+	})
+	.strict()
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// TYPE EXPORTS (REQUEST INPUTS)
+// ═══════════════════════════════════════════════════════════════════════════════
+
+type WebhookCreateInput = input<typeof WebhookCreateInput>
+
+declare const WebhookUpdateInput = WebhookCreateInput
+type WebhookUpdateInput = input<typeof WebhookUpdateInput>
+
+declare const WebhookFilterCreateInput = z
+	.object({
+		webhookId: z.string().min(1, 'webhookId must be a non-empty string'),
+		filterKey: z.string().min(1, 'filterKey must be a non-empty string'),
+		filterValue: z.string().min(1, 'filterValue must be a non-empty string'),
+		filterType: WebhookFilterType,
+		filterOperator: WebhookFilterOperation,
+		active: z.boolean(),
+	})
+	.strict()
+type WebhookFilterCreateInput = input<typeof WebhookFilterCreateInput>
+
+declare const WebhookFilterUpdateInput = WebhookFilterCreateInput
+type WebhookFilterUpdateInput = input<typeof WebhookFilterUpdateInput>
+
+/**
+ * Webhook Types
+ *
+ * Type definitions for the Webhooks API.
+ */
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// ENUMS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/** Supported data types for webhook filter values */
+type FilterType = 'string' | 'number' | 'boolean'
+
+/** Supported filter comparison operations */
+type FilterOperation =
+	| 'eq'
+	| 'neq'
+	| 'gt'
+	| 'gte'
+	| 'lt'
+	| 'lte'
+	| 'contains'
+	| 'notContains'
+	| 'in'
+	| 'notIn'
+	| 'startsWith'
+	| 'endsWith'
+	| 'regexp'
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// ENTITIES
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/** A registered webhook */
+interface Webhook {
+	/** Unique webhook identifier (UUID) */
+	id: string
+	/** Associated sensor identifier, null if not scoped to a sensor */
+	sensor: string | null
+	/** Human-readable webhook name */
+	name: string
+	/** Optional webhook description */
+	description: string | null
+	/** Destination URL that receives event payloads */
+	targetUrl: string
+	/** Shared secret used to sign webhook payloads */
+	secret: string
+	/** Whether the webhook is currently active */
+	active: boolean
+	/** ISO 8601 creation timestamp */
+	created_at: string | null
+	/** ISO 8601 last update timestamp */
+	updated_at: string | null
+	/** ISO 8601 soft-delete timestamp, null if not deleted */
+	deleted_at: string | null
+}
+
+/** A filter attached to a webhook that controls which events trigger delivery */
+interface WebhookFilter {
+	/** Unique filter identifier (UUID) */
+	id: string
+	/** UUID of the parent webhook */
+	webhookId: string
+	/** Event field to filter on (e.g., 'type', 'action') */
+	filterKey: string
+	/** Value to compare against */
+	filterValue: string
+	/** Data type of the filter value */
+	filterType: FilterType
+	/** Comparison operator */
+	filterOperator: FilterOperation
+	/** Whether the filter is currently active */
+	active: boolean
+	/** ISO 8601 creation timestamp */
+	created_at: string | null
+	/** ISO 8601 last update timestamp */
+	updated_at: string | null
+	/** ISO 8601 soft-delete timestamp, null if not deleted */
+	deleted_at: string | null
+}
+
+/** Response for DELETE /webhooks/:id */
+interface WebhookDeleteResponse {
+	message: string
+}
+
+/** Response for DELETE /webhook-filters/:id */
+interface WebhookFilterDeleteResponse {
+	message: string
+}
+
+/**
+ * Client Configuration Types
+ *
+ * Configuration types for the Webhooks client.
+ */
+
+/**
+ * Transport interface for Webhooks client.
+ *
+ * Extends base transport requirements with webhook-specific paths.
+ * Required when using transport mode with WebhooksClient.
+ */
+interface WebhooksTransportLike {
+    /** Base URL of the API */
+    baseUrl: string;
+    /** API path profiles for Webhook operations */
+    paths: WebhookPaths;
+    /** Make an authenticated request */
+    request<T>(path: string, options?: RequestOptions): Promise<T>;
+}
+/**
+ * Webhooks client configuration options.
+ *
+ * Supports four modes:
+ * - **Provider mode**: `{ provider: TimebackProvider }` — pre-built provider with token sharing
+ * - **Environment mode**: `{ platform?, env, auth }` — Timeback hosted APIs
+ * - **Explicit mode**: `{ baseUrl, auth: { authUrl } }` — custom API URLs
+ * - **Transport mode**: `{ transport: WebhooksTransportLike }` — custom transport with paths
+ */
+type WebhooksClientConfig = ClientConfig | TransportOnlyConfig<WebhooksTransportLike> | ProviderClientConfig;
+/**
+ * Configuration for Webhooks transport.
+ */
+type WebhooksTransportConfig = BaseTransportConfig & {
+    /** API path profiles for Webhook operations */
+    paths: WebhookPaths;
+};
+/**
+ * Instance type of WebhooksClient.
+ */
+type WebhooksClientInstance = InstanceType<typeof WebhooksClient>;
+
+/**
+ * Webhooks Resource
+ *
+ * Manage webhooks - create, list, update, delete, activate, and deactivate.
+ */
+
+/**
+ * Webhooks resource.
+ *
+ * Provides methods to manage webhook registrations for receiving
+ * event notifications.
+ */
+declare class WebhooksResource {
+    private readonly transport;
+    constructor(transport: WebhooksTransportLike);
+    /**
+     * List webhooks, optionally filtered by sensor.
+     *
+     * @param sensor - Optional sensor ID to filter by
+     * @returns Array of registered webhooks
+     *
+     * @example
+     * ```typescript
+     * const webhooks = await client.webhooks.list()
+     * const filtered = await client.webhooks.list('https://example.edu/sensors/1')
+     * ```
+     */
+    list(sensor?: string): Promise<Webhook[]>;
+    /**
+     * Get a specific webhook by ID.
+     *
+     * @param id - The webhook UUID
+     * @returns The webhook object
+     *
+     * @example
+     * ```typescript
+     * const webhook = await client.webhooks.get('123e4567-e89b-12d3-a456-426614174000')
+     * ```
+     */
+    get(id: string): Promise<Webhook>;
+    /**
+     * Create a new webhook.
+     *
+     * @param input - Webhook configuration
+     * @returns The created webhook
+     *
+     * @example
+     * ```typescript
+     * const webhook = await client.webhooks.create({
+     *   name: 'My Webhook',
+     *   targetUrl: 'https://myapp.example.com/caliper-events',
+     *   secret: 'my-shared-secret',
+     *   active: true,
+     * })
+     * ```
+     */
+    create(input: WebhookCreateInput): Promise<Webhook>;
+    /**
+     * Update an existing webhook.
+     *
+     * @param id - The webhook UUID
+     * @param input - Updated webhook configuration
+     * @returns The updated webhook
+     *
+     * @example
+     * ```typescript
+     * const updated = await client.webhooks.update(webhookId, {
+     *   name: 'Updated Name',
+     *   targetUrl: 'https://new-url.example.com/events',
+     *   secret: 'new-secret',
+     *   active: true,
+     * })
+     * ```
+     */
+    update(id: string, input: WebhookUpdateInput): Promise<Webhook>;
+    /**
+     * Delete a webhook.
+     *
+     * @param id - The webhook UUID
+     * @returns The delete response with status
+     *
+     * @example
+     * ```typescript
+     * await client.webhooks.delete(webhookId)
+     * ```
+     */
+    delete(id: string): Promise<WebhookDeleteResponse>;
+    /**
+     * Activate a webhook.
+     *
+     * @param id - The webhook UUID
+     * @returns The activated webhook
+     *
+     * @example
+     * ```typescript
+     * const webhook = await client.webhooks.activate(webhookId)
+     * console.log(webhook.active) // true
+     * ```
+     */
+    activate(id: string): Promise<Webhook>;
+    /**
+     * Deactivate a webhook.
+     *
+     * @param id - The webhook UUID
+     * @returns The deactivated webhook
+     *
+     * @example
+     * ```typescript
+     * const webhook = await client.webhooks.deactivate(webhookId)
+     * console.log(webhook.active) // false
+     * ```
+     */
+    deactivate(id: string): Promise<Webhook>;
+}
+
+/**
+ * Webhook Filters Resource
+ *
+ * Manage webhook filters - create, list, update, and delete.
+ */
+
+/**
+ * Webhook Filters resource.
+ *
+ * Provides methods to manage filters that control which events
+ * trigger webhook delivery.
+ */
+declare class WebhookFiltersResource {
+    private readonly transport;
+    constructor(transport: WebhooksTransportLike);
+    /**
+     * List all webhook filters.
+     *
+     * @returns Array of all webhook filters
+     *
+     * @example
+     * ```typescript
+     * const filters = await client.webhookFilters.list()
+     * ```
+     */
+    list(): Promise<WebhookFilter[]>;
+    /**
+     * Get a specific webhook filter by ID.
+     *
+     * @param id - The webhook filter ID
+     * @returns The webhook filter object
+     *
+     * @example
+     * ```typescript
+     * const filter = await client.webhookFilters.get(filterId)
+     * ```
+     */
+    get(id: string): Promise<WebhookFilter>;
+    /**
+     * List all filters for a specific webhook.
+     *
+     * @param webhookId - The parent webhook UUID
+     * @returns Array of filters for the specified webhook
+     *
+     * @example
+     * ```typescript
+     * const filters = await client.webhookFilters.listByWebhook(webhookId)
+     * ```
+     */
+    listByWebhook(webhookId: string): Promise<WebhookFilter[]>;
+    /**
+     * Create a new webhook filter.
+     *
+     * @param input - Filter configuration
+     * @returns The created webhook filter
+     *
+     * @example
+     * ```typescript
+     * const filter = await client.webhookFilters.create({
+     *   webhookId: '123e4567-e89b-12d3-a456-426614174000',
+     *   filterKey: 'type',
+     *   filterValue: 'ActivityEvent',
+     *   filterType: 'string',
+     *   filterOperator: 'eq',
+     *   active: true,
+     * })
+     * ```
+     */
+    create(input: WebhookFilterCreateInput): Promise<WebhookFilter>;
+    /**
+     * Update an existing webhook filter.
+     *
+     * @param id - The webhook filter ID
+     * @param input - Updated filter configuration
+     * @returns The updated webhook filter
+     *
+     * @example
+     * ```typescript
+     * const updated = await client.webhookFilters.update(filterId, {
+     *   webhookId: webhookId,
+     *   filterKey: 'type',
+     *   filterValue: 'TimeSpentEvent',
+     *   filterType: 'string',
+     *   filterOperator: 'eq',
+     *   active: true,
+     * })
+     * ```
+     */
+    update(id: string, input: WebhookFilterUpdateInput): Promise<WebhookFilter>;
+    /**
+     * Delete a webhook filter.
+     *
+     * @param id - The webhook filter ID
+     * @returns The delete response with status
+     *
+     * @example
+     * ```typescript
+     * await client.webhookFilters.delete(filterId)
+     * ```
+     */
+    delete(id: string): Promise<WebhookFilterDeleteResponse>;
+}
+
+/**
+ * Webhooks Client
+ *
+ * Main entry point for the Webhooks management SDK.
+ */
+/**
+ * Webhooks API client.
+ *
+ * Provides methods to create, list, update, delete, activate, and
+ * deactivate webhooks, as well as manage webhook filters.
+ *
+ * @example
+ * ```typescript
+ * // Environment mode (Timeback APIs)
+ * const client = new WebhooksClient({
+ *   env: 'staging',
+ *   auth: {
+ *     clientId: 'your-client-id',
+ *     clientSecret: 'your-client-secret',
+ *   },
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Provider mode (shared tokens)
+ * import { TimebackProvider } from '@timeback/internal-client-infra'
+ *
+ * const provider = new TimebackProvider({
+ *   platform: 'BEYOND_AI',
+ *   env: 'staging',
+ *   auth: { clientId: '...', clientSecret: '...' },
+ * })
+ *
+ * const client = new WebhooksClient({ provider })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Managing webhooks
+ * const webhook = await client.webhooks.create({
+ *   name: 'My Webhook',
+ *   targetUrl: 'https://myapp.example.com/events',
+ *   secret: 'my-shared-secret',
+ *   active: true,
+ * })
+ *
+ * // Add a filter
+ * await client.webhookFilters.create({
+ *   webhookId: webhook.id,
+ *   filterKey: 'type',
+ *   filterValue: 'ActivityEvent',
+ *   filterType: 'string',
+ *   filterOperator: 'eq',
+ *   active: true,
+ * })
+ * ```
+ */
+declare const WebhooksClient: {
+    new (config?: WebhooksClientConfig): {
+        readonly transport: WebhooksTransportLike;
+        readonly _provider?: _timeback_internal_client_infra.TimebackProvider | undefined;
+        readonly webhooks: WebhooksResource;
+        readonly webhookFilters: WebhookFiltersResource;
+        getTransport(): WebhooksTransportLike;
+        checkAuth(): Promise<_timeback_internal_client_infra.AuthCheckResult>;
+    };
+};
+
+/**
+ * Webhooks Client Factory
+ *
+ * Creates WebhooksClient classes bound to specific provider registries.
+ */
+
+/**
+ * Create a WebhooksClient class bound to a specific provider registry.
+ *
+ * @param registry - Provider registry to use (defaults to all Timeback platforms)
+ * @returns WebhooksClient class bound to the registry
+ */
+declare function createWebhooksClient(registry?: ProviderRegistry): {
+    new (config?: WebhooksClientConfig): {
+        /** @internal */
+        readonly transport: WebhooksTransportLike;
+        /** @internal */
+        readonly _provider?: TimebackProvider | undefined;
+        /** Manage webhook registrations */
+        readonly webhooks: WebhooksResource;
+        /** Manage filters that control which events trigger webhook delivery */
+        readonly webhookFilters: WebhookFiltersResource;
+        /**
+         * Get the underlying transport for advanced use cases.
+         * @returns The transport instance used by this client
+         */
+        getTransport(): WebhooksTransportLike;
+        /**
+         * Verify that OAuth authentication is working.
+         * @returns Auth check result
+         * @throws {Error} If client was initialized with custom transport (no provider)
+         */
+        checkAuth(): Promise<AuthCheckResult>;
+    };
+};
+
+/**
+ * Transport Layer
+ *
+ * HTTP transport for Webhooks API communication.
+ */
+
+/**
+ * HTTP transport layer for Webhooks API communication.
+ *
+ * Extends BaseTransport with webhook-specific path configuration.
+ */
+declare class Transport extends BaseTransport {
+    /** API path profiles for Webhook operations */
+    readonly paths: WebhookPaths;
+    constructor(config: WebhooksTransportConfig);
+}
+
+export { Transport, WebhookCreateInput, WebhookFilterCreateInput, WebhookFilterUpdateInput, WebhookUpdateInput, WebhooksClient, createWebhooksClient };
+export type { FilterOperation, FilterType, Webhook, WebhookFilter, WebhooksClientConfig, WebhooksClientInstance };

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAMH,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AACzC,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAA;AAEhD,YAAY,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAA;AACtD,YAAY,EAAE,oBAAoB,EAAE,WAAW,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAC9F,YAAY,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAA;AAMtE,YAAY,EACX,kBAAkB,EAClB,kBAAkB,EAClB,wBAAwB,EACxB,wBAAwB,GACxB,MAAM,qBAAqB,CAAA;AAE5B,YAAY,EACX,OAAO,EACP,aAAa,EACb,UAAU,EACV,eAAe,GACf,MAAM,oCAAoC,CAAA;AAM3C,OAAO,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA"}