@chargezen/sdk 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,33 @@
-# Temporary Holding Version
+# Chargezen Node.js SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Typed access to the Chargezen API (`https://api.chargezen.com/v1`) from your backend: customers,
+subscriptions, products, plans and email. Keys are secret; never use them in a browser.
+
+```ts
+import { randomUUID } from "node:crypto";
+import { createChargezen } from "@chargezen/sdk";
+
+const chargezen = createChargezen({ keyId: process.env.CHARGEZEN_KEY_ID!, secret: process.env.CHARGEZEN_SECRET! });
+
+const { data } = await chargezen.GET("/customers", { params: { query: { query: "ada@example.com" } } });
+const customerId = data!.customers[0].customer_ref.id;
+
+// Every change takes an Idempotency-Key. Keep it: sending the same key again retries safely.
+await chargezen.POST("/customers/{customer_id}/subscriptions/{id}/pause", {
+  params: { path: { customer_id: customerId, id: "123" }, header: { "Idempotency-Key": randomUUID() } },
+  body: { resume_on: "2027-01-12" },
+});
+```
+
+Errors come back as `error` with `{ error: { code, message, failure } }`; `failure: "temporary"` means a
+retry with the same Idempotency-Key can succeed.
+
+`orderNow` repeats Order now while the charge is still processing, and `waitForSubscriptionCreation`
+follows a new subscription until it is ready.
+
+## Development
+
+`src/schema.ts` is generated from the API contract, `Chargezen/public_api/openapi.yaml`
+(`npm run generate` with the Chargezen repo checked out beside this one). Don't edit it by hand.
+The journey test runs against a real Chargezen API on Factory:
+`../scripts/cz-test playwright --config playwright.journey.config.js`.

package/dist/index.d.ts

@@ -0,0 +1,151 @@
+import type { components, paths } from "./schema.js";
+export type { components, paths };
+export interface ChargezenOptions {
+    /** The key id shown in Settings > API keys (ekid_...). */
+    keyId: string;
+    /** The key's secret (esk_...), shown once when the key is created. Never use it in a browser. */
+    secret: string;
+    baseUrl?: string;
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * A typed client for every path in the Chargezen API, for example
+ * `chargezen.GET("/customers", { params: { query: { query: "ada@example.com" } } })`.
+ * Every POST takes an Idempotency-Key header: make one per change (crypto.randomUUID()) and send the
+ * same key again to retry that change safely.
+ */
+export declare function createChargezen({ keyId, secret, baseUrl, fetch }: ChargezenOptions): import("openapi-fetch").Client<paths, `${string}/${string}`>;
+export type Chargezen = ReturnType<typeof createChargezen>;
+/** How long to keep asking, and how often. */
+export interface Polling {
+    intervalMs: number;
+    timeoutMs: number;
+}
+type OrderNowBody = paths["/customers/{customer_id}/subscriptions/{id}/order_now"]["post"]["requestBody"]["content"]["application/json"];
+/**
+ * Places the subscription's next coming order now. While the charge is still settling the API answers
+ * 202 "processing"; this repeats the request with the same Idempotency-Key, which never charges twice,
+ * until the order is placed or needs the customer's payment approval, or `polling.timeoutMs` passes
+ * (then it returns the last "processing" answer: call again with the same key to keep waiting).
+ */
+export declare function orderNow(chargezen: Chargezen, request: {
+    customerId: string;
+    subscriptionId: string;
+    billingOccurrence: OrderNowBody["billing_occurrence"];
+    idempotencyKey: string;
+}, polling: Polling): Promise<import("openapi-fetch").FetchResponse<{
+    parameters: {
+        query?: never;
+        header: {
+            "Idempotency-Key": components["parameters"]["IdempotencyKey"];
+        };
+        path: {
+            customer_id: string;
+            id: string;
+        };
+        cookie?: never;
+    };
+    requestBody: {
+        content: {
+            "application/json": {
+                billing_occurrence: {
+                    cycle_index: number;
+                    scheduled_at: string;
+                };
+            };
+        };
+    };
+    responses: {
+        200: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": {
+                    status: "placed";
+                    next_charge_at: string | null;
+                } | {
+                    status: "needs_payment_approval";
+                    payment_approval_url: string;
+                };
+            };
+        };
+        202: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": {
+                    status: "processing";
+                };
+            };
+        };
+        401: components["responses"]["Error"];
+        403: components["responses"]["Error"];
+        404: components["responses"]["Error"];
+        409: components["responses"]["Error"];
+        422: components["responses"]["Error"];
+        503: components["responses"]["Error"];
+    };
+}, {
+    params: {
+        path: {
+            customer_id: string;
+            id: string;
+        };
+        header: {
+            "Idempotency-Key": string;
+        };
+    };
+    body: {
+        billing_occurrence: {
+            cycle_index: number;
+            scheduled_at: string;
+        };
+    };
+}, `${string}/${string}`>>;
+/**
+ * Follows a subscription creation (the `id` POST /customers/{customer_id}/subscriptions returned) until
+ * it is "ready", or `polling.timeoutMs` passes (then it returns the last "pending" answer).
+ */
+export declare function waitForSubscriptionCreation(chargezen: Chargezen, creationId: string, polling: Polling): Promise<import("openapi-fetch").FetchResponse<{
+    parameters: {
+        query?: never;
+        header?: never;
+        path: {
+            id: string;
+        };
+        cookie?: never;
+    };
+    requestBody?: never;
+    responses: {
+        200: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": {
+                    status: "pending" | "ready";
+                    subscription_contract_id: string;
+                    subscription_ref: {
+                        type: "customer_subscription_contract";
+                        id: string;
+                    } | null;
+                    observed_at: string;
+                };
+            };
+        };
+        401: components["responses"]["Error"];
+        403: components["responses"]["Error"];
+        404: components["responses"]["Error"];
+        409: components["responses"]["Error"];
+        422: components["responses"]["Error"];
+        503: components["responses"]["Error"];
+    };
+}, {
+    params: {
+        path: {
+            id: string;
+        };
+    };
+}, `${string}/${string}`>>;

