@meterly/sdk 0.1.0

package/README.md

@@ -0,0 +1,353 @@
+# Meterly JavaScript SDK
+
+Small TypeScript SDK for integrating Meterly prepaid usage control and credit workflows into Node.js and Next.js apps. `guard()` is the preferred path for protected operations that may fail after work starts. Credits are usage entitlement units, not money.
+
+## Requirements
+
+- Node.js 18 or newer
+- Meterly command API reachable, usually `http://localhost:5000`
+- Meterly query API reachable, usually `http://localhost:5001`
+
+The SDK uses native `fetch`. There are no runtime dependencies.
+
+## Quick Start
+
+```bash
+cd sdk/js
+npm install
+npm run build
+```
+
+```ts
+import { MeterlyClient } from "@meterly/sdk";
+
+const meterly = new MeterlyClient({
+  commandApiUrl: "http://localhost:5000",
+  queryApiUrl: "http://localhost:5001",
+  apiKey: "dev-meterly-key"
+});
+
+const grant = await meterly.grantCredits(
+  {
+    externalCustomerId: "customer_123",
+    creditAmount: 1000,
+    creditUnit: "image_credits",
+    reference: "order_123",
+    description: "1000 image credits purchase",
+    provider: "revenuecat",
+    providerEventId: "rc_evt_123"
+  },
+  {
+    idempotencyKey: "grant-order_123"
+  }
+);
+
+const balances = await meterly.getBalances(grant.grant.customerId);
+console.log(balances.balances);
+```
+
+## Direct Credit Grants
+
+Verify purchase state in your own backend, then grant credits directly when Meterly is the spend and balance source of truth:
+
+```ts
+await meterly.grantCredits(
+  {
+    externalCustomerId: "user_123",
+    creditAmount: 1000,
+    creditUnit: "image_credits",
+    reference: "order_123",
+    description: "1000 image credits purchase",
+    provider: "revenuecat",
+    providerEventId: "rc_evt_123",
+    providerEventType: "INITIAL_PURCHASE"
+  },
+  { idempotencyKey: "grant-order_123" }
+);
+```
+
+Meterly creates the customer/account if missing, stores optional provider proof metadata, and applies credits through the ledger-backed AddCredits path. Tenant API keys are server-side only; do not use them in browser or mobile clients.
+
+## Guard Helper
+
+`guard` wraps reservation, callback execution, commit, and release. The preferred form accepts a single options object:
+
+```ts
+const result = await meterly.guard(
+  {
+    customerId,
+    amount: 250,
+    unit: "image_credits",
+    idempotencyKey: "guard-image-generation-001",
+    reference: "image-generation",
+    description: "Reserve credits for expensive work",
+    ttlSeconds: 300
+  },
+  async ({ reservationId }) => {
+    const output = await doExpensiveWork();
+    return {
+      reservationId,
+      output
+    };
+  }
+);
+```
+
+The positional form remains supported for compatibility:
+
+```ts
+const result = await meterly.guard(
+  customerId,
+  250,
+  async ({ reservationId }) => {
+    const output = await doExpensiveWork();
+    return {
+      reservationId,
+      output
+    };
+  },
+  {
+    reference: "image-generation",
+    description: "Reserve credits for expensive work",
+    ttlSeconds: 300
+  }
+);
+```
+
+Behavior:
+
+- reserves credits first
+- commits the reservation if the callback succeeds
+- releases the reservation if the callback throws
+- rethrows the original callback error after a successful release
+- throws `MeterlyGuardError` if both the callback and the release fail
+
+## Idempotency
+
+Every command mutation can send an `idempotencyKey` option. The SDK forwards it as the `Idempotency-Key` header:
+
+```ts
+await meterly.grantCredits(
+  {
+    externalCustomerId: "customer_123",
+    creditAmount: 100,
+    reference: "support-adjustment-001"
+  },
+  { idempotencyKey: "grant-support-adjustment-001" }
+);
+```
+
+Use a stable key for retried operations so network retries and duplicate client submits do not apply credits twice.
+
+## Usage Units
+
+Usage units let one tenant use separate entitlement units, such as `credits`, `image_credits`, `tokens`, or `gpu_seconds`. The default unit is `credits`.
+
+```ts
+const units = await meterly.listUsageUnits();
+
+await meterly.createUsageUnit({
+  code: "gpu_seconds",
+  displayName: "GPU seconds",
+  description: "Runtime authorization unit for GPU jobs"
+});
+
+await meterly.guard(
+  {
+    customerId,
+    amount: 30,
+    unit: "gpu_seconds",
+    reference: "gpu-job-42",
+    idempotencyKey: "reserve-gpu-job-42"
+  },
+  async () => runGpuJob()
+);
+```
+
+Package and provider-mapping flows inherit the package unit. There is no cross-unit conversion; reserve, commit, release, and usage reads operate on the unit you provide.
+
+API keys also scope data access to a tenant. In local development, the default tenant comes from:
+
+- API key: `dev-meterly-key`
+- tenant: `dev-tenant`
+
+Meterly can also issue persistent keys from `POST /api/v1/api-keys` or the admin console. Generated keys start with `mly_test_`, are stored hashed at rest, and the raw key is shown only once when created. Use the generated raw key as `apiKey` in `MeterlyClient`.
+
+## HMAC Signing
+
+HMAC signing is optional and intended for production backend services that want replay protection beyond bearer-key authentication. Create a key with `signingMode: "hmac"`, store the raw key once on your server, and configure the SDK:
+
+```ts
+const meterly = new MeterlyClient({
+  commandApiUrl: process.env.METERLY_COMMAND_API_URL!,
+  queryApiUrl: process.env.METERLY_QUERY_API_URL!,
+  apiKey: process.env.METERLY_API_KEY!,
+  signingMode: "hmac"
+});
+```
+
+For HMAC keys, every request still sends `Authorization: Bearer <api_key>`. The SDK also sends:
+
+- `X-Meterly-Timestamp`
+- `X-Meterly-Body-SHA256`
+- `X-Meterly-Signature`
+
+Canonical string:
+
+```text
+METHOD
+PATH_WITH_QUERY
+BODY_SHA256
+TIMESTAMP
+```
+
+The HMAC secret is the raw API key, which Meterly shows only once and never stores in plaintext. Do not use tenant API keys or HMAC signing in browser or mobile clients.
+
+## Supported Methods
+
+```ts
+await meterly.createCustomer(input, options);
+await meterly.grantCredits(input, options);
+await meterly.listCreditGrants(options);
+await meterly.addCredits(customerId, amount, options);
+await meterly.useCredits(customerId, amount, options);
+await meterly.reserveCredits(customerId, amount, options);
+await meterly.commitReservation(reservationId);
+await meterly.releaseReservation(reservationId);
+await meterly.getBalance(customerId);
+await meterly.getBalances(customerId);
+await meterly.getUsage(customerId, options);
+await meterly.getLedgerEntries(customerId, options);
+await meterly.getUsageSummary();
+await meterly.listUsageUnits();
+await meterly.createUsageUnit(input);
+await meterly.guard({ customerId, amount, idempotencyKey }, callback);
+await meterly.guard(customerId, amount, callback, options);
+```
+
+`useCredits` is the direct/simple usage debit method. For AI/API work where execution can fail after authorization, prefer object-form `guard()` or the explicit `reserveCredits` -> `commitReservation` / `releaseReservation` flow.
+
+Request options:
+
+- `reference`
+- `description`
+- `metadata`
+- `ttlSeconds`
+- `idempotencyKey`
+- `unit` or `creditUnit`
+
+Current backend compatibility:
+
+- `reference` and `description` are sent to Meterly
+- `ttlSeconds` is translated into reservation `expiresAt`
+- `unit` and `creditUnit` are sent as `creditUnit` on credit-affecting writes
+- `idempotencyKey` is sent as the `Idempotency-Key` HTTP header on command mutations
+- `metadata` is typed for future backend support but is not sent today
+
+Retry behavior:
+
+- the first request for a given `Idempotency-Key` executes normally and stores the response
+- retries with the same key and the same request payload return the stored response
+- retries with the same key and a different request payload return `409 Conflict`
+- concurrent retries with the same key while the first request is still running return `409 Conflict`
+
+## Next.js API Route Example
+
+```ts
+import { NextRequest, NextResponse } from "next/server";
+import { MeterlyClient, MeterlyGuardError } from "@meterly/sdk";
+
+const meterly = new MeterlyClient({
+  commandApiUrl: process.env.METERLY_COMMAND_API_URL ?? "http://localhost:5000",
+  queryApiUrl: process.env.METERLY_QUERY_API_URL ?? "http://localhost:5001",
+  apiKey: process.env.METERLY_API_KEY
+});
+
+export async function POST(request: NextRequest) {
+  const body = await request.json();
+
+  try {
+    const result = await meterly.guard(
+      {
+        customerId: body.customerId,
+        amount: body.credits,
+        idempotencyKey: body.idempotencyKey,
+        reference: body.reference,
+        description: "Protected Meterly operation",
+        ttlSeconds: 300
+      },
+      async () => {
+        return await runProtectedWork(body);
+      }
+    );
+
+    return NextResponse.json({ ok: true, result });
+  } catch (error) {
+    if (error instanceof MeterlyGuardError) {
+      return NextResponse.json(
+        {
+          ok: false,
+          message: error.message,
+          reservationId: error.reservationId
+        },
+        { status: 500 }
+      );
+    }
+
+    return NextResponse.json(
+      {
+        ok: false,
+        message: error instanceof Error ? error.message : "Unknown error"
+      },
+      { status: 500 }
+    );
+  }
+}
+```
+
+## Local Demo Usage
+
+From the repository root:
+
+```bash
+docker compose up --build
+```
+
+You can exercise the SDK directly against the same local stack:
+
+```ts
+import { MeterlyClient } from "@meterly/sdk";
+
+const meterly = new MeterlyClient({
+  commandApiUrl: "http://localhost:5000",
+  queryApiUrl: "http://localhost:5001",
+  apiKey: "dev-meterly-key"
+});
+
+const granted = await meterly.grantCredits(
+  {
+    externalCustomerId: `demo_${Date.now()}`,
+    creditAmount: 1000,
+    reference: "local-demo"
+  },
+  { idempotencyKey: "grant-local-demo" }
+);
+
+await meterly.useCredits(granted.grant.customerId, 120, {
+  reference: "demo-usage"
+});
+
+// For protected work, prefer object-form meterly.guard(...) so failed work releases the hold.
+
+const usage = await meterly.getUsage(created.customerId);
+console.log(usage.usage);
+```
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm run build
+```

package/dist/client.d.ts

@@ -0,0 +1,54 @@
+import type { BaseResponse, BalancesResult, CheckoutSessionResult, CreateCheckoutSessionOptions, CreateCustomerInput, CreateCustomerResult, CreateUsageUnitInput, CreditGrantsListResult, CreditPackageGrantsListResult, CreditAccount, GrantCreditsInput, GrantCreditsResult, GrantCreditPackageInput, GrantCreditPackageResult, GuardCallback, GuardOptions, LedgerEntriesQueryOptions, ListCreditGrantsOptions, LedgerEntriesResult, ListCreditPackageGrantsOptions, ListStripePaymentsOptions, MeterlyClientConfig, MeterlyRequestOptions, PaymentProviderStatus, ReserveCreditsOptions, StripePaymentResult, StripePaymentsListResult, StripeReconcileResult, UsageQueryOptions, UsageResult, UsageUnitResult, UsageUnitsListResult, UsageSummary } from "./types";
+interface ApiEnvelope {
+    message?: string;
+}
+interface ReservationResponse extends ApiEnvelope {
+    reservationId?: string;
+}
+export declare class MeterlyClient {
+    private readonly commandApiUrl;
+    private readonly queryApiUrl;
+    private readonly apiKey?;
+    private readonly signingMode;
+    private readonly fetchImpl;
+    private readonly extraHeaders?;
+    constructor(config: MeterlyClientConfig);
+    createCustomer(input: CreateCustomerInput, options?: MeterlyRequestOptions): Promise<CreateCustomerResult>;
+    addCredits(customerId: string, amount: number, options?: MeterlyRequestOptions): Promise<BaseResponse>;
+    useCredits(customerId: string, amount: number, options?: MeterlyRequestOptions): Promise<BaseResponse>;
+    reserveCredits(customerId: string, amount: number, options?: ReserveCreditsOptions): Promise<Required<Pick<ReservationResponse, "reservationId">> & BaseResponse>;
+    commitReservation(reservationId: string, options?: MeterlyRequestOptions): Promise<BaseResponse>;
+    releaseReservation(reservationId: string, options?: MeterlyRequestOptions): Promise<BaseResponse>;
+    /** @deprecated Legacy checkout compatibility only; not part of the current RevenueCat-first product surface. */
+    createCheckoutSession(customerId: string, packageId: string, options?: CreateCheckoutSessionOptions): Promise<CheckoutSessionResult>;
+    grantCreditPackage(packageId: string, input: GrantCreditPackageInput, options?: Pick<MeterlyRequestOptions, "idempotencyKey">): Promise<GrantCreditPackageResult>;
+    grantCredits(input: GrantCreditsInput, options?: Pick<MeterlyRequestOptions, "idempotencyKey">): Promise<GrantCreditsResult>;
+    listCreditGrants(options?: ListCreditGrantsOptions): Promise<CreditGrantsListResult>;
+    listCreditPackageGrants(options?: ListCreditPackageGrantsOptions): Promise<CreditPackageGrantsListResult>;
+    /** @deprecated Legacy Stripe status compatibility only; current provider setup is RevenueCat-first. */
+    getPaymentProviderStatus(): Promise<PaymentProviderStatus>;
+    listUsageUnits(status?: string): Promise<UsageUnitsListResult>;
+    createUsageUnit(input: CreateUsageUnitInput): Promise<UsageUnitResult>;
+    /** @deprecated Legacy Stripe compatibility only. */
+    listStripePayments(options?: ListStripePaymentsOptions): Promise<StripePaymentsListResult>;
+    /** @deprecated Legacy Stripe compatibility only. */
+    getStripePayment(id: string): Promise<StripePaymentResult>;
+    /** @deprecated Legacy Stripe compatibility only. */
+    reconcileStripePayment(id: string): Promise<StripeReconcileResult>;
+    /** @deprecated Legacy Stripe compatibility only. */
+    repairStripePayment(id: string): Promise<StripePaymentResult>;
+    getBalance(customerId: string): Promise<CreditAccount | null>;
+    getBalances(customerId: string): Promise<BalancesResult>;
+    getUsage(customerId: string, options?: UsageQueryOptions): Promise<UsageResult>;
+    getLedgerEntries(customerId: string, options?: LedgerEntriesQueryOptions): Promise<LedgerEntriesResult>;
+    getUsageSummary(): Promise<UsageSummary | null>;
+    guard<TResult>(customerId: string, amount: number, callback: GuardCallback<TResult>, options?: ReserveCreditsOptions): Promise<TResult>;
+    guard<TResult>(options: GuardOptions, callback: GuardCallback<TResult>): Promise<TResult>;
+    private normalizeGuardArgs;
+    private request;
+    private requestNullable;
+    private buildHeaders;
+    private buildMutationHeaders;
+    private parseResponse;
+}
+export {};

package/dist/client.js

@@ -0,0 +1,439 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MeterlyClient = void 0;
+const node_crypto_1 = require("node:crypto");
+const errors_1 = require("./errors");
+function normalizeBaseUrl(value, name) {
+    const trimmed = value.trim().replace(/\/+$/, "");
+    if (!trimmed) {
+        throw new Error(`${name} is required`);
+    }
+    return trimmed;
+}
+function assertIntegerAmount(amount) {
+    if (!Number.isInteger(amount) || amount <= 0) {
+        throw new TypeError("Meterly credit amounts must be positive integers.");
+    }
+}
+function assertTtlSeconds(ttlSeconds) {
+    if (!Number.isInteger(ttlSeconds) || ttlSeconds <= 0) {
+        throw new TypeError("ttlSeconds must be a positive integer.");
+    }
+}
+function buildQuery(baseUrl, params) {
+    const url = new URL(baseUrl);
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined && value !== "") {
+            url.searchParams.set(key, String(value));
+        }
+    }
+    return url.toString();
+}
+function toExpiresAt(ttlSeconds) {
+    if (ttlSeconds === undefined) {
+        return undefined;
+    }
+    assertTtlSeconds(ttlSeconds);
+    return new Date(Date.now() + ttlSeconds * 1000).toISOString();
+}
+function buildMutationPayload(amount, options) {
+    assertIntegerAmount(amount);
+    const creditUnit = options?.creditUnit ?? options?.unit;
+    return {
+        amount,
+        ...(creditUnit ? { creditUnit } : {}),
+        ...(options?.reference ? { reference: options.reference } : {}),
+        ...(options?.description ? { description: options.description } : {})
+    };
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null;
+}
+function extractMessage(value, fallback) {
+    if (isObject(value) && typeof value.message === "string" && value.message.trim()) {
+        return value.message;
+    }
+    return fallback;
+}
+function createApiError(method, url, status, responseBody, statusText) {
+    const message = extractMessage(responseBody, statusText || `HTTP ${status}`);
+    const details = { status, method, url, responseBody };
+    if (status === 409 &&
+        typeof message === "string" &&
+        message.toLowerCase().includes("insufficient credits")) {
+        return new errors_1.MeterlyInsufficientCreditsError(message, details);
+    }
+    return new errors_1.MeterlyApiError(message, details);
+}
+function normalizeSigningMode(value) {
+    if (value === undefined || value === "bearer") {
+        return "bearer";
+    }
+    if (value === "hmac") {
+        return "hmac";
+    }
+    throw new Error("signingMode must be \"bearer\" or \"hmac\".");
+}
+function bodyToString(body) {
+    if (body === undefined || body === null) {
+        return "";
+    }
+    if (typeof body === "string") {
+        return body;
+    }
+    if (body instanceof URLSearchParams) {
+        return body.toString();
+    }
+    throw new Error("Meterly HMAC signing supports string request bodies.");
+}
+function sha256Hex(value) {
+    return (0, node_crypto_1.createHash)("sha256").update(value).digest("hex");
+}
+function pathWithQuery(url) {
+    const parsed = new URL(url);
+    return `${parsed.pathname || "/"}${parsed.search}`;
+}
+class MeterlyClient {
+    commandApiUrl;
+    queryApiUrl;
+    apiKey;
+    signingMode;
+    fetchImpl;
+    extraHeaders;
+    constructor(config) {
+        this.commandApiUrl = normalizeBaseUrl(config.commandApiUrl, "commandApiUrl");
+        this.queryApiUrl = normalizeBaseUrl(config.queryApiUrl, "queryApiUrl");
+        this.apiKey = config.apiKey;
+        this.signingMode = normalizeSigningMode(config.signingMode);
+        this.fetchImpl = config.fetch ?? globalThis.fetch;
+        this.extraHeaders = config.headers;
+        if (!this.fetchImpl) {
+            throw new Error("Fetch is required. Use Node.js 18+ or provide a fetch implementation.");
+        }
+    }
+    async createCustomer(input, options) {
+        return this.request("POST", `${this.commandApiUrl}/api/v1/customers`, {
+            body: JSON.stringify({
+                customerExternalId: input.customerExternalId,
+                ...(input.creditUnit ? { creditUnit: input.creditUnit } : {})
+            }),
+            headers: this.buildMutationHeaders(options)
+        });
+    }
+    async addCredits(customerId, amount, options) {
+        return this.request("POST", `${this.commandApiUrl}/api/v1/customers/${encodeURIComponent(customerId)}/credits/add`, {
+            body: JSON.stringify(buildMutationPayload(amount, options)),
+            headers: this.buildMutationHeaders(options)
+        });
+    }
+    async useCredits(customerId, amount, options) {
+        return this.request("POST", `${this.commandApiUrl}/api/v1/customers/${encodeURIComponent(customerId)}/credits/use`, {
+            body: JSON.stringify(buildMutationPayload(amount, options)),
+            headers: this.buildMutationHeaders(options)
+        });
+    }
+    async reserveCredits(customerId, amount, options) {
+        const response = await this.request("POST", `${this.commandApiUrl}/api/v1/customers/${encodeURIComponent(customerId)}/credits/reserve`, {
+            body: JSON.stringify({
+                ...buildMutationPayload(amount, options),
+                ...(options?.reservationId ? { reservationId: options.reservationId } : {}),
+                ...(options?.ttlSeconds !== undefined
+                    ? { expiresAt: toExpiresAt(options.ttlSeconds) }
+                    : {})
+            }),
+            headers: this.buildMutationHeaders(options)
+        });
+        if (!response.reservationId) {
+            throw new errors_1.MeterlyApiError("Meterly reserveCredits response did not include reservationId.", {
+                status: 502,
+                method: "POST",
+                url: `${this.commandApiUrl}/api/v1/customers/${encodeURIComponent(customerId)}/credits/reserve`,
+                responseBody: response
+            });
+        }
+        return {
+            message: extractMessage(response, "Credits reserved."),
+            reservationId: response.reservationId
+        };
+    }
+    async commitReservation(reservationId, options) {
+        return this.request("POST", `${this.commandApiUrl}/api/v1/reservations/${encodeURIComponent(reservationId)}/commit`, { headers: this.buildMutationHeaders(options) });
+    }
+    async releaseReservation(reservationId, options) {
+        return this.request("POST", `${this.commandApiUrl}/api/v1/reservations/${encodeURIComponent(reservationId)}/release`, { headers: this.buildMutationHeaders(options) });
+    }
+    /** @deprecated Legacy checkout compatibility only; not part of the current RevenueCat-first product surface. */
+    async createCheckoutSession(customerId, packageId, options) {
+        const response = await this.request("POST", `${this.commandApiUrl}/api/v1/customers/${encodeURIComponent(customerId)}/checkout/sessions`, {
+            body: JSON.stringify({
+                packageId,
+                ...(options?.reference ? { reference: options.reference } : {})
+            }),
+            headers: this.buildMutationHeaders(options)
+        });
+        if (!response.checkoutUrl || !response.sessionId) {
+            throw new errors_1.MeterlyApiError("Meterly checkout session response missing checkoutUrl/sessionId.", {
+                status: 502,
+                method: "POST",
+                url: `${this.commandApiUrl}/api/v1/customers/${encodeURIComponent(customerId)}/checkout/sessions`,
+                responseBody: response
+            });
+        }
+        return {
+            message: extractMessage(response, "Checkout session created."),
+            checkoutUrl: response.checkoutUrl,
+            sessionId: response.sessionId
+        };
+    }
+    async grantCreditPackage(packageId, input, options) {
+        return this.request("POST", `${this.commandApiUrl}/api/v1/credit-packages/${encodeURIComponent(packageId)}/grants`, {
+            body: JSON.stringify(input),
+            headers: this.buildMutationHeaders(options)
+        });
+    }
+    async grantCredits(input, options) {
+        assertIntegerAmount(input.creditAmount);
+        return this.request("POST", `${this.commandApiUrl}/api/v1/credit-grants`, {
+            body: JSON.stringify(input),
+            headers: this.buildMutationHeaders(options)
+        });
+    }
+    async listCreditGrants(options = {}) {
+        return this.request("GET", buildQuery(`${this.commandApiUrl}/api/v1/credit-grants`, {
+            customerId: options.customerId,
+            externalCustomerId: options.externalCustomerId,
+            provider: options.provider,
+            providerPaymentId: options.providerPaymentId,
+            providerEventId: options.providerEventId
+        }));
+    }
+    async listCreditPackageGrants(options = {}) {
+        return this.request("GET", buildQuery(`${this.commandApiUrl}/api/v1/credit-package-grants`, {
+            customerId: options.customerId,
+            externalCustomerId: options.externalCustomerId,
+            packageId: options.packageId,
+            provider: options.provider,
+            providerPaymentId: options.providerPaymentId,
+            providerEventId: options.providerEventId
+        }));
+    }
+    /** @deprecated Legacy Stripe status compatibility only; current provider setup is RevenueCat-first. */
+    async getPaymentProviderStatus() {
+        return this.request("GET", `${this.commandApiUrl}/api/v1/payment-provider/status`);
+    }
+    async listUsageUnits(status) {
+        return this.request("GET", buildQuery(`${this.commandApiUrl}/api/v1/usage-units`, { status }));
+    }
+    async createUsageUnit(input) {
+        return this.request("POST", `${this.commandApiUrl}/api/v1/usage-units`, {
+            body: JSON.stringify(input),
+            headers: this.buildMutationHeaders()
+        });
+    }
+    /** @deprecated Legacy Stripe compatibility only. */
+    async listStripePayments(options = {}) {
+        return this.request("GET", buildQuery(`${this.commandApiUrl}/api/v1/payments/stripe`, {
+            status: options.status,
+            page: options.page,
+            pageSize: options.pageSize
+        }));
+    }
+    /** @deprecated Legacy Stripe compatibility only. */
+    async getStripePayment(id) {
+        return this.request("GET", `${this.commandApiUrl}/api/v1/payments/stripe/${encodeURIComponent(id)}`);
+    }
+    /** @deprecated Legacy Stripe compatibility only. */
+    async reconcileStripePayment(id) {
+        return this.request("POST", `${this.commandApiUrl}/api/v1/payments/stripe/${encodeURIComponent(id)}/reconcile`);
+    }
+    /** @deprecated Legacy Stripe compatibility only. */
+    async repairStripePayment(id) {
+        return this.request("POST", `${this.commandApiUrl}/api/v1/payments/stripe/${encodeURIComponent(id)}/repair`);
+    }
+    async getBalance(customerId) {
+        const response = await this.requestNullable("GET", `${this.queryApiUrl}/api/v1/customers/${encodeURIComponent(customerId)}/balance`);
+        return response?.account ?? null;
+    }
+    async getBalances(customerId) {
+        const response = await this.requestNullable("GET", `${this.queryApiUrl}/api/v1/customers/${encodeURIComponent(customerId)}/balances`);
+        return {
+            message: response?.message ?? "No balances found.",
+            customerId,
+            balances: response?.balances ?? []
+        };
+    }
+    async getUsage(customerId, options = {}) {
+        const response = await this.requestNullable("GET", buildQuery(`${this.queryApiUrl}/api/v1/customers/${encodeURIComponent(customerId)}/usage`, {
+            page: options.page,
+            pageSize: options.pageSize,
+            sortOrder: options.sortOrder,
+            type: options.type,
+            unit: options.unit,
+            search: options.search,
+            startAt: options.startAt,
+            endAt: options.endAt
+        }));
+        return {
+            message: response?.message ?? "No usage events found.",
+            usage: response?.usage ?? [],
+            pagination: response?.pagination
+        };
+    }
+    async getLedgerEntries(customerId, options = {}) {
+        const response = await this.requestNullable("GET", buildQuery(`${this.queryApiUrl}/api/v1/customers/${encodeURIComponent(customerId)}/ledger-entries`, {
+            page: options.page,
+            pageSize: options.pageSize,
+            sortOrder: options.sortOrder
+        }));
+        return {
+            message: response?.message ?? "No ledger entries found.",
+            ledgerEntries: response?.ledgerEntries ?? [],
+            pagination: response?.pagination
+        };
+    }
+    async getUsageSummary() {
+        const response = await this.requestNullable("GET", `${this.queryApiUrl}/api/v1/usage/summary`);
+        return response?.summary ?? null;
+    }
+    async guard(customerIdOrOptions, amountOrCallback, callbackOrOptions, maybeOptions) {
+        const { customerId, amount, callback, options } = this.normalizeGuardArgs(customerIdOrOptions, amountOrCallback, callbackOrOptions, maybeOptions);
+        const reservation = await this.reserveCredits(customerId, amount, options);
+        try {
+            const result = await callback({ reservationId: reservation.reservationId });
+            await this.commitReservation(reservation.reservationId);
+            return result;
+        }
+        catch (callbackError) {
+            try {
+                await this.releaseReservation(reservation.reservationId);
+            }
+            catch (releaseError) {
+                throw new errors_1.MeterlyGuardError({
+                    customerId,
+                    reservationId: reservation.reservationId,
+                    callbackError,
+                    releaseError
+                });
+            }
+            throw callbackError;
+        }
+    }
+    normalizeGuardArgs(customerIdOrOptions, amountOrCallback, callbackOrOptions, maybeOptions) {
+        if (typeof customerIdOrOptions === "string") {
+            if (typeof amountOrCallback !== "number" || typeof callbackOrOptions !== "function") {
+                throw new TypeError("guard(customerId, amount, callback, options) requires a callback.");
+            }
+            return {
+                customerId: customerIdOrOptions,
+                amount: amountOrCallback,
+                callback: callbackOrOptions,
+                options: maybeOptions
+            };
+        }
+        if (typeof amountOrCallback !== "function") {
+            throw new TypeError("guard(options, callback) requires a callback.");
+        }
+        const { customerId, amount, ...options } = customerIdOrOptions;
+        return {
+            customerId,
+            amount,
+            callback: amountOrCallback,
+            options
+        };
+    }
+    async request(method, url, init = {}) {
+        const response = await this.fetchImpl(url, {
+            ...init,
+            method,
+            headers: this.buildHeaders(method, url, init.headers, init.body),
+            cache: "no-store"
+        });
+        const parsed = await this.parseResponse(method, url, response, false);
+        if (parsed === null) {
+            throw new errors_1.MeterlyApiError("Meterly API returned an empty response body.", {
+                status: response.status,
+                method,
+                url
+            });
+        }
+        return parsed;
+    }
+    async requestNullable(method, url, init = {}) {
+        const response = await this.fetchImpl(url, {
+            ...init,
+            method,
+            headers: this.buildHeaders(method, url, init.headers, init.body),
+            cache: "no-store"
+        });
+        return this.parseResponse(method, url, response, true);
+    }
+    buildHeaders(method, url, headers, body) {
+        const built = new Headers(headers);
+        if (!built.has("Content-Type")) {
+            built.set("Content-Type", "application/json");
+        }
+        if (this.apiKey && !built.has("Authorization")) {
+            built.set("Authorization", `Bearer ${this.apiKey}`);
+        }
+        if (this.extraHeaders) {
+            for (const [key, value] of Object.entries(this.extraHeaders)) {
+                if (!built.has(key)) {
+                    built.set(key, value);
+                }
+            }
+        }
+        if (this.signingMode === "hmac") {
+            if (!this.apiKey) {
+                throw new Error("Meterly HMAC signing requires apiKey.");
+            }
+            const timestamp = Math.floor(Date.now() / 1000).toString();
+            const bodyText = bodyToString(body);
+            const bodyHash = sha256Hex(bodyText);
+            const canonical = [
+                method.toUpperCase(),
+                pathWithQuery(url),
+                bodyHash,
+                timestamp
+            ].join("\n");
+            built.set("X-Meterly-Timestamp", timestamp);
+            built.set("X-Meterly-Body-SHA256", bodyHash);
+            built.set("X-Meterly-Signature", (0, node_crypto_1.createHmac)("sha256", this.apiKey).update(canonical).digest("hex"));
+        }
+        return built;
+    }
+    buildMutationHeaders(options) {
+        if (!options?.idempotencyKey) {
+            return undefined;
+        }
+        return {
+            "Idempotency-Key": options.idempotencyKey
+        };
+    }
+    async parseResponse(method, url, response, allowNoContent) {
+        if (response.status === 204) {
+            return allowNoContent ? null : {};
+        }
+        const text = await response.text();
+        let responseBody = undefined;
+        if (text) {
+            try {
+                responseBody = JSON.parse(text);
+            }
+            catch {
+                if (response.ok) {
+                    throw new errors_1.MeterlyApiError("Received invalid JSON from Meterly API.", {
+                        status: response.status,
+                        method,
+                        url,
+                        responseBody: text
+                    });
+                }
+            }
+        }
+        if (!response.ok) {
+            throw createApiError(method, url, response.status, responseBody, response.statusText);
+        }
+        return (responseBody ?? null);
+    }
+}
+exports.MeterlyClient = MeterlyClient;

package/dist/errors.d.ts

@@ -0,0 +1,29 @@
+export interface MeterlyApiErrorDetails {
+    status: number;
+    method: string;
+    url: string;
+    responseBody?: unknown;
+}
+export declare class MeterlyApiError extends Error {
+    readonly status: number;
+    readonly method: string;
+    readonly url: string;
+    readonly responseBody?: unknown;
+    constructor(message: string, details: MeterlyApiErrorDetails);
+}
+export declare class MeterlyInsufficientCreditsError extends MeterlyApiError {
+    constructor(message: string, details: MeterlyApiErrorDetails);
+}
+export interface MeterlyGuardErrorOptions {
+    customerId: string;
+    reservationId: string;
+    callbackError: unknown;
+    releaseError: unknown;
+}
+export declare class MeterlyGuardError extends Error {
+    readonly customerId: string;
+    readonly reservationId: string;
+    readonly callbackError: unknown;
+    readonly releaseError: unknown;
+    constructor(options: MeterlyGuardErrorOptions);
+}

package/dist/errors.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MeterlyGuardError = exports.MeterlyInsufficientCreditsError = exports.MeterlyApiError = void 0;
+class MeterlyApiError extends Error {
+    status;
+    method;
+    url;
+    responseBody;
+    constructor(message, details) {
+        super(message);
+        this.name = "MeterlyApiError";
+        this.status = details.status;
+        this.method = details.method;
+        this.url = details.url;
+        this.responseBody = details.responseBody;
+    }
+}
+exports.MeterlyApiError = MeterlyApiError;
+class MeterlyInsufficientCreditsError extends MeterlyApiError {
+    constructor(message, details) {
+        super(message, details);
+        this.name = "MeterlyInsufficientCreditsError";
+    }
+}
+exports.MeterlyInsufficientCreditsError = MeterlyInsufficientCreditsError;
+class MeterlyGuardError extends Error {
+    customerId;
+    reservationId;
+    callbackError;
+    releaseError;
+    constructor(options) {
+        super(`Meterly guard failed for customer ${options.customerId}: callback threw and reservation release also failed.`);
+        this.name = "MeterlyGuardError";
+        this.customerId = options.customerId;
+        this.reservationId = options.reservationId;
+        this.callbackError = options.callbackError;
+        this.releaseError = options.releaseError;
+    }
+}
+exports.MeterlyGuardError = MeterlyGuardError;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { MeterlyClient } from "./client";
+export { MeterlyApiError, MeterlyGuardError, MeterlyInsufficientCreditsError } from "./errors";
+export type { BaseResponse, CheckoutSessionResult, CreateCheckoutSessionOptions, CreateCustomerInput, CreateCustomerResult, CreditAccount, CreditGrant, CreditGrantsListResult, CreditPackageGrant, CreditPackageGrantsListResult, CreditUsageEvent, GrantCreditsInput, GrantCreditsResult, GrantCreditPackageInput, GrantCreditPackageResult, GuardContext, GuardOptions, LedgerEntriesQueryOptions, LedgerEntriesResult, ListCreditGrantsOptions, ListCreditPackageGrantsOptions, MeterlyClientConfig, MeterlyRequestOptions, PaymentProviderStatus, ReserveCreditsOptions, ListStripePaymentsOptions, ReconcileOutcome, StripePayment, StripePaymentResult, StripePaymentStatus, StripePaymentsListResult, StripeReconcileResult, UsageQueryOptions, UsageResult, UsageSummary } from "./types";

package/dist/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MeterlyInsufficientCreditsError = exports.MeterlyGuardError = exports.MeterlyApiError = exports.MeterlyClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "MeterlyClient", { enumerable: true, get: function () { return client_1.MeterlyClient; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "MeterlyApiError", { enumerable: true, get: function () { return errors_1.MeterlyApiError; } });
+Object.defineProperty(exports, "MeterlyGuardError", { enumerable: true, get: function () { return errors_1.MeterlyGuardError; } });
+Object.defineProperty(exports, "MeterlyInsufficientCreditsError", { enumerable: true, get: function () { return errors_1.MeterlyInsufficientCreditsError; } });

package/dist/types.d.ts

@@ -0,0 +1,335 @@
+export interface MeterlyClientConfig {
+    commandApiUrl: string;
+    queryApiUrl: string;
+    apiKey?: string;
+    signingMode?: "bearer" | "hmac";
+    fetch?: typeof fetch;
+    headers?: Record<string, string>;
+}
+export interface BaseResponse {
+    message: string;
+}
+export interface PaginationMeta {
+    page: number;
+    pageSize: number;
+    returnedItems: number;
+    hasMore: boolean;
+    sortBy?: string;
+    sortOrder?: "asc" | "desc";
+}
+export interface Customer {
+    id: string;
+    customerExternalId: string;
+    creditUnit: string;
+    createdAt: string;
+}
+export interface CreditAccount {
+    id: string;
+    customerId: string;
+    creditUnit: string;
+    balance: number;
+    reserved: number;
+    available: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CustomerRecord {
+    customer?: Customer;
+    account?: CreditAccount | null;
+}
+export type CreditAction = "ACCOUNT_CREATED" | "CREDITS_ADDED" | "CREDITS_USED" | "CREDITS_USE_REJECTED" | "CREDITS_RESERVED" | "CREDITS_COMMITTED" | "CREDITS_RELEASED" | "RESERVATION_EXPIRED" | string;
+export interface CreditUsageEvent {
+    id: string;
+    customerId: string;
+    reservationId?: string;
+    eventId: string;
+    type: CreditAction;
+    amount: number;
+    creditUnit?: string;
+    reference?: string;
+    description?: string;
+    occurredAt: string;
+    createdAt: string;
+}
+export interface UsageUnit {
+    unitId: string;
+    tenantId: string;
+    code: string;
+    displayName: string;
+    description?: string;
+    precision: number;
+    status: "active" | "archived" | string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface LedgerEntry {
+    id: string;
+    customerId: string;
+    creditAccountId: string;
+    reservationId?: string;
+    eventId: string;
+    eventType: string;
+    eventVersion: number;
+    entryType: "DEBIT" | "CREDIT" | "RESERVE" | "RELEASE";
+    action: CreditAction;
+    amount: number;
+    balanceAfter: number;
+    availableAfter: number;
+    creditUnit: string;
+    reference?: string;
+    description?: string;
+    occurredAt: string;
+    createdAt: string;
+}
+export interface UsageSummary {
+    id: string;
+    customerCount: number;
+    /** Legacy cross-unit compatibility aggregate; prefer per-unit balance reads. */
+    totalBalance: number;
+    /** Legacy cross-unit compatibility aggregate; prefer per-unit balance reads. */
+    totalReserved: number;
+    /** Legacy cross-unit compatibility aggregate; prefer per-unit balance reads. */
+    totalAvailable: number;
+    /** Legacy cross-unit compatibility aggregate; prefer usageEventsByType or per-unit grant views. */
+    totalCreditsAdded: number;
+    /** Legacy cross-unit compatibility aggregate; prefer usageEventsByType or per-unit usage views. */
+    totalCreditsUsed: number;
+    totalReservations: number;
+    openReservations: number;
+    rejectedUsageEvents: number;
+    usageEventsByType?: Record<string, number>;
+}
+export interface CreateCustomerInput {
+    customerExternalId: string;
+    creditUnit?: string;
+}
+export interface CreateCustomerResult extends BaseResponse {
+    customerId: string;
+}
+export interface MeterlyRequestOptions {
+    reference?: string;
+    description?: string;
+    creditUnit?: string;
+    unit?: string;
+    metadata?: Record<string, unknown>;
+    idempotencyKey?: string;
+}
+export interface ReserveCreditsOptions extends MeterlyRequestOptions {
+    reservationId?: string;
+    ttlSeconds?: number;
+}
+export interface UsageQueryOptions {
+    page?: number;
+    pageSize?: number;
+    sortOrder?: "asc" | "desc";
+    type?: string;
+    unit?: string;
+    search?: string;
+    startAt?: string;
+    endAt?: string;
+}
+export interface LedgerEntriesQueryOptions {
+    page?: number;
+    pageSize?: number;
+    sortOrder?: "asc" | "desc";
+}
+export interface UsageResult {
+    message: string;
+    usage: CreditUsageEvent[];
+    pagination?: PaginationMeta;
+}
+export interface BalancesResult extends BaseResponse {
+    customerId: string;
+    balances: CreditAccount[];
+}
+export interface UsageUnitsListResult extends BaseResponse {
+    usageUnits: UsageUnit[];
+}
+export interface CreateUsageUnitInput {
+    code: string;
+    displayName?: string;
+    description?: string;
+}
+export interface UsageUnitResult extends BaseResponse {
+    usageUnit: UsageUnit;
+}
+export interface LedgerEntriesResult {
+    message: string;
+    ledgerEntries: LedgerEntry[];
+    pagination?: PaginationMeta;
+}
+export interface GuardContext {
+    reservationId: string;
+}
+export type GuardCallback<TResult> = (context: GuardContext) => Promise<TResult> | TResult;
+export interface GuardOptions extends ReserveCreditsOptions {
+    customerId: string;
+    amount: number;
+}
+/** @deprecated Legacy checkout compatibility only; not part of the current RevenueCat-first product surface. */
+export interface CreateCheckoutSessionOptions extends MeterlyRequestOptions {
+}
+/** @deprecated Legacy checkout compatibility only; not part of the current RevenueCat-first product surface. */
+export interface CheckoutSessionResult extends BaseResponse {
+    checkoutUrl: string;
+    sessionId: string;
+}
+export interface GrantCreditPackageInput {
+    externalCustomerId: string;
+    reference: string;
+    description?: string;
+    provider?: string;
+    providerAccountId?: string;
+    providerPaymentId?: string;
+    providerEventId?: string;
+    providerEventType?: string;
+    verificationSource?: string;
+}
+export interface GrantCreditsInput {
+    externalCustomerId: string;
+    creditAmount: number;
+    creditUnit?: string;
+    reference: string;
+    description?: string;
+    provider?: string;
+    providerAccountId?: string;
+    providerPaymentId?: string;
+    providerEventId?: string;
+    providerEventType?: string;
+    verificationSource?: string;
+}
+export interface CreditGrant {
+    grantId: string;
+    tenantId: string;
+    customerId: string;
+    externalCustomerId: string;
+    creditAmount: number;
+    creditUnit: string;
+    reference: string;
+    description?: string;
+    provider?: string;
+    providerAccountId?: string;
+    providerPaymentId?: string;
+    providerEventId?: string;
+    providerEventType?: string;
+    verificationSource: string;
+    status: "pending" | "granted" | string;
+    createdAt: string;
+}
+export interface GrantCreditsResult extends BaseResponse {
+    grant: CreditGrant;
+}
+export interface ListCreditGrantsOptions {
+    customerId?: string;
+    externalCustomerId?: string;
+    provider?: string;
+    providerPaymentId?: string;
+    providerEventId?: string;
+}
+export interface CreditGrantsListResult extends BaseResponse {
+    grants: CreditGrant[];
+}
+export interface CreditPackageGrant {
+    grantId: string;
+    tenantId: string;
+    packageId: string;
+    customerId: string;
+    externalCustomerId: string;
+    creditAmount: number;
+    creditUnit: string;
+    priceAmount?: number;
+    priceCurrency?: string;
+    reference: string;
+    description?: string;
+    provider?: string;
+    providerAccountId?: string;
+    providerPaymentId?: string;
+    providerEventId?: string;
+    providerEventType?: string;
+    verificationSource: string;
+    status: "pending" | "granted" | string;
+    createdAt: string;
+}
+export interface GrantCreditPackageResult extends BaseResponse {
+    grant: CreditPackageGrant;
+}
+export interface ListCreditPackageGrantsOptions {
+    customerId?: string;
+    externalCustomerId?: string;
+    packageId?: string;
+    provider?: string;
+    providerPaymentId?: string;
+    providerEventId?: string;
+}
+export interface CreditPackageGrantsListResult extends BaseResponse {
+    grants: CreditPackageGrant[];
+}
+export interface HostedConnectStatus {
+    supported: boolean;
+    status: "coming_soon" | string;
+    message: string;
+}
+/** @deprecated Legacy Stripe status compatibility only; current provider setup is RevenueCat-first. */
+export interface PaymentProviderStatus {
+    tenantId: string;
+    provider: "stripe" | string;
+    mode: "self_hosted" | string;
+    enabled: boolean;
+    configured: boolean;
+    checkoutAvailable: boolean;
+    webhookEndpoint: string;
+    successUrlConfigured: boolean;
+    cancelUrlConfigured: boolean;
+    webhookSecretConfigured: boolean;
+    secretKeyConfigured: boolean;
+    hostedConnect: HostedConnectStatus;
+}
+/** @deprecated Legacy Stripe compatibility only. */
+export type StripePaymentStatus = "received" | "processed" | "duplicate" | "failed" | "reconciled" | string;
+export type ReconcileOutcome = "reconciled" | "mismatch" | "pending" | "failed" | string;
+/** @deprecated Legacy Stripe compatibility only. */
+export interface StripePayment {
+    stripeEventId: string;
+    stripeSessionId?: string;
+    tenantId: string;
+    projectId?: string;
+    customerId: string;
+    packageId: string;
+    credits: number;
+    amount?: number;
+    currency?: string;
+    reference?: string;
+    status: StripePaymentStatus;
+    creditEventId?: string;
+    errorMessage?: string;
+    createdAt: string;
+    processedAt?: string;
+    reconciledAt?: string;
+}
+/** @deprecated Legacy Stripe compatibility only. */
+export interface ListStripePaymentsOptions {
+    status?: StripePaymentStatus;
+    page?: number;
+    pageSize?: number;
+}
+/** @deprecated Legacy Stripe compatibility only. */
+export interface StripePaymentsListResult extends BaseResponse {
+    payments: StripePayment[];
+    pagination: {
+        page: number;
+        pageSize: number;
+        hasMore: boolean;
+    };
+}
+/** @deprecated Legacy Stripe compatibility only. */
+export interface StripePaymentResult extends BaseResponse {
+    payment: StripePayment;
+}
+/** @deprecated Legacy Stripe compatibility only. */
+export interface StripeReconcileResult extends BaseResponse {
+    outcome: ReconcileOutcome;
+    status: StripePaymentStatus;
+    errorMessage?: string;
+    detail?: string;
+    payment: StripePayment;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@meterly/sdk",
+  "version": "0.1.0",
+  "description": "Developer-facing JavaScript SDK for Meterly credit workflows",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "tsx test/guard.test.ts"
+  },
+  "devDependencies": {
+    "@types/node": "^24.9.1",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3"
+  }
+}