featurebase-node 0.0.2

package/resources/changelogs/changelogs.d.mts

@@ -0,0 +1,723 @@
+import { APIResource } from "../../core/resource.mjs";
+import * as SubscribersAPI from "./subscribers.mjs";
+import { SubscriberAddParams, SubscriberAddResponse, SubscriberRemoveParams, SubscriberRemoveResponse, Subscribers } from "./subscribers.mjs";
+import { APIPromise } from "../../core/api-promise.mjs";
+import { RequestOptions } from "../../internal/request-options.mjs";
+/**
+ * Release notes and updates published by the organization. Changelogs keep users informed about new features, improvements, and fixes.
+ */
+export declare class Changelogs extends APIResource {
+    subscribers: SubscribersAPI.Subscribers;
+    /**
+     * Creates a new changelog for the authenticated organization.
+     *
+     * ### Required Fields
+     *
+     * - `title` - The title of the changelog
+     *
+     * ### Content
+     *
+     * Provide content in one of two formats (at least one is required):
+     *
+     * - `htmlContent` - HTML content of the changelog
+     * - `markdownContent` - Markdown content of the changelog
+     *
+     * **Note:** For images in content, you can use:
+     *
+     * - External URLs in img src attributes (automatically uploaded to our storage)
+     * - Base64 encoded data URIs (data:image/...) which are processed and stored
+     *
+     * ### Optional Fields
+     *
+     * - `categories` - Array of category names (e.g., ["New", "Fixed", "Improved"])
+     * - `featuredImage` - URL of the featured image (external URLs are uploaded to our
+     *   storage)
+     * - `allowedSegmentIds` - Array of segment IDs that are allowed to view the
+     *   changelog
+     * - `locale` - The locale of the changelog (defaults to organization default)
+     * - `date` - The date of the changelog
+     * - `state` - The state of the changelog: `draft` (default) or `live`
+     *
+     * ### Response
+     *
+     * Returns the created changelog object.
+     *
+     * @example
+     * ```ts
+     * const changelog = await client.changelogs.create({
+     *   title: 'New Features Update',
+     * });
+     * ```
+     */
+    create(params: ChangelogCreateParams, options?: RequestOptions): APIPromise<Changelog>;
+    /**
+     * Retrieves a single changelog by its unique identifier or slug.
+     *
+     * Returns the full changelog object including:
+     *
+     * - Title and content (in HTML and markdown formats)
+     * - Featured image
+     * - Publication date
+     * - Categories
+     * - Comment count
+     * - Email notification status
+     *
+     * ### Localization
+     *
+     * The changelog content is returned in the organization's default locale. If the
+     * changelog doesn't exist in the default locale, the first available locale is
+     * used.
+     *
+     * ### State
+     *
+     * Both published (`live`) and draft changelogs can be retrieved. The `state` field
+     * indicates the current publication status.
+     *
+     * @example
+     * ```ts
+     * const changelog = await client.changelogs.retrieve(
+     *   '507f1f77bcf86cd799439011',
+     * );
+     * ```
+     */
+    retrieve(id: string, params?: ChangelogRetrieveParams | null | undefined, options?: RequestOptions): APIPromise<Changelog>;
+    /**
+     * Updates an existing changelog by its unique identifier.
+     *
+     * You can update:
+     *
+     * - **title** - The changelog title
+     * - **htmlContent** - HTML content (one of htmlContent or markdownContent)
+     * - **markdownContent** - Markdown content (one of htmlContent or markdownContent)
+     * - **categories** - Array of category names
+     * - **featuredImage** - Featured image URL
+     * - **allowedSegmentIds** - Segment IDs for access control
+     * - **date** - The date of the changelog
+     *
+     * ### Content Format
+     *
+     * Provide content in one of two formats:
+     *
+     * - `htmlContent` - HTML content of the changelog
+     * - `markdownContent` - Markdown content of the changelog
+     *
+     * **Note:** For images in content, you can use:
+     *
+     * - External URLs in img src attributes (automatically uploaded to our storage)
+     * - Base64 encoded data URIs (data:image/...) which are processed and stored
+     *
+     * ### Categories
+     *
+     * Provide category names as an array. The categories must already exist in your
+     * organization.
+     *
+     * **Example:** `["New", "Fixed", "Improved"]`
+     *
+     * ### Response
+     *
+     * Returns the updated changelog object with all fields populated.
+     *
+     * ### Errors
+     *
+     * - `400` - Invalid changelog ID format or invalid input
+     * - `404` - Changelog not found or doesn't belong to your organization
+     *
+     * @example
+     * ```ts
+     * const changelog = await client.changelogs.update(
+     *   '507f1f77bcf86cd799439011',
+     * );
+     * ```
+     */
+    update(id: string, params: ChangelogUpdateParams, options?: RequestOptions): APIPromise<Changelog>;
+    /**
+     * Returns all changelogs for the authenticated organization.
+     *
+     * Changelogs are release notes and updates that keep users informed about new
+     * features, improvements, and bug fixes. Each changelog can have:
+     *
+     * - Multiple translations (locales)
+     * - Categories for organization
+     * - Featured images
+     * - Scheduled publishing
+     *
+     * ### Pagination
+     *
+     * This endpoint uses **cursor-based pagination**:
+     *
+     * - `limit` - Number of changelogs to return (1-100, default 10)
+     * - `cursor` - Opaque cursor from a previous response's `nextCursor` field
+     *
+     * **Example:** To paginate through results:
+     *
+     * 1. First request: `GET /v2/changelogs?limit=10`
+     * 2. If `nextCursor` is not null, use it for the next page
+     * 3. Next request: `GET /v2/changelogs?limit=10&cursor={nextCursor}`
+     *
+     * ### Response Format
+     *
+     * Returns a list object with:
+     *
+     * - `object` - Always "list"
+     * - `data` - Array of changelog objects
+     * - `nextCursor` - Cursor for the next page (null if no more results)
+     *
+     * ### Filtering
+     *
+     * Filter changelogs using query parameters:
+     *
+     * - `id` - Find a specific changelog by ID or slug
+     * - `q` - Search query for title/content
+     * - `categories` - Filter by category names
+     * - `locale` - Get changelogs in a specific locale (defaults to org default)
+     * - `state` - Filter by state: `live`, `draft`, or `all`
+     * - `startDate` - Include changelogs dated on or after this date
+     * - `endDate` - Include changelogs dated on or before this date
+     *
+     * ### Sorting
+     *
+     * Results are sorted by date (descending by default):
+     *
+     * - `sortBy` - Field to sort by (currently only `date`)
+     * - `sortOrder` - Sort direction: `asc` or `desc` (default: `desc`)
+     *
+     * @example
+     * ```ts
+     * const changelogs = await client.changelogs.list();
+     * ```
+     */
+    list(params?: ChangelogListParams | null | undefined, options?: RequestOptions): APIPromise<ChangelogListResponse>;
+    /**
+     * Deletes a changelog by its unique identifier.
+     *
+     * ### Deletion Behavior
+     *
+     * The changelog and all associated comments are permanently deleted. This action
+     * cannot be undone.
+     *
+     * ### Permissions
+     *
+     * Only organization admins can delete changelogs.
+     *
+     * ### Response
+     *
+     * Returns a deletion confirmation:
+     *
+     * ```json
+     * {
+     *   "id": "6457e3ff70afca5d8c27dccc",
+     *   "object": "changelog",
+     *   "deleted": true
+     * }
+     * ```
+     *
+     * ### Errors
+     *
+     * - `400` - Invalid changelog ID format
+     * - `404` - Changelog not found or doesn't belong to your organization
+     *
+     * @example
+     * ```ts
+     * const changelog = await client.changelogs.delete(
+     *   '507f1f77bcf86cd799439011',
+     * );
+     * ```
+     */
+    delete(id: string, params?: ChangelogDeleteParams | null | undefined, options?: RequestOptions): APIPromise<ChangelogDeleteResponse>;
+    /**
+     * Publishes a changelog and optionally sends an email notification to subscribers.
+     *
+     * ### Optional Fields
+     *
+     * - `sendEmail` - Whether to send an email notification to subscribers (default:
+     *   false)
+     * - `locales` - Array of locales to publish. An empty array publishes to all
+     *   available locales
+     * - `scheduledDate` - A future date/time when the changelog should be published
+     *
+     * ### Scheduling
+     *
+     * If `scheduledDate` is provided:
+     *
+     * - Must be a future date
+     * - The changelog will be scheduled for publishing at that time
+     * - Any existing scheduled publish for the same locales will be cancelled and
+     *   replaced
+     *
+     * ### Email Notifications
+     *
+     * If `sendEmail` is true:
+     *
+     * - Email notifications are sent to all subscribers in the published locales
+     * - Emails are only sent once per locale (won't resend on republish)
+     *
+     * ### Response
+     *
+     * Returns a success confirmation:
+     *
+     * ```json
+     * {
+     *   "success": true,
+     *   "state": "published"
+     * }
+     * ```
+     *
+     * Or for scheduled publishes:
+     *
+     * ```json
+     * {
+     *   "success": true,
+     *   "state": "scheduled"
+     * }
+     * ```
+     *
+     * ### Errors
+     *
+     * - `400` - Invalid changelog ID or scheduled date is not in the future
+     * - `404` - Changelog not found or doesn't belong to your organization
+     *
+     * @example
+     * ```ts
+     * const publishUnpublishSuccess =
+     *   await client.changelogs.publish(
+     *     '507f1f77bcf86cd799439011',
+     *   );
+     * ```
+     */
+    publish(id: string, params: ChangelogPublishParams, options?: RequestOptions): APIPromise<PublishUnpublishSuccess>;
+    /**
+     * Unpublishes a changelog, removing it from public view.
+     *
+     * ### Optional Fields
+     *
+     * - `locales` - Array of locales to unpublish from. An empty array unpublishes
+     *   from all locales
+     *
+     * ### Behavior
+     *
+     * - The changelog content is preserved (reverts to draft state)
+     * - Any scheduled publishes for the specified locales are cancelled
+     * - The changelog can be re-published later
+     *
+     * ### Response
+     *
+     * Returns a success confirmation:
+     *
+     * ```json
+     * {
+     *   "success": true,
+     *   "state": "unpublished"
+     * }
+     * ```
+     *
+     * ### Errors
+     *
+     * - `400` - Invalid changelog ID format
+     * - `404` - Changelog not found or doesn't belong to your organization
+     *
+     * @example
+     * ```ts
+     * const publishUnpublishSuccess =
+     *   await client.changelogs.unpublish(
+     *     '507f1f77bcf86cd799439011',
+     *   );
+     * ```
+     */
+    unpublish(id: string, params: ChangelogUnpublishParams, options?: RequestOptions): APIPromise<PublishUnpublishSuccess>;
+}
+export interface Changelog {
+    /**
+     * Unique identifier
+     */
+    id: string;
+    /**
+     * Segment IDs that are allowed to view this changelog
+     */
+    allowedSegmentIds: Array<string>;
+    /**
+     * Array of locale codes where the changelog has content
+     */
+    availableLocales: Array<string>;
+    /**
+     * Categories the changelog belongs to
+     */
+    categories: Array<Changelog.Category>;
+    /**
+     * Number of comments
+     */
+    commentCount: number;
+    /**
+     * Content in HTML format
+     */
+    content: string;
+    /**
+     * ISO 8601 timestamp when created
+     */
+    createdAt: string;
+    /**
+     * Publication date as ISO 8601 timestamp
+     */
+    date: string;
+    /**
+     * Whether email notification was sent to subscribers
+     */
+    emailSentToSubscribers: boolean;
+    /**
+     * Featured image URL
+     */
+    featuredImage: string | null;
+    /**
+     * Whether the draft content differs from the published live content
+     */
+    isDraftDiffersFromLive: boolean;
+    /**
+     * Whether the changelog is published (has a live version) in this locale
+     */
+    isPublished: boolean;
+    /**
+     * Locale of the changelog
+     */
+    locale: 'bn' | 'bs' | 'pt-BR' | 'bg' | 'ca' | 'hr' | 'cs' | 'da' | 'nl' | 'en' | 'et' | 'fi' | 'fr' | 'de' | 'el' | 'hi' | 'hu' | 'id' | 'it' | 'ja' | 'ko' | 'lv' | 'lt' | 'ms' | 'mn' | 'nb' | 'pl' | 'pt' | 'ro' | 'ru' | 'sr' | 'zh-CN' | 'sk' | 'sl' | 'es' | 'sw' | 'sv' | 'th' | 'zh-TW' | 'tr' | 'uk' | 'vi';
+    /**
+     * Content in markdown format
+     */
+    markdownContent: string | null;
+    /**
+     * Notification settings for each locale
+     */
+    notifications: {
+        [key: string]: Changelog.Notifications;
+    };
+    /**
+     * Object type identifier
+     */
+    object: 'changelog';
+    /**
+     * Organization identifier
+     */
+    organization: string;
+    /**
+     * Array of locale codes where the changelog is published
+     */
+    publishedLocales: Array<string>;
+    /**
+     * URL-friendly slug
+     */
+    slug: string;
+    /**
+     * URL-friendly slugs for each locale
+     */
+    slugs: {
+        [key: string]: string;
+    };
+    /**
+     * State of the changelog
+     */
+    state: 'live' | 'draft';
+    /**
+     * Changelog title
+     */
+    title: string;
+    /**
+     * ISO 8601 timestamp when updated
+     */
+    updatedAt: string;
+    /**
+     * Public URL to view the changelog
+     */
+    url: string;
+}
+export declare namespace Changelog {
+    interface Category {
+        /**
+         * Category unique identifier
+         */
+        id: string;
+        /**
+         * Category name
+         */
+        name: string;
+        /**
+         * Roles allowed to view this category
+         */
+        roles?: Array<string>;
+    }
+    interface Notifications {
+        /**
+         * Scheduled publication date as ISO 8601 timestamp
+         */
+        scheduledDate: string | null;
+        /**
+         * Whether the email notification has been sent
+         */
+        emailSent?: boolean;
+        /**
+         * Whether the changelog is hidden from the board and widgets
+         */
+        hideFromBoardAndWidgets?: boolean;
+        /**
+         * Whether email notification should be sent for this locale
+         */
+        sendEmailNotification?: boolean;
+    }
+}
+export interface PublishUnpublishSuccess {
+    /**
+     * Indicates the operation was successful
+     */
+    success: true;
+    /**
+     * The state of the changelog after the operation
+     */
+    state?: 'published' | 'scheduled' | 'unpublished';
+}
+export interface ChangelogListResponse {
+    /**
+     * Array of changelogs
+     */
+    data: Array<Changelog>;
+    /**
+     * Cursor for fetching the next page (cursor-based pagination)
+     */
+    nextCursor: string | null;
+    /**
+     * Object type identifier
+     */
+    object: 'list';
+    /**
+     * Pagination metadata for page-based requests
+     */
+    pagination?: ChangelogListResponse.Pagination;
+}
+export declare namespace ChangelogListResponse {
+    /**
+     * Pagination metadata for page-based requests
+     */
+    interface Pagination {
+        /**
+         * Items per page
+         */
+        limit: number;
+        /**
+         * Current page number
+         */
+        page: number;
+        /**
+         * Total number of items
+         */
+        total: number;
+        /**
+         * Total number of pages
+         */
+        totalPages: number;
+    }
+}
+export interface ChangelogDeleteResponse {
+    /**
+     * Unique identifier of the deleted changelog
+     */
+    id: string;
+    /**
+     * Indicates the resource was deleted
+     */
+    deleted: true;
+    /**
+     * Object type identifier
+     */
+    object: 'changelog';
+}
+export interface ChangelogCreateParams {
+    /**
+     * Body param: The title of the changelog
+     */
+    title: string;
+    /**
+     * Body param: An array of segment IDs that are allowed to view the changelog
+     */
+    allowedSegmentIds?: Array<string>;
+    /**
+     * Body param: An array of category names to which the changelog belongs
+     */
+    categories?: Array<string>;
+    /**
+     * Body param: The date of the changelog
+     */
+    date?: string | null;
+    /**
+     * Body param: The URL of the featured image for the changelog. External URLs will
+     * be uploaded to our storage.
+     */
+    featuredImage?: string;
+    /**
+     * Body param: The HTML content of the changelog. Provide either htmlContent or
+     * markdownContent. For images, external URLs and base64 data URIs are
+     * automatically processed and stored.
+     */
+    htmlContent?: string;
+    /**
+     * Body param: The locale of the changelog, defaulting to the organization default
+     * locale
+     */
+    locale?: 'bn' | 'bs' | 'pt-BR' | 'bg' | 'ca' | 'hr' | 'cs' | 'da' | 'nl' | 'en' | 'et' | 'fi' | 'fr' | 'de' | 'el' | 'hi' | 'hu' | 'id' | 'it' | 'ja' | 'ko' | 'lv' | 'lt' | 'ms' | 'mn' | 'nb' | 'pl' | 'pt' | 'ro' | 'ru' | 'sr' | 'zh-CN' | 'sk' | 'sl' | 'es' | 'sw' | 'sv' | 'th' | 'zh-TW' | 'tr' | 'uk' | 'vi';
+    /**
+     * Body param: The markdown content of the changelog. Provide either htmlContent or
+     * markdownContent. For images, external URLs and base64 data URIs are
+     * automatically processed and stored.
+     */
+    markdownContent?: string;
+    /**
+     * Body param: The state of the changelog (draft or live)
+     */
+    state?: 'draft' | 'live';
+    /**
+     * Header param: API version for this request. Defaults to your organization's
+     * configured API version if not specified.
+     */
+    'Featurebase-Version'?: string;
+}
+export interface ChangelogRetrieveParams {
+    /**
+     * API version for this request. Defaults to your organization's configured API
+     * version if not specified.
+     */
+    'Featurebase-Version'?: string;
+}
+export interface ChangelogUpdateParams {
+    /**
+     * Body param: An array of segment IDs that are allowed to view the changelog
+     */
+    allowedSegmentIds?: Array<string>;
+    /**
+     * Body param: An array of category names to which the changelog belongs
+     */
+    categories?: Array<string>;
+    /**
+     * Body param: The date of the changelog
+     */
+    date?: string | null;
+    /**
+     * Body param: The URL of the featured image for the changelog. External URLs will
+     * be uploaded to our storage.
+     */
+    featuredImage?: string;
+    /**
+     * Body param: The HTML content of the changelog. Provide either htmlContent or
+     * markdownContent. For images, external URLs and base64 data URIs are
+     * automatically processed and stored.
+     */
+    htmlContent?: string;
+    /**
+     * Body param: The markdown content of the changelog. Provide either htmlContent or
+     * markdownContent. For images, external URLs and base64 data URIs are
+     * automatically processed and stored.
+     */
+    markdownContent?: string;
+    /**
+     * Body param: The title of the changelog
+     */
+    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 ChangelogListParams {
+    /**
+     * Query param: Find changelog by its id (also accepts slug)
+     */
+    id?: string;
+    /**
+     * Query param: Filter changelogs by category names (single value or array)
+     */
+    categories?: string | Array<string>;
+    /**
+     * Query param: Cursor for pagination. Use nextCursor from previous response.
+     */
+    cursor?: string;
+    /**
+     * Query param: Include Changelogs dated on or before the specified end date
+     */
+    endDate?: string | null;
+    /**
+     * Query param: Maximum number of changelogs to return
+     */
+    limit?: number;
+    /**
+     * Query param: The locale of the changelogs. Defaults to the organization default
+     * locale.
+     */
+    locale?: 'bn' | 'bs' | 'pt-BR' | 'bg' | 'ca' | 'hr' | 'cs' | 'da' | 'nl' | 'en' | 'et' | 'fi' | 'fr' | 'de' | 'el' | 'hi' | 'hu' | 'id' | 'it' | 'ja' | 'ko' | 'lv' | 'lt' | 'ms' | 'mn' | 'nb' | 'pl' | 'pt' | 'ro' | 'ru' | 'sr' | 'zh-CN' | 'sk' | 'sl' | 'es' | 'sw' | 'sv' | 'th' | 'zh-TW' | 'tr' | 'uk' | 'vi';
+    /**
+     * Query param: Search for changelogs by title or content
+     */
+    q?: string;
+    /**
+     * Query param: Field to sort by
+     */
+    sortBy?: 'date';
+    /**
+     * Query param: Sort direction
+     */
+    sortOrder?: 'asc' | 'desc';
+    /**
+     * Query param: Include Changelogs dated on or after the specified start date
+     */
+    startDate?: string | null;
+    /**
+     * Query param: The state of the changelog. Use "all" to get both draft and live
+     * changelogs.
+     */
+    state?: 'draft' | 'live' | 'all';
+    /**
+     * Header param: API version for this request. Defaults to your organization's
+     * configured API version if not specified.
+     */
+    'Featurebase-Version'?: string;
+}
+export interface ChangelogDeleteParams {
+    /**
+     * API version for this request. Defaults to your organization's configured API
+     * version if not specified.
+     */
+    'Featurebase-Version'?: string;
+}
+export interface ChangelogPublishParams {
+    /**
+     * Body param: An array of locales to publish the changelog to. An empty array
+     * publishes to all locales.
+     */
+    locales?: Array<'bn' | 'bs' | 'pt-BR' | 'bg' | 'ca' | 'hr' | 'cs' | 'da' | 'nl' | 'en' | 'et' | 'fi' | 'fr' | 'de' | 'el' | 'hi' | 'hu' | 'id' | 'it' | 'ja' | 'ko' | 'lv' | 'lt' | 'ms' | 'mn' | 'nb' | 'pl' | 'pt' | 'ro' | 'ru' | 'sr' | 'zh-CN' | 'sk' | 'sl' | 'es' | 'sw' | 'sv' | 'th' | 'zh-TW' | 'tr' | 'uk' | 'vi'>;
+    /**
+     * Body param: The date when the changelog should be published. Must be a future
+     * date. Pass null or omit to publish immediately.
+     */
+    scheduledDate?: string | null;
+    /**
+     * Body param: A flag indicating whether to send an email notification to
+     * subscribers.
+     */
+    sendEmail?: boolean | null;
+    /**
+     * Header param: API version for this request. Defaults to your organization's
+     * configured API version if not specified.
+     */
+    'Featurebase-Version'?: string;
+}
+export interface ChangelogUnpublishParams {
+    /**
+     * Body param: An array of locales to unpublish the changelog from. An empty array
+     * unpublishes from all locales.
+     */
+    locales?: Array<'bn' | 'bs' | 'pt-BR' | 'bg' | 'ca' | 'hr' | 'cs' | 'da' | 'nl' | 'en' | 'et' | 'fi' | 'fr' | 'de' | 'el' | 'hi' | 'hu' | 'id' | 'it' | 'ja' | 'ko' | 'lv' | 'lt' | 'ms' | 'mn' | 'nb' | 'pl' | 'pt' | 'ro' | 'ru' | 'sr' | 'zh-CN' | 'sk' | 'sl' | 'es' | 'sw' | 'sv' | 'th' | 'zh-TW' | 'tr' | 'uk' | 'vi'>;
+    /**
+     * Header param: API version for this request. Defaults to your organization's
+     * configured API version if not specified.
+     */
+    'Featurebase-Version'?: string;
+}
+export declare namespace Changelogs {
+    export { type Changelog as Changelog, type PublishUnpublishSuccess as PublishUnpublishSuccess, type ChangelogListResponse as ChangelogListResponse, type ChangelogDeleteResponse as ChangelogDeleteResponse, type ChangelogCreateParams as ChangelogCreateParams, type ChangelogRetrieveParams as ChangelogRetrieveParams, type ChangelogUpdateParams as ChangelogUpdateParams, type ChangelogListParams as ChangelogListParams, type ChangelogDeleteParams as ChangelogDeleteParams, type ChangelogPublishParams as ChangelogPublishParams, type ChangelogUnpublishParams as ChangelogUnpublishParams, };
+    export { Subscribers as Subscribers, type SubscriberAddResponse as SubscriberAddResponse, type SubscriberRemoveResponse as SubscriberRemoveResponse, type SubscriberAddParams as SubscriberAddParams, type SubscriberRemoveParams as SubscriberRemoveParams, };
+}
+//# sourceMappingURL=changelogs.d.mts.map