@timeback/webhooks 0.1.1-beta.20260219190739

package/README.md

@@ -0,0 +1,226 @@
+# @timeback/webhooks
+
+TypeScript client for Timeback Webhooks — manage webhook registrations and event filters for real-time notifications.
+
+## Installation
+
+```bash
+bun add @timeback/webhooks
+```
+
+## Quick Start
+
+```typescript
+import { WebhooksClient } from '@timeback/webhooks'
+
+const client = new WebhooksClient({
+	env: 'staging', // or 'production'
+	auth: {
+		clientId: 'your-client-id',
+		clientSecret: 'your-client-secret',
+	},
+})
+
+// Create a webhook
+const webhook = await client.webhooks.create({
+	name: 'My Webhook',
+	targetUrl: 'https://myapp.example.com/events',
+	secret: 'my-shared-secret',
+	active: true,
+})
+
+// Add a filter to only receive ActivityEvents
+await client.webhookFilters.create({
+	webhookId: webhook.id,
+	filterKey: 'type',
+	filterValue: 'ActivityEvent',
+	filterType: 'string',
+	filterOperator: 'eq',
+	active: true,
+})
+
+// List all webhooks
+const webhooks = await client.webhooks.list()
+```
+
+## API Design
+
+### Standalone vs Composed
+
+```typescript
+// Composed
+import { TimebackClient } from '@timeback/core'
+
+// Standalone
+const client = new WebhooksClient({ env: 'staging', auth })
+
+const timeback = new TimebackClient({ env: 'staging', auth })
+timeback.webhooks.webhooks.list()
+```
+
+### Client Structure
+
+```typescript
+const client = new WebhooksClient(options)
+
+// Webhooks
+client.webhooks.list(sensor?)               // List webhooks (optionally filter by sensor)
+client.webhooks.get(id)                     // Get webhook by ID
+client.webhooks.create(input)               // Create a webhook
+client.webhooks.update(id, input)           // Update a webhook
+client.webhooks.delete(id)                  // Delete a webhook
+client.webhooks.activate(id)               // Activate a webhook
+client.webhooks.deactivate(id)             // Deactivate a webhook
+
+// Webhook Filters
+client.webhookFilters.list()                // List all filters
+client.webhookFilters.get(id)               // Get filter by ID
+client.webhookFilters.listByWebhook(id)     // List filters for a webhook
+client.webhookFilters.create(input)         // Create a filter
+client.webhookFilters.update(id, input)     // Update a filter
+client.webhookFilters.delete(id)            // Delete a filter
+```
+
+### Managing Webhooks
+
+```typescript
+// Create a webhook for Caliper event notifications
+const webhook = await client.webhooks.create({
+	name: 'Activity Tracker',
+	targetUrl: 'https://myapp.example.com/caliper-events',
+	secret: 'my-shared-secret',
+	active: true,
+})
+
+// Temporarily disable a webhook
+await client.webhooks.deactivate(webhook.id)
+
+// Re-enable it
+await client.webhooks.activate(webhook.id)
+
+// Update the target URL
+await client.webhooks.update(webhook.id, {
+	name: 'Activity Tracker',
+	targetUrl: 'https://new-url.example.com/events',
+	secret: 'my-shared-secret',
+	active: true,
+})
+
+// List webhooks filtered by sensor
+const webhooks = await client.webhooks.list('https://example.edu/sensors/1')
+
+// Delete a webhook
+await client.webhooks.delete(webhook.id)
+```
+
+### Webhook Filters
+
+Filters control which events trigger delivery to a webhook:
+
+```typescript
+// Only receive ActivityEvent types
+const filter = await client.webhookFilters.create({
+	webhookId: webhook.id,
+	filterKey: 'type',
+	filterValue: 'ActivityEvent',
+	filterType: 'string',
+	filterOperator: 'eq',
+	active: true,
+})
+
+// Update the filter to match a different event type
+await client.webhookFilters.update(filter.id, {
+	webhookId: webhook.id,
+	filterKey: 'type',
+	filterValue: 'TimeSpentEvent',
+	filterType: 'string',
+	filterOperator: 'eq',
+	active: true,
+})
+
+// List all filters for a specific webhook
+const filters = await client.webhookFilters.listByWebhook(webhook.id)
+
+// Delete a filter
+await client.webhookFilters.delete(filter.id)
+```
+
+### Authentication
+
+The client handles OAuth2 token management automatically:
+
+```typescript
+// Environment mode (recommended for Timeback APIs)
+const client = new WebhooksClient({
+	env: 'staging', // or 'production'
+	auth: {
+		clientId: 'xxx',
+		clientSecret: 'xxx',
+	},
+})
+
+// Explicit mode (custom API)
+const client = new WebhooksClient({
+	baseUrl: 'https://webhooks.example.com',
+	auth: {
+		clientId: 'xxx',
+		clientSecret: 'xxx',
+		authUrl: 'https://auth.example.com/oauth2/token',
+	},
+})
+```
+
+Tokens are cached and refreshed automatically before expiry.
+
+### Error Handling
+
+```typescript
+try {
+	await client.webhooks.get('invalid-id')
+} catch (error) {
+	if (error instanceof Error) {
+		console.log(error.message)
+	}
+}
+```
+
+## Configuration
+
+```typescript
+new WebhooksClient({
+	// Environment mode (Timeback APIs)
+	env: 'staging' | 'production',
+	auth: {
+		clientId: string,
+		clientSecret: string,
+	},
+
+	// OR Explicit mode (custom API)
+	baseUrl: string,
+	auth: {
+		clientId: string,
+		clientSecret: string,
+		authUrl: string,
+	},
+
+	// Internal (for composition with @timeback/core)
+	transport?: WebhooksTransportLike, // Custom transport
+})
+```
+
+## Debug Mode
+
+Enable debug logging by setting `DEBUG=1` or `DEBUG=true`:
+
+```bash
+DEBUG=1 bun run my-script.ts
+```
+
+This outputs detailed logs for HTTP requests and authentication:
+
+```bash
+[2025-01-15T10:30:00.000Z] DEBUG [webhooks:auth] Fetching new access token...
+[2025-01-15T10:30:00.500Z] DEBUG [webhooks:auth] Token acquired (500ms, expires in 3600s)
+[2025-01-15T10:30:00.501Z] DEBUG [webhooks:http] → POST https://api.example.com/webhooks
+[2025-01-15T10:30:00.800Z] DEBUG [webhooks:http] ← 201 Created (299ms)
+```

