@notiflows/node 0.0.1

package/src/resources/notiflows.ts

@@ -0,0 +1,155 @@
+// 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 { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+export class NotiflowsResource extends APIResource {
+  /**
+   * Execute a notiflow to send notifications to one or more recipients.
+   *
+   * You must provide either `recipients` (direct targeting) or `topic` (pub/sub
+   * targeting), but not both.
+   *
+   * **Direct targeting (`recipients`):** Specify exactly which users should receive
+   * the notification. Users are identified by their `external_id`. If a user doesn't
+   * exist, they will be created automatically with the provided attributes.
+   *
+   * **Topic targeting (`topic`):** Send to all users subscribed to the specified
+   * topic. Useful for broadcast scenarios.
+   *
+   * **Template variables:** The `data` object is passed to notification templates.
+   * Access variables using Liquid syntax: `{{ data.variable_name }}`
+   *
+   * @example
+   * ```ts
+   * const response = await client.notiflows.run(
+   *   '01HQXYZ123456789ABCDEFGHIJ',
+   * );
+   * ```
+   */
+  run(
+    notiflowID: string,
+    body: NotiflowRunParams,
+    options?: RequestOptions,
+  ): APIPromise<NotiflowRunResponse> {
+    return this._client.post(path`/notiflows/${notiflowID}/run`, { body, ...options });
+  }
+}
+
+/**
+ * Response after successfully running a notiflow
+ */
+export interface NotiflowRunResponse {
+  /**
+   * ID of the notiflow run. Use this to query notifications created by this run.
+   */
+  notiflow_run_id: string;
+}
+
+export interface NotiflowRunParams {
+  /**
+   * Actor (triggering user) specification. Accessible in templates as `actor.*`.
+   */
+  actor?: NotiflowRunParams.Actor;
+
+  /**
+   * Template variables. Accessible in notification templates as `data.*`.
+   */
+  data?: unknown;
+
+  /**
+   * List of recipients. Each recipient must have an `external_id`. Users are
+   * auto-created if they don't exist.
+   */
+  recipients?: Array<NotiflowRunParams.Recipient>;
+
+  /**
+   * Topic name for pub/sub targeting. Cannot be used with `recipients`.
+   */
+  topic?: string;
+}
+
+export namespace NotiflowRunParams {
+  /**
+   * Actor (triggering user) specification. Accessible in templates as `actor.*`.
+   */
+  export interface Actor {
+    /**
+     * Your system's identifier for the actor (required)
+     */
+    external_id: string;
+
+    avatar?: string;
+
+    custom_fields?: unknown;
+
+    email?: string;
+
+    first_name?: string;
+
+    last_name?: string;
+
+    locale?: string;
+
+    phone?: string;
+
+    timezone?: string;
+  }
+
+  /**
+   * Recipient specification for running a notiflow. Users are auto-created if they
+   * don't exist.
+   */
+  export interface Recipient {
+    /**
+     * Your system's unique identifier for this user (required)
+     */
+    external_id: string;
+
+    /**
+     * Avatar URL
+     */
+    avatar?: string;
+
+    /**
+     * Custom attributes
+     */
+    custom_fields?: unknown;
+
+    /**
+     * Email address (used if user is auto-created)
+     */
+    email?: string;
+
+    /**
+     * First name
+     */
+    first_name?: string;
+
+    /**
+     * Last name
+     */
+    last_name?: string;
+
+    /**
+     * BCP 47 locale
+     */
+    locale?: string;
+
+    /**
+     * Phone number in E.164 format
+     */
+    phone?: string;
+
+    /**
+     * IANA timezone
+     */
+    timezone?: string;
+  }
+}
+
+export declare namespace NotiflowsResource {
+  export { type NotiflowRunResponse as NotiflowRunResponse, type NotiflowRunParams as NotiflowRunParams };
+}

package/src/resources/topics/index.ts

@@ -0,0 +1,11 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export {
+  Subscriptions,
+  type BulkOperationResponse,
+  type BulkSubscribeRequest,
+  type SubscriptionListParams,
+  type SubscriptionSubscribeBulkParams,
+  type SubscriptionUnsubscribeBulkParams,
+} from './subscriptions';
+export { Topics, type Topic, type TopicListParams, type TopicsCursorPage } from './topics';

package/src/resources/topics/subscriptions.ts