package/dist/index.js

@@ -0,0 +1,51 @@
+import createClient from "openapi-fetch";
+/**
+ * A typed client for every path in the Chargezen API, for example
+ * `chargezen.GET("/customers", { params: { query: { query: "ada@example.com" } } })`.
+ * Every POST takes an Idempotency-Key header: make one per change (crypto.randomUUID()) and send the
+ * same key again to retry that change safely.
+ */
+export function createChargezen({ keyId, secret, baseUrl = "https://api.chargezen.com/v1", fetch }) {
+    return createClient({
+        baseUrl,
+        fetch,
+        headers: { "X-Chargezen-Key-Id": keyId, Authorization: `Bearer ${secret}` },
+    });
+}
+/**
+ * Places the subscription's next coming order now. While the charge is still settling the API answers
+ * 202 "processing"; this repeats the request with the same Idempotency-Key, which never charges twice,
+ * until the order is placed or needs the customer's payment approval, or `polling.timeoutMs` passes
+ * (then it returns the last "processing" answer: call again with the same key to keep waiting).
+ */
+export async function orderNow(chargezen, request, polling) {
+    const deadline = Date.now() + polling.timeoutMs;
+    for (;;) {
+        const result = await chargezen.POST("/customers/{customer_id}/subscriptions/{id}/order_now", {
+            params: {
+                path: { customer_id: request.customerId, id: request.subscriptionId },
+                header: { "Idempotency-Key": request.idempotencyKey },
+            },
+            body: { billing_occurrence: request.billingOccurrence },
+        });
+        if (result.response.status !== 202 || Date.now() + polling.intervalMs > deadline)
+            return result;
+        await sleep(polling.intervalMs);
+    }
+}
+/**
+ * Follows a subscription creation (the `id` POST /customers/{customer_id}/subscriptions returned) until
+ * it is "ready", or `polling.timeoutMs` passes (then it returns the last "pending" answer).
+ */
+export async function waitForSubscriptionCreation(chargezen, creationId, polling) {
+    const deadline = Date.now() + polling.timeoutMs;
+    for (;;) {
+        const result = await chargezen.GET("/subscription_creations/{id}", { params: { path: { id: creationId } } });
+        if (result.data?.status !== "pending" || Date.now() + polling.intervalMs > deadline)
+            return result;
+        await sleep(polling.intervalMs);
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}