@ophelio/sdk 0.2.0 → 0.2.1

package/README.md

@@ -66,10 +66,12 @@ GETs are retried automatically on network errors / 429 / 502 / 503 / 504
 (exponential backoff with jitter, `Retry-After` honoured; configure with
 `maxRetries`, default 2). Plain mutations are **never** retried.
 
-`entitlements.redeem` and `entitlements.recordUsage` are idempotency-keyed:
-the SDK generates a key per call and reuses it across its own retries, so
-they're safely retryable. If you retry at the application level (offline
-gate queues), pass your own key:
+The idempotency-keyed mutations — `memberships.create`, `memberships.renew`,
+`memberships.createTransaction`, `entitlements.redeem`, and
+`entitlements.recordUsage` — each generate a key per call and reuse it across
+the SDK's own retries, so they're safely retried on transient failures. If you
+retry at the application level (offline gate queues, at-least-once job runners),
+pass your own key so replays are recognised across processes:
 
 ```ts
 await ophelio.entitlements.redeem(
@@ -170,7 +172,8 @@ Everything reachable with an API key is covered:
 | `webhookSubscriptions`       | `list()`, `get(id)`, `create(...)`, `update(id, ...)`, `delete(id)`, `listDeliveries(id, params?)`                                                                                                                                                                                                                                                                     |
 
 Every method accepts a trailing `options` argument: `{ signal?, headers? }`
-(plus `idempotencyKey?` on `redeem` / `recordUsage`).
+(plus `idempotencyKey?` on the idempotency-keyed mutations: `memberships.create`
+/ `renew` / `createTransaction` and `entitlements.redeem` / `recordUsage`).
 
 Endpoints requiring a user session (API key management, organisation and
 project admin) are intentionally not in the SDK — API keys cannot call them.

package/dist/index.cjs

@@ -117,6 +117,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;
@@ -384,7 +393,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
 		});
@@ -399,7 +408,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;
@@ -562,13 +571,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) {
@@ -615,14 +633,19 @@ var MembershipsResource = class extends APIResource {
 	/**
 	* 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) {
@@ -633,14 +656,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
 		});
 	}
 	/**

package/dist/index.d.cts

@@ -2916,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;
@@ -2952,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;
@@ -3654,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;
     };
@@ -3680,6 +3688,14 @@ interface operations {
           "application/json": components["schemas"]["ErrorResponse"];
         };
       };
+      409: {
+        headers: {
+          [name: string]: unknown;
+        };
+        content: {
+          "application/json": components["schemas"]["ErrorResponse"];
+        };
+      };
     };
   };
   MembershipsController_get: {
@@ -3828,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;
     };
@@ -3854,6 +3872,14 @@ interface operations {
           "application/json": components["schemas"]["ErrorResponse"];
         };
       };
+      409: {
+        headers: {
+          [name: string]: unknown;
+        };
+        content: {
+          "application/json": components["schemas"]["ErrorResponse"];
+        };
+      };
     };
   };
   MembershipsController_upgrade: {
@@ -3999,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;
     };
@@ -4025,6 +4053,14 @@ interface operations {
           "application/json": components["schemas"]["ErrorResponse"];
         };
       };
+      409: {
+        headers: {
+          [name: string]: unknown;
+        };
+        content: {
+          "application/json": components["schemas"]["ErrorResponse"];
+        };
+      };
     };
   };
   MembershipsController_listTermTransactions: {
@@ -4523,7 +4559,14 @@ declare class MembersResource extends APIResource {
 declare class MembershipsResource extends APIResource {
   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>;
@@ -4532,11 +4575,19 @@ declare class MembershipsResource extends APIResource {
   /**
    * 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.

package/dist/index.d.mts

@@ -2916,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;
@@ -2952,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;
@@ -3654,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;
     };
@@ -3680,6 +3688,14 @@ interface operations {
           "application/json": components["schemas"]["ErrorResponse"];
         };
       };
+      409: {
+        headers: {
+          [name: string]: unknown;
+        };
+        content: {
+          "application/json": components["schemas"]["ErrorResponse"];
+        };
+      };
     };
   };
   MembershipsController_get: {
@@ -3828,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;
     };
@@ -3854,6 +3872,14 @@ interface operations {
           "application/json": components["schemas"]["ErrorResponse"];
         };
       };
+      409: {
+        headers: {
+          [name: string]: unknown;
+        };
+        content: {
+          "application/json": components["schemas"]["ErrorResponse"];
+        };
+      };
     };
   };
   MembershipsController_upgrade: {
@@ -3999,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;
     };
@@ -4025,6 +4053,14 @@ interface operations {
           "application/json": components["schemas"]["ErrorResponse"];
         };
       };
+      409: {
+        headers: {
+          [name: string]: unknown;
+        };
+        content: {
+          "application/json": components["schemas"]["ErrorResponse"];
+        };
+      };
     };
   };
   MembershipsController_listTermTransactions: {
@@ -4523,7 +4559,14 @@ declare class MembersResource extends APIResource {
 declare class MembershipsResource extends APIResource {
   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>;
@@ -4532,11 +4575,19 @@ declare class MembershipsResource extends APIResource {
   /**
    * 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.

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;
@@ -383,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
 		});
@@ -398,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;
@@ -561,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) {
@@ -614,14 +632,19 @@ var MembershipsResource = class extends APIResource {
 	/**
 	* 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) {
@@ -632,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
 		});
 	}
 	/**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ophelio/sdk",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Official JavaScript / TypeScript SDK for the Ophel.io membership & entitlement API.",
   "license": "MIT",
   "author": "Ophel.io",