featurebase-node 0.3.0 → 0.5.0

package/src/client.ts

@@ -14,18 +14,21 @@ import * as Opts from './internal/request-options';
 import { stringifyQuery } from './internal/utils/query';
 import { VERSION } from './version';
 import * as Errors from './core/error';
+import * as Pagination from './core/pagination';
+import { AbstractPage, type CursorPageParams, CursorPageResponse } from './core/pagination';
 import * as Uploads from './core/uploads';
 import * as API from './resources/index';
 import { APIPromise } from './core/api-promise';
 import {
   Survey,
   SurveyListParams,
-  SurveyListResponse,
+  SurveyListResponsesParams,
+  SurveyListResponsesResponse,
+  SurveyListResponsesResponsesCursorPage,
   SurveyNextAction,
   SurveyRetrieveParams,
-  SurveyRetrieveResponsesParams,
-  SurveyRetrieveResponsesResponse,
   Surveys,
+  SurveysCursorPage,
 } from './resources/surveys';
 import {
   Webhook,
@@ -33,12 +36,12 @@ import {
   WebhookDeleteParams,
   WebhookDeleteResponse,
   WebhookListParams,
-  WebhookListResponse,
   WebhookRefreshSecretParams,
   WebhookRequestConfigInput,
   WebhookRetrieveParams,
   WebhookUpdateParams,
   Webhooks,
+  WebhooksCursorPage,
 } from './resources/webhooks';
 import {
   Changelog,
@@ -46,12 +49,12 @@ import {
   ChangelogDeleteParams,
   ChangelogDeleteResponse,
   ChangelogListParams,
-  ChangelogListResponse,
   ChangelogPublishParams,
   ChangelogRetrieveParams,
   ChangelogUnpublishParams,
   ChangelogUpdateParams,
   Changelogs,
+  ChangelogsCursorPage,
   PublishUnpublishSuccess,
 } from './resources/changelogs/changelogs';
 import { Feedback } from './resources/feedback/feedback';
@@ -521,6 +524,30 @@ export class Featurebase {
     return { response, options, controller, requestLogID, retryOfRequestLogID, startTime };
   }
 
+  getAPIList<Item, PageClass extends Pagination.AbstractPage<Item> = Pagination.AbstractPage<Item>>(
+    path: string,
+    Page: new (...args: any[]) => PageClass,
+    opts?: PromiseOrValue<RequestOptions>,
+  ): Pagination.PagePromise<PageClass, Item> {
+    return this.requestAPIList(
+      Page,
+      opts && 'then' in opts ?
+        opts.then((opts) => ({ method: 'get', path, ...opts }))
+      : { method: 'get', path, ...opts },
+    );
+  }
+
+  requestAPIList<
+    Item = unknown,
+    PageClass extends Pagination.AbstractPage<Item> = Pagination.AbstractPage<Item>,
+  >(
+    Page: new (...args: ConstructorParameters<typeof Pagination.AbstractPage>) => PageClass,
+    options: PromiseOrValue<FinalRequestOptions>,
+  ): Pagination.PagePromise<PageClass, Item> {
+    const request = this.makeRequest(options, null, undefined);
+    return new Pagination.PagePromise<PageClass, Item>(this as any as Featurebase, request, Page);
+  }
+
   async fetchWithTimeout(
     url: RequestInfo,
     init: RequestInit | undefined,
@@ -799,6 +826,9 @@ Featurebase.Webhooks = Webhooks;
 export declare namespace Featurebase {
   export type RequestOptions = Opts.RequestOptions;
 
+  export import CursorPage = Pagination.CursorPage;
+  export { type CursorPageParams as CursorPageParams, type CursorPageResponse as CursorPageResponse };
+
   export { Support as Support };
 
   export { Feedback as Feedback };
@@ -807,8 +837,8 @@ export declare namespace Featurebase {
     Changelogs as Changelogs,
     type Changelog as Changelog,
     type PublishUnpublishSuccess as PublishUnpublishSuccess,
-    type ChangelogListResponse as ChangelogListResponse,
     type ChangelogDeleteResponse as ChangelogDeleteResponse,
+    type ChangelogsCursorPage as ChangelogsCursorPage,
     type ChangelogCreateParams as ChangelogCreateParams,
     type ChangelogRetrieveParams as ChangelogRetrieveParams,
     type ChangelogUpdateParams as ChangelogUpdateParams,
@@ -828,19 +858,20 @@ export declare namespace Featurebase {
     Surveys as Surveys,
     type Survey as Survey,
     type SurveyNextAction as SurveyNextAction,
-    type SurveyListResponse as SurveyListResponse,
-    type SurveyRetrieveResponsesResponse as SurveyRetrieveResponsesResponse,
+    type SurveyListResponsesResponse as SurveyListResponsesResponse,
+    type SurveysCursorPage as SurveysCursorPage,
+    type SurveyListResponsesResponsesCursorPage as SurveyListResponsesResponsesCursorPage,
     type SurveyRetrieveParams as SurveyRetrieveParams,
     type SurveyListParams as SurveyListParams,
-    type SurveyRetrieveResponsesParams as SurveyRetrieveResponsesParams,
+    type SurveyListResponsesParams as SurveyListResponsesParams,
   };
 
   export {
     Webhooks as Webhooks,
     type Webhook as Webhook,
     type WebhookRequestConfigInput as WebhookRequestConfigInput,
-    type WebhookListResponse as WebhookListResponse,
     type WebhookDeleteResponse as WebhookDeleteResponse,
+    type WebhooksCursorPage as WebhooksCursorPage,
     type WebhookCreateParams as WebhookCreateParams,
     type WebhookRetrieveParams as WebhookRetrieveParams,
     type WebhookUpdateParams as WebhookUpdateParams,

package/src/core/pagination.ts

@@ -0,0 +1,157 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { FeaturebaseError } from './error';
+import { FinalRequestOptions } from '../internal/request-options';
+import { defaultParseResponse } from '../internal/parse';
+import { type Featurebase } from '../client';
+import { APIPromise } from './api-promise';
+import { type APIResponseProps } from '../internal/parse';
+import { maybeObj } from '../internal/utils/values';
+
+export type PageRequestOptions = Pick<FinalRequestOptions, 'query' | 'headers' | 'body' | 'path' | 'method'>;
+
+export abstract class AbstractPage<Item> implements AsyncIterable<Item> {
+  #client: Featurebase;
+  protected options: FinalRequestOptions;
+
+  protected response: Response;
+  protected body: unknown;
+
+  constructor(client: Featurebase, response: Response, body: unknown, options: FinalRequestOptions) {
+    this.#client = client;
+    this.options = options;
+    this.response = response;
+    this.body = body;
+  }
+
+  abstract nextPageRequestOptions(): PageRequestOptions | null;
+
+  abstract getPaginatedItems(): Item[];
+
+  hasNextPage(): boolean {
+    const items = this.getPaginatedItems();
+    if (!items.length) return false;
+    return this.nextPageRequestOptions() != null;
+  }
+
+  async getNextPage(): Promise<this> {
+    const nextOptions = this.nextPageRequestOptions();
+    if (!nextOptions) {
+      throw new FeaturebaseError(
+        'No next page expected; please check `.hasNextPage()` before calling `.getNextPage()`.',
+      );
+    }
+
+    return await this.#client.requestAPIList(this.constructor as any, nextOptions);
+  }
+
+  async *iterPages(): AsyncGenerator<this> {
+    let page: this = this;
+    yield page;
+    while (page.hasNextPage()) {
+      page = await page.getNextPage();
+      yield page;
+    }
+  }
+
+  async *[Symbol.asyncIterator](): AsyncGenerator<Item> {
+    for await (const page of this.iterPages()) {
+      for (const item of page.getPaginatedItems()) {
+        yield item;
+      }
+    }
+  }
+}
+
+/**
+ * This subclass of Promise will resolve to an instantiated Page once the request completes.
+ *
+ * It also implements AsyncIterable to allow auto-paginating iteration on an unawaited list call, eg:
+ *
+ *    for await (const item of client.items.list()) {
+ *      console.log(item)
+ *    }
+ */
+export class PagePromise<
+    PageClass extends AbstractPage<Item>,
+    Item = ReturnType<PageClass['getPaginatedItems']>[number],
+  >
+  extends APIPromise<PageClass>
+  implements AsyncIterable<Item>
+{
+  constructor(
+    client: Featurebase,
+    request: Promise<APIResponseProps>,
+    Page: new (...args: ConstructorParameters<typeof AbstractPage>) => PageClass,
+  ) {
+    super(
+      client,
+      request,
+      async (client, props) =>
+        new Page(client, props.response, await defaultParseResponse(client, props), props.options),
+    );
+  }
+
+  /**
+   * Allow auto-paginating iteration on an unawaited list call, eg:
+   *
+   *    for await (const item of client.items.list()) {
+   *      console.log(item)
+   *    }
+   */
+  async *[Symbol.asyncIterator](): AsyncGenerator<Item> {
+    const page = await this;
+    for await (const item of page) {
+      yield item;
+    }
+  }
+}
+
+export interface CursorPageResponse<Item> {
+  data: Array<Item>;
+
+  nextCursor: string | null;
+}
+
+export interface CursorPageParams {
+  cursor?: string;
+
+  limit?: number;
+}
+
+export class CursorPage<Item> extends AbstractPage<Item> implements CursorPageResponse<Item> {
+  data: Array<Item>;
+
+  nextCursor: string | null;
+
+  constructor(
+    client: Featurebase,
+    response: Response,
+    body: CursorPageResponse<Item>,
+    options: FinalRequestOptions,
+  ) {
+    super(client, response, body, options);
+
+    this.data = body.data || [];
+    this.nextCursor = body.nextCursor || null;
+  }
+
+  getPaginatedItems(): Item[] {
+    return this.data ?? [];
+  }
+
+  nextPageRequestOptions(): PageRequestOptions | null {
+    const cursor = this.nextCursor;
+    if (!cursor) {
+      return null;
+    }
+
+    return {
+      ...this.options,
+      query: {
+        ...maybeObj(this.options.query),
+        cursor,
+      },
+    };
+  }
+}

package/src/index.ts

@@ -5,6 +5,7 @@ export { Featurebase as default } from './client';
 export { type Uploadable, toFile } from './core/uploads';
 export { APIPromise } from './core/api-promise';
 export { Featurebase, type ClientOptions } from './client';
+export { PagePromise } from './core/pagination';
 export {
   FeaturebaseError,
   APIError,

package/src/pagination.ts

@@ -0,0 +1,2 @@
+/** @deprecated Import from ./core/pagination instead */
+export * from './core/pagination';

package/src/resources/changelogs/changelogs.ts

@@ -10,6 +10,7 @@ import {
   Subscribers,
 } from './subscribers';
 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';
@@ -67,7 +68,11 @@ export class Changelogs extends APIResource {
       body,
       ...options,
       headers: buildHeaders([
-        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        {
+          ...(featurebaseVersion?.toString() != null ?
+            { 'Featurebase-Version': featurebaseVersion?.toString() }
+          : undefined),
+        },
         options?.headers,
       ]),
     });
@@ -112,7 +117,11 @@ export class Changelogs extends APIResource {
     return this._client.get(path`/v2/changelogs/${id}`, {
       ...options,
       headers: buildHeaders([
-        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        {
+          ...(featurebaseVersion?.toString() != null ?
+            { 'Featurebase-Version': featurebaseVersion?.toString() }
+          : undefined),
+        },
         options?.headers,
       ]),
     });
@@ -172,7 +181,11 @@ export class Changelogs extends APIResource {
       body,
       ...options,
       headers: buildHeaders([
-        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        {
+          ...(featurebaseVersion?.toString() != null ?
+            { 'Featurebase-Version': featurebaseVersion?.toString() }
+          : undefined),
+        },
         options?.headers,
       ]),
     });
@@ -231,19 +244,26 @@ export class Changelogs extends APIResource {
    *
    * @example
    * ```ts
-   * const changelogs = await client.changelogs.list();
+   * // Automatically fetches more pages as needed.
+   * for await (const changelog of client.changelogs.list()) {
+   *   // ...
+   * }
    * ```
    */
   list(
     params: ChangelogListParams | null | undefined = {},
     options?: RequestOptions,
-  ): APIPromise<ChangelogListResponse> {
+  ): PagePromise<ChangelogsCursorPage, Changelog> {
     const { 'Featurebase-Version': featurebaseVersion, ...query } = params ?? {};
-    return this._client.get('/v2/changelogs', {
+    return this._client.getAPIList('/v2/changelogs', CursorPage<Changelog>, {
       query,
       ...options,
       headers: buildHeaders([
-        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        {
+          ...(featurebaseVersion?.toString() != null ?
+            { 'Featurebase-Version': featurebaseVersion?.toString() }
+          : undefined),
+        },
         options?.headers,
       ]),
     });
@@ -294,7 +314,11 @@ export class Changelogs extends APIResource {
     return this._client.delete(path`/v2/changelogs/${id}`, {
       ...options,
       headers: buildHeaders([
-        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        {
+          ...(featurebaseVersion?.toString() != null ?
+            { 'Featurebase-Version': featurebaseVersion?.toString() }
+          : undefined),
+        },
         options?.headers,
       ]),
     });
@@ -370,7 +394,11 @@ export class Changelogs extends APIResource {
       body,
       ...options,
       headers: buildHeaders([
-        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        {
+          ...(featurebaseVersion?.toString() != null ?
+            { 'Featurebase-Version': featurebaseVersion?.toString() }
+          : undefined),
+        },
         options?.headers,
       ]),
     });
@@ -424,13 +452,19 @@ export class Changelogs extends APIResource {
       body,
       ...options,
       headers: buildHeaders([
-        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        {
+          ...(featurebaseVersion?.toString() != null ?
+            { 'Featurebase-Version': featurebaseVersion?.toString() }
+          : undefined),
+        },
         options?.headers,
       ]),
     });
   }
 }
 
+export type ChangelogsCursorPage = CursorPage<Changelog>;
+
 export interface Changelog {
   /**
    * Unique identifier
@@ -648,55 +682,6 @@ export interface PublishUnpublishSuccess {
   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 namespace ChangelogListResponse {
-  /**
-   * Pagination metadata for page-based requests
-   */
-  export 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
@@ -812,7 +797,7 @@ export interface ChangelogCreateParams {
    * Header param: API version for this request. Defaults to your organization's
    * configured API version if not specified.
    */
-  'Featurebase-Version'?: string;
+  'Featurebase-Version'?: '2026-01-01.nova' | '2025-12-12.clover';
 }
 
 export interface ChangelogRetrieveParams {
@@ -820,7 +805,7 @@ export interface ChangelogRetrieveParams {
    * API version for this request. Defaults to your organization's configured API
    * version if not specified.
    */
-  'Featurebase-Version'?: string;
+  'Featurebase-Version'?: '2026-01-01.nova' | '2025-12-12.clover';
 }
 
 export interface ChangelogUpdateParams {
@@ -868,10 +853,10 @@ export interface ChangelogUpdateParams {
    * Header param: API version for this request. Defaults to your organization's
    * configured API version if not specified.
    */
-  'Featurebase-Version'?: string;
+  'Featurebase-Version'?: '2026-01-01.nova' | '2025-12-12.clover';
 }
 
-export interface ChangelogListParams {
+export interface ChangelogListParams extends CursorPageParams {
   /**
    * Query param: Find changelog by its id (also accepts slug)
    */
@@ -882,21 +867,11 @@ export interface ChangelogListParams {
    */
   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.
@@ -975,7 +950,7 @@ export interface ChangelogListParams {
    * Header param: API version for this request. Defaults to your organization's
    * configured API version if not specified.
    */
-  'Featurebase-Version'?: string;
+  'Featurebase-Version'?: '2026-01-01.nova' | '2025-12-12.clover';
 }
 
 export interface ChangelogDeleteParams {
@@ -983,7 +958,7 @@ export interface ChangelogDeleteParams {
    * API version for this request. Defaults to your organization's configured API
    * version if not specified.
    */
-  'Featurebase-Version'?: string;
+  'Featurebase-Version'?: '2026-01-01.nova' | '2025-12-12.clover';
 }
 
 export interface ChangelogPublishParams {
@@ -1052,7 +1027,7 @@ export interface ChangelogPublishParams {
    * Header param: API version for this request. Defaults to your organization's
    * configured API version if not specified.
    */
-  'Featurebase-Version'?: string;
+  'Featurebase-Version'?: '2026-01-01.nova' | '2025-12-12.clover';
 }
 
 export interface ChangelogUnpublishParams {
@@ -1109,7 +1084,7 @@ export interface ChangelogUnpublishParams {
    * Header param: API version for this request. Defaults to your organization's
    * configured API version if not specified.
    */
-  'Featurebase-Version'?: string;
+  'Featurebase-Version'?: '2026-01-01.nova' | '2025-12-12.clover';
 }
 
 Changelogs.Subscribers = Subscribers;
@@ -1118,8 +1093,8 @@ export declare namespace Changelogs {
   export {
     type Changelog as Changelog,
     type PublishUnpublishSuccess as PublishUnpublishSuccess,
-    type ChangelogListResponse as ChangelogListResponse,
     type ChangelogDeleteResponse as ChangelogDeleteResponse,
+    type ChangelogsCursorPage as ChangelogsCursorPage,
     type ChangelogCreateParams as ChangelogCreateParams,
     type ChangelogRetrieveParams as ChangelogRetrieveParams,
     type ChangelogUpdateParams as ChangelogUpdateParams,

package/src/resources/changelogs/index.ts

@@ -4,7 +4,6 @@ export {
   Changelogs,
   type Changelog,
   type PublishUnpublishSuccess,
-  type ChangelogListResponse,
   type ChangelogDeleteResponse,
   type ChangelogCreateParams,
   type ChangelogRetrieveParams,
@@ -13,6 +12,7 @@ export {
   type ChangelogDeleteParams,
   type ChangelogPublishParams,
   type ChangelogUnpublishParams,
+  type ChangelogsCursorPage,
 } from './changelogs';
 export {
   Subscribers,

package/src/resources/changelogs/subscribers.ts

@@ -61,7 +61,11 @@ export class Subscribers extends APIResource {
       body,
       ...options,
       headers: buildHeaders([
-        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        {
+          ...(featurebaseVersion?.toString() != null ?
+            { 'Featurebase-Version': featurebaseVersion?.toString() }
+          : undefined),
+        },
         options?.headers,
       ]),
     });
@@ -111,7 +115,11 @@ export class Subscribers extends APIResource {
       body,
       ...options,
       headers: buildHeaders([
-        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        {
+          ...(featurebaseVersion?.toString() != null ?
+            { 'Featurebase-Version': featurebaseVersion?.toString() }
+          : undefined),
+        },
         options?.headers,
       ]),
     });
@@ -200,7 +208,7 @@ export interface SubscriberAddParams {
    * Header param: API version for this request. Defaults to your organization's
    * configured API version if not specified.
    */
-  'Featurebase-Version'?: string;
+  'Featurebase-Version'?: '2026-01-01.nova' | '2025-12-12.clover';
 }
 
 export interface SubscriberRemoveParams {
@@ -213,7 +221,7 @@ export interface SubscriberRemoveParams {
    * Header param: API version for this request. Defaults to your organization's
    * configured API version if not specified.
    */
-  'Featurebase-Version'?: string;
+  'Featurebase-Version'?: '2026-01-01.nova' | '2025-12-12.clover';
 }
 
 export declare namespace Subscribers {

package/src/resources/feedback/boards.ts

@@ -32,7 +32,11 @@ export class Boards extends APIResource {
     return this._client.get(path`/v2/boards/${id}`, {
       ...options,
       headers: buildHeaders([
-        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        {
+          ...(featurebaseVersion?.toString() != null ?
+            { 'Featurebase-Version': featurebaseVersion?.toString() }
+          : undefined),
+        },
         options?.headers,
       ]),
     });
@@ -63,7 +67,11 @@ export class Boards extends APIResource {
     return this._client.get('/v2/boards', {
       ...options,
       headers: buildHeaders([
-        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        {
+          ...(featurebaseVersion?.toString() != null ?
+            { 'Featurebase-Version': featurebaseVersion?.toString() }
+          : undefined),
+        },
         options?.headers,
       ]),
     });
@@ -250,7 +258,7 @@ export interface BoardRetrieveParams {
    * API version for this request. Defaults to your organization's configured API
    * version if not specified.
    */
-  'Featurebase-Version'?: string;
+  'Featurebase-Version'?: '2026-01-01.nova' | '2025-12-12.clover';
 }
 
 export interface BoardListParams {
@@ -258,7 +266,7 @@ export interface BoardListParams {
    * API version for this request. Defaults to your organization's configured API
    * version if not specified.
    */
-  'Featurebase-Version'?: string;
+  'Featurebase-Version'?: '2026-01-01.nova' | '2025-12-12.clover';
 }
 
 export declare namespace Boards {