@ophelio/sdk 0.1.1 → 0.2.1

package/dist/index.mjs

@@ -116,6 +116,15 @@ function sleep(ms) {
 const DEFAULT_BASE_URL = "https://api.ophel.io";
 const DEFAULT_TIMEOUT_MS = 3e4;
 const DEFAULT_MAX_RETRIES = 2;
+/**
+* Resolves the caller-supplied idempotency key to the value sent on the wire.
+* Trims it and falls back to a generated key when it is absent, empty, or
+* whitespace-only — a blank key must never leave an idempotency-keyed mutation
+* retryable but unkeyed, or a retried write could duplicate.
+*/
+function resolveIdempotencyKey(idempotencyKey) {
+	return idempotencyKey?.trim() || crypto.randomUUID();
+}
 var Transport = class {
 	apiKey;
 	baseUrl;
@@ -215,6 +224,13 @@ var APIResource = class {
 		this.transport = transport;
 	}
 };
+function pageQuery(params) {
+	if (!params) return void 0;
+	const query = {};
+	if (params.page_size !== void 0) query.page_size = String(params.page_size);
+	if (params.page_token !== void 0) query.page_token = params.page_token;
+	return query;
+}
 //#endregion
 //#region src/resources/admit.ts
 var AdmitResource = class extends APIResource {
@@ -299,13 +315,19 @@ var BillingOptionsResource = class extends APIResource {
 //#endregion
 //#region src/resources/customers.ts
 var CustomersResource = class extends APIResource {
-	async list(options) {
-		return (await this.transport.request({
+	async list(params, options) {
+		const response = await this.transport.request({
 			method: "GET",
 			path: "/api/v1/customers",
+			query: pageQuery(params),
 			retryable: true,
 			options
-		})).customers;
+		});
+		return {
+			items: response.customers,
+			next_page_token: response.next_page_token,
+			total_size: response.total_size
+		};
 	}
 	get(id, options) {
 		return this.transport.request({
@@ -341,13 +363,19 @@ var CustomersResource = class extends APIResource {
 			options
 		});
 	}
-	async listMemberships(id, options) {
-		return (await this.transport.request({
+	async listMemberships(id, params, options) {
+		const response = await this.transport.request({
 			method: "GET",
 			path: `/api/v1/customers/${encodeURIComponent(id)}/memberships`,
+			query: pageQuery(params),
 			retryable: true,
 			options
-		})).memberships;
+		});
+		return {
+			items: response.memberships,
+			next_page_token: response.next_page_token,
+			total_size: response.total_size
+		};
 	}
 };
 //#endregion
@@ -364,7 +392,7 @@ var EntitlementsResource = class extends APIResource {
 			method: "POST",
 			path: "/api/v1/entitlements/redeem",
 			body: params,
-			idempotencyKey: idempotencyKey ?? crypto.randomUUID(),
+			idempotencyKey: resolveIdempotencyKey(idempotencyKey),
 			retryable: true,
 			options: requestOptions
 		});
@@ -379,7 +407,7 @@ var EntitlementsResource = class extends APIResource {
 			method: "POST",
 			path: "/api/v1/entitlements/usage",
 			body: params,
-			idempotencyKey: idempotencyKey ?? crypto.randomUUID(),
+			idempotencyKey: resolveIdempotencyKey(idempotencyKey),
 			retryable: true,
 			options: requestOptions
 		})).usage;
@@ -520,13 +548,19 @@ var MembersResource = class extends APIResource {
 //#endregion
 //#region src/resources/memberships.ts
 var MembershipsResource = class extends APIResource {
-	async list(options) {
-		return (await this.transport.request({
+	async list(params, options) {
+		const response = await this.transport.request({
 			method: "GET",
 			path: "/api/v1/memberships",
+			query: pageQuery(params),
 			retryable: true,
 			options
-		})).memberships;
+		});
+		return {
+			items: response.memberships,
+			next_page_token: response.next_page_token,
+			total_size: response.total_size
+		};
 	}
 	get(id, options) {
 		return this.transport.request({
@@ -536,13 +570,22 @@ var MembershipsResource = class extends APIResource {
 			options
 		});
 	}
-	create(params, options) {
+	/**
+	* 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, options = {}) {
+		const { idempotencyKey, ...requestOptions } = options;
 		return this.transport.request({
 			method: "POST",
 			path: "/api/v1/memberships",
 			body: params,
-			retryable: false,
-			options
+			idempotencyKey: resolveIdempotencyKey(idempotencyKey),
+			retryable: true,
+			options: requestOptions
 		});
 	}
 	update(id, params, options) {
@@ -572,25 +615,36 @@ var MembershipsResource = class extends APIResource {
 			options
 		});
 	}
-	async listTransactions(id, options) {
-		return (await this.transport.request({
+	async listTransactions(id, params, options) {
+		const response = await this.transport.request({
 			method: "GET",
 			path: `/api/v1/memberships/${encodeURIComponent(id)}/transactions`,
+			query: pageQuery(params),
 			retryable: true,
 			options
-		})).transactions;
+		});
+		return {
+			items: response.transactions,
+			next_page_token: response.next_page_token,
+			total_size: response.total_size
+		};
 	}
 	/**
 	* 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, params, options) {
+	createTransaction(id, params, options = {}) {
+		const { idempotencyKey, ...requestOptions } = options;
 		return this.transport.request({
 			method: "POST",
 			path: `/api/v1/memberships/${encodeURIComponent(id)}/transactions`,
 			body: params,
-			retryable: false,
-			options
+			idempotencyKey: resolveIdempotencyKey(idempotencyKey),
+			retryable: true,
+			options: requestOptions
 		});
 	}
 	async listMembers(id, options) {
@@ -601,14 +655,21 @@ var MembershipsResource = class extends APIResource {
 			options
 		})).members;
 	}
-	/** Open the next term. Rejected (409) while cancelled or cancellation-pending. */
-	renew(id, params, options) {
+	/**
+	* 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, params, options = {}) {
+		const { idempotencyKey, ...requestOptions } = options;
 		return this.transport.request({
 			method: "POST",
 			path: `/api/v1/memberships/${encodeURIComponent(id)}/renew`,
 			body: params,
-			retryable: false,
-			options
+			idempotencyKey: resolveIdempotencyKey(idempotencyKey),
+			retryable: true,
+			options: requestOptions
 		});
 	}
 	/**
@@ -635,13 +696,21 @@ var MembershipsResource = class extends APIResource {
 		});
 	}
 	async listScheduledChanges(id, params, options) {
-		return (await this.transport.request({
+		const response = await this.transport.request({
 			method: "GET",
 			path: `/api/v1/memberships/${encodeURIComponent(id)}/scheduled-changes`,
-			query: params?.status ? { status: params.status } : void 0,
+			query: {
+				...pageQuery(params),
+				...params?.status ? { status: params.status } : {}
+			},
 			retryable: true,
 			options
-		})).scheduled_changes;
+		});
+		return {
+			items: response.scheduled_changes,
+			next_page_token: response.next_page_token,
+			total_size: response.total_size
+		};
 	}
 	async cancelScheduledChange(id, changeId, options) {
 		await this.transport.request({
@@ -651,13 +720,19 @@ var MembershipsResource = class extends APIResource {
 			options
 		});
 	}
-	async listTermTransactions(id, termId, options) {
-		return (await this.transport.request({
+	async listTermTransactions(id, termId, params, options) {
+		const response = await this.transport.request({
 			method: "GET",
 			path: `/api/v1/memberships/${encodeURIComponent(id)}/terms/${encodeURIComponent(termId)}/transactions`,
+			query: pageQuery(params),
 			retryable: true,
 			options
-		})).transactions;
+		});
+		return {
+			items: response.transactions,
+			next_page_token: response.next_page_token,
+			total_size: response.total_size
+		};
 	}
 };
 //#endregion
@@ -941,13 +1016,19 @@ var WebhookSubscriptionsResource = class extends APIResource {
 			options
 		});
 	}
-	async listDeliveries(id, options) {
-		return (await this.transport.request({
+	async listDeliveries(id, params, options) {
+		const response = await this.transport.request({
 			method: "GET",
 			path: `/api/v1/webhook-subscriptions/${encodeURIComponent(id)}/deliveries`,
+			query: pageQuery(params),
 			retryable: true,
 			options
-		})).webhook_deliveries;
+		});
+		return {
+			items: response.webhook_deliveries,
+			next_page_token: response.next_page_token,
+			total_size: response.total_size
+		};
 	}
 	/** The HMAC signing secret is only returned on creation — store it then. */
 	create(params, options) {
@@ -1071,6 +1152,52 @@ var Ophelio = class Ophelio {
 		this.webhookSubscriptions = new WebhookSubscriptionsResource(transport);
 	}
 };
+//#endregion
+//#region src/core/pagination.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.
+*/
+async function* paginate(fetchPage, params = {}) {
+	let pageToken = params.page_token;
+	do {
+		const page = await fetchPage({
+			...params,
+			page_token: pageToken
+		});
+		yield* page.items;
+		pageToken = page.next_page_token || void 0;
+	} while (pageToken);
+}
+/**
+* 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))
+* ```
+*/
+async function collect(fetchPage, params = {}) {
+	const items = [];
+	for await (const item of paginate(fetchPage, params)) items.push(item);
+	return items;
+}
 /**
 * Canonical webhook event codes for the Ophel.io platform.
 *
@@ -1095,4 +1222,4 @@ const WEBHOOK_EVENT_CODES = [
 	"plan.updated"
 ];
 //#endregion
-export { AlreadyExistsError, DEFAULT_BASE_URL, InternalError, InvalidArgumentError, NotFoundError, Ophelio, OphelioConnectionError, OphelioError, OphelioTimeoutError, PermissionDeniedError, ResourceExhaustedError, UnauthenticatedError, UnavailableError, UnimplementedError, WEBHOOK_EVENT_CODES, WebhookSignatureVerificationError, constructEvent, verifyWebhookSignature };
+export { AlreadyExistsError, DEFAULT_BASE_URL, InternalError, InvalidArgumentError, NotFoundError, Ophelio, OphelioConnectionError, OphelioError, OphelioTimeoutError, PermissionDeniedError, ResourceExhaustedError, UnauthenticatedError, UnavailableError, UnimplementedError, WEBHOOK_EVENT_CODES, WebhookSignatureVerificationError, collect, constructEvent, paginate, verifyWebhookSignature };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ophelio/sdk",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Official JavaScript / TypeScript SDK for the Ophel.io membership & entitlement API.",
   "license": "MIT",
   "author": "Ophel.io",
@@ -37,11 +37,14 @@
     "pretest": "npm run generate:types",
     "test": "vitest run",
     "pretypecheck": "npm run generate:types",
-    "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.test.json"
+    "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.test.json",
+    "check:package": "npm run build && publint --strict && attw --pack"
   },
   "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.0",
     "@types/node": "^25.6.0",
     "ophelio-utils": "*",
+    "publint": "^0.3.21",
     "tsdown": "^0.22.0",
     "typescript": "^6.0.3",
     "vitest": "^4.0.18"