@attrove/sdk 0.1.14 → 0.1.16

package/cjs/admin-client.js

@@ -13,6 +13,7 @@ const index_js_2 = require("./types/index.js");
 const index_js_3 = require("./types/index.js");
 const constants_js_1 = require("./constants.js");
 const settings_js_1 = require("./resources/settings.js");
+const webhooks_js_1 = require("./resources/webhooks.js");
 /**
  * Validate the admin client configuration.
  *
@@ -197,6 +198,7 @@ class AttroveAdmin {
         // Initialize resources
         this.users = new AdminUsersResource(this.http, this.config.clientId);
         this.settings = new settings_js_1.AdminSettingsResource(this.http, this.config.clientId);
+        this.webhooks = new webhooks_js_1.AdminWebhooksResource(this.http, this.config.clientId);
     }
 }
 exports.AttroveAdmin = AttroveAdmin;

package/cjs/client.js

@@ -13,6 +13,7 @@ const users_js_1 = require("./resources/users.js");
 const messages_js_1 = require("./resources/messages.js");
 const conversations_js_1 = require("./resources/conversations.js");
 const integrations_js_1 = require("./resources/integrations.js");
+const entities_js_1 = require("./resources/entities.js");
 const calendars_js_1 = require("./resources/calendars.js");
 const events_js_1 = require("./resources/events.js");
 const meetings_js_1 = require("./resources/meetings.js");
@@ -29,27 +30,27 @@ const constants_js_1 = require("./constants.js");
  */
 function validateConfig(config) {
     // Validate apiKey
-    if (!config.apiKey || typeof config.apiKey !== "string") {
-        throw new index_js_1.ValidationError("apiKey is required and must be a non-empty string", index_js_2.ErrorCodes.VALIDATION_REQUIRED_FIELD, { field: "apiKey" });
+    if (!config.apiKey || typeof config.apiKey !== 'string') {
+        throw new index_js_1.ValidationError('apiKey is required and must be a non-empty string', index_js_2.ErrorCodes.VALIDATION_REQUIRED_FIELD, { field: 'apiKey' });
     }
-    if (!config.apiKey.startsWith("sk_")) {
-        throw new index_js_1.ValidationError('apiKey must start with "sk_" prefix. Make sure you are using a valid API key.', index_js_2.ErrorCodes.VALIDATION_INVALID_FORMAT, { field: "apiKey", expected: "sk_..." });
+    if (!config.apiKey.startsWith('sk_')) {
+        throw new index_js_1.ValidationError('apiKey must start with "sk_" prefix. Make sure you are using a valid API key.', index_js_2.ErrorCodes.VALIDATION_INVALID_FORMAT, { field: 'apiKey', expected: 'sk_...' });
     }
     // Validate userId
-    if (!config.userId || typeof config.userId !== "string") {
-        throw new index_js_1.ValidationError("userId is required and must be a non-empty string", index_js_2.ErrorCodes.VALIDATION_REQUIRED_FIELD, { field: "userId" });
+    if (!config.userId || typeof config.userId !== 'string') {
+        throw new index_js_1.ValidationError('userId is required and must be a non-empty string', index_js_2.ErrorCodes.VALIDATION_REQUIRED_FIELD, { field: 'userId' });
     }
     if (!(0, index_js_3.isValidUUID)(config.userId)) {
-        throw new index_js_1.ValidationError('userId must be a valid UUID format (e.g., "123e4567-e89b-12d3-a456-426614174000")', index_js_2.ErrorCodes.VALIDATION_INVALID_FORMAT, { field: "userId", expected: "UUID format" });
+        throw new index_js_1.ValidationError('userId must be a valid UUID format (e.g., "123e4567-e89b-12d3-a456-426614174000")', index_js_2.ErrorCodes.VALIDATION_INVALID_FORMAT, { field: 'userId', expected: 'UUID format' });
     }
     // Validate optional fields
     if (config.timeout !== undefined &&
-        (typeof config.timeout !== "number" || config.timeout <= 0)) {
-        throw new index_js_1.ValidationError("timeout must be a positive number in milliseconds", index_js_2.ErrorCodes.VALIDATION_OUT_OF_RANGE, { field: "timeout", value: config.timeout });
+        (typeof config.timeout !== 'number' || config.timeout <= 0)) {
+        throw new index_js_1.ValidationError('timeout must be a positive number in milliseconds', index_js_2.ErrorCodes.VALIDATION_OUT_OF_RANGE, { field: 'timeout', value: config.timeout });
     }
     if (config.maxRetries !== undefined &&
-        (typeof config.maxRetries !== "number" || config.maxRetries < 0)) {
-        throw new index_js_1.ValidationError("maxRetries must be a non-negative number", index_js_2.ErrorCodes.VALIDATION_OUT_OF_RANGE, { field: "maxRetries", value: config.maxRetries });
+        (typeof config.maxRetries !== 'number' || config.maxRetries < 0)) {
+        throw new index_js_1.ValidationError('maxRetries must be a non-negative number', index_js_2.ErrorCodes.VALIDATION_OUT_OF_RANGE, { field: 'maxRetries', value: config.maxRetries });
     }
 }
 /**
@@ -118,6 +119,7 @@ class Attrove {
         this.messages = new messages_js_1.MessagesResource(this.http, this.config.userId);
         this.conversations = new conversations_js_1.ConversationsResource(this.http, this.config.userId);
         this.integrations = new integrations_js_1.IntegrationsResource(this.http, this.config.userId);
+        this.entities = new entities_js_1.EntitiesResource(this.http, this.config.userId);
         this.calendars = new calendars_js_1.CalendarsResource(this.http, this.config.userId);
         this.events = new events_js_1.EventsResource(this.http, this.config.userId);
         this.meetings = new meetings_js_1.MeetingsResource(this.http, this.config.userId);
@@ -224,7 +226,7 @@ class Attrove {
         // Add the user's prompt to history
         const fullHistory = [
             ...history,
-            { role: "user", content: prompt },
+            { role: 'user', content: prompt },
         ];
         // Extract query options (separate from stream options)
         const queryOptions = {

package/cjs/constants.js

@@ -13,7 +13,7 @@ exports.getWsCloseReason = exports.WS_CLOSE_CODES = exports.RETRYABLE_STATUS_SET
  * Automatically synchronized with package.json during the release process.
  * For programmatic access, use `getVersion()` from './version'.
  */
-exports.SDK_VERSION = "0.1.14"; // auto-synced from package.json during release
+exports.SDK_VERSION = "0.1.16"; // auto-synced from package.json during release
 /**
  * Default API base URL for Attrove services.
  */

package/cjs/index.js

@@ -33,7 +33,7 @@
  * @packageDocumentation
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getVersion = exports.DEFAULT_MAX_RETRIES = exports.DEFAULT_TIMEOUT = exports.DEFAULT_BASE_URL = exports.SDK_VERSION = exports.generateMessageId = exports.isServerError = exports.isTimeoutError = exports.isNetworkError = exports.isRateLimitError = exports.isValidationError = exports.isNotFoundError = exports.isAuthorizationError = exports.isAuthenticationError = exports.isAttroveError = exports.ServerError = exports.TimeoutError = exports.NetworkError = exports.RateLimitError = exports.ValidationError = exports.NotFoundError = exports.AuthorizationError = exports.AuthenticationError = exports.AttroveError = exports.AttroveAdmin = exports.Attrove = void 0;
+exports.getVersion = exports.DEFAULT_MAX_RETRIES = exports.DEFAULT_TIMEOUT = exports.DEFAULT_BASE_URL = exports.SDK_VERSION = exports.verifyWebhookSignatureDetailed = exports.verifyWebhookSignature = exports.generateMessageId = exports.isServerError = exports.isTimeoutError = exports.isNetworkError = exports.isRateLimitError = exports.isValidationError = exports.isNotFoundError = exports.isAuthorizationError = exports.isAuthenticationError = exports.isAttroveError = exports.ServerError = exports.TimeoutError = exports.NetworkError = exports.RateLimitError = exports.ValidationError = exports.NotFoundError = exports.AuthorizationError = exports.AuthenticationError = exports.AttroveError = exports.AttroveAdmin = exports.Attrove = void 0;
 const tslib_1 = require("tslib");
 const client_js_1 = require("./client.js");
 const admin_client_js_1 = require("./admin-client.js");
@@ -86,6 +86,9 @@ Object.defineProperty(exports, "isServerError", { enumerable: true, get: functio
 // Export streaming utilities
 var streaming_js_1 = require("./utils/streaming.js");
 Object.defineProperty(exports, "generateMessageId", { enumerable: true, get: function () { return streaming_js_1.generateMessageId; } });
+var webhooks_js_1 = require("./utils/webhooks.js");
+Object.defineProperty(exports, "verifyWebhookSignature", { enumerable: true, get: function () { return webhooks_js_1.verifyWebhookSignature; } });
+Object.defineProperty(exports, "verifyWebhookSignatureDetailed", { enumerable: true, get: function () { return webhooks_js_1.verifyWebhookSignatureDetailed; } });
 // Export constants for advanced usage
 var constants_js_1 = require("./constants.js");
 Object.defineProperty(exports, "SDK_VERSION", { enumerable: true, get: function () { return constants_js_1.SDK_VERSION; } });

package/cjs/resources/entities.js

@@ -0,0 +1,90 @@
+"use strict";
+/**
+ * Entities Resource
+ *
+ * Provides methods for listing and retrieving contacts (entities)
+ * that a user has communicated with across connected integrations.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EntitiesResource = void 0;
+/**
+ * Entities resource for accessing contact data.
+ *
+ * Provides methods for listing and retrieving contacts (people and bots)
+ * that the user has communicated with across connected integrations
+ * (Gmail, Slack, Outlook, etc.).
+ */
+class EntitiesResource {
+    constructor(http, userId) {
+        this.http = http;
+        this.userId = userId;
+    }
+    /**
+     * List contacts with optional filtering.
+     *
+     * @param options - Filtering and pagination options
+     * @returns Paginated list of contacts
+     *
+     * @throws {AuthenticationError} If the API key is invalid or expired
+     * @throws {ValidationError} If the filter parameters are invalid
+     * @throws {NetworkError} If unable to reach the API
+     *
+     * @example
+     * ```ts
+     * // List all contacts
+     * const { data, pagination } = await attrove.entities.list();
+     *
+     * // Search by name or email
+     * const { data } = await attrove.entities.list({ search: 'john' });
+     *
+     * // Only non-bot contacts
+     * const { data } = await attrove.entities.list({ isBot: false });
+     *
+     * // Filter by type
+     * const { data } = await attrove.entities.list({ entityType: 'person' });
+     * ```
+     */
+    async list(options = {}) {
+        const params = {};
+        if (options.search) {
+            params.search = options.search;
+        }
+        if (options.entityType) {
+            params.entity_type = options.entityType;
+        }
+        if (options.isBot !== undefined) {
+            params.is_bot = String(options.isBot);
+        }
+        if (options.limit !== undefined) {
+            params.limit = String(options.limit);
+        }
+        if (options.offset !== undefined) {
+            params.offset = String(options.offset);
+        }
+        const response = await this.http.request(`/v1/users/${this.userId}/entities`, { method: 'GET' }, params);
+        return {
+            data: response.data,
+            pagination: response.pagination,
+        };
+    }
+    /**
+     * Get a single contact by ID.
+     *
+     * @param id - Entity ID (ent_xxx opaque format or raw UUID)
+     * @returns The requested contact
+     *
+     * @throws {AuthenticationError} If the API key is invalid or expired
+     * @throws {NotFoundError} If the contact does not exist
+     * @throws {NetworkError} If unable to reach the API
+     *
+     * @example
+     * ```ts
+     * const contact = await attrove.entities.get('ent_5cyYg0:a9KRt4Y');
+     * console.log(contact.name, contact.entity_type);
+     * ```
+     */
+    async get(id) {
+        return this.http.get(`/v1/users/${this.userId}/entities/${id}`);
+    }
+}
+exports.EntitiesResource = EntitiesResource;

package/cjs/resources/index.js

@@ -3,7 +3,7 @@
  * Resource exports
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AdminSettingsResource = exports.QueryResource = exports.ThreadsResource = exports.MeetingsResource = exports.EventsResource = exports.CalendarsResource = exports.IntegrationsResource = exports.ConversationsResource = exports.MessagesResource = exports.UsersResource = void 0;
+exports.AdminWebhooksResource = exports.AdminSettingsResource = exports.QueryResource = exports.ThreadsResource = exports.MeetingsResource = exports.EventsResource = exports.CalendarsResource = exports.EntitiesResource = exports.IntegrationsResource = exports.ConversationsResource = exports.MessagesResource = exports.UsersResource = void 0;
 var users_js_1 = require("./users.js");
 Object.defineProperty(exports, "UsersResource", { enumerable: true, get: function () { return users_js_1.UsersResource; } });
 var messages_js_1 = require("./messages.js");
@@ -12,6 +12,8 @@ var conversations_js_1 = require("./conversations.js");
 Object.defineProperty(exports, "ConversationsResource", { enumerable: true, get: function () { return conversations_js_1.ConversationsResource; } });
 var integrations_js_1 = require("./integrations.js");
 Object.defineProperty(exports, "IntegrationsResource", { enumerable: true, get: function () { return integrations_js_1.IntegrationsResource; } });
+var entities_js_1 = require("./entities.js");
+Object.defineProperty(exports, "EntitiesResource", { enumerable: true, get: function () { return entities_js_1.EntitiesResource; } });
 var calendars_js_1 = require("./calendars.js");
 Object.defineProperty(exports, "CalendarsResource", { enumerable: true, get: function () { return calendars_js_1.CalendarsResource; } });
 var events_js_1 = require("./events.js");
@@ -24,3 +26,5 @@ var query_js_1 = require("./query.js");
 Object.defineProperty(exports, "QueryResource", { enumerable: true, get: function () { return query_js_1.QueryResource; } });
 var settings_js_1 = require("./settings.js");
 Object.defineProperty(exports, "AdminSettingsResource", { enumerable: true, get: function () { return settings_js_1.AdminSettingsResource; } });
+var webhooks_js_1 = require("./webhooks.js");
+Object.defineProperty(exports, "AdminWebhooksResource", { enumerable: true, get: function () { return webhooks_js_1.AdminWebhooksResource; } });

package/cjs/resources/messages.js

@@ -45,7 +45,7 @@ class MessagesResource {
     async list(options = {}) {
         const params = {};
         if (options.ids?.length) {
-            params.ids = options.ids.join(",");
+            params.ids = options.ids.join(',');
         }
         if (options.integrationId) {
             params.integration_id = options.integrationId;
@@ -65,13 +65,19 @@ class MessagesResource {
         if (options.offset !== undefined) {
             params.offset = String(options.offset);
         }
+        if (options.sentBy) {
+            params.sent_by = options.sentBy;
+        }
+        if (options.entityId) {
+            params.entity_id = options.entityId;
+        }
         if (options.excludeBots !== undefined) {
             params.exclude_bots = String(options.excludeBots);
         }
         if (options.expand?.length) {
-            params.expand = options.expand.join(",");
+            params.expand = options.expand.join(',');
         }
-        const response = await this.http.request(`/v1/users/${this.userId}/messages`, { method: "GET" }, params);
+        const response = await this.http.request(`/v1/users/${this.userId}/messages`, { method: 'GET' }, params);
         return {
             data: response.data,
             pagination: response.pagination,

package/cjs/resources/webhooks.js

@@ -0,0 +1,171 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AdminWebhooksResource = void 0;
+const index_js_1 = require("../errors/index.js");
+const index_js_2 = require("../types/index.js");
+function validateWebhookId(id, fieldName = 'id') {
+    if (!(0, index_js_2.isValidUUID)(id)) {
+        throw new index_js_1.ValidationError(`${fieldName} must be a valid UUID format`, index_js_2.ErrorCodes.VALIDATION_INVALID_FORMAT, { field: fieldName, expected: 'UUID format' });
+    }
+}
+function validateWebhookCreateOptions(options) {
+    if (!options.url || typeof options.url !== 'string') {
+        throw new index_js_1.ValidationError('url is required and must be a non-empty string', index_js_2.ErrorCodes.VALIDATION_REQUIRED_FIELD, { field: 'url' });
+    }
+    if (!options.url.startsWith('https://')) {
+        throw new index_js_1.ValidationError('url must use HTTPS', index_js_2.ErrorCodes.VALIDATION_INVALID_FORMAT, { field: 'url' });
+    }
+    if (!Array.isArray(options.eventTypes) || options.eventTypes.length === 0) {
+        throw new index_js_1.ValidationError('eventTypes must contain at least one event type', index_js_2.ErrorCodes.VALIDATION_REQUIRED_FIELD, { field: 'eventTypes' });
+    }
+}
+function validateWebhookUpdateOptions(options) {
+    if (options.url === undefined &&
+        options.eventTypes === undefined &&
+        options.isActive === undefined) {
+        throw new index_js_1.ValidationError('At least one field must be provided for update', index_js_2.ErrorCodes.VALIDATION_REQUIRED_FIELD, { field: 'options' });
+    }
+    if (typeof options.url === 'string' && !options.url.startsWith('https://')) {
+        throw new index_js_1.ValidationError('url must use HTTPS', index_js_2.ErrorCodes.VALIDATION_INVALID_FORMAT, { field: 'url' });
+    }
+    if (options.eventTypes !== undefined &&
+        (!Array.isArray(options.eventTypes) || options.eventTypes.length === 0)) {
+        throw new index_js_1.ValidationError('eventTypes must contain at least one event type', index_js_2.ErrorCodes.VALIDATION_INVALID_FORMAT, { field: 'eventTypes' });
+    }
+}
+function mapEndpoint(raw) {
+    return {
+        id: raw.id,
+        partnerId: raw.partner_id,
+        url: raw.url,
+        eventTypes: raw.event_types,
+        isActive: raw.is_active,
+        autoPausedAt: raw.auto_paused_at,
+        consecutiveFailures: raw.consecutive_failures,
+        secretPrefix: raw.secret_prefix,
+        secretSuffix: raw.secret_suffix,
+        createdByUserId: raw.created_by_user_id,
+        createdAt: raw.created_at,
+        updatedAt: raw.updated_at,
+    };
+}
+function mapDelivery(raw) {
+    return {
+        id: raw.id,
+        eventId: raw.event_id,
+        endpointId: raw.endpoint_id,
+        attempt: raw.attempt,
+        status: raw.status,
+        nextAttemptAt: raw.next_attempt_at,
+        responseStatus: raw.response_status,
+        responseBodyTruncated: raw.response_body_truncated,
+        durationMs: raw.duration_ms,
+        errorCode: raw.error_code,
+        webhookId: raw.webhook_id,
+        deliveredAt: raw.delivered_at,
+        createdAt: raw.created_at,
+        updatedAt: raw.updated_at,
+        eventType: raw.event_type,
+        eventVersion: raw.event_version,
+        occurredAt: raw.occurred_at,
+    };
+}
+class AdminWebhooksResource {
+    constructor(http, clientId) {
+        this.http = http;
+        this.clientId = clientId;
+    }
+    /** Creates a new webhook endpoint. The response includes the plaintext secret (shown only once). */
+    async create(options) {
+        validateWebhookCreateOptions(options);
+        const raw = await this.http.post('/v1/webhooks', {
+            url: options.url,
+            event_types: options.eventTypes,
+            is_active: options.isActive,
+        });
+        return {
+            ...mapEndpoint(raw),
+            secret: raw.secret,
+        };
+    }
+    /** Lists all webhook endpoints for this partner. */
+    async list() {
+        const raw = await this.http.get('/v1/webhooks');
+        return raw.map(mapEndpoint);
+    }
+    /** Retrieves a single webhook endpoint by ID. */
+    async get(id) {
+        validateWebhookId(id);
+        const raw = await this.http.get(`/v1/webhooks/${id}`);
+        return mapEndpoint(raw);
+    }
+    /** Updates a webhook endpoint's URL, subscribed event types, or active status. */
+    async update(id, options) {
+        validateWebhookId(id);
+        validateWebhookUpdateOptions(options);
+        const body = {};
+        if (options.url !== undefined) {
+            body['url'] = options.url;
+        }
+        if (options.eventTypes !== undefined) {
+            body['event_types'] = options.eventTypes;
+        }
+        if (options.isActive !== undefined) {
+            body['is_active'] = options.isActive;
+        }
+        const raw = await this.http.patch(`/v1/webhooks/${id}`, body);
+        return mapEndpoint(raw);
+    }
+    /** Deletes a webhook endpoint and all associated deliveries. */
+    async delete(id) {
+        validateWebhookId(id);
+        return this.http.delete(`/v1/webhooks/${id}`);
+    }
+    /** Sends a synthetic test event to the specified endpoint to verify connectivity. */
+    async test(id) {
+        validateWebhookId(id);
+        const raw = await this.http.post(`/v1/webhooks/${id}/test`, {});
+        return {
+            endpointId: raw.endpoint_id,
+            eventId: raw.event_id,
+            fanoutCount: raw.fanout_count,
+        };
+    }
+    /** Rotates the webhook signing secret. The previous secret remains valid for 24 hours. */
+    async rotateSecret(id) {
+        validateWebhookId(id);
+        const raw = await this.http.post(`/v1/webhooks/${id}/rotate-secret`, {});
+        return {
+            id: raw.id,
+            secret: raw.secret,
+            secretPrefix: raw.secret_prefix,
+            secretSuffix: raw.secret_suffix,
+            rotatedAt: raw.rotated_at,
+        };
+    }
+    /** Lists delivery attempts for a webhook endpoint, optionally filtered by status. */
+    async listDeliveries(id, options = {}) {
+        validateWebhookId(id);
+        const query = {};
+        if (typeof options.limit === 'number') {
+            if (!Number.isInteger(options.limit) ||
+                options.limit < 1 ||
+                options.limit > 100) {
+                throw new index_js_1.ValidationError('limit must be an integer between 1 and 100', index_js_2.ErrorCodes.VALIDATION_OUT_OF_RANGE, { field: 'limit', value: options.limit });
+            }
+            query.limit = String(options.limit);
+        }
+        if (typeof options.offset === 'number') {
+            if (!Number.isInteger(options.offset) || options.offset < 0) {
+                throw new index_js_1.ValidationError('offset must be a non-negative integer', index_js_2.ErrorCodes.VALIDATION_OUT_OF_RANGE, { field: 'offset', value: options.offset });
+            }
+            query.offset = String(options.offset);
+        }
+        if (options.status) {
+            query.status = options.status;
+        }
+        const raw = await this.http.get(`/v1/webhooks/${id}/deliveries`, query);
+        return raw.map(mapDelivery);
+    }
+}
+exports.AdminWebhooksResource = AdminWebhooksResource;

package/cjs/types/index.js

@@ -6,7 +6,7 @@
  * and do not depend on internal monorepo packages.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isValidStreamFrame = exports.ErrorCodes = exports.isValidISODate = exports.isApiKey = exports.isValidApiKey = exports.createUUID = exports.createISODate = exports.createApiKey = exports.createConversationId = exports.createMessageId = exports.createIntegrationId = exports.createUserId = exports.isValidUUID = exports.asBrandedString = void 0;
+exports.isValidStreamFrame = exports.UNKNOWN_SENDER = exports.ErrorCodes = exports.isValidISODate = exports.isApiKey = exports.isValidApiKey = exports.createUUID = exports.createISODate = exports.createApiKey = exports.createConversationId = exports.createMessageId = exports.createIntegrationId = exports.createUserId = exports.isValidUUID = exports.asBrandedString = void 0;
 /**
  * Helper to cast a string to a branded type.
  *
@@ -290,6 +290,8 @@ exports.ErrorCodes = {
     SERVICE_UNAVAILABLE: 'SERVICE_UNAVAILABLE',
     REQUEST_TIMEOUT: 'REQUEST_TIMEOUT',
 };
+/** Sentinel value for messages where the sender could not be resolved from the platform. */
+exports.UNKNOWN_SENDER = 'unknown';
 /**
  * Valid stream frame types.
  */

package/cjs/utils/fetch.js

@@ -152,6 +152,7 @@ class HttpClient {
         else if (auth.type === "partner") {
             headers["Authorization"] = `Bearer ${auth.clientSecret}`;
             headers["X-Auth-Type"] = "partner";
+            headers["X-Client-Id"] = auth.clientId;
         }
         return headers;
     }

package/cjs/utils/index.js

@@ -3,9 +3,12 @@
  * Utility exports
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.generateMessageId = exports.StreamingClient = exports.HttpClient = void 0;
+exports.verifyWebhookSignatureDetailed = exports.verifyWebhookSignature = exports.generateMessageId = exports.StreamingClient = exports.HttpClient = void 0;
 var fetch_js_1 = require("./fetch.js");
 Object.defineProperty(exports, "HttpClient", { enumerable: true, get: function () { return fetch_js_1.HttpClient; } });
 var streaming_js_1 = require("./streaming.js");
 Object.defineProperty(exports, "StreamingClient", { enumerable: true, get: function () { return streaming_js_1.StreamingClient; } });
 Object.defineProperty(exports, "generateMessageId", { enumerable: true, get: function () { return streaming_js_1.generateMessageId; } });
+var webhooks_js_1 = require("./webhooks.js");
+Object.defineProperty(exports, "verifyWebhookSignature", { enumerable: true, get: function () { return webhooks_js_1.verifyWebhookSignature; } });
+Object.defineProperty(exports, "verifyWebhookSignatureDetailed", { enumerable: true, get: function () { return webhooks_js_1.verifyWebhookSignatureDetailed; } });

package/cjs/utils/webhooks.js

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyWebhookSignature = exports.verifyWebhookSignatureDetailed = void 0;
+const tslib_1 = require("tslib");
+/// <reference types="node" />
+const crypto_1 = tslib_1.__importDefault(require("crypto"));
+const DEFAULT_TOLERANCE_SECONDS = 300;
+function getHeader(headers, name) {
+    const lowerName = name.toLowerCase();
+    if (typeof Headers !== 'undefined' && headers instanceof Headers) {
+        return headers.get(lowerName);
+    }
+    const record = headers;
+    for (const [key, value] of Object.entries(record)) {
+        if (key.toLowerCase() !== lowerName) {
+            continue;
+        }
+        if (Array.isArray(value)) {
+            return value[0] ?? null;
+        }
+        return value ?? null;
+    }
+    return null;
+}
+function normalizeBody(body) {
+    if (typeof body === 'string') {
+        return Buffer.from(body, 'utf8');
+    }
+    if (body instanceof Uint8Array) {
+        return Buffer.from(body);
+    }
+    return Buffer.from(body);
+}
+function extractSignatures(signatureHeader) {
+    const candidates = signatureHeader
+        .split(/\s+/)
+        .map((segment) => segment.trim())
+        .filter(Boolean);
+    const signatures = [];
+    for (const candidate of candidates) {
+        if (candidate.startsWith('v1,')) {
+            signatures.push(candidate.slice(3));
+            continue;
+        }
+        if (candidate.startsWith('v1=')) {
+            signatures.push(candidate.slice(3));
+            continue;
+        }
+        // Allow bare values to be tolerant of intermediary header transformations.
+        signatures.push(candidate);
+    }
+    return signatures.filter((signature) => signature.length > 0);
+}
+function expectedSignature(params) {
+    const hmac = crypto_1.default.createHmac('sha256', params.secret);
+    hmac.update(`${params.webhookId}.${params.timestamp}.`, 'utf8');
+    hmac.update(params.body);
+    return hmac.digest();
+}
+function safeCompare(left, right) {
+    if (left.length !== right.length) {
+        return false;
+    }
+    return crypto_1.default.timingSafeEqual(left, right);
+}
+/**
+ * Verifies Attrove webhook signatures using HMAC-SHA256 (`v1`).
+ * Returns a structured result with a reason on failure for easier debugging.
+ *
+ * Uses the raw secret string (including `whsec_` prefix) as the HMAC key.
+ * This matches the Attrove server's signing behaviour but differs from the
+ * Standard Webhooks reference implementation which base64-decodes the secret.
+ * Always use this SDK function (not a generic Standard Webhooks library) to verify.
+ *
+ * Signing input: `${webhook-id}.${webhook-timestamp}.${rawBody}`
+ *
+ * @remarks Node.js only — requires `crypto` and `Buffer` from Node.js built-ins.
+ */
+function verifyWebhookSignatureDetailed(headers, rawBody, secret, options = {}) {
+    const webhookId = getHeader(headers, 'webhook-id');
+    const timestamp = getHeader(headers, 'webhook-timestamp');
+    const signatureHeader = getHeader(headers, 'webhook-signature');
+    if (!webhookId || !timestamp || !signatureHeader) {
+        return { valid: false, reason: 'missing_headers' };
+    }
+    if (!secret) {
+        return { valid: false, reason: 'missing_secret' };
+    }
+    const timestampSeconds = Number(timestamp);
+    if (!Number.isFinite(timestampSeconds)) {
+        return { valid: false, reason: 'invalid_timestamp' };
+    }
+    const now = options.currentTimestamp ?? Math.floor(Date.now() / 1000);
+    const tolerance = options.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS;
+    if (Math.abs(now - timestampSeconds) > tolerance) {
+        return { valid: false, reason: 'timestamp_expired' };
+    }
+    const bodyBuffer = normalizeBody(rawBody);
+    const expected = expectedSignature({
+        secret,
+        webhookId,
+        timestamp,
+        body: bodyBuffer,
+    });
+    const providedSignatures = extractSignatures(signatureHeader);
+    const matched = providedSignatures.some((provided) => {
+        let decoded;
+        try {
+            decoded = Buffer.from(provided, 'base64');
+        }
+        catch {
+            return false;
+        }
+        return safeCompare(decoded, expected);
+    });
+    if (matched) {
+        return { valid: true };
+    }
+    return { valid: false, reason: 'no_matching_signature' };
+}
+exports.verifyWebhookSignatureDetailed = verifyWebhookSignatureDetailed;
+/**
+ * Verifies Attrove webhook signatures using HMAC-SHA256 (`v1`).
+ * Convenience wrapper that returns a boolean instead of a detailed result.
+ *
+ * @remarks Node.js only — requires `crypto` and `Buffer` from Node.js built-ins.
+ */
+function verifyWebhookSignature(headers, rawBody, secret, options = {}) {
+    return verifyWebhookSignatureDetailed(headers, rawBody, secret, options)
+        .valid;
+}
+exports.verifyWebhookSignature = verifyWebhookSignature;

package/esm/admin-client.d.ts

@@ -7,6 +7,7 @@
 import { HttpClient } from "./utils/fetch.js";
 import { AttroveAdminConfig, CreateUserOptions, CreateUserResponse, CreateTokenResponse } from "./types/index.js";
 import { AdminSettingsResource } from "./resources/settings.js";
+import { AdminWebhooksResource } from "./resources/webhooks.js";
 /**
  * Users admin resource for managing users.
  *
@@ -110,6 +111,10 @@ export declare class AttroveAdmin {
      * Settings resource for managing organization sync configuration.
      */
     readonly settings: AdminSettingsResource;
+    /**
+     * Webhooks resource for managing outbound webhook endpoints.
+     */
+    readonly webhooks: AdminWebhooksResource;
     /**
      * Create a new admin client.
      *

package/esm/admin-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"admin-client.d.ts","sourceRoot":"","sources":["../../../../packages/sdk/src/admin-client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAG9C,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EAEpB,MAAM,kBAAkB,CAAC;AAM1B,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAkDhE;;;;;GAKG;AACH,qBAAa,kBAAkB;IAE3B,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBADR,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,MAAM;IAGnC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACG,MAAM,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAsBrE;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;CAqBvE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CACe;IAEtC;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAC;IAEnC;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,CAAC;IAEzC;;;;;;;;;;;;;;OAcG;gBACS,MAAM,EAAE,kBAAkB;CA0BvC"}
+{"version":3,"file":"admin-client.d.ts","sourceRoot":"","sources":["../../../../packages/sdk/src/admin-client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAG9C,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EAEpB,MAAM,kBAAkB,CAAC;AAM1B,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAkDhE;;;;;GAKG;AACH,qBAAa,kBAAkB;IAE3B,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBADR,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,MAAM;IAGnC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACG,MAAM,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAsBrE;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;CAqBvE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CACe;IAEtC;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAC;IAEnC;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,CAAC;IAEzC;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,CAAC;IAEzC;;;;;;;;;;;;;;OAcG;gBACS,MAAM,EAAE,kBAAkB;CA2BvC"}

package/esm/admin-client.js

@@ -10,6 +10,7 @@ import { ErrorCodes } from "./types/index.js";
 import { isValidUUID, } from "./types/index.js";
 import { DEFAULT_BASE_URL, DEFAULT_TIMEOUT, DEFAULT_MAX_RETRIES, } from "./constants.js";
 import { AdminSettingsResource } from "./resources/settings.js";
+import { AdminWebhooksResource } from "./resources/webhooks.js";
 /**
  * Validate the admin client configuration.
  *
@@ -193,6 +194,7 @@ export class AttroveAdmin {
         // Initialize resources
         this.users = new AdminUsersResource(this.http, this.config.clientId);
         this.settings = new AdminSettingsResource(this.http, this.config.clientId);
+        this.webhooks = new AdminWebhooksResource(this.http, this.config.clientId);
     }
 }
 //# sourceMappingURL=admin-client.js.map