featurebase-node 0.0.2

package/src/resources/companies/contacts.ts

@@ -0,0 +1,299 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import { APIPromise } from '../../core/api-promise';
+import { buildHeaders } from '../../internal/headers';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+import * as ContactsAPI_ from '../contacts/contacts';
+
+/**
+ * Companies represent organizations or businesses that your users belong to. Use this endpoint to list and retrieve company information.
+ */
+export class Contacts extends APIResource {
+  /**
+   * Returns all contacts (customers) attached to a specific company.
+   *
+   * Only returns contacts with type "customer" that have the company in their
+   * `companyIds` array. Uses cursor-based pagination.
+   *
+   * ### Path Parameters
+   *
+   * - `id` - The Featurebase internal ID of the company (MongoDB ObjectId)
+   *
+   * ### Query Parameters
+   *
+   * - `limit` - Number of contacts to return (1-100, default: 10)
+   * - `cursor` - Opaque cursor from a previous response for pagination
+   *
+   * ### Response Structure
+   *
+   * The response includes:
+   *
+   * - `object` - Always "list"
+   * - `data` - Array of contact objects
+   * - `nextCursor` - Cursor for the next page (null if no more results)
+   *
+   * ### Example Response
+   *
+   * ```json
+   * {
+   *   "object": "list",
+   *   "data": [
+   *     {
+   *       "object": "contact",
+   *       "id": "507f1f77bcf86cd799439011",
+   *       "userId": "usr_12345",
+   *       "email": "john@acme.com",
+   *       "name": "John Doe",
+   *       "type": "customer",
+   *       "companies": [...],
+   *       "createdAt": "2025-01-01T12:00:00.000Z"
+   *     }
+   *   ],
+   *   "nextCursor": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9"
+   * }
+   * ```
+   *
+   * ### Error Responses
+   *
+   * - **404 Not Found** - Company with the specified ID does not exist
+   *
+   * ### Version Availability
+   *
+   * This endpoint is only available in API version 2026-01-01.nova and newer.
+   *
+   * @example
+   * ```ts
+   * const contactList = await client.companies.contacts.list(
+   *   '507f1f77bcf86cd799439011',
+   * );
+   * ```
+   */
+  list(
+    id: string,
+    params: ContactListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<ContactsAPI_.ContactList> {
+    const { 'Featurebase-Version': featurebaseVersion, ...query } = params ?? {};
+    return this._client.get(path`/v2/companies/${id}/contacts`, {
+      query,
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Attaches a contact (customer) to a company.
+   *
+   * Adds the company to the contact's `companyIds` array and embedded `companies`
+   * array. This operation is **additive** - existing company associations are
+   * preserved. Also increments the `linkedUsers` count on the company.
+   *
+   * ### Path Parameters
+   *
+   * - `id` - The Featurebase internal ID of the company (MongoDB ObjectId)
+   *
+   * ### Request Body
+   *
+   * | Field       | Type   | Required | Description                                                             |
+   * | ----------- | ------ | -------- | ----------------------------------------------------------------------- |
+   * | `contactId` | string | Yes      | The Featurebase internal ID of the contact to attach (MongoDB ObjectId) |
+   *
+   * ### Example Request
+   *
+   * ```json
+   * {
+   *   "contactId": "507f1f77bcf86cd799439012"
+   * }
+   * ```
+   *
+   * ### Response
+   *
+   * Returns the updated contact object with the new company association.
+   *
+   * ### Example Response
+   *
+   * ```json
+   * {
+   *   "object": "contact",
+   *   "id": "507f1f77bcf86cd799439012",
+   *   "userId": "usr_12345",
+   *   "email": "john@acme.com",
+   *   "name": "John Doe",
+   *   "type": "customer",
+   *   "companies": [
+   *     {
+   *       "object": "company",
+   *       "id": "507f1f77bcf86cd799439011",
+   *       "companyId": "comp_12345",
+   *       "name": "Acme Inc"
+   *     }
+   *   ]
+   * }
+   * ```
+   *
+   * ### Error Responses
+   *
+   * - **404 Not Found** - Company or contact does not exist
+   *
+   * ### Version Availability
+   *
+   * This endpoint is only available in API version 2026-01-01.nova and newer.
+   *
+   * @example
+   * ```ts
+   * const response = await client.companies.contacts.attach(
+   *   '507f1f77bcf86cd799439011',
+   *   { contactId: '507f1f77bcf86cd799439012' },
+   * );
+   * ```
+   */
+  attach(
+    id: string,
+    params: ContactAttachParams,
+    options?: RequestOptions,
+  ): APIPromise<ContactAttachResponse> {
+    const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
+    return this._client.post(path`/v2/companies/${id}/contacts`, {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Removes a contact (customer) from a company.
+   *
+   * Removes the company from the contact's `companyIds` array and embedded
+   * `companies` array. Also decrements the `linkedUsers` count on the company.
+   *
+   * ### Path Parameters
+   *
+   * - `id` - The Featurebase internal ID of the company (MongoDB ObjectId)
+   * - `contactId` - The Featurebase internal ID of the contact to remove (MongoDB
+   *   ObjectId)
+   *
+   * ### Response
+   *
+   * Returns the updated contact object with the company removed.
+   *
+   * ### Example Response
+   *
+   * ```json
+   * {
+   *   "object": "contact",
+   *   "id": "507f1f77bcf86cd799439012",
+   *   "userId": "usr_12345",
+   *   "email": "john@acme.com",
+   *   "name": "John Doe",
+   *   "type": "customer",
+   *   "companies": []
+   * }
+   * ```
+   *
+   * ### Error Responses
+   *
+   * - **400 Bad Request** - Contact is not attached to this company
+   * - **404 Not Found** - Company or contact does not exist
+   *
+   * ### Version Availability
+   *
+   * This endpoint is only available in API version 2026-01-01.nova and newer.
+   *
+   * @example
+   * ```ts
+   * const contact = await client.companies.contacts.remove(
+   *   '507f1f77bcf86cd799439012',
+   *   { id: '507f1f77bcf86cd799439011' },
+   * );
+   * ```
+   */
+  remove(
+    contactID: string,
+    params: ContactRemoveParams,
+    options?: RequestOptions,
+  ): APIPromise<ContactRemoveResponse> {
+    const { id, 'Featurebase-Version': featurebaseVersion } = params;
+    return this._client.delete(path`/v2/companies/${id}/contacts/${contactID}`, {
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+}
+
+/**
+ * User who submitted the response
+ */
+export type ContactAttachResponse = ContactsAPI_.Contact | (null & {});
+
+/**
+ * User who submitted the response
+ */
+export type ContactRemoveResponse = ContactsAPI_.Contact | (null & {});
+
+export interface ContactListParams {
+  /**
+   * 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 contacts 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 ContactAttachParams {
+  /**
+   * Body param: The Featurebase internal ID of the contact to attach (MongoDB
+   * ObjectId)
+   */
+  contactId: string;
+
+  /**
+   * Header param: API version for this request. Defaults to your organization's
+   * configured API version if not specified.
+   */
+  'Featurebase-Version'?: string;
+}
+
+export interface ContactRemoveParams {
+  /**
+   * Path param: The Featurebase internal ID of the company (MongoDB ObjectId)
+   */
+  id: 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 Contacts {
+  export {
+    type ContactAttachResponse as ContactAttachResponse,
+    type ContactRemoveResponse as ContactRemoveResponse,
+    type ContactListParams as ContactListParams,
+    type ContactAttachParams as ContactAttachParams,
+    type ContactRemoveParams as ContactRemoveParams,
+  };
+}

package/src/resources/companies/index.ts

@@ -0,0 +1,21 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export {
+  Companies,
+  type Company,
+  type DeletedCompany,
+  type CompanyListResponse,
+  type CompanyRetrieveParams,
+  type CompanyListParams,
+  type CompanyDeleteParams,
+  type CompanyCreateOrUpdateParams,
+  type CompanyDeleteByCompanyIDParams,
+} from './companies';
+export {
+  Contacts,
+  type ContactAttachResponse,
+  type ContactRemoveResponse,
+  type ContactListParams,
+  type ContactAttachParams,
+  type ContactRemoveParams,
+} from './contacts';

package/src/resources/companies.ts

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './companies/index';

package/src/resources/contacts/by-user-id/by-user-id.ts

@@ -0,0 +1,200 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../core/resource';
+import * as ContactsAPI from '../contacts';
+import * as EmailPreferencesAPI from './email-preferences';
+import {
+  EmailPreferenceRetrieveParams,
+  EmailPreferenceUpdateParams,
+  EmailPreferences,
+} from './email-preferences';
+import { APIPromise } from '../../../core/api-promise';
+import { buildHeaders } from '../../../internal/headers';
+import { RequestOptions } from '../../../internal/request-options';
+import { path } from '../../../internal/utils/path';
+
+/**
+ * Contacts are the customers and leads in your Featurebase organization. Use this endpoint to list and retrieve contact information.
+ */
+export class ByUserID extends APIResource {
+  emailPreferences: EmailPreferencesAPI.EmailPreferences = new EmailPreferencesAPI.EmailPreferences(
+    this._client,
+  );
+
+  /**
+   * Retrieves a single contact by their external user ID (from your system via SSO).
+   *
+   * **Important:** This endpoint only returns customers (type: "customer"). Leads
+   * are not returned.
+   *
+   * ### Path Parameters
+   *
+   * - `userId` - The external user ID from your system (matched via SSO integration)
+   *
+   * ### Response Format
+   *
+   * Returns a single contact object with:
+   *
+   * - `object` - Always "contact"
+   * - `id` - Unique contact identifier
+   * - `userId` - External user ID from SSO
+   * - `email` - Contact email address
+   * - `name` - Contact display name
+   * - `profilePicture` - Profile picture URL
+   * - `type` - Always "customer" for this endpoint
+   * - `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",
+   *   "userId": "usr_12345",
+   *   "email": "john@example.com",
+   *   "name": "John Doe",
+   *   "type": "customer",
+   *   ...
+   * }
+   * ```
+   *
+   * ### Use Case
+   *
+   * This endpoint is useful when you need to look up a contact using your own
+   * system's user identifier, such as when displaying Featurebase data alongside
+   * your user's information in your own application.
+   *
+   * ### Version Availability
+   *
+   * This endpoint is only available in API version 2026-01-01.nova and newer.
+   *
+   * @example
+   * ```ts
+   * const byUserID = await client.contacts.byUserID.retrieve(
+   *   'usr_12345',
+   * );
+   * ```
+   */
+  retrieve(
+    userID: string,
+    params: ByUserIDRetrieveParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<ByUserIDRetrieveResponse> {
+    const { 'Featurebase-Version': featurebaseVersion } = params ?? {};
+    return this._client.get(path`/v2/contacts/by-user-id/${userID}`, {
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Permanently deletes a contact by their external user ID.
+   *
+   * **Important:** This endpoint only deletes customers (type: "customer"). Leads
+   * cannot be deleted using this endpoint.
+   *
+   * ### Path Parameters
+   *
+   * - `userId` - The external user ID from your system
+   *
+   * ### 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
+   * }
+   * ```
+   *
+   * ### Use Case
+   *
+   * Use this endpoint when you need to delete a contact using your own system's user
+   * identifier, such as when a user deletes their account in your application.
+   *
+   * ### Version Availability
+   *
+   * This endpoint is only available in API version 2026-01-01.nova and newer.
+   *
+   * @example
+   * ```ts
+   * const deletedContact =
+   *   await client.contacts.byUserID.delete('usr_12345');
+   * ```
+   */
+  delete(
+    userID: string,
+    params: ByUserIDDeleteParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<ContactsAPI.DeletedContact> {
+    const { 'Featurebase-Version': featurebaseVersion } = params ?? {};
+    return this._client.delete(path`/v2/contacts/by-user-id/${userID}`, {
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+}
+
+/**
+ * User who submitted the response
+ */
+export type ByUserIDRetrieveResponse = ContactsAPI.Contact | (null & {});
+
+export interface ByUserIDRetrieveParams {
+  /**
+   * API version for this request. Defaults to your organization's configured API
+   * version if not specified.
+   */
+  'Featurebase-Version'?: string;
+}
+
+export interface ByUserIDDeleteParams {
+  /**
+   * API version for this request. Defaults to your organization's configured API
+   * version if not specified.
+   */
+  'Featurebase-Version'?: string;
+}
+
+ByUserID.EmailPreferences = EmailPreferences;
+
+export declare namespace ByUserID {
+  export {
+    type ByUserIDRetrieveResponse as ByUserIDRetrieveResponse,
+    type ByUserIDRetrieveParams as ByUserIDRetrieveParams,
+    type ByUserIDDeleteParams as ByUserIDDeleteParams,
+  };
+
+  export {
+    EmailPreferences as EmailPreferences,
+    type EmailPreferenceRetrieveParams as EmailPreferenceRetrieveParams,
+    type EmailPreferenceUpdateParams as EmailPreferenceUpdateParams,
+  };
+}