featurebase-node 0.0.2

package/src/resources/companies/companies.ts

@@ -0,0 +1,632 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as ContactsAPI from './contacts';
+import {
+  ContactAttachParams,
+  ContactAttachResponse,
+  ContactListParams,
+  ContactRemoveParams,
+  ContactRemoveResponse,
+  Contacts,
+} from './contacts';
+import { APIPromise } from '../../core/api-promise';
+import { buildHeaders } from '../../internal/headers';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+/**
+ * Companies represent organizations or businesses that your users belong to. Use this endpoint to list and retrieve company information.
+ */
+export class Companies extends APIResource {
+  contacts: ContactsAPI.Contacts = new ContactsAPI.Contacts(this._client);
+
+  /**
+   * Retrieves a single company by its Featurebase ID.
+   *
+   * ### Path Parameters
+   *
+   * - `id` - The Featurebase internal ID of the company (MongoDB ObjectId)
+   *
+   * ### Response
+   *
+   * Returns a company object with:
+   *
+   * - `id` - Featurebase internal ID
+   * - `companyId` - External company ID from your system
+   * - `name` - Company name
+   * - `monthlySpend` - Monthly spend/revenue
+   * - `industry` - Industry
+   * - `website` - Company website URL
+   * - `plan` - Plan/tier name
+   * - `linkedUsers` - Number of users linked to this company
+   * - `companySize` - Employee headcount
+   * - `lastActivity` - Last activity timestamp
+   * - `customFields` - Custom field values
+   * - `createdAt` - Creation timestamp
+   * - `updatedAt` - Last update timestamp
+   *
+   * ### Example Response
+   *
+   * ```json
+   * {
+   *   "object": "company",
+   *   "id": "507f1f77bcf86cd799439011",
+   *   "companyId": "comp_12345",
+   *   "name": "Acme Inc",
+   *   "monthlySpend": 5000,
+   *   "industry": "Technology",
+   *   "website": "https://acme.com",
+   *   "plan": "enterprise",
+   *   "linkedUsers": 15,
+   *   "companySize": 250,
+   *   "lastActivity": "2025-01-15T00:00:00.000Z",
+   *   "customFields": { "location": "Europe" },
+   *   "createdAt": "2025-01-01T12:00:00.000Z",
+   *   "updatedAt": "2025-01-10T15:30:00.000Z"
+   * }
+   * ```
+   *
+   * ### 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 company = await client.companies.retrieve(
+   *   '507f1f77bcf86cd799439011',
+   * );
+   * ```
+   */
+  retrieve(
+    id: string,
+    params: CompanyRetrieveParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<Company> {
+    const { 'Featurebase-Version': featurebaseVersion } = params ?? {};
+    return this._client.get(path`/v2/companies/${id}`, {
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Returns all companies in your organization with cursor-based pagination.
+   *
+   * ### Query Parameters
+   *
+   * - `limit` - Number of companies 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 company objects
+   * - `nextCursor` - Cursor for the next page (null if no more results)
+   *
+   * ### Company Object
+   *
+   * Each company includes:
+   *
+   * - `id` - Featurebase internal ID (MongoDB ObjectId)
+   * - `companyId` - External company ID from your system
+   * - `name` - Company name
+   * - `monthlySpend` - Monthly spend/revenue
+   * - `industry` - Industry
+   * - `website` - Company website URL
+   * - `plan` - Plan/tier name
+   * - `linkedUsers` - Number of users linked to this company
+   * - `companySize` - Employee headcount
+   * - `lastActivity` - Last activity timestamp
+   * - `customFields` - Custom field values
+   * - `createdAt` - Creation timestamp
+   * - `updatedAt` - Last update timestamp
+   *
+   * ### Example Response
+   *
+   * ```json
+   * {
+   *   "object": "list",
+   *   "data": [
+   *     {
+   *       "object": "company",
+   *       "id": "507f1f77bcf86cd799439011",
+   *       "companyId": "comp_12345",
+   *       "name": "Acme Inc",
+   *       "monthlySpend": 5000,
+   *       "industry": "Technology",
+   *       "website": "https://acme.com",
+   *       "plan": "enterprise",
+   *       "linkedUsers": 15,
+   *       "companySize": 250,
+   *       "lastActivity": "2025-01-15T00:00:00.000Z",
+   *       "customFields": { "location": "Europe" },
+   *       "createdAt": "2025-01-01T12:00:00.000Z",
+   *       "updatedAt": "2025-01-10T15:30:00.000Z"
+   *     }
+   *   ],
+   *   "nextCursor": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9"
+   * }
+   * ```
+   *
+   * ### Version Availability
+   *
+   * This endpoint is only available in API version 2026-01-01.nova and newer.
+   *
+   * @example
+   * ```ts
+   * const companies = await client.companies.list();
+   * ```
+   */
+  list(
+    params: CompanyListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<CompanyListResponse> {
+    const { 'Featurebase-Version': featurebaseVersion, ...query } = params ?? {};
+    return this._client.get('/v2/companies', {
+      query,
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Deletes a company by its Featurebase ID.
+   *
+   * This will also remove the company from all linked users' associations.
+   *
+   * ### Path Parameters
+   *
+   * - `id` - The Featurebase internal ID of the company (MongoDB ObjectId)
+   *
+   * ### Response
+   *
+   * Returns a deletion confirmation object:
+   *
+   * ```json
+   * {
+   *   "id": "507f1f77bcf86cd799439011",
+   *   "object": "company",
+   *   "deleted": true
+   * }
+   * ```
+   *
+   * ### 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 deletedCompany = await client.companies.delete(
+   *   '507f1f77bcf86cd799439011',
+   * );
+   * ```
+   */
+  delete(
+    id: string,
+    params: CompanyDeleteParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<DeletedCompany> {
+    const { 'Featurebase-Version': featurebaseVersion } = params ?? {};
+    return this._client.delete(path`/v2/companies/${id}`, {
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Creates a new company or updates an existing one.
+   *
+   * Uses the external `companyId` as the unique identifier for upsert matching. If a
+   * company with the given `companyId` already exists, it will be updated.
+   * Otherwise, a new company will be created.
+   *
+   * ### Request Body
+   *
+   * | Field          | Type   | Required | Description                                              |
+   * | -------------- | ------ | -------- | -------------------------------------------------------- |
+   * | `companyId`    | string | Yes      | External company ID from your system (unique identifier) |
+   * | `name`         | string | Yes      | Company name                                             |
+   * | `monthlySpend` | number | No       | Monthly spend/revenue from this company                  |
+   * | `industry`     | string | No       | Industry the company operates in                         |
+   * | `website`      | string | No       | Company website URL                                      |
+   * | `plan`         | string | No       | Current plan/subscription name                           |
+   * | `companySize`  | number | No       | Number of employees                                      |
+   * | `createdAt`    | string | No       | When the company was created (ISO 8601)                  |
+   * | `customFields` | object | No       | Custom field values                                      |
+   *
+   * ### Example Request
+   *
+   * ```json
+   * {
+   *   "companyId": "comp_12345",
+   *   "name": "Acme Inc",
+   *   "monthlySpend": 5000,
+   *   "industry": "Technology",
+   *   "website": "https://acme.com",
+   *   "plan": "enterprise",
+   *   "companySize": 250,
+   *   "customFields": {
+   *     "region": "EMEA",
+   *     "tier": "gold"
+   *   }
+   * }
+   * ```
+   *
+   * ### Example Response
+   *
+   * ```json
+   * {
+   *   "object": "company",
+   *   "id": "507f1f77bcf86cd799439011",
+   *   "companyId": "comp_12345",
+   *   "name": "Acme Inc",
+   *   "monthlySpend": 5000,
+   *   "industry": "Technology",
+   *   "website": "https://acme.com",
+   *   "plan": "enterprise",
+   *   "linkedUsers": 1,
+   *   "companySize": 250,
+   *   "lastActivity": "2025-01-15T00:00:00.000Z",
+   *   "customFields": { "region": "EMEA", "tier": "gold" },
+   *   "createdAt": "2025-01-01T12:00:00.000Z",
+   *   "updatedAt": "2025-01-15T10:30:00.000Z"
+   * }
+   * ```
+   *
+   * ### Error Responses
+   *
+   * - **400 Bad Request** - Invalid company data
+   *
+   * ### Version Availability
+   *
+   * This endpoint is only available in API version 2026-01-01.nova and newer.
+   *
+   * @example
+   * ```ts
+   * const company = await client.companies.createOrUpdate({
+   *   companyId: 'comp_12345',
+   *   name: 'Acme Inc',
+   * });
+   * ```
+   */
+  createOrUpdate(params: CompanyCreateOrUpdateParams, options?: RequestOptions): APIPromise<Company> {
+    const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
+    return this._client.post('/v2/companies', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Permanently deletes a company by its external company ID (the `companyId` from
+   * your system).
+   *
+   * This will also remove the company from all linked users' associations.
+   *
+   * ### Path Parameters
+   *
+   * - `companyId` - The external company ID from your system
+   *
+   * ### Deletion Behavior
+   *
+   * When a company is deleted:
+   *
+   * - The company record is permanently removed
+   * - The company is removed from all linked users' `companyIds` and `companies`
+   *   arrays
+   *
+   * ### Response
+   *
+   * Returns a deletion confirmation object:
+   *
+   * - `id` - The Featurebase internal ID of the deleted company
+   * - `object` - Always "company"
+   * - `deleted` - Always `true`
+   *
+   * ### Example Response
+   *
+   * ```json
+   * {
+   *   "id": "507f1f77bcf86cd799439011",
+   *   "object": "company",
+   *   "deleted": true
+   * }
+   * ```
+   *
+   * ### Use Case
+   *
+   * Use this endpoint when you need to delete a company using your own system's
+   * company identifier, such as when a company is removed from your application.
+   *
+   * ### Version Availability
+   *
+   * This endpoint is only available in API version 2026-01-01.nova and newer.
+   *
+   * @example
+   * ```ts
+   * const deletedCompany =
+   *   await client.companies.deleteByCompanyID('comp_12345');
+   * ```
+   */
+  deleteByCompanyID(
+    companyID: string,
+    params: CompanyDeleteByCompanyIDParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<DeletedCompany> {
+    const { 'Featurebase-Version': featurebaseVersion } = params ?? {};
+    return this._client.delete(path`/v2/companies/by-company-id/${companyID}`, {
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+}
+
+export interface Company {
+  /**
+   * Featurebase internal ID
+   */
+  id: string;
+
+  /**
+   * External company ID from your system
+   */
+  companyId: string;
+
+  /**
+   * Company employee headcount
+   */
+  companySize: number | null;
+
+  /**
+   * ISO date when company was created
+   */
+  createdAt: string | null;
+
+  /**
+   * Industry
+   */
+  industry: string | null;
+
+  /**
+   * ISO date of last activity
+   */
+  lastActivity: string | null;
+
+  /**
+   * Number of users linked to this company
+   */
+  linkedUsers: number | null;
+
+  /**
+   * Monthly spend
+   */
+  monthlySpend: number | null;
+
+  /**
+   * Company name
+   */
+  name: string;
+
+  /**
+   * Object type identifier
+   */
+  object: 'company';
+
+  /**
+   * Plan or tier name
+   */
+  plan: string | null;
+
+  /**
+   * ISO date when company was last updated
+   */
+  updatedAt: string | null;
+
+  /**
+   * Company website URL
+   */
+  website: string | null;
+
+  /**
+   * Custom field values
+   */
+  customFields?: { [key: string]: unknown };
+}
+
+export interface DeletedCompany {
+  /**
+   * Unique identifier of the deleted company
+   */
+  id: string;
+
+  /**
+   * Indicates the resource was deleted
+   */
+  deleted: true;
+
+  /**
+   * Object type identifier
+   */
+  object: 'company';
+}
+
+export interface CompanyListResponse {
+  /**
+   * Array of companies
+   */
+  data: Array<Company>;
+
+  /**
+   * Cursor for fetching the next page (cursor-based pagination)
+   */
+  nextCursor: string | null;
+
+  /**
+   * Object type identifier
+   */
+  object: 'list';
+}
+
+export interface CompanyRetrieveParams {
+  /**
+   * API version for this request. Defaults to your organization's configured API
+   * version if not specified.
+   */
+  'Featurebase-Version'?: string;
+}
+
+export interface CompanyListParams {
+  /**
+   * 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 companies 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 CompanyDeleteParams {
+  /**
+   * API version for this request. Defaults to your organization's configured API
+   * version if not specified.
+   */
+  'Featurebase-Version'?: string;
+}
+
+export interface CompanyCreateOrUpdateParams {
+  /**
+   * Body param: External company ID from your system. Used as the unique identifier
+   * for upsert matching.
+   */
+  companyId: string;
+
+  /**
+   * Body param: Company name
+   */
+  name: string;
+
+  /**
+   * Body param: Number of employees in the company
+   */
+  companySize?: number | null;
+
+  /**
+   * Body param: When the company was created in your system (ISO 8601)
+   */
+  createdAt?: string | null;
+
+  /**
+   * Body param: Custom field values on the company. Values can be string, number,
+   * boolean, null, or array of primitives.
+   */
+  customFields?: CompanyCreateOrUpdateParams.CustomFields;
+
+  /**
+   * Body param: Industry the company operates in
+   */
+  industry?: string;
+
+  /**
+   * Body param: Monthly spend/revenue from this company
+   */
+  monthlySpend?: number;
+
+  /**
+   * Body param: Current plan/subscription name
+   */
+  plan?: string;
+
+  /**
+   * Body param: Company website URL
+   */
+  website?: string;
+
+  /**
+   * Header param: API version for this request. Defaults to your organization's
+   * configured API version if not specified.
+   */
+  'Featurebase-Version'?: string;
+}
+
+export namespace CompanyCreateOrUpdateParams {
+  /**
+   * Custom field values on the company. Values can be string, number, boolean, null,
+   * or array of primitives.
+   */
+  export interface CustomFields {
+    priority?: string;
+
+    region?: string;
+
+    tier?: string;
+  }
+}
+
+export interface CompanyDeleteByCompanyIDParams {
+  /**
+   * API version for this request. Defaults to your organization's configured API
+   * version if not specified.
+   */
+  'Featurebase-Version'?: string;
+}
+
+Companies.Contacts = Contacts;
+
+export declare namespace Companies {
+  export {
+    type Company as Company,
+    type DeletedCompany as DeletedCompany,
+    type CompanyListResponse as CompanyListResponse,
+    type CompanyRetrieveParams as CompanyRetrieveParams,
+    type CompanyListParams as CompanyListParams,
+    type CompanyDeleteParams as CompanyDeleteParams,
+    type CompanyCreateOrUpdateParams as CompanyCreateOrUpdateParams,
+    type CompanyDeleteByCompanyIDParams as CompanyDeleteByCompanyIDParams,
+  };
+
+  export {
+    Contacts as Contacts,
+    type ContactAttachResponse as ContactAttachResponse,
+    type ContactRemoveResponse as ContactRemoveResponse,
+    type ContactListParams as ContactListParams,
+    type ContactAttachParams as ContactAttachParams,
+    type ContactRemoveParams as ContactRemoveParams,
+  };
+}