featurebase-node 0.3.0 → 0.4.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';
@@ -231,15 +232,18 @@ 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([
@@ -431,6 +435,8 @@ export class Changelogs extends APIResource {
   }
 }
 
+export type ChangelogsCursorPage = CursorPage<Changelog>;
+
 export interface Changelog {
   /**
    * Unique identifier
@@ -648,55 +654,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
@@ -871,7 +828,7 @@ export interface ChangelogUpdateParams {
   'Featurebase-Version'?: string;
 }
 
-export interface ChangelogListParams {
+export interface ChangelogListParams extends CursorPageParams {
   /**
    * Query param: Find changelog by its id (also accepts slug)
    */
@@ -882,21 +839,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.
@@ -1118,8 +1065,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/feedback/comments.ts

@@ -3,6 +3,7 @@
 import { APIResource } from '../../core/resource';
 import * as TicketsAPI from '../support/tickets/tickets';
 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';
@@ -258,15 +259,18 @@ export class Comments extends APIResource {
    *
    * @example
    * ```ts
-   * const comments = await client.feedback.comments.list();
+   * // Automatically fetches more pages as needed.
+   * for await (const comment of client.feedback.comments.list()) {
+   *   // ...
+   * }
    * ```
    */
   list(
     params: CommentListParams | null | undefined = {},
     options?: RequestOptions,
-  ): APIPromise<CommentListResponse> {
+  ): PagePromise<CommentsCursorPage, Comment> {
     const { 'Featurebase-Version': featurebaseVersion, ...query } = params ?? {};
-    return this._client.get('/v2/comments', {
+    return this._client.getAPIList('/v2/comments', CursorPage<Comment>, {
       query,
       ...options,
       headers: buildHeaders([
@@ -412,6 +416,8 @@ export class Comments extends APIResource {
   }
 }
 
+export type CommentsCursorPage = CursorPage<Comment>;
+
 export interface Comment {
   /**
    * Unique identifier
@@ -520,55 +526,6 @@ export namespace Comment {
   }
 }
 
-export interface CommentListResponse {
-  /**
-   * Array of comments
-   */
-  data: Array<Comment>;
-
-  /**
-   * Cursor for fetching the next page (cursor-based pagination)
-   */
-  nextCursor: string | null;
-
-  /**
-   * Object type identifier
-   */
-  object: 'list';
-
-  /**
-   * Pagination metadata for page-based requests
-   */
-  pagination?: CommentListResponse.Pagination;
-}
-
-export namespace CommentListResponse {
-  /**
-   * 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 CommentDelete0Response {
   /**
    * Unique identifier of the deleted comment
@@ -706,27 +663,17 @@ export interface CommentUpdateParams {
   'Featurebase-Version'?: string;
 }
 
-export interface CommentListParams {
+export interface CommentListParams extends CursorPageParams {
   /**
    * Query param: Filter comments by changelog ID
    */
   changelogId?: string;
 
-  /**
-   * Query param: Cursor for pagination. Use nextCursor from previous response.
-   */
-  cursor?: string;
-
   /**
    * Query param: Filter by review status
    */
   inReview?: boolean | null;
 
-  /**
-   * Query param: Maximum number of comments to return
-   */
-  limit?: number;
-
   /**
    * Query param: Filter comments by post ID
    */
@@ -773,9 +720,9 @@ export interface CommentDelete1Params {
 export declare namespace Comments {
   export {
     type Comment as Comment,
-    type CommentListResponse as CommentListResponse,
     type CommentDelete0Response as CommentDelete0Response,
     type CommentDelete1Response as CommentDelete1Response,
+    type CommentsCursorPage as CommentsCursorPage,
     type CommentCreateParams as CommentCreateParams,
     type CommentRetrieveParams as CommentRetrieveParams,
     type CommentUpdateParams as CommentUpdateParams,

package/src/resources/feedback/feedback.ts

@@ -12,10 +12,10 @@ import {
   CommentDelete1Params,
   CommentDelete1Response,
   CommentListParams,
-  CommentListResponse,
   CommentRetrieveParams,
   CommentUpdateParams,
   Comments,
+  CommentsCursorPage,
 } from './comments';
 import * as CustomFieldsAPI from './custom-fields';
 import {
@@ -40,10 +40,10 @@ import {
   PostDeleteParams,
   PostDeleteResponse,
   PostListParams,
-  PostListResponse,
   PostRetrieveParams,
   PostUpdateParams,
   Posts,
+  PostsCursorPage,
 } from './posts/posts';
 
 export class Feedback extends APIResource {
@@ -72,8 +72,8 @@ export declare namespace Feedback {
   export {
     Posts as Posts,
     type Post as Post,
-    type PostListResponse as PostListResponse,
     type PostDeleteResponse as PostDeleteResponse,
+    type PostsCursorPage as PostsCursorPage,
     type PostCreateParams as PostCreateParams,
     type PostRetrieveParams as PostRetrieveParams,
     type PostUpdateParams as PostUpdateParams,
@@ -92,9 +92,9 @@ export declare namespace Feedback {
   export {
     Comments as Comments,
     type Comment as Comment,
-    type CommentListResponse as CommentListResponse,
     type CommentDelete0Response as CommentDelete0Response,
     type CommentDelete1Response as CommentDelete1Response,
+    type CommentsCursorPage as CommentsCursorPage,
     type CommentCreateParams as CommentCreateParams,
     type CommentRetrieveParams as CommentRetrieveParams,
     type CommentUpdateParams as CommentUpdateParams,

package/src/resources/feedback/index.ts

@@ -10,7 +10,6 @@ export {
 export {
   Comments,
   type Comment,
-  type CommentListResponse,
   type CommentDelete0Response,
   type CommentDelete1Response,
   type CommentCreateParams,
@@ -19,6 +18,7 @@ export {
   type CommentListParams,
   type CommentDelete0Params,
   type CommentDelete1Params,
+  type CommentsCursorPage,
 } from './comments';
 export {
   CustomFields,
@@ -38,11 +38,11 @@ export {
 export {
   Posts,
   type Post,
-  type PostListResponse,
   type PostDeleteResponse,
   type PostCreateParams,
   type PostRetrieveParams,
   type PostUpdateParams,
   type PostListParams,
   type PostDeleteParams,
+  type PostsCursorPage,
 } from './posts/index';

package/src/resources/feedback/posts/index.ts

@@ -3,13 +3,13 @@
 export {
   Posts,
   type Post,
-  type PostListResponse,
   type PostDeleteResponse,
   type PostCreateParams,
   type PostRetrieveParams,
   type PostUpdateParams,
   type PostListParams,
   type PostDeleteParams,
+  type PostsCursorPage,
 } from './posts';
 export {
   Voters,
@@ -19,4 +19,5 @@ export {
   type VoterListParams,
   type VoterAddParams,
   type VoterRemoveParams,
+  type VoterListResponsesCursorPage,
 } from './voters';