featurebase-node 0.0.2

package/resources/companies/companies.d.mts

@@ -0,0 +1,497 @@
+import { APIResource } from "../../core/resource.mjs";
+import * as ContactsAPI from "./contacts.mjs";
+import { ContactAttachParams, ContactAttachResponse, ContactListParams, ContactRemoveParams, ContactRemoveResponse, Contacts } from "./contacts.mjs";
+import { APIPromise } from "../../core/api-promise.mjs";
+import { RequestOptions } from "../../internal/request-options.mjs";
+/**
+ * Companies represent organizations or businesses that your users belong to. Use this endpoint to list and retrieve company information.
+ */
+export declare class Companies extends APIResource {
+    contacts: ContactsAPI.Contacts;
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /**
+     * 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>;
+}
+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 declare namespace CompanyCreateOrUpdateParams {
+    /**
+     * Custom field values on the company. Values can be string, number, boolean, null,
+     * or array of primitives.
+     */
+    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;
+}
+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, };
+}
+//# sourceMappingURL=companies.d.mts.map

package/resources/companies/companies.d.mts.map

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