package/dist/client.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 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,
+ * })
+ * ```
+ */
+export declare const WebhooksClient: {
+    new (config?: import("./types").WebhooksClientConfig): {
+        readonly transport: import("./types").WebhooksTransportLike;
+        readonly _provider?: import("@timeback/internal-client-infra").TimebackProvider | undefined;
+        readonly webhooks: import("./resources").WebhooksResource;
+        readonly webhookFilters: import("./resources").WebhookFiltersResource;
+        getTransport(): import("./types").WebhooksTransportLike;
+        checkAuth(): Promise<import("@timeback/internal-client-infra").AuthCheckResult>;
+    };
+};
+export type { WebhooksClientInstance } from './types';
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,eAAO,MAAM,cAAc;;;;;;;;;CAAyB,CAAA;AAEpD,YAAY,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAA"}

package/dist/constants.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Webhooks Constants
+ *
+ * Configuration constants for the Webhooks client.
+ */
+import type { ClientUrlMaps, Platform } from '@timeback/internal-client-infra';
+/**
+ * Environment variable names for Webhooks configuration.
+ *
+ * Supports fallback chains - tries each env var in order until one is defined:
+ * - `TIMEBACK_API_*` (canonical/preferred)
+ * - `TIMEBACK_*` (unified Timeback shorthand)
+ * - `WEBHOOKS_*` (service-specific)
+ */
+export declare const WEBHOOKS_ENV_VARS: {
+    readonly baseUrl: readonly ["TIMEBACK_API_BASE_URL", "TIMEBACK_BASE_URL", "WEBHOOKS_BASE_URL"];
+    readonly authUrl: readonly ["TIMEBACK_API_AUTH_URL", "TIMEBACK_AUTH_URL", "WEBHOOKS_TOKEN_URL"];
+    readonly clientId: readonly ["TIMEBACK_API_CLIENT_ID", "TIMEBACK_CLIENT_ID", "WEBHOOKS_CLIENT_ID"];
+    readonly clientSecret: readonly ["TIMEBACK_API_CLIENT_SECRET", "TIMEBACK_CLIENT_SECRET", "WEBHOOKS_CLIENT_SECRET"];
+};
+/**
+ * Get URL maps for a specific platform.
+ * Webhooks share the same base URL as the Caliper API.
+ *
+ * @param platform - Platform name
+ * @returns Client URL maps for the platform
+ */
+export declare function getUrlMapsForPlatform(platform?: Platform): ClientUrlMaps;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAA;AAE9E;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB;;;;;CASpB,CAAA;AAEV;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,GAAE,QAA2B,GAAG,aAAa,CAM1F"}

package/dist/factory.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Webhooks Client Factory
+ *
+ * Creates WebhooksClient classes bound to specific provider registries.
+ */
+import { WebhookFiltersResource, WebhooksResource } from './resources';
+import type { AuthCheckResult, ProviderRegistry, TimebackProvider } from '@timeback/internal-client-infra';
+import type { WebhooksClientConfig, WebhooksTransportLike } from './types';
+/**
+ * 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
+ */
+export 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>;
+    };
+};
+//# sourceMappingURL=factory.d.ts.map

package/dist/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../src/factory.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAGtE,OAAO,KAAK,EACX,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,MAAM,iCAAiC,CAAA;AACxC,OAAO,KAAK,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAA;AAE1E;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,GAAE,gBAA4C;;QAQzF,gBAAgB;;QAGhB,gBAAgB;;QAGhB,mCAAmC;;QAEnC,wEAAwE;;QA0CxE;;;WAGG;;QAKH;;;;WAIG;;;EASJ"}