featurebase-node 0.0.2

package/resources/contacts/contacts.mjs

@@ -0,0 +1,439 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+import { APIResource } from "../../core/resource.mjs";
+import * as EmailPreferencesAPI from "./email-preferences.mjs";
+import { EmailPreferences, } from "./email-preferences.mjs";
+import * as ByUserIDAPI from "./by-user-id/by-user-id.mjs";
+import { ByUserID, } from "./by-user-id/by-user-id.mjs";
+import { buildHeaders } from "../../internal/headers.mjs";
+import { path } from "../../internal/utils/path.mjs";
+/**
+ * Contacts are the customers and leads in your Featurebase organization. Use this endpoint to list and retrieve contact information.
+ */
+export class Contacts extends APIResource {
+    constructor() {
+        super(...arguments);
+        this.byUserID = new ByUserIDAPI.ByUserID(this._client);
+        this.emailPreferences = new EmailPreferencesAPI.EmailPreferences(this._client);
+    }
+    /**
+     * Retrieves a single contact by their Featurebase ID.
+     *
+     * Returns both customers and leads.
+     *
+     * ### Path Parameters
+     *
+     * - `id` - The Featurebase contact ID (24-character ObjectId)
+     *
+     * ### Response Format
+     *
+     * Returns a single contact object with:
+     *
+     * - `object` - Always "contact"
+     * - `id` - Unique contact identifier
+     * - `userId` - External user ID from SSO (if set)
+     * - `email` - Contact email address
+     * - `name` - Contact display name
+     * - `profilePicture` - Profile picture URL
+     * - `type` - Contact type ("customer" or "lead")
+     * - `companies` - Array of companies the contact belongs to
+     * - `customFields` - Custom field values
+     * - `postsCreated` - Number of posts created
+     * - `commentsCreated` - Number of comments created
+     * - `lastActivity` - Last activity timestamp
+     *
+     * ### Example
+     *
+     * ```json
+     * {
+     *   "object": "contact",
+     *   "id": "676f0f6765bdaa7d7d760f88",
+     *   "email": "john@example.com",
+     *   "name": "John Doe",
+     *   "type": "customer",
+     *   ...
+     * }
+     * ```
+     *
+     * ### Version Availability
+     *
+     * This endpoint is only available in API version 2026-01-01.nova and newer.
+     *
+     * @example
+     * ```ts
+     * const contact = await client.contacts.retrieve(
+     *   '507f1f77bcf86cd799439011',
+     * );
+     * ```
+     */
+    retrieve(id, params = {}, options) {
+        const { 'Featurebase-Version': featurebaseVersion } = params ?? {};
+        return this._client.get(path `/v2/contacts/${id}`, {
+            ...options,
+            headers: buildHeaders([
+                { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+                options?.headers,
+            ]),
+        });
+    }
+    /**
+     * Returns a list of contacts (customers and leads) in your organization using
+     * cursor-based pagination.
+     *
+     * ### Query Parameters
+     *
+     * - `limit` - Number of contacts to return (1-100, default 10)
+     * - `cursor` - Cursor from previous response for pagination
+     * - `contactType` - Filter by contact type: "customer" (default), "lead", or "all"
+     *
+     * ### Response Format
+     *
+     * Returns a list object with:
+     *
+     * - `object` - Always "list"
+     * - `data` - Array of contact objects
+     * - `nextCursor` - Cursor for the next page, or null if no more results
+     *
+     * ### Contact Object
+     *
+     * Each contact includes:
+     *
+     * - `id` - Unique contact identifier
+     * - `userId` - External user ID from SSO (if set)
+     * - `email` - Contact email address
+     * - `name` - Contact display name
+     * - `profilePicture` - Profile picture URL
+     * - `type` - Contact type ("customer" or "lead")
+     * - `companies` - Array of companies the contact belongs to
+     * - `customFields` - Custom field values
+     * - `postsCreated` - Number of posts created
+     * - `commentsCreated` - Number of comments created
+     * - `lastActivity` - Last activity timestamp
+     *
+     * ### Example
+     *
+     * ```json
+     * {
+     *   "object": "list",
+     *   "data": [
+     *     {
+     *       "object": "contact",
+     *       "id": "676f0f6765bdaa7d7d760f88",
+     *       "email": "john@example.com",
+     *       "name": "John Doe",
+     *       "type": "customer",
+     *       ...
+     *     }
+     *   ],
+     *   "nextCursor": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9"
+     * }
+     * ```
+     *
+     * ### Version Availability
+     *
+     * This endpoint is only available in API version 2026-01-01.nova and newer.
+     *
+     * @example
+     * ```ts
+     * const contactList = await client.contacts.list();
+     * ```
+     */
+    list(params = {}, options) {
+        const { 'Featurebase-Version': featurebaseVersion, ...query } = params ?? {};
+        return this._client.get('/v2/contacts', {
+            query,
+            ...options,
+            headers: buildHeaders([
+                { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+                options?.headers,
+            ]),
+        });
+    }
+    /**
+     * Permanently deletes a contact by their Featurebase ID.
+     *
+     * Supports deleting both customers and leads.
+     *
+     * ### Path Parameters
+     *
+     * - `id` - The Featurebase contact ID (24-character ObjectId)
+     *
+     * ### Deletion Behavior
+     *
+     * When a contact is deleted:
+     *
+     * - The contact record is permanently removed
+     * - Associated data cleanup is triggered asynchronously
+     * - Comments and posts created by the contact are handled according to retention
+     *   policies
+     *
+     * ### Response
+     *
+     * Returns a deletion confirmation object:
+     *
+     * - `id` - The ID of the deleted contact
+     * - `object` - Always "contact"
+     * - `deleted` - Always `true`
+     *
+     * ### Example Response
+     *
+     * ```json
+     * {
+     *   "id": "676f0f6765bdaa7d7d760f88",
+     *   "object": "contact",
+     *   "deleted": true
+     * }
+     * ```
+     *
+     * ### Version Availability
+     *
+     * This endpoint is only available in API version 2026-01-01.nova and newer.
+     *
+     * @example
+     * ```ts
+     * const deletedContact = await client.contacts.delete(
+     *   '507f1f77bcf86cd799439011',
+     * );
+     * ```
+     */
+    delete(id, params = {}, options) {
+        const { 'Featurebase-Version': featurebaseVersion } = params ?? {};
+        return this._client.delete(path `/v2/contacts/${id}`, {
+            ...options,
+            headers: buildHeaders([
+                { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+                options?.headers,
+            ]),
+        });
+    }
+    /**
+     * Blocks a contact by their Featurebase ID from the messenger/inbox.
+     *
+     * ### Path Parameters
+     *
+     * - `id` - The Featurebase internal ID of the contact (MongoDB ObjectId)
+     *
+     * ### Supported Contact Types
+     *
+     * This endpoint blocks both:
+     *
+     * - **Customers** - Users with registered accounts
+     * - **Leads** - Anonymous or unregistered visitors
+     *
+     * ### Blocking Behavior
+     *
+     * When a contact is blocked:
+     *
+     * - The contact cannot send new messages via messenger
+     * - Existing conversations are not deleted but no new messages can be added by the
+     *   blocked user
+     * - The block can be removed by unblocking the contact
+     *
+     * ### Response
+     *
+     * Returns a block confirmation object:
+     *
+     * - `id` - The ID of the blocked contact
+     * - `object` - Always "contact"
+     * - `blocked` - Always `true`
+     *
+     * ### Example Response
+     *
+     * ```json
+     * {
+     *   "id": "507f1f77bcf86cd799439011",
+     *   "object": "contact",
+     *   "blocked": true
+     * }
+     * ```
+     *
+     * ### Version Availability
+     *
+     * This endpoint is only available in API version 2026-01-01.nova and newer.
+     *
+     * @example
+     * ```ts
+     * const response = await client.contacts.block(
+     *   '507f1f77bcf86cd799439011',
+     * );
+     * ```
+     */
+    block(id, params = {}, options) {
+        const { 'Featurebase-Version': featurebaseVersion } = params ?? {};
+        return this._client.post(path `/v2/contacts/${id}/block`, {
+            ...options,
+            headers: buildHeaders([
+                { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+                options?.headers,
+            ]),
+        });
+    }
+    /**
+     * Creates a new contact or updates an existing one.
+     *
+     * If a contact with the given `email` or `userId` already exists, it will be
+     * updated. Otherwise, a new contact will be created.
+     *
+     * **At least one of `email` or `userId` must be provided for identification.**
+     *
+     * ### Request Body
+     *
+     * | Field                   | Type    | Required            | Description                             |
+     * | ----------------------- | ------- | ------------------- | --------------------------------------- |
+     * | `email`                 | string  | One of email/userId | Contact email address                   |
+     * | `userId`                | string  | One of email/userId | External user ID from your system       |
+     * | `name`                  | string  | No                  | Contact display name                    |
+     * | `profilePicture`        | string  | No                  | Profile picture URL                     |
+     * | `companies`             | array   | No                  | Companies the contact belongs to        |
+     * | `customFields`          | object  | No                  | Custom field values                     |
+     * | `subscribedToChangelog` | boolean | No                  | Whether subscribed to changelog         |
+     * | `locale`                | string  | No                  | Contact locale/language                 |
+     * | `phone`                 | string  | No                  | Contact phone number                    |
+     * | `roles`                 | array   | No                  | Role IDs to assign                      |
+     * | `userHash`              | string  | No                  | HMAC hash for identity verification     |
+     * | `createdAt`             | string  | No                  | When the contact was created (ISO 8601) |
+     *
+     * ### Company Object
+     *
+     * Each company in the `companies` array can have:
+     *
+     * - `id` (required) - External company ID from your system
+     * - `name` (required) - Company name
+     * - `monthlySpend` - Monthly spend/revenue
+     * - `customFields` - Custom field values
+     * - `industry` - Industry
+     * - `website` - Company website URL
+     * - `plan` - Current plan/subscription
+     * - `companySize` - Number of employees
+     * - `createdAt` - When the company was created
+     *
+     * ### Response
+     *
+     * Returns the created or updated contact object.
+     *
+     * - **201 Created** - A new contact was created
+     * - **200 OK** - An existing contact was updated
+     *
+     * ### Example Request
+     *
+     * ```json
+     * {
+     *   "email": "john@example.com",
+     *   "name": "John Doe",
+     *   "userId": "usr_12345",
+     *   "companies": [
+     *     {
+     *       "id": "company_123",
+     *       "name": "Acme Inc",
+     *       "monthlySpend": 500,
+     *       "plan": "enterprise"
+     *     }
+     *   ],
+     *   "customFields": {
+     *     "plan": "pro",
+     *     "signupSource": "website"
+     *   },
+     *   "subscribedToChangelog": true
+     * }
+     * ```
+     *
+     * ### Example Response
+     *
+     * ```json
+     * {
+     *   "object": "contact",
+     *   "id": "676f0f6765bdaa7d7d760f88",
+     *   "email": "john@example.com",
+     *   "name": "John Doe",
+     *   "userId": "usr_12345",
+     *   "type": "customer",
+     *   "companies": [...],
+     *   "customFields": {...},
+     *   ...
+     * }
+     * ```
+     *
+     * ### Version Availability
+     *
+     * This endpoint is only available in API version 2026-01-01.nova and newer.
+     *
+     * @example
+     * ```ts
+     * const response = await client.contacts.createOrUpdate();
+     * ```
+     */
+    createOrUpdate(params, options) {
+        const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
+        return this._client.post('/v2/contacts', {
+            body,
+            ...options,
+            headers: buildHeaders([
+                { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+                options?.headers,
+            ]),
+        });
+    }
+    /**
+     * Unblocks a contact by their Featurebase ID from the messenger/inbox.
+     *
+     * ### Path Parameters
+     *
+     * - `id` - The Featurebase internal ID of the contact (MongoDB ObjectId)
+     *
+     * ### Supported Contact Types
+     *
+     * This endpoint unblocks both:
+     *
+     * - **Customers** - Users with registered accounts
+     * - **Leads** - Anonymous or unregistered visitors
+     *
+     * ### Unblocking Behavior
+     *
+     * When a contact is unblocked:
+     *
+     * - The contact can resume sending messages via messenger
+     * - Previously blocked conversations remain intact
+     * - The contact regains full messenger functionality
+     *
+     * ### Response
+     *
+     * Returns an unblock confirmation object:
+     *
+     * - `id` - The ID of the unblocked contact
+     * - `object` - Always "contact"
+     * - `unblocked` - Always `true`
+     *
+     * ### Example Response
+     *
+     * ```json
+     * {
+     *   "id": "507f1f77bcf86cd799439011",
+     *   "object": "contact",
+     *   "unblocked": true
+     * }
+     * ```
+     *
+     * ### Version Availability
+     *
+     * This endpoint is only available in API version 2026-01-01.nova and newer.
+     *
+     * @example
+     * ```ts
+     * const response = await client.contacts.unblock(
+     *   '507f1f77bcf86cd799439011',
+     * );
+     * ```
+     */
+    unblock(id, params = {}, options) {
+        const { 'Featurebase-Version': featurebaseVersion } = params ?? {};
+        return this._client.post(path `/v2/contacts/${id}/unblock`, {
+            ...options,
+            headers: buildHeaders([
+                { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+                options?.headers,
+            ]),
+        });
+    }
+}
+Contacts.ByUserID = ByUserID;
+Contacts.EmailPreferences = EmailPreferences;
+//# sourceMappingURL=contacts.mjs.map

package/resources/contacts/contacts.mjs.map

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