featurebase-node 0.0.2

package/resources/contacts/contacts.d.mts

@@ -0,0 +1,708 @@
+import { APIResource } from "../../core/resource.mjs";
+import * as ContactsAPI from "./contacts.mjs";
+import * as CompaniesAPI from "../companies/companies.mjs";
+import * as EmailPreferencesAPI from "./email-preferences.mjs";
+import { EmailPreferenceRetrieveParams, EmailPreferenceUpdateParams, EmailPreferences, PreferenceState, PreferencesOutput, UpdatePreferenceBody } from "./email-preferences.mjs";
+import * as ByUserIDAPI from "./by-user-id/by-user-id.mjs";
+import { ByUserID, ByUserIDDeleteParams, ByUserIDRetrieveParams, ByUserIDRetrieveResponse } from "./by-user-id/by-user-id.mjs";
+import { APIPromise } from "../../core/api-promise.mjs";
+import { RequestOptions } from "../../internal/request-options.mjs";
+/**
+ * Contacts are the customers and leads in your Featurebase organization. Use this endpoint to list and retrieve contact information.
+ */
+export declare class Contacts extends APIResource {
+    byUserID: ByUserIDAPI.ByUserID;
+    emailPreferences: EmailPreferencesAPI.EmailPreferences;
+    /**
+     * 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: string, params?: ContactRetrieveParams | null | undefined, options?: RequestOptions): APIPromise<ContactRetrieveResponse>;
+    /**
+     * 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?: ContactListParams | null | undefined, options?: RequestOptions): APIPromise<ContactList>;
+    /**
+     * 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: string, params?: ContactDeleteParams | null | undefined, options?: RequestOptions): APIPromise<DeletedContact>;
+    /**
+     * 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: string, params?: ContactBlockParams | null | undefined, options?: RequestOptions): APIPromise<ContactBlockResponse>;
+    /**
+     * 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: ContactCreateOrUpdateParams, options?: RequestOptions): APIPromise<ContactCreateOrUpdateResponse>;
+    /**
+     * 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: string, params?: ContactUnblockParams | null | undefined, options?: RequestOptions): APIPromise<ContactUnblockResponse>;
+}
+/**
+ * User who submitted the response
+ */
+export interface Contact {
+    /**
+     * Unique identifier
+     */
+    id: string;
+    /**
+     * Contact display name
+     */
+    name: string;
+    /**
+     * Object type identifier
+     */
+    object: 'contact';
+    /**
+     * Type of contact
+     */
+    type: 'customer' | 'lead';
+    /**
+     * Number of comments created
+     */
+    commentsCreated?: number;
+    /**
+     * Companies the contact belongs to
+     */
+    companies?: Array<CompaniesAPI.Company>;
+    /**
+     * Custom field values on the contact
+     */
+    customFields?: {
+        [key: string]: unknown;
+    };
+    /**
+     * Contact description/bio
+     */
+    description?: string;
+    /**
+     * Contact email
+     */
+    email?: string | null;
+    /**
+     * Last activity ISO timestamp
+     */
+    lastActivity?: string;
+    /**
+     * Contact locale
+     */
+    locale?: string;
+    /**
+     * Whether manually opted out from changelog
+     */
+    manuallyOptedOutFromChangelog?: boolean;
+    /**
+     * Organization ID the contact belongs to
+     */
+    organizationId?: string;
+    /**
+     * Number of posts created
+     */
+    postsCreated?: number;
+    /**
+     * Profile picture URL
+     */
+    profilePicture?: string | null;
+    /**
+     * Contact roles
+     */
+    roles?: Array<string>;
+    /**
+     * Whether subscribed to changelog
+     */
+    subscribedToChangelog?: boolean;
+    /**
+     * External user ID from SSO
+     */
+    userId?: string;
+    /**
+     * Whether email is verified
+     */
+    verified?: boolean;
+}
+export interface ContactList {
+    /**
+     * Array of contacts
+     */
+    data: Array<ContactList.Data>;
+    /**
+     * Cursor for fetching the next page (cursor-based pagination)
+     */
+    nextCursor: string | null;
+    /**
+     * Object type identifier
+     */
+    object: 'list';
+}
+export declare namespace ContactList {
+    /**
+     * User who submitted the response
+     */
+    type Data = ContactsAPI.Contact | (null & {});
+}
+export interface DeletedContact {
+    /**
+     * Unique identifier of the deleted contact
+     */
+    id: string;
+    /**
+     * Indicates the resource was deleted
+     */
+    deleted: true;
+    /**
+     * Object type identifier
+     */
+    object: 'contact';
+}
+/**
+ * User who submitted the response
+ */
+export type ContactRetrieveResponse = Contact | (null & {});
+export interface ContactBlockResponse {
+    /**
+     * Unique identifier of the blocked contact
+     */
+    id: string;
+    /**
+     * Indicates the contact was blocked
+     */
+    blocked: true;
+    /**
+     * Object type identifier
+     */
+    object: 'contact';
+}
+/**
+ * User who submitted the response
+ */
+export type ContactCreateOrUpdateResponse = Contact | (null & {});
+export interface ContactUnblockResponse {
+    /**
+     * Unique identifier of the unblocked contact
+     */
+    id: string;
+    /**
+     * Object type identifier
+     */
+    object: 'contact';
+    /**
+     * Indicates the contact was unblocked
+     */
+    unblocked: true;
+}
+export interface ContactRetrieveParams {
+    /**
+     * API version for this request. Defaults to your organization's configured API
+     * version if not specified.
+     */
+    'Featurebase-Version'?: string;
+}
+export interface ContactListParams {
+    /**
+     * Query param: Filter contacts by type. Defaults to "customer".
+     */
+    contactType?: 'customer' | 'lead' | 'all';
+    /**
+     * Query param: An opaque cursor for pagination. Use the nextCursor value from a
+     * previous response to fetch the next page of results.
+     */
+    cursor?: string;
+    /**
+     * Query param: A limit on the number of objects to be returned, between 1 and 100.
+     */
+    limit?: number;
+    /**
+     * Header param: API version for this request. Defaults to your organization's
+     * configured API version if not specified.
+     */
+    'Featurebase-Version'?: string;
+}
+export interface ContactDeleteParams {
+    /**
+     * API version for this request. Defaults to your organization's configured API
+     * version if not specified.
+     */
+    'Featurebase-Version'?: string;
+}
+export interface ContactBlockParams {
+    /**
+     * API version for this request. Defaults to your organization's configured API
+     * version if not specified.
+     */
+    'Featurebase-Version'?: string;
+}
+export interface ContactCreateOrUpdateParams {
+    /**
+     * Body param: Companies the contact belongs to
+     */
+    companies?: Array<ContactCreateOrUpdateParams.Company>;
+    /**
+     * Body param: When the contact was created in your system (ISO 8601)
+     */
+    createdAt?: string | null;
+    /**
+     * Body param: Custom field values on the contact. Values can be string, number,
+     * boolean, null, or array of primitives.
+     */
+    customFields?: ContactCreateOrUpdateParams.CustomFields;
+    /**
+     * Body param: Contact email address. Used for identification if userId is not
+     * provided.
+     */
+    email?: string;
+    /**
+     * Body param: Contact locale/language preference
+     */
+    locale?: string;
+    /**
+     * Body param: Contact display name
+     */
+    name?: string;
+    /**
+     * Body param: Contact phone number
+     */
+    phone?: string | null;
+    /**
+     * Body param: Profile picture URL
+     */
+    profilePicture?: string | null;
+    /**
+     * Body param: Array of role IDs to assign to the contact
+     */
+    roles?: Array<string>;
+    /**
+     * Body param: Whether the contact is subscribed to changelog updates
+     */
+    subscribedToChangelog?: boolean;
+    /**
+     * Body param: HMAC-SHA256 hash of userId or email for identity verification
+     */
+    userHash?: string;
+    /**
+     * Body param: External user ID from your system. Takes precedence over email for
+     * identification.
+     */
+    userId?: string;
+    /**
+     * Header param: API version for this request. Defaults to your organization's
+     * configured API version if not specified.
+     */
+    'Featurebase-Version'?: string;
+}
+export declare namespace ContactCreateOrUpdateParams {
+    interface Company {
+        /**
+         * External company ID from your system
+         */
+        id: string;
+        /**
+         * Company name
+         */
+        name: string;
+        /**
+         * HMAC-SHA256 hash of company ID for identity verification
+         */
+        companyHash?: string;
+        /**
+         * Number of employees in the company
+         */
+        companySize?: number | null;
+        /**
+         * When the company was created (ISO 8601)
+         */
+        createdAt?: string | null;
+        /**
+         * Custom field values on the company. Values can be string, number, boolean, null,
+         * or array of primitives.
+         */
+        customFields?: Company.CustomFields;
+        /**
+         * Industry the company operates in
+         */
+        industry?: string;
+        /**
+         * Monthly spend/revenue from this company
+         */
+        monthlySpend?: number;
+        /**
+         * Current plan/subscription name
+         */
+        plan?: string;
+        /**
+         * Company website URL
+         */
+        website?: string;
+    }
+    namespace Company {
+        /**
+         * Custom field values on the company. Values can be string, number, boolean, null,
+         * or array of primitives.
+         */
+        interface CustomFields {
+            industry?: string;
+            plan?: string;
+            priority?: string;
+        }
+    }
+    /**
+     * Custom field values on the contact. Values can be string, number, boolean, null,
+     * or array of primitives.
+     */
+    interface CustomFields {
+        accountType?: string;
+        plan?: string;
+        signupSource?: string;
+    }
+}
+export interface ContactUnblockParams {
+    /**
+     * API version for this request. Defaults to your organization's configured API
+     * version if not specified.
+     */
+    'Featurebase-Version'?: string;
+}
+export declare namespace Contacts {
+    export { type Contact as Contact, type ContactList as ContactList, type DeletedContact as DeletedContact, type ContactRetrieveResponse as ContactRetrieveResponse, type ContactBlockResponse as ContactBlockResponse, type ContactCreateOrUpdateResponse as ContactCreateOrUpdateResponse, type ContactUnblockResponse as ContactUnblockResponse, type ContactRetrieveParams as ContactRetrieveParams, type ContactListParams as ContactListParams, type ContactDeleteParams as ContactDeleteParams, type ContactBlockParams as ContactBlockParams, type ContactCreateOrUpdateParams as ContactCreateOrUpdateParams, type ContactUnblockParams as ContactUnblockParams, };
+    export { ByUserID as ByUserID, type ByUserIDRetrieveResponse as ByUserIDRetrieveResponse, type ByUserIDRetrieveParams as ByUserIDRetrieveParams, type ByUserIDDeleteParams as ByUserIDDeleteParams, };
+    export { EmailPreferences as EmailPreferences, type PreferenceState as PreferenceState, type PreferencesOutput as PreferencesOutput, type UpdatePreferenceBody as UpdatePreferenceBody, type EmailPreferenceRetrieveParams as EmailPreferenceRetrieveParams, type EmailPreferenceUpdateParams as EmailPreferenceUpdateParams, };
+}
+//# sourceMappingURL=contacts.d.mts.map