@@ -0,0 +1,182 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as UsersSubscriptionsAPI from '../users/subscriptions';
+import { SubscriptionsCursorPage } from '../users/subscriptions';
+import { APIPromise } from '../../core/api-promise';
+import { CursorPage, type CursorPageParams, PagePromise } from '../../core/pagination';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+export class Subscriptions extends APIResource {
+  /**
+   * Retrieve all users subscribed to a specific topic.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const subscription of client.topics.subscriptions.list(
+   *   'order-updates',
+   * )) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    topicID: string,
+    query: SubscriptionListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<SubscriptionsCursorPage, UsersSubscriptionsAPI.Subscription> {
+    return this._client.getAPIList(
+      path`/topics/${topicID}/subscriptions`,
+      CursorPage<UsersSubscriptionsAPI.Subscription>,
+      { query, ...options },
+    );
+  }
+
+  /**
+   * Subscribe multiple users to a topic in a single request.
+   *
+   * - Topics are created automatically if they don't exist.
+   * - If a user is already subscribed, they are included in the `successful`
+   *   response.
+   * - Returns `207 Multi-Status` if some subscriptions failed.
+   *
+   * @example
+   * ```ts
+   * const bulkOperationResponse =
+   *   await client.topics.subscriptions.subscribeBulk(
+   *     'order-updates',
+   *     {
+   *       user_external_ids: [
+   *         'user_12345',
+   *         'user_67890',
+   *         'user_11111',
+   *       ],
+   *     },
+   *   );
+   * ```
+   */
+  subscribeBulk(
+    topicID: string,
+    body: SubscriptionSubscribeBulkParams,
+    options?: RequestOptions,
+  ): APIPromise<BulkOperationResponse> {
+    return this._client.post(path`/topics/${topicID}/subscriptions`, { body, ...options });
+  }
+
+  /**
+   * Unsubscribe multiple users from a topic in a single request.
+   *
+   * - Returns `207 Multi-Status` if some unsubscriptions failed (e.g., user not
+   *   found).
+   * - Users not subscribed to the topic are included in the `failed` response.
+   *
+   * @example
+   * ```ts
+   * const bulkOperationResponse =
+   *   await client.topics.subscriptions.unsubscribeBulk(
+   *     'order-updates',
+   *     {
+   *       user_external_ids: [
+   *         'user_12345',
+   *         'user_67890',
+   *         'user_11111',
+   *       ],
+   *     },
+   *   );
+   * ```
+   */
+  unsubscribeBulk(
+    topicID: string,
+    body: SubscriptionUnsubscribeBulkParams,
+    options?: RequestOptions,
+  ): APIPromise<BulkOperationResponse> {
+    return this._client.delete(path`/topics/${topicID}/subscriptions`, { body, ...options });
+  }
+}
+
+/**
+ * Response for bulk operations showing successful and failed items
+ */
+export interface BulkOperationResponse {
+  /**
+   * Failed operations with error details
+   */
+  failed: Array<BulkOperationResponse.Failed>;
+
+  /**
+   * Successfully processed subscriptions
+   */
+  successful: Array<UsersSubscriptionsAPI.Subscription>;
+}
+
+export namespace BulkOperationResponse {
+  /**
+   * Details of a failed bulk operation item
+   */
+  export interface Failed {
+    /**
+     * The external ID that failed
+     */
+    external_id: string;
+
+    /**
+     * Human-readable error reason
+     */
+    reason: string;
+  }
+}
+
+/**
+ * Request body for bulk subscribe/unsubscribe operations
+ */
+export interface BulkSubscribeRequest {
+  /**
+   * List of user external IDs to subscribe/unsubscribe
+   */
+  user_external_ids: Array<string>;
+}
+
+export interface SubscriptionListParams extends CursorPageParams {
+  /**
+   * Cursor for fetching the previous page
+   */
+  before?: string;
+
+  /**
+   * Filter by created after (ISO 8601 datetime)
+   */
+  created_after?: string;
+
+  /**
+   * Filter by created before (ISO 8601 datetime)
+   */
+  created_before?: string;
+}
+
+export interface SubscriptionSubscribeBulkParams {
+  /**
+   * List of user external IDs to subscribe/unsubscribe
+   */
+  user_external_ids: Array<string>;
+}
+
+export interface SubscriptionUnsubscribeBulkParams {
+  /**
+   * List of user external IDs to subscribe/unsubscribe
+   */
+  user_external_ids: Array<string>;
+}
+
+export declare namespace Subscriptions {
+  export {
+    type BulkOperationResponse as BulkOperationResponse,
+    type BulkSubscribeRequest as BulkSubscribeRequest,
+    type SubscriptionListParams as SubscriptionListParams,
+    type SubscriptionSubscribeBulkParams as SubscriptionSubscribeBulkParams,
+    type SubscriptionUnsubscribeBulkParams as SubscriptionUnsubscribeBulkParams,
+  };
+}
+
+export { type SubscriptionsCursorPage };

package/src/resources/topics/topics.ts

@@ -0,0 +1,115 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as SubscriptionsAPI from './subscriptions';
+import {
+  BulkOperationResponse,
+  BulkSubscribeRequest,
+  SubscriptionListParams,
+  SubscriptionSubscribeBulkParams,
+  SubscriptionUnsubscribeBulkParams,
+  Subscriptions,
+} from './subscriptions';
+import { APIPromise } from '../../core/api-promise';
+import { CursorPage, type CursorPageParams, PagePromise } from '../../core/pagination';
+import { buildHeaders } from '../../internal/headers';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+export class Topics extends APIResource {
+  subscriptions: SubscriptionsAPI.Subscriptions = new SubscriptionsAPI.Subscriptions(this._client);
+
+  /**
+   * Retrieve a topic by name.
+   *
+   * @example
+   * ```ts
+   * const topic = await client.topics.retrieve('order-updates');
+   * ```
+   */
+  retrieve(id: string, options?: RequestOptions): APIPromise<Topic> {
+    return this._client.get(path`/topics/${id}`, options);
+  }
+
+  /**
+   * Retrieve a paginated list of all topics in your project.
+   *
+   * Topics are used for pub/sub notification patterns. Users subscribe to topics,
+   * and you can run notiflows for all subscribers of a topic.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const topic of client.topics.list()) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    query: TopicListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<TopicsCursorPage, Topic> {
+    return this._client.getAPIList('/topics', CursorPage<Topic>, { query, ...options });
+  }
+
+  /**
+   * Delete a topic and all its subscriptions.
+   *
+   * **Warning:** This removes all user subscriptions to this topic. Users will need
+   * to re-subscribe if the topic is recreated.
+   *
+   * @example
+   * ```ts
+   * await client.topics.delete('order-updates');
+   * ```
+   */
+  delete(id: string, options?: RequestOptions): APIPromise<void> {
+    return this._client.delete(path`/topics/${id}`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+}
+
+export type TopicsCursorPage = CursorPage<Topic>;
+
+/**
+ * A topic for pub/sub notification patterns
+ */
+export interface Topic {
+  /**
+   * When the topic was created
+   */
+  created_at: string;
+
+  /**
+   * Unique topic name within your project
+   */
+  name: string;
+}
+
+export interface TopicListParams extends CursorPageParams {
+  /**
+   * Cursor for fetching the previous page
+   */
+  before?: string;
+}
+
+Topics.Subscriptions = Subscriptions;
+
+export declare namespace Topics {
+  export {
+    type Topic as Topic,
+    type TopicsCursorPage as TopicsCursorPage,
+    type TopicListParams as TopicListParams,
+  };
+
+  export {
+    Subscriptions as Subscriptions,
+    type BulkOperationResponse as BulkOperationResponse,
+    type BulkSubscribeRequest as BulkSubscribeRequest,
+    type SubscriptionListParams as SubscriptionListParams,
+    type SubscriptionSubscribeBulkParams as SubscriptionSubscribeBulkParams,
+    type SubscriptionUnsubscribeBulkParams as SubscriptionUnsubscribeBulkParams,
+  };
+}

package/src/resources/topics.ts

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

package/src/resources/users/channel-settings.ts

@@ -0,0 +1,205 @@
+// 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';
+
+export class ChannelSettings extends APIResource {
+  /**
+   * Retrieve a user's settings for a specific channel.
+   *
+   * Channel settings store provider-specific data like device tokens (for push) or
+   * Slack user IDs (for chat).
+   *
+   * @example
+   * ```ts
+   * const channelSettings =
+   *   await client.users.channelSettings.retrieve(
+   *     '01HQXYZ123456789ABCDEFGHIJ',
+   *     { user_id: 'user_12345' },
+   *   );
+   * ```
+   */
+  retrieve(
+    channelID: string,
+    params: ChannelSettingRetrieveParams,
+    options?: RequestOptions,
+  ): APIPromise<ChannelSettings> {
+    const { user_id } = params;
+    return this._client.get(path`/users/${user_id}/channel-settings/${channelID}`, options);
+  }
+
+  /**
+   * Update a user's settings for a specific channel. Creates the settings if they
+   * don't exist.
+   *
+   * **Provider-specific settings:**
+   *
+   * **Mobile Push (APNS/FCM):**
+   *
+   * ```json
+   * {
+   *   "settings": {
+   *     "device_tokens": ["token1", "token2"]
+   *   }
+   * }
+   * ```
+   *
+   * **Slack:**
+   *
+   * ```json
+   * {
+   *   "settings": {
+   *     "slack_channel_id": "C0123456789",
+   *     "slack_user_id": "U0123456789"
+   *   }
+   * }
+   * ```
+   *
+   * At least one of `slack_channel_id` or `slack_user_id` must be provided.
+   *
+   * @example
+   * ```ts
+   * const channelSettings =
+   *   await client.users.channelSettings.update(
+   *     '01HQXYZ123456789ABCDEFGHIJ',
+   *     {
+   *       user_id: 'user_12345',
+   *       settings: {
+   *         device_tokens: ['ExampleTokenABCDEF123456789...'],
+   *       },
+   *     },
+   *   );
+   * ```
+   */
+  update(
+    channelID: string,
+    params: ChannelSettingUpdateParams,
+    options?: RequestOptions,
+  ): APIPromise<ChannelSettings> {
+    const { user_id, ...body } = params;
+    return this._client.put(path`/users/${user_id}/channel-settings/${channelID}`, { body, ...options });
+  }
+
+  /**
+   * Remove a user's settings for a specific channel.
+   *
+   * After deletion, the user will no longer receive notifications through this
+   * channel until new settings are configured.
+   *
+   * @example
+   * ```ts
+   * await client.users.channelSettings.delete(
+   *   '01HQXYZ123456789ABCDEFGHIJ',
+   *   { user_id: 'user_12345' },
+   * );
+   * ```
+   */
+  delete(channelID: string, params: ChannelSettingDeleteParams, options?: RequestOptions): APIPromise<void> {
+    const { user_id } = params;
+    return this._client.delete(path`/users/${user_id}/channel-settings/${channelID}`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+}
+
+/**
+ * User's settings for a specific channel (e.g., device tokens, Slack credentials)
+ */
+export interface ChannelSettings {
+  /**
+   * Channel ID
+   */
+  channel_id: string;
+
+  /**
+   * When the settings were created
+   */
+  created_at: string;
+
+  /**
+   * The provider type for this channel
+   */
+  provider: 'apns' | 'fcm' | 'slack';
+
+  /**
+   * Provider-specific settings. See MobilePushSettings or SlackSettings schemas.
+   */
+  settings: MobilePushSettings | SlackSettings;
+
+  /**
+   * When the settings were last updated
+   */
+  updated_at: string;
+
+  /**
+   * Internal user ID
+   */
+  user_id: string;
+}
+
+/**
+ * Settings for mobile push notifications (APNS/FCM)
+ */
+export interface MobilePushSettings {
+  /**
+   * List of device tokens for push notifications. At least one token is required.
+   */
+  device_tokens: Array<string>;
+}
+
+/**
+ * Settings for Slack notifications. At least one of `slack_channel_id` or
+ * `slack_user_id` must be provided.
+ */
+export interface SlackSettings {
+  /**
+   * Slack channel ID (starts with C)
+   */
+  slack_channel_id?: string;
+
+  /**
+   * Slack user ID for direct messages (starts with U)
+   */
+  slack_user_id?: string;
+}
+
+export interface ChannelSettingRetrieveParams {
+  /**
+   * User external ID
+   */
+  user_id: string;
+}
+
+export interface ChannelSettingUpdateParams {
+  /**
+   * Path param: User external ID
+   */
+  user_id: string;
+
+  /**
+   * Body param: Provider-specific settings. Structure depends on channel provider.
+   */
+  settings: MobilePushSettings | SlackSettings;
+}
+
+export interface ChannelSettingDeleteParams {
+  /**
+   * User external ID
+   */
+  user_id: string;
+}
+
+export declare namespace ChannelSettings {
+  export {
+    type ChannelSettings as ChannelSettings,
+    type MobilePushSettings as MobilePushSettings,
+    type SlackSettings as SlackSettings,
+    type ChannelSettingRetrieveParams as ChannelSettingRetrieveParams,
+    type ChannelSettingUpdateParams as ChannelSettingUpdateParams,
+    type ChannelSettingDeleteParams as ChannelSettingDeleteParams,
+  };
+}