featurebase-node 0.0.2

package/src/resources/contacts/email-preferences.ts

@@ -0,0 +1,399 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as EmailPreferencesAPI 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 EmailPreferences extends APIResource {
+  /**
+   * Retrieves the email preference state for a customer contact by their Featurebase
+   * ID.
+   *
+   * **Important:** This endpoint only supports customer contacts. Leads do not have
+   * a customer email preference surface in the public API.
+   *
+   * ### Path Parameters
+   *
+   * - `id` - The Featurebase contact ID (24-character ObjectId)
+   *
+   * ### Response Format
+   *
+   * Returns a contact email preferences object with:
+   *
+   * - `object` - Always "contact_email_preferences"
+   * - `contactId` - Featurebase contact ID
+   * - `userId` - External user ID, if available
+   * - `email` - Contact email address, if available
+   * - `preferences` - Current email preference state
+   *
+   * ### Preference Semantics
+   *
+   * Each preference includes:
+   *
+   * - `status` - The stored preference state for that category
+   * - `effectiveStatus` - The final state after applying the global `all` preference
+   *   override
+   *
+   * ### Example Response
+   *
+   * ```json
+   * {
+   *   "object": "contact_email_preferences",
+   *   "contactId": "676f0f6765bdaa7d7d760f88",
+   *   "userId": "usr_12345",
+   *   "email": "john@example.com",
+   *   "preferences": {
+   *     "all": {
+   *       "status": "unsubscribed",
+   *       "effectiveStatus": "unsubscribed"
+   *     },
+   *     "postUpdates": {
+   *       "status": "subscribed",
+   *       "effectiveStatus": "unsubscribed"
+   *     },
+   *     "postComments": {
+   *       "status": "subscribed",
+   *       "effectiveStatus": "unsubscribed"
+   *     },
+   *     "commentReplies": {
+   *       "status": "subscribed",
+   *       "effectiveStatus": "unsubscribed"
+   *     },
+   *     "changelog": {
+   *       "status": "subscribed",
+   *       "effectiveStatus": "unsubscribed"
+   *     }
+   *   }
+   * }
+   * ```
+   *
+   * @example
+   * ```ts
+   * const preferencesOutput =
+   *   await client.contacts.emailPreferences.retrieve(
+   *     '507f1f77bcf86cd799439011',
+   *   );
+   * ```
+   */
+  retrieve(
+    id: string,
+    params: EmailPreferenceRetrieveParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<PreferencesOutput> {
+    const { 'Featurebase-Version': featurebaseVersion } = params ?? {};
+    return this._client.get(path`/v2/contacts/${id}/email-preferences`, {
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Updates one or more email preferences for a customer contact by their
+   * Featurebase ID.
+   *
+   * **Important:** This endpoint only supports customer contacts. Leads do not have
+   * a customer email preference surface in the public API.
+   *
+   * ### Path Parameters
+   *
+   * - `id` - The Featurebase contact ID (24-character ObjectId)
+   *
+   * ### Request Body
+   *
+   * - `preferences` - A partial map of preference keys to their desired stored
+   *   status. Only the preferences included in the request are updated; any
+   *   preferences omitted are left unchanged. At least one preference must be
+   *   provided.
+   *
+   * ### Supported Preference Keys
+   *
+   * - `all` - Master delivery gate. When `unsubscribed`, the contact will not
+   *   receive any emails regardless of the per-category values. Per-category values
+   *   are still persisted, so flipping `all` back to `subscribed` restores the
+   *   contact's previous granular preferences.
+   * - `postUpdates` - Status changes and updates on posts the contact interacts
+   *   with.
+   * - `postComments` - New comments on posts the contact follows.
+   * - `commentReplies` - Replies to the contact's own comments.
+   * - `changelog` - New changelog releases.
+   *
+   * ### Per-key Values
+   *
+   * - `subscribed` - The contact will receive this email category (subject to the
+   *   `all` gate).
+   * - `unsubscribed` - The contact will not receive this email category.
+   *
+   * ### Combining `all` with per-category keys
+   *
+   * You can send `all` together with any per-category keys in the same request. The
+   * full map is applied atomically as the contact's new stored state — there is no
+   * implicit reset of the other keys. This makes the endpoint safe for
+   * preference-center UIs that POST the entire form state on submit.
+   *
+   * The computed per-category result (after applying the `all` gate) is surfaced as
+   * `effectiveStatus` in the response, while `status` reflects the value actually
+   * stored for that key.
+   *
+   * ### Example Request (partial update)
+   *
+   * ```json
+   * {
+   *   "preferences": {
+   *     "postUpdates": "unsubscribed",
+   *     "changelog": "subscribed"
+   *   }
+   * }
+   * ```
+   *
+   * ### Example Request (full preference-center submit)
+   *
+   * ```json
+   * {
+   *   "preferences": {
+   *     "all": "subscribed",
+   *     "postUpdates": "subscribed",
+   *     "postComments": "unsubscribed",
+   *     "commentReplies": "unsubscribed",
+   *     "changelog": "unsubscribed"
+   *   }
+   * }
+   * ```
+   *
+   * ### Example Response
+   *
+   * ```json
+   * {
+   *   "object": "contact_email_preferences",
+   *   "contactId": "676f0f6765bdaa7d7d760f88",
+   *   "userId": "usr_12345",
+   *   "email": "john@example.com",
+   *   "preferences": {
+   *     "all": {
+   *       "status": "subscribed",
+   *       "effectiveStatus": "subscribed"
+   *     },
+   *     "postUpdates": {
+   *       "status": "subscribed",
+   *       "effectiveStatus": "subscribed"
+   *     },
+   *     "postComments": {
+   *       "status": "unsubscribed",
+   *       "effectiveStatus": "unsubscribed"
+   *     },
+   *     "commentReplies": {
+   *       "status": "unsubscribed",
+   *       "effectiveStatus": "unsubscribed"
+   *     },
+   *     "changelog": {
+   *       "status": "unsubscribed",
+   *       "effectiveStatus": "unsubscribed"
+   *     }
+   *   }
+   * }
+   * ```
+   *
+   * @example
+   * ```ts
+   * const preferencesOutput =
+   *   await client.contacts.emailPreferences.update(
+   *     '507f1f77bcf86cd799439011',
+   *     { preferences: {} },
+   *   );
+   * ```
+   */
+  update(
+    id: string,
+    params: EmailPreferenceUpdateParams,
+    options?: RequestOptions,
+  ): APIPromise<PreferencesOutput> {
+    const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
+    return this._client.patch(path`/v2/contacts/${id}/email-preferences`, {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+}
+
+/**
+ * Global email preference state for all email notifications.
+ */
+export interface PreferenceState {
+  /**
+   * Final effective status after applying global preference overrides
+   */
+  effectiveStatus: 'subscribed' | 'unsubscribed';
+
+  /**
+   * Stored preference status for this category
+   */
+  status: 'subscribed' | 'unsubscribed';
+}
+
+export interface PreferencesOutput {
+  /**
+   * Featurebase contact ID
+   */
+  contactId: string;
+
+  /**
+   * Object type identifier
+   */
+  object: 'contact_email_preferences';
+
+  /**
+   * Email preference state for this contact, including both stored status and final
+   * effective status.
+   */
+  preferences: PreferencesOutput.Preferences;
+
+  /**
+   * Contact email address, if available
+   */
+  email?: string | null;
+
+  /**
+   * External user ID from your system, if available
+   */
+  userId?: string | null;
+}
+
+export namespace PreferencesOutput {
+  /**
+   * Email preference state for this contact, including both stored status and final
+   * effective status.
+   */
+  export interface Preferences {
+    /**
+     * Global email preference state for all email notifications.
+     */
+    all: EmailPreferencesAPI.PreferenceState;
+
+    /**
+     * Global email preference state for all email notifications.
+     */
+    changelog: EmailPreferencesAPI.PreferenceState;
+
+    /**
+     * Global email preference state for all email notifications.
+     */
+    commentReplies: EmailPreferencesAPI.PreferenceState;
+
+    /**
+     * Global email preference state for all email notifications.
+     */
+    postComments: EmailPreferencesAPI.PreferenceState;
+
+    /**
+     * Global email preference state for all email notifications.
+     */
+    postUpdates: EmailPreferencesAPI.PreferenceState;
+  }
+}
+
+export interface UpdatePreferenceBody {
+  preferences: UpdatePreferenceBody.Preferences;
+}
+
+export namespace UpdatePreferenceBody {
+  export interface Preferences {
+    /**
+     * Master delivery gate. When `unsubscribed`, the contact receives no emails
+     * regardless of the per-category values. Per-category values are preserved.
+     */
+    all?: 'subscribed' | 'unsubscribed';
+
+    /**
+     * Stored status for new changelog release notifications.
+     */
+    changelog?: 'subscribed' | 'unsubscribed';
+
+    /**
+     * Stored status for replies to the contact’s own comments.
+     */
+    commentReplies?: 'subscribed' | 'unsubscribed';
+
+    /**
+     * Stored status for new comments on posts the contact follows.
+     */
+    postComments?: 'subscribed' | 'unsubscribed';
+
+    /**
+     * Stored status for post status changes and updates on posts the contact follows.
+     */
+    postUpdates?: 'subscribed' | 'unsubscribed';
+  }
+}
+
+export interface EmailPreferenceRetrieveParams {
+  /**
+   * API version for this request. Defaults to your organization's configured API
+   * version if not specified.
+   */
+  'Featurebase-Version'?: string;
+}
+
+export interface EmailPreferenceUpdateParams {
+  /**
+   * Body param
+   */
+  preferences: EmailPreferenceUpdateParams.Preferences;
+
+  /**
+   * Header param: API version for this request. Defaults to your organization's
+   * configured API version if not specified.
+   */
+  'Featurebase-Version'?: string;
+}
+
+export namespace EmailPreferenceUpdateParams {
+  export interface Preferences {
+    /**
+     * Master delivery gate. When `unsubscribed`, the contact receives no emails
+     * regardless of the per-category values. Per-category values are preserved.
+     */
+    all?: 'subscribed' | 'unsubscribed';
+
+    /**
+     * Stored status for new changelog release notifications.
+     */
+    changelog?: 'subscribed' | 'unsubscribed';
+
+    /**
+     * Stored status for replies to the contact’s own comments.
+     */
+    commentReplies?: 'subscribed' | 'unsubscribed';
+
+    /**
+     * Stored status for new comments on posts the contact follows.
+     */
+    postComments?: 'subscribed' | 'unsubscribed';
+
+    /**
+     * Stored status for post status changes and updates on posts the contact follows.
+     */
+    postUpdates?: 'subscribed' | 'unsubscribed';
+  }
+}
+
+export declare namespace EmailPreferences {
+  export {
+    type PreferenceState as PreferenceState,
+    type PreferencesOutput as PreferencesOutput,
+    type UpdatePreferenceBody as UpdatePreferenceBody,
+    type EmailPreferenceRetrieveParams as EmailPreferenceRetrieveParams,
+    type EmailPreferenceUpdateParams as EmailPreferenceUpdateParams,
+  };
+}

package/src/resources/contacts/index.ts

@@ -0,0 +1,32 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export {
+  ByUserID,
+  type ByUserIDRetrieveResponse,
+  type ByUserIDRetrieveParams,
+  type ByUserIDDeleteParams,
+} from './by-user-id/index';
+export {
+  Contacts,
+  type Contact,
+  type ContactList,
+  type DeletedContact,
+  type ContactRetrieveResponse,
+  type ContactBlockResponse,
+  type ContactCreateOrUpdateResponse,
+  type ContactUnblockResponse,
+  type ContactRetrieveParams,
+  type ContactListParams,
+  type ContactDeleteParams,
+  type ContactBlockParams,
+  type ContactCreateOrUpdateParams,
+  type ContactUnblockParams,
+} from './contacts';
+export {
+  EmailPreferences,
+  type PreferenceState,
+  type PreferencesOutput,
+  type UpdatePreferenceBody,
+  type EmailPreferenceRetrieveParams,
+  type EmailPreferenceUpdateParams,
+} from './email-preferences';

package/src/resources/contacts.ts

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