featurebase-node 0.0.2

package/resources/tickets/tickets.d.ts

@@ -0,0 +1,794 @@
+import { APIResource } from "../../core/resource.js";
+import * as PostStatusesAPI from "../post-statuses.js";
+import * as ConversationsAPI from "../conversations/conversations.js";
+import * as CategoriesAPI from "./categories.js";
+import { Categories, CategoryListParams, CategoryListResponse, CategoryRetrieveParams } from "./categories.js";
+import * as CustomFieldsAPI from "./custom-fields.js";
+import { CustomFieldListParams, CustomFieldRetrieveParams, CustomFields } from "./custom-fields.js";
+import * as StatusesAPI from "./statuses.js";
+import { StatusListParams, StatusListResponse, StatusRetrieveParams, Statuses } from "./statuses.js";
+import { APIPromise } from "../../core/api-promise.js";
+import { RequestOptions } from "../../internal/request-options.js";
+/**
+ * Tickets represent support requests in your Featurebase organization. Create, update, reply to, and manage tickets via these endpoints.
+ */
+export declare class Tickets extends APIResource {
+    customFields: CustomFieldsAPI.CustomFields;
+    categories: CategoriesAPI.Categories;
+    statuses: StatusesAPI.Statuses;
+    /**
+     * Creates a new ticket.
+     *
+     * ### Required Fields
+     *
+     * | Field              | Type   | Description                                                   |
+     * | ------------------ | ------ | ------------------------------------------------------------- |
+     * | `ticketCategoryId` | string | Ticket category ID                                            |
+     * | `title`            | string | Ticket title (min 2 characters)                               |
+     * | `author`           | object | Author/contact info (id, userId, email, name, profilePicture) |
+     *
+     * ### Optional Fields
+     *
+     * | Field                  | Type    | Description                                |
+     * | ---------------------- | ------- | ------------------------------------------ |
+     * | `content`              | string  | Ticket description (HTML)                  |
+     * | `customFields`         | object  | Custom field values                        |
+     * | `companyId`            | string  | Company to associate                       |
+     * | `linkedConversationId` | string  | Conversation to link                       |
+     * | `assigneeId`           | string  | Admin to assign                            |
+     * | `statusId`             | string  | Initial status                             |
+     * | `createdAt`            | string  | ISO 8601 timestamp for backdating          |
+     * | `skipNotifications`    | boolean | Skip sending notifications (default false) |
+     *
+     * ### File Custom Fields
+     *
+     * File-type custom fields can be provided in two ways:
+     *
+     * **Method 1: Multipart upload** — Send the request as `multipart/form-data`. Put
+     * the JSON body in a field named `data`, and attach files with field names like
+     * `customFields.<fieldId>`. For `allowMultiple` fields, send multiple files with
+     * the same field name.
+     *
+     * **Method 2: External URL** — In the JSON body, set the file custom field value
+     * to `{ "url": "https://..." }`. Optionally include `"name"` to set the filename
+     * (e.g. `{ "url": "https://...", "name": "report.pdf" }`); if omitted, the
+     * filename is extracted from the download response. For `allowMultiple` fields,
+     * use an array: `[{ "url": "..." }, ...]`. The server downloads the file (max
+     * 10MB, HTTPS only) and stores it.
+     *
+     * Both methods produce signed download URLs in the response.
+     *
+     * **Limits:** Max 10 files per request, 400MB total upload size. Executable file
+     * types (.exe, .bat, .js, .sh, etc.) are blocked.
+     *
+     * **Response format:** File custom field values in the response are JSON strings
+     * containing `{ "key": "...", "name": "...", "url": "https://signed-url..." }`.
+     * For `allowMultiple` fields, an array of these objects. The `url` is a
+     * time-limited signed download URL (expires in 1 hour).
+     *
+     * ### Response
+     *
+     * Returns the created ticket object with **201 Created** status.
+     *
+     * @example
+     * ```ts
+     * const ticket = await client.tickets.create({
+     *   author: {},
+     *   ticketCategoryId: '507f1f77bcf86cd799439011',
+     *   title: 'Cannot login to dashboard',
+     * });
+     * ```
+     */
+    create(params: TicketCreateParams, options?: RequestOptions): APIPromise<Ticket>;
+    /**
+     * Retrieves a single ticket by its ticket number.
+     *
+     * ### Path Parameters
+     *
+     * - `id` - The ticket number (e.g. 42 from TK-42)
+     *
+     * ### Response
+     *
+     * Returns the ticket object, including `conversationParts` from the linked
+     * conversation (message history).
+     *
+     * @example
+     * ```ts
+     * const ticket = await client.tickets.retrieve(1);
+     * ```
+     */
+    retrieve(id: number, params?: TicketRetrieveParams | null | undefined, options?: RequestOptions): APIPromise<Ticket>;
+    /**
+     * Updates a ticket's properties. Only provided fields will be updated.
+     *
+     * ### Path Parameters
+     *
+     * - `id` - The ticket number
+     *
+     * ### Request Body
+     *
+     * All fields are optional.
+     *
+     * | Field               | Type        | Description                                        |
+     * | ------------------- | ----------- | -------------------------------------------------- |
+     * | `title`             | string      | Update title                                       |
+     * | `content`           | string      | Update description (HTML)                          |
+     * | `statusId`          | string      | Set status by ID                                   |
+     * | `open`              | boolean     | Close (false) or reopen (true) the ticket          |
+     * | `assigneeId`        | string/null | Assign/unassign admin                              |
+     * | `companyId`         | string/null | Update company association                         |
+     * | `customFields`      | object      | Update custom field values                         |
+     * | `snoozedUntil`      | string/null | Snooze until ISO 8601 timestamp (null to unsnooze) |
+     * | `skipNotifications` | boolean     | Skip notifications (default false)                 |
+     *
+     * ### Closing a Ticket
+     *
+     * Set `open: false` to close the ticket. Closing a ticket will also unsnooze it.
+     * The status is not changed automatically — use `statusId` to change the status
+     * explicitly.
+     *
+     * ### File Custom Fields
+     *
+     * File-type custom fields support the same two upload methods as ticket creation:
+     * multipart upload (`customFields.<fieldId>` file parts with JSON in the `data`
+     * field) and external URLs (`{ "url": "https://..." }` with optional `"name"` in
+     * the custom field value). Same limits apply (10 files, 400MB total, executable
+     * types blocked).
+     *
+     * ### Response
+     *
+     * Returns the updated ticket object.
+     *
+     * @example
+     * ```ts
+     * const ticket = await client.tickets.update(1);
+     * ```
+     */
+    update(id: number, params: TicketUpdateParams, options?: RequestOptions): APIPromise<Ticket>;
+    /**
+     * Returns a list of tickets in your organization using cursor-based pagination.
+     *
+     * ### Query Parameters
+     *
+     * | Parameter           | Type     | Description                                                      |
+     * | ------------------- | -------- | ---------------------------------------------------------------- |
+     * | `limit`             | number   | Number of tickets to return (1-100, default 10)                  |
+     * | `cursor`            | string   | Cursor from previous response for pagination                     |
+     * | `ticketCategoryIds` | string[] | Filter by ticket category IDs                                    |
+     * | `statusIds`         | string[] | Filter by status IDs                                             |
+     * | `q`                 | string   | Search query                                                     |
+     * | `assigneeId`        | string   | Filter by assignee ID                                            |
+     * | `categoryType`      | string   | Filter by category type: "customer", "tracker", or "back-office" |
+     * | `sortBy`            | string   | Sort field: "date" (default), "recent", or "ticketNumber"        |
+     * | `sortOrder`         | string   | Sort direction: "asc" or "desc" (default)                        |
+     *
+     * ### Response
+     *
+     * Returns a list object with `data` (array of ticket objects) and `nextCursor`.
+     *
+     * @example
+     * ```ts
+     * const tickets = await client.tickets.list();
+     * ```
+     */
+    list(params?: TicketListParams | null | undefined, options?: RequestOptions): APIPromise<TicketListResponse>;
+    /**
+     * Permanently deletes a ticket by its ticket number.
+     *
+     * ### Path Parameters
+     *
+     * - `id` - The ticket number
+     *
+     * ### Response
+     *
+     * Returns a deletion confirmation:
+     *
+     * ```json
+     * {
+     *   "id": "507f1f77bcf86cd799439011",
+     *   "object": "ticket",
+     *   "deleted": true
+     * }
+     * ```
+     *
+     * ### Behavior
+     *
+     * - **Customer-facing tickets**: Deletes the ticket and its linked conversation.
+     * - **Back-office / tracker tickets**: Deletes the ticket and unlinks it from the
+     *   conversation (conversation is preserved).
+     *
+     * ### Caution
+     *
+     * This operation is **irreversible**.
+     *
+     * @example
+     * ```ts
+     * const ticket = await client.tickets.delete(1);
+     * ```
+     */
+    delete(id: number, params?: TicketDeleteParams | null | undefined, options?: RequestOptions): APIPromise<TicketDeleteResponse>;
+    /**
+     * Adds a reply to a ticket's linked conversation. Supports both contact and admin
+     * replies.
+     *
+     * ### Path Parameters
+     *
+     * - `id` - The ticket number
+     *
+     * ### Contact Reply
+     *
+     * | Field               | Type     | Required | Description                              |
+     * | ------------------- | -------- | -------- | ---------------------------------------- |
+     * | `type`              | string   | Yes      | Must be "contact"                        |
+     * | `contactId`         | string   | No\*     | Featurebase contact ID                   |
+     * | `contactEmail`      | string   | No\*     | Contact email                            |
+     * | `body`              | string   | Yes      | Message content (HTML)                   |
+     * | `messageType`       | string   | No       | Always "comment" for contacts            |
+     * | `attachmentUrls`    | string[] | No       | Attachment URLs (max 10)                 |
+     * | `skipNotifications` | boolean  | No       | Skip notifications (default false)       |
+     * | `createdAt`         | string   | No       | ISO 8601 timestamp to backdate the reply |
+     *
+     * \*At least one of `contactId` or `contactEmail` is required.
+     *
+     * ### Admin Reply
+     *
+     * | Field               | Type     | Required | Description                                      |
+     * | ------------------- | -------- | -------- | ------------------------------------------------ |
+     * | `type`              | string   | Yes      | Must be "admin"                                  |
+     * | `adminId`           | string   | Yes      | ID of the admin authoring the reply              |
+     * | `body`              | string   | Yes      | Message content (HTML)                           |
+     * | `messageType`       | string   | No       | "comment" (default) or "note" for internal notes |
+     * | `attachmentUrls`    | string[] | No       | Attachment URLs (max 10)                         |
+     * | `skipNotifications` | boolean  | No       | Skip notifications (default false)               |
+     * | `createdAt`         | string   | No       | ISO 8601 timestamp to backdate the reply         |
+     *
+     * ### Response
+     *
+     * Returns a reply confirmation object.
+     *
+     * @example
+     * ```ts
+     * const ticket = await client.tickets.reply(1, {
+     *   body: '<p>Thank you for your help!</p>',
+     *   type: 'contact',
+     * });
+     * ```
+     */
+    reply(id: number, params: TicketReplyParams, options?: RequestOptions): APIPromise<Ticket>;
+}
+/**
+ * Author to attribute the post to. If not provided, uses the authenticated user.
+ * Supports multiple identification methods: id (Featurebase ID), userId (external
+ * SSO ID), or email.
+ */
+export interface AuthorInput {
+    /**
+     * Featurebase user ID to attribute content to
+     */
+    id?: string;
+    /**
+     * Author email (used to find or create user)
+     */
+    email?: string;
+    /**
+     * Author display name
+     */
+    name?: string;
+    /**
+     * Author profile picture URL
+     */
+    profilePicture?: string;
+    /**
+     * External user ID from your system (matched via SSO)
+     */
+    userId?: string;
+}
+export interface Ticket {
+    /**
+     * Unique identifier (MongoDB ID)
+     */
+    id: string;
+    /**
+     * Assigned admin ID
+     */
+    assigneeId: string | null;
+    /**
+     * Contact who created the ticket
+     */
+    author: Ticket.Author | null;
+    /**
+     * Ticket category type
+     */
+    categoryType: 'customer' | 'tracker' | 'back-office';
+    /**
+     * Associated company ID
+     */
+    companyId: string | null;
+    /**
+     * Ticket content/description (HTML)
+     */
+    content: string;
+    /**
+     * ISO 8601 creation timestamp
+     */
+    createdAt: string;
+    /**
+     * Custom field values keyed by field ID. File-type fields contain a JSON string of
+     * { key, name, url } with a signed download URL (1 hour expiry). For allowMultiple
+     * file fields, the value is a JSON string of an array of these objects.
+     */
+    customFields: {
+        [key: string]: unknown;
+    };
+    /**
+     * Third-party integration links
+     */
+    integrations: Ticket.Integrations;
+    /**
+     * Linked conversations
+     */
+    linkedConversations: Array<Ticket.LinkedConversation>;
+    /**
+     * Object type identifier
+     */
+    object: 'ticket';
+    /**
+     * Whether the ticket is open
+     */
+    open: boolean;
+    /**
+     * ISO 8601 timestamp until snoozed (from linked conversation)
+     */
+    snoozedUntil: string | null;
+    /**
+     * Current ticket status
+     */
+    status: PostStatusesAPI.PostStatus;
+    /**
+     * Assigned team ID (from linked conversation)
+     */
+    teamAssigneeId: string | null;
+    /**
+     * Ticket category ID
+     */
+    ticketCategoryId: string;
+    /**
+     * Sequential display ID (e.g. TK-42)
+     */
+    ticketNumber: number;
+    /**
+     * Full URL to view the ticket
+     */
+    ticketUrl: string;
+    /**
+     * Ticket title
+     */
+    title: string;
+    /**
+     * ISO 8601 last updated timestamp
+     */
+    updatedAt: string;
+    /**
+     * Conversation message history. Only included when fetching a single ticket by ID.
+     */
+    conversationParts?: Array<ConversationsAPI.ConversationPart>;
+}
+export declare namespace Ticket {
+    /**
+     * Contact who created the ticket
+     */
+    interface Author {
+        /**
+         * Author unique identifier
+         */
+        id: string | null;
+        /**
+         * Author email
+         */
+        email: string | null;
+        /**
+         * Author display name
+         */
+        name: string;
+        /**
+         * Author profile picture URL
+         */
+        profilePicture: string | null;
+        /**
+         * Type of user
+         */
+        type: 'admin' | 'customer' | 'guest' | 'integration' | 'bot' | 'lead';
+    }
+    /**
+     * Third-party integration links
+     */
+    interface Integrations {
+        clickup: Array<Integrations.Clickup>;
+        devops: Array<Integrations.Devop>;
+        github: Array<Integrations.GitHub>;
+        hubspot: Array<Integrations.Hubspot>;
+        jira: Array<Integrations.Jira>;
+        linear: Array<Integrations.Linear>;
+    }
+    namespace Integrations {
+        interface Clickup {
+            /**
+             * ClickUp task ID
+             */
+            id: string;
+            /**
+             * ClickUp task title
+             */
+            title: string;
+            /**
+             * URL to the ClickUp task
+             */
+            url: string;
+        }
+        interface Devop {
+            /**
+             * Azure DevOps work item ID
+             */
+            id: number;
+            /**
+             * Azure DevOps project ID
+             */
+            projectId: string;
+            /**
+             * Azure DevOps project name
+             */
+            projectName: string;
+            /**
+             * Work item title
+             */
+            title: string;
+            /**
+             * URL to the work item
+             */
+            url: string;
+        }
+        interface GitHub {
+            /**
+             * GitHub issue ID
+             */
+            id: string;
+            /**
+             * GitHub issue number
+             */
+            number: string;
+            /**
+             * Full repository name (owner/repo)
+             */
+            repositoryFullName: string;
+            /**
+             * Repository name
+             */
+            repositoryName: string;
+            /**
+             * GitHub issue title
+             */
+            title: string;
+            /**
+             * URL to the GitHub issue
+             */
+            url: string;
+        }
+        interface Hubspot {
+            /**
+             * Deal amount (for DEAL type)
+             */
+            dealAmount: number | null;
+            /**
+             * Whether the deal is closed (for DEAL type)
+             */
+            dealClosed: boolean | null;
+            /**
+             * HubSpot object ID
+             */
+            objectId: number;
+            /**
+             * HubSpot object type
+             */
+            type: 'TICKET' | 'DEAL' | 'CONTACT';
+        }
+        interface Jira {
+            /**
+             * Jira issue ID
+             */
+            issueId: string;
+            /**
+             * URL to the Jira issue
+             */
+            issueUrl: string | null;
+        }
+        interface Linear {
+            /**
+             * Linear issue ID
+             */
+            issueId: string;
+            /**
+             * URL to the Linear issue
+             */
+            issueUrl: string | null;
+        }
+    }
+    interface LinkedConversation {
+        /**
+         * Conversation ID
+         */
+        id: string;
+        /**
+         * Link role
+         */
+        role: 'customer' | 'tracker' | 'back-office';
+    }
+}
+export interface TicketListResponse {
+    /**
+     * Array of tickets
+     */
+    data: Array<Ticket>;
+    /**
+     * Cursor for fetching the next page
+     */
+    nextCursor: string | null;
+    /**
+     * Object type identifier
+     */
+    object: 'list';
+}
+export interface TicketDeleteResponse {
+    /**
+     * Unique identifier of the deleted ticket
+     */
+    id: string;
+    /**
+     * Indicates the resource was deleted
+     */
+    deleted: true;
+    /**
+     * Object type identifier
+     */
+    object: 'ticket';
+}
+export interface TicketCreateParams {
+    /**
+     * Body param: Author to attribute the post to. If not provided, uses the
+     * authenticated user. Supports multiple identification methods: id (Featurebase
+     * ID), userId (external SSO ID), or email.
+     */
+    author: AuthorInput;
+    /**
+     * Body param
+     */
+    ticketCategoryId: string;
+    /**
+     * Body param
+     */
+    title: string;
+    /**
+     * Body param
+     */
+    assigneeId?: string;
+    /**
+     * Body param
+     */
+    companyId?: string;
+    /**
+     * Body param
+     */
+    content?: string;
+    /**
+     * Body param
+     */
+    createdAt?: string | null;
+    /**
+     * Body param
+     */
+    customFields?: {
+        [key: string]: unknown;
+    };
+    /**
+     * Body param
+     */
+    linkedConversationId?: string;
+    /**
+     * Body param
+     */
+    skipNotifications?: boolean;
+    /**
+     * Body param
+     */
+    statusId?: string;
+    /**
+     * Header param: API version for this request. Defaults to your organization's
+     * configured API version if not specified.
+     */
+    'Featurebase-Version'?: string;
+}
+export interface TicketRetrieveParams {
+    /**
+     * API version for this request. Defaults to your organization's configured API
+     * version if not specified.
+     */
+    'Featurebase-Version'?: string;
+}
+export interface TicketUpdateParams {
+    /**
+     * Body param
+     */
+    assigneeId?: string | null;
+    /**
+     * Body param
+     */
+    companyId?: string | null;
+    /**
+     * Body param
+     */
+    content?: string;
+    /**
+     * Body param
+     */
+    customFields?: {
+        [key: string]: unknown;
+    };
+    /**
+     * Body param
+     */
+    open?: boolean;
+    /**
+     * Body param
+     */
+    skipNotifications?: boolean;
+    /**
+     * Body param
+     */
+    snoozedUntil?: string | null;
+    /**
+     * Body param
+     */
+    statusId?: string;
+    /**
+     * Body param
+     */
+    title?: string;
+    /**
+     * Header param: API version for this request. Defaults to your organization's
+     * configured API version if not specified.
+     */
+    'Featurebase-Version'?: string;
+}
+export interface TicketListParams {
+    /**
+     * Query param
+     */
+    assigneeId?: string;
+    /**
+     * Query param
+     */
+    categoryType?: 'customer' | 'tracker' | 'back-office';
+    /**
+     * Query param
+     */
+    cursor?: string;
+    /**
+     * Query param
+     */
+    limit?: number;
+    /**
+     * Query param
+     */
+    q?: string;
+    /**
+     * Query param
+     */
+    sortBy?: 'date' | 'recent' | 'ticketNumber';
+    /**
+     * Query param
+     */
+    sortOrder?: 'asc' | 'desc';
+    /**
+     * Query param
+     */
+    statusIds?: Array<string>;
+    /**
+     * Query param
+     */
+    ticketCategoryIds?: Array<string>;
+    /**
+     * Header param: API version for this request. Defaults to your organization's
+     * configured API version if not specified.
+     */
+    'Featurebase-Version'?: string;
+}
+export interface TicketDeleteParams {
+    /**
+     * API version for this request. Defaults to your organization's configured API
+     * version if not specified.
+     */
+    'Featurebase-Version'?: string;
+}
+export type TicketReplyParams = TicketReplyParams.Variant0 | TicketReplyParams.Variant1;
+export declare namespace TicketReplyParams {
+    interface Variant0 {
+        /**
+         * Body param
+         */
+        body: string;
+        /**
+         * Body param
+         */
+        type: 'contact';
+        /**
+         * Body param
+         */
+        attachmentUrls?: Array<string>;
+        /**
+         * Body param
+         */
+        contactEmail?: string;
+        /**
+         * Body param
+         */
+        contactId?: string;
+        /**
+         * Body param
+         */
+        createdAt?: string | null;
+        /**
+         * Body param
+         */
+        messageType?: 'comment';
+        /**
+         * Body param
+         */
+        skipNotifications?: boolean;
+        /**
+         * Header param: API version for this request. Defaults to your organization's
+         * configured API version if not specified.
+         */
+        'Featurebase-Version'?: string;
+    }
+    interface Variant1 {
+        /**
+         * Body param
+         */
+        adminId: string;
+        /**
+         * Body param
+         */
+        body: string;
+        /**
+         * Body param
+         */
+        type: 'admin';
+        /**
+         * Body param
+         */
+        attachmentUrls?: Array<string>;
+        /**
+         * Body param
+         */
+        createdAt?: string | null;
+        /**
+         * Body param
+         */
+        messageType?: 'comment' | 'note';
+        /**
+         * Body param
+         */
+        skipNotifications?: boolean;
+        /**
+         * Header param: API version for this request. Defaults to your organization's
+         * configured API version if not specified.
+         */
+        'Featurebase-Version'?: string;
+    }
+}
+export declare namespace Tickets {
+    export { type AuthorInput as AuthorInput, type Ticket as Ticket, type TicketListResponse as TicketListResponse, type TicketDeleteResponse as TicketDeleteResponse, type TicketCreateParams as TicketCreateParams, type TicketRetrieveParams as TicketRetrieveParams, type TicketUpdateParams as TicketUpdateParams, type TicketListParams as TicketListParams, type TicketDeleteParams as TicketDeleteParams, type TicketReplyParams as TicketReplyParams, };
+    export { CustomFields as CustomFields, type CustomFieldRetrieveParams as CustomFieldRetrieveParams, type CustomFieldListParams as CustomFieldListParams, };
+    export { Categories as Categories, type CategoryListResponse as CategoryListResponse, type CategoryRetrieveParams as CategoryRetrieveParams, type CategoryListParams as CategoryListParams, };
+    export { Statuses as Statuses, type StatusListResponse as StatusListResponse, type StatusRetrieveParams as StatusRetrieveParams, type StatusListParams as StatusListParams, };
+}
+//# sourceMappingURL=tickets.d.ts.map