@ophelio/sdk 0.1.1 → 0.2.1

package/dist/index.d.cts

@@ -56,12 +56,6 @@ declare class Transport {
   private parseBody;
 }
 //#endregion
-//#region src/resources/resource.d.ts
-declare class APIResource {
-  protected readonly transport: Transport;
-  constructor(transport: Transport);
-}
-//#endregion
 //#region src/generated/schema.d.ts
 /**
  * This file was auto-generated by openapi-typescript.
@@ -993,6 +987,16 @@ interface components {
       create_time: string;
     };
     ListAuditLogsResponse: {
+      /**
+       * @description Opaque token for the next page; empty string on the last page.
+       * @example
+       */
+      next_page_token: string;
+      /**
+       * @description Total number of results across all pages.
+       * @example 42
+       */
+      total_size: number;
       audit_logs: components["schemas"]["AuditLogs"][];
     };
     Project: {
@@ -1427,6 +1431,16 @@ interface components {
       create_time: string;
     };
     ListWebhookDeliveriesResponse: {
+      /**
+       * @description Opaque token for the next page; empty string on the last page.
+       * @example
+       */
+      next_page_token: string;
+      /**
+       * @description Total number of results across all pages.
+       * @example 42
+       */
+      total_size: number;
       webhook_deliveries: components["schemas"]["WebhookDelivery"][];
     };
     CreateWebhookSubscriptionDto: {
@@ -1540,6 +1554,16 @@ interface components {
       current_term: components["schemas"]["MembershipTerm"] | null;
     };
     ListMembershipsResponse: {
+      /**
+       * @description Opaque token for the next page; empty string on the last page.
+       * @example
+       */
+      next_page_token: string;
+      /**
+       * @description Total number of results across all pages.
+       * @example 42
+       */
+      total_size: number;
       memberships: components["schemas"]["Membership"][];
     };
     ListMembershipMembersResponse: {
@@ -1623,6 +1647,16 @@ interface components {
       applied_term: components["schemas"]["MembershipTerm"] | null;
     };
     ListScheduledChangesResponse: {
+      /**
+       * @description Opaque token for the next page; empty string on the last page.
+       * @example
+       */
+      next_page_token: string;
+      /**
+       * @description Total number of results across all pages.
+       * @example 42
+       */
+      total_size: number;
       scheduled_changes: components["schemas"]["MembershipScheduledChangeResponseDto"][];
     };
     Transaction: {
@@ -1643,6 +1677,16 @@ interface components {
       update_time: string;
     };
     ListTransactionsResponse: {
+      /**
+       * @description Opaque token for the next page; empty string on the last page.
+       * @example
+       */
+      next_page_token: string;
+      /**
+       * @description Total number of results across all pages.
+       * @example 42
+       */
+      total_size: number;
       transactions: components["schemas"]["Transaction"][];
     };
     CreateTransactionDto: {
@@ -1666,6 +1710,16 @@ interface components {
       update_time: string;
     };
     ListCustomersResponse: {
+      /**
+       * @description Opaque token for the next page; empty string on the last page.
+       * @example
+       */
+      next_page_token: string;
+      /**
+       * @description Total number of results across all pages.
+       * @example 42
+       */
+      total_size: number;
       customers: components["schemas"]["Customer"][];
     };
     CreateCustomerDto: {
@@ -1676,6 +1730,19 @@ interface components {
       name: string; /** Format: email */
       email: string;
     };
+    ListCustomerMembershipsResponse: {
+      /**
+       * @description Opaque token for the next page; empty string on the last page.
+       * @example
+       */
+      next_page_token: string;
+      /**
+       * @description Total number of results across all pages.
+       * @example 42
+       */
+      total_size: number;
+      memberships: components["schemas"]["Membership"][];
+    };
   };
   responses: never;
   parameters: never;
@@ -1705,7 +1772,10 @@ interface operations {
   };
   AuditLogsController_list: {
     parameters: {
-      query?: never;
+      query?: {
+        page_size?: number;
+        page_token?: string;
+      };
       header?: never;
       path?: never;
       cookie?: never;
@@ -2846,8 +2916,7 @@ interface operations {
     parameters: {
       query?: never;
       header: {
-        "idempotency-key": string;
-        "Idempotency-Key": string;
+        /** @description Required idempotency key, up to 255 characters. Deduplicated per member: repeating a request with the same key and member returns the original redemption, and reusing that key for the same member with a different entitlement returns 409. A longer key is rejected with 400. */"Idempotency-Key": string;
       };
       path?: never;
       cookie?: never;
@@ -2882,14 +2951,21 @@ interface operations {
           "application/json": components["schemas"]["ErrorResponse"];
         };
       };
+      409: {
+        headers: {
+          [name: string]: unknown;
+        };
+        content: {
+          "application/json": components["schemas"]["ErrorResponse"];
+        };
+      };
     };
   };
   EntitlementsController_usage: {
     parameters: {
       query?: never;
       header: {
-        "idempotency-key": string;
-        "Idempotency-Key": string;
+        /** @description Required idempotency key, up to 255 characters. One usage row is recorded per member, so the same key may carry different members across calls. A longer key is rejected with 400. */"Idempotency-Key": string;
       };
       path?: never;
       cookie?: never;
@@ -3277,7 +3353,10 @@ interface operations {
   };
   WebhookSubscriptionsController_listDeliveries: {
     parameters: {
-      query?: never;
+      query?: {
+        page_size?: number;
+        page_token?: string;
+      };
       header?: never;
       path?: never;
       cookie?: never;
@@ -3558,7 +3637,10 @@ interface operations {
   };
   MembershipsController_list: {
     parameters: {
-      query?: never;
+      query?: {
+        page_size?: number;
+        page_token?: string;
+      };
       header?: never;
       path?: never;
       cookie?: never;
@@ -3578,7 +3660,9 @@ interface operations {
   MembershipsController_create: {
     parameters: {
       query?: never;
-      header?: never;
+      header?: {
+        /** @description Optional idempotency key, up to 255 characters. Repeating a request with the same key returns the original result; reusing a key with a different request body returns 409. A longer key is rejected with 400, and an empty or whitespace-only value is treated as no key. */"Idempotency-Key"?: string;
+      };
       path?: never;
       cookie?: never;
     };
@@ -3604,6 +3688,14 @@ interface operations {
           "application/json": components["schemas"]["ErrorResponse"];
         };
       };
+      409: {
+        headers: {
+          [name: string]: unknown;
+        };
+        content: {
+          "application/json": components["schemas"]["ErrorResponse"];
+        };
+      };
     };
   };
   MembershipsController_get: {
@@ -3752,7 +3844,9 @@ interface operations {
   MembershipsController_renew: {
     parameters: {
       query?: never;
-      header?: never;
+      header?: {
+        /** @description Optional idempotency key, up to 255 characters. Repeating a request with the same key returns the original result; reusing a key with a different request body returns 409. A longer key is rejected with 400, and an empty or whitespace-only value is treated as no key. */"Idempotency-Key"?: string;
+      };
       path?: never;
       cookie?: never;
     };
@@ -3778,6 +3872,14 @@ interface operations {
           "application/json": components["schemas"]["ErrorResponse"];
         };
       };
+      409: {
+        headers: {
+          [name: string]: unknown;
+        };
+        content: {
+          "application/json": components["schemas"]["ErrorResponse"];
+        };
+      };
     };
   };
   MembershipsController_upgrade: {
@@ -3845,6 +3947,8 @@ interface operations {
   MembershipsController_listScheduledChanges: {
     parameters: {
       query?: {
+        page_size?: number;
+        page_token?: string;
         status?: ("pending" | "applied" | "cancelled" | "superseded" | "failed" | "all")[];
       };
       header?: never;
@@ -3890,7 +3994,10 @@ interface operations {
   };
   MembershipsController_listTransactions: {
     parameters: {
-      query?: never;
+      query?: {
+        page_size?: number;
+        page_token?: string;
+      };
       header?: never;
       path?: never;
       cookie?: never;
@@ -3918,7 +4025,9 @@ interface operations {
   MembershipsController_recordTransaction: {
     parameters: {
       query?: never;
-      header?: never;
+      header?: {
+        /** @description Optional idempotency key, up to 255 characters. Repeating a request with the same key returns the original result; reusing a key with a different request body returns 409. A longer key is rejected with 400, and an empty or whitespace-only value is treated as no key. */"Idempotency-Key"?: string;
+      };
       path?: never;
       cookie?: never;
     };
@@ -3944,11 +4053,22 @@ interface operations {
           "application/json": components["schemas"]["ErrorResponse"];
         };
       };
+      409: {
+        headers: {
+          [name: string]: unknown;
+        };
+        content: {
+          "application/json": components["schemas"]["ErrorResponse"];
+        };
+      };
     };
   };
   MembershipsController_listTermTransactions: {
     parameters: {
-      query?: never;
+      query?: {
+        page_size?: number;
+        page_token?: string;
+      };
       header?: never;
       path?: never;
       cookie?: never;
@@ -3975,7 +4095,10 @@ interface operations {
   };
   CustomersController_list: {
     parameters: {
-      query?: never;
+      query?: {
+        page_size?: number;
+        page_token?: string;
+      };
       header?: never;
       path?: never;
       cookie?: never;
@@ -4110,7 +4233,10 @@ interface operations {
   };
   CustomersController_listMemberships: {
     parameters: {
-      query?: never;
+      query?: {
+        page_size?: number;
+        page_token?: string;
+      };
       header?: never;
       path?: never;
       cookie?: never;
@@ -4122,7 +4248,7 @@ interface operations {
           [name: string]: unknown;
         };
         content: {
-          "application/json": components["schemas"]["ListMembershipsResponse"];
+          "application/json": components["schemas"]["ListCustomerMembershipsResponse"];
         };
       };
       404: {
@@ -4298,6 +4424,19 @@ type ScheduledChange = Schemas['MembershipScheduledChangeResponseDto'];
 type PlanChangeResult = Schemas['PlanChangeResponseDto'];
 type MemberSyncResponse = Schemas['MemberSyncResponse'];
 type RedeemEntitlementResponse = Schemas['RedeemEntitlementResponseDto'];
+interface PageParams {
+  /** Rows per page. Server default 50; capped at 250. */
+  page_size?: number;
+  /** Opaque token from a previous page's `next_page_token`. */
+  page_token?: string;
+}
+interface Page<T> {
+  items: T[];
+  /** Opaque token for the next page; empty string on the last page. */
+  next_page_token: string;
+  /** Total number of rows across all pages. */
+  total_size: number;
+}
 type CreateMembershipParams = Schemas['CreateMembershipDto'];
 type UpdateMembershipParams = Schemas['UpdateMembershipDto'];
 type CancelMembershipParams = Schemas['CancelMembershipDto'];
@@ -4330,6 +4469,12 @@ type RenewMembershipParams = Schemas['RenewMembershipDto'];
 type PlanChangeParams = Schemas['PlanChangeDto'];
 type EntitlementType = 'free_entry' | 'guest_pass' | 'discount' | 'early_access';
 //#endregion
+//#region src/resources/resource.d.ts
+declare class APIResource {
+  protected readonly transport: Transport;
+  constructor(transport: Transport);
+}
+//#endregion
 //#region src/resources/admit.d.ts
 declare class AdmitResource extends APIResource {
   /** Gate admission check: `GET /admit?card=<cardId>`. */
@@ -4356,12 +4501,12 @@ declare class BillingOptionsResource extends APIResource {
 //#endregion
 //#region src/resources/customers.d.ts
 declare class CustomersResource extends APIResource {
-  list(options?: RequestOptions): Promise<Customer[]>;
+  list(params?: PageParams, options?: RequestOptions): Promise<Page<Customer>>;
   get(id: string, options?: RequestOptions): Promise<Customer>;
   create(params: CreateCustomerParams, options?: RequestOptions): Promise<Customer>;
   update(id: string, params: UpdateCustomerParams, options?: RequestOptions): Promise<Customer>;
   delete(id: string, options?: RequestOptions): Promise<void>;
-  listMemberships(id: string, options?: RequestOptions): Promise<Membership[]>;
+  listMemberships(id: string, params?: PageParams, options?: RequestOptions): Promise<Page<Membership>>;
 }
 //#endregion
 //#region src/resources/entitlements.d.ts
@@ -4412,22 +4557,37 @@ declare class MembersResource extends APIResource {
 //#endregion
 //#region src/resources/memberships.d.ts
 declare class MembershipsResource extends APIResource {
-  list(options?: RequestOptions): Promise<Membership[]>;
+  list(params?: PageParams, options?: RequestOptions): Promise<Page<Membership>>;
   get(id: string, options?: RequestOptions): Promise<Membership>;
-  create(params: CreateMembershipParams, options?: RequestOptions): Promise<Membership>;
+  /**
+   * Create a membership atomically (record, members, first term, optional
+   * payment). Idempotent: the Idempotency-Key is generated once per call (and
+   * reused across the SDK's internal retries), so a retried create returns the
+   * original membership instead of creating a duplicate. Supply your own key to
+   * dedupe application-level retries across processes.
+   */
+  create(params: CreateMembershipParams, options?: IdempotentRequestOptions): Promise<Membership>;
   update(id: string, params: UpdateMembershipParams, options?: RequestOptions): Promise<Membership>;
   /** Cancellation is a state change, not a delete — see also `uncancel`. */
   cancel(id: string, params: CancelMembershipParams, options?: RequestOptions): Promise<Membership>;
   uncancel(id: string, options?: RequestOptions): Promise<Membership>;
-  listTransactions(id: string, options?: RequestOptions): Promise<Transaction[]>;
+  listTransactions(id: string, params?: PageParams, options?: RequestOptions): Promise<Page<Transaction>>;
   /**
    * Report a payment outcome. Ophel.io never processes payments — your
    * payment provider does; this records the result and drives dunning.
+   * Idempotent: the Idempotency-Key is generated once per call (and reused
+   * across the SDK's internal retries), so a retried report records the
+   * transaction once and does not advance dunning twice.
    */
-  createTransaction(id: string, params: CreateTransactionParams, options?: RequestOptions): Promise<Transaction>;
+  createTransaction(id: string, params: CreateTransactionParams, options?: IdempotentRequestOptions): Promise<Transaction>;
   listMembers(id: string, options?: RequestOptions): Promise<Member[]>;
-  /** Open the next term. Rejected (409) while cancelled or cancellation-pending. */
-  renew(id: string, params: RenewMembershipParams, options?: RequestOptions): Promise<Membership>;
+  /**
+   * Open the next term. Rejected (409) while cancelled or cancellation-pending.
+   * Idempotent: the Idempotency-Key is generated once per call (and reused
+   * across the SDK's internal retries), so a retried renewal returns the
+   * original result instead of opening a second term.
+   */
+  renew(id: string, params: RenewMembershipParams, options?: IdempotentRequestOptions): Promise<Membership>;
   /**
    * Move to a linked higher plan. Applies immediately or schedules at term
    * end — `scheduled_change` is non-null in the deferred case.
@@ -4435,11 +4595,11 @@ declare class MembershipsResource extends APIResource {
   upgrade(id: string, params: PlanChangeParams, options?: RequestOptions): Promise<PlanChangeResult>;
   /** Mirror of upgrade towards a linked lower plan. */
   downgrade(id: string, params: PlanChangeParams, options?: RequestOptions): Promise<PlanChangeResult>;
-  listScheduledChanges(id: string, params?: {
+  listScheduledChanges(id: string, params?: PageParams & {
     status?: 'all';
-  }, options?: RequestOptions): Promise<ScheduledChange[]>;
+  }, options?: RequestOptions): Promise<Page<ScheduledChange>>;
   cancelScheduledChange(id: string, changeId: string, options?: RequestOptions): Promise<void>;
-  listTermTransactions(id: string, termId: string, options?: RequestOptions): Promise<Transaction[]>;
+  listTermTransactions(id: string, termId: string, params?: PageParams, options?: RequestOptions): Promise<Page<Transaction>>;
 }
 //#endregion
 //#region src/resources/plan-entitlements.d.ts
@@ -4501,7 +4661,7 @@ declare class SalesChannelsResource extends APIResource {
 declare class WebhookSubscriptionsResource extends APIResource {
   list(options?: RequestOptions): Promise<WebhookSubscription[]>;
   get(id: string, options?: RequestOptions): Promise<WebhookSubscription>;
-  listDeliveries(id: string, options?: RequestOptions): Promise<WebhookDelivery[]>;
+  listDeliveries(id: string, params?: PageParams, options?: RequestOptions): Promise<Page<WebhookDelivery>>;
   /** The HMAC signing secret is only returned on creation — store it then. */
   create(params: CreateWebhookSubscriptionParams, options?: RequestOptions): Promise<WebhookSubscription>;
   update(id: string, params: UpdateWebhookSubscriptionParams, options?: RequestOptions): Promise<WebhookSubscription>;
@@ -4623,4 +4783,36 @@ declare class OphelioTimeoutError extends OphelioError {}
 /** X-Ophelio-Signature did not match the webhook payload. */
 declare class WebhookSignatureVerificationError extends OphelioError {}
 //#endregion
-export { AdmitResult, AlreadyExistsError, BillingOption, BillingOptionSalesChannel, CancelMembershipParams, CreateBillingOptionParams, CreateBillingOptionSalesChannelParams, CreateCustomerParams, CreateEntitlementParams, CreateMemberRoleParams, CreateMembershipParams, CreatePlanEntitlementParams, CreatePlanLinkParams, CreatePlanParams, CreatePlanPricingGroupMappingParams, CreatePricingGroupParams, CreateSalesChannelParams, CreateTransactionParams, CreateWebhookSubscriptionParams, Customer, DEFAULT_BASE_URL, Entitlement, EntitlementType, EntitlementUsage, type IdempotentRequestOptions, InternalError, InvalidArgumentError, Member, MemberEntitlement, MemberRole, MemberSyncResponse, Membership, MembershipTerm, NotFoundError, Ophelio, OphelioConnectionError, OphelioError, type OphelioOptions, OphelioTimeoutError, type OphelioWebhookEvent, PermissionDeniedError, Plan, PlanChangeParams, PlanChangeResult, PlanEntitlement, PlanLink, PlanLinkView, PlanPricingGroupMapping, PricingGroup, RecordUsageParams, RedeemEntitlementParams, RedeemEntitlementResponse, ReissueCardParams, RenewMembershipParams, type RequestOptions, ResourceExhaustedError, SalesChannel, ScheduledChange, SyncMember, Transaction, UnauthenticatedError, UnavailableError, UnimplementedError, UpdateBillingOptionParams, UpdateCustomerParams, UpdateEntitlementParams, UpdateMemberRoleParams, UpdateMembershipParams, UpdatePlanEntitlementParams, UpdatePlanParams, UpdatePricingGroupParams, UpdateSalesChannelParams, UpdateWebhookSubscriptionParams, WEBHOOK_EVENT_CODES, WebhookDelivery, type WebhookEventCode, WebhookSignatureVerificationError, WebhookSubscription, type components, constructEvent, type operations, type paths, verifyWebhookSignature };
+//#region src/core/pagination.d.ts
+/**
+ * Streams every item across all pages of a paginated `list*` method, fetching
+ * the next page lazily as you iterate:
+ *
+ * ```ts
+ * for await (const membership of paginate((page) => ophelio.memberships.list(page))) {
+ *   // …
+ * }
+ *
+ * // nested + filtered + abortable:
+ * for await (const change of paginate((page) =>
+ *   ophelio.memberships.listScheduledChanges(id, { ...page, status: 'all' }, { signal }))) {
+ *   // …
+ * }
+ * ```
+ *
+ * Because this walks offset pages, a row may be seen twice or skipped across a
+ * page boundary if the collection is written to concurrently.
+ */
+declare function paginate<T>(fetchPage: (params: PageParams) => Promise<Page<T>>, params?: PageParams): AsyncGenerator<T>;
+/**
+ * Drains every page into a single array — the "give me everything" shortcut
+ * over `paginate`. Loads the whole collection into memory, so prefer
+ * `paginate` for large or unbounded lists.
+ *
+ * ```ts
+ * const customers = await collect((page) => ophelio.customers.list(page))
+ * ```
+ */
+declare function collect<T>(fetchPage: (params: PageParams) => Promise<Page<T>>, params?: PageParams): Promise<T[]>;
+//#endregion
+export { AdmitResult, AlreadyExistsError, BillingOption, BillingOptionSalesChannel, CancelMembershipParams, CreateBillingOptionParams, CreateBillingOptionSalesChannelParams, CreateCustomerParams, CreateEntitlementParams, CreateMemberRoleParams, CreateMembershipParams, CreatePlanEntitlementParams, CreatePlanLinkParams, CreatePlanParams, CreatePlanPricingGroupMappingParams, CreatePricingGroupParams, CreateSalesChannelParams, CreateTransactionParams, CreateWebhookSubscriptionParams, Customer, DEFAULT_BASE_URL, Entitlement, EntitlementType, EntitlementUsage, type IdempotentRequestOptions, InternalError, InvalidArgumentError, Member, MemberEntitlement, MemberRole, MemberSyncResponse, Membership, MembershipTerm, NotFoundError, Ophelio, OphelioConnectionError, OphelioError, type OphelioOptions, OphelioTimeoutError, type OphelioWebhookEvent, Page, PageParams, PermissionDeniedError, Plan, PlanChangeParams, PlanChangeResult, PlanEntitlement, PlanLink, PlanLinkView, PlanPricingGroupMapping, PricingGroup, RecordUsageParams, RedeemEntitlementParams, RedeemEntitlementResponse, ReissueCardParams, RenewMembershipParams, type RequestOptions, ResourceExhaustedError, SalesChannel, ScheduledChange, SyncMember, Transaction, UnauthenticatedError, UnavailableError, UnimplementedError, UpdateBillingOptionParams, UpdateCustomerParams, UpdateEntitlementParams, UpdateMemberRoleParams, UpdateMembershipParams, UpdatePlanEntitlementParams, UpdatePlanParams, UpdatePricingGroupParams, UpdateSalesChannelParams, UpdateWebhookSubscriptionParams, WEBHOOK_EVENT_CODES, WebhookDelivery, type WebhookEventCode, WebhookSignatureVerificationError, WebhookSubscription, collect, type components, constructEvent, type operations, paginate, type paths, verifyWebhookSignature };