@openaisdk/billing-sdk-node 1.3.0

package/dist/index.js

@@ -0,0 +1,301 @@
+import { createHmac, timingSafeEqual } from 'crypto';
+const SDK_VERSION = '1.3.0';
+const SDK_PACKAGE_NAME = '@openaisdk/billing-sdk-node';
+const DEFAULT_BASE_URL = 'https://billing.example.com';
+const DEFAULT_TIMEOUT_MS = 30_000;
+const REQUEST_ID_HEADER = 'MegaBilling-Request-Id';
+const WEBHOOK_SIGNATURE_HEADER = 'x-billing-signature';
+const WEBHOOK_SIGNATURE_SCHEME = 'v1';
+const WEBHOOK_DEFAULT_TOLERANCE_SECONDS = 300;
+const NETWORK_ERROR_MESSAGE = 'Network request failed. Check connectivity or BILLING_API_URL and retry.';
+export const BILLING_WEBHOOK_EVENT_TYPES = [
+    'billing.test',
+    'subscription.created',
+    'subscription.activated',
+    'subscription.renewed',
+    'subscription.plan_changed',
+    'subscription.change_scheduled',
+    'subscription.change_applied',
+    'subscription.change_canceled',
+    'subscription.past_due',
+    'subscription.cancellation_scheduled',
+    'subscription.canceled',
+    'subscription.paused',
+    'subscription.resumed',
+    'subscription.trial_started',
+    'invoice.finalized',
+    'invoice.paid',
+    'invoice.voided',
+    'invoice.credit_note_issued',
+    'payment.failed',
+    'payment.refunded',
+    'entitlement.updated',
+    'entitlement.granted',
+    'entitlement.revoked',
+];
+export class BillingError extends Error {
+    code;
+    status;
+    requestId;
+    param;
+    constructor(options) {
+        super(options.message);
+        this.name = 'BillingError';
+        this.code = options.code;
+        this.status = options.status;
+        this.requestId = options.requestId;
+        this.param = options.param;
+    }
+}
+export class BillingWebhookVerificationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'BillingWebhookVerificationError';
+        this.code = code;
+    }
+}
+export class MegaBilling {
+    apiKey;
+    baseUrl;
+    timeoutMs;
+    fetchImpl;
+    customers = {
+        create: (params, options) => this.request('POST', '/v1/customers', params, options),
+        retrieve: (customerId, options) => this.request('GET', `/v1/customers/${encodeURIComponent(customerId)}`, undefined, options),
+        list: (params, options) => this.request('GET', withQuery('/v1/customers', params), undefined, options),
+        update: (customerId, payload, options) => this.request('PATCH', `/v1/customers/${encodeURIComponent(customerId)}`, payload, options),
+    };
+    subscriptions = {
+        retrieve: (subscriptionId, options) => this.request('GET', `/v1/subscriptions/${encodeURIComponent(subscriptionId)}`, undefined, options),
+        list: (params, options) => this.request('GET', withQuery('/v1/subscriptions', params), undefined, options),
+        cancel: (subscriptionId, payload, options) => this.request('POST', `/v1/subscriptions/${encodeURIComponent(subscriptionId)}/cancel`, payload ?? {}, options),
+    };
+    invoices = {
+        retrieve: (invoiceId, options) => this.request('GET', `/v1/invoices/${encodeURIComponent(invoiceId)}`, undefined, options),
+        listCreditNotes: (invoiceId, options) => this.request('GET', `/v1/invoices/${encodeURIComponent(invoiceId)}/credit-notes`, undefined, options),
+    };
+    checkout = {
+        sessions: {
+            create: (params, options) => this.request('POST', '/v1/checkout/sessions', params, options),
+        },
+    };
+    access = {
+        retrieve: (customerId, options) => this.request('GET', `/v1/customers/${encodeURIComponent(customerId)}/access`, undefined, options),
+    };
+    meterEvents = {
+        create: (params, options) => this.request('POST', '/v1/billing/meter-events', params, options),
+        summary: (meterId, params, options) => this.request('GET', withQuery(`/v1/billing/meters/${encodeURIComponent(meterId)}/event-summaries`, params), undefined, options),
+    };
+    webhooks = {
+        constructEvent: (payload, signatureHeader, secret, options) => constructWebhookEvent(payload, signatureHeader, secret, options),
+        generateTestHeaderString: (payload, secret, timestamp = Math.floor(Date.now() / 1000)) => generateWebhookTestHeaderString(payload, secret, timestamp),
+    };
+    constructor(options) {
+        if (!options.apiKey?.trim()) {
+            throw new Error('MegaBilling requires a non-empty apiKey');
+        }
+        this.apiKey = options.apiKey;
+        this.baseUrl = normalizeBaseUrl(options.baseUrl ?? process.env.BILLING_API_URL ?? DEFAULT_BASE_URL);
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.fetchImpl = options.fetch ?? fetch;
+    }
+    async request(method, path, body, options) {
+        const timeoutController = new AbortController();
+        let didTimeout = false;
+        const timeoutId = setTimeout(() => {
+            didTimeout = true;
+            timeoutController.abort();
+        }, this.timeoutMs);
+        const signal = options?.signal
+            ? AbortSignal.any([options.signal, timeoutController.signal])
+            : timeoutController.signal;
+        try {
+            const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+                method,
+                headers: this.buildHeaders(body, options),
+                body: body === undefined ? undefined : JSON.stringify(body),
+                signal,
+            });
+            const requestId = response.headers.get(REQUEST_ID_HEADER);
+            const payload = (await safeJson(response));
+            if (!response.ok) {
+                throw toBillingError(response.status, payload, requestId);
+            }
+            return withRequestId((payload ?? {}), requestId);
+        }
+        catch (error) {
+            if (error instanceof BillingError) {
+                throw error;
+            }
+            if (didTimeout) {
+                throw new BillingError({
+                    code: 'request_timeout',
+                    message: `Request timed out after ${this.timeoutMs}ms`,
+                    status: 408,
+                    requestId: null,
+                });
+            }
+            throw new BillingError({
+                code: 'network_error',
+                message: NETWORK_ERROR_MESSAGE,
+                status: 0,
+                requestId: null,
+            });
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    buildHeaders(body, options) {
+        const headers = new Headers();
+        headers.set('Accept', 'application/json');
+        headers.set('Authorization', `Bearer ${this.apiKey}`);
+        headers.set('User-Agent', `${SDK_PACKAGE_NAME}/${SDK_VERSION}`);
+        if (body !== undefined) {
+            headers.set('Content-Type', 'application/json');
+        }
+        const idempotencyKey = getIdempotencyKey(options);
+        if (idempotencyKey) {
+            headers.set('Idempotency-Key', idempotencyKey);
+        }
+        return headers;
+    }
+}
+function getIdempotencyKey(options) {
+    if (!options || !('idempotencyKey' in options)) {
+        return undefined;
+    }
+    return options.idempotencyKey;
+}
+function withQuery(path, params) {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params ?? {})) {
+        if (value !== undefined) {
+            search.set(key, String(value));
+        }
+    }
+    const query = search.toString();
+    return query ? `${path}?${query}` : path;
+}
+function normalizeBaseUrl(value) {
+    return value.replace(/\/+$/, '');
+}
+async function safeJson(response) {
+    const text = await response.text();
+    if (!text) {
+        return null;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+function toBillingError(status, payload, headerRequestId) {
+    const apiError = payload && typeof payload === 'object' && 'error' in payload
+        ? payload.error
+        : undefined;
+    return new BillingError({
+        code: apiError?.code ?? `http_${status}`,
+        message: apiError?.message ?? `Request failed with status ${status}`,
+        status,
+        requestId: headerRequestId ?? null,
+        param: apiError?.param,
+    });
+}
+function withRequestId(payload, requestId) {
+    return {
+        ...payload,
+        requestId,
+    };
+}
+function constructWebhookEvent(payload, signatureHeader, secret, options) {
+    if (!signatureHeader?.trim()) {
+        throw new BillingWebhookVerificationError('webhook_header_invalid', `Missing ${WEBHOOK_SIGNATURE_HEADER} header`);
+    }
+    if (!secret.trim()) {
+        throw new BillingWebhookVerificationError('webhook_signature_invalid', 'Webhook secret must be a non-empty string');
+    }
+    const payloadString = toWebhookPayloadString(payload);
+    const parsedHeader = parseWebhookSignatureHeader(signatureHeader);
+    const expectedSignature = computeWebhookSignature(secret, payloadString, parsedHeader.timestamp);
+    const isValid = parsedHeader.signatures.some((signature) => secureCompareHex(signature, expectedSignature));
+    if (!isValid) {
+        throw new BillingWebhookVerificationError('webhook_signature_invalid', 'No signatures found matching the expected signature for payload.');
+    }
+    const receivedAtMs = options?.receivedAt instanceof Date
+        ? options.receivedAt.getTime()
+        : typeof options?.receivedAt === 'number'
+            ? options.receivedAt
+            : Date.now();
+    const toleranceSeconds = options?.toleranceSeconds ?? WEBHOOK_DEFAULT_TOLERANCE_SECONDS;
+    const ageSeconds = Math.abs(Math.floor(receivedAtMs / 1000) - parsedHeader.timestamp);
+    if (toleranceSeconds > 0 && ageSeconds > toleranceSeconds) {
+        throw new BillingWebhookVerificationError('webhook_timestamp_expired', 'Webhook timestamp is outside the tolerance window.');
+    }
+    let parsedPayload;
+    try {
+        parsedPayload = JSON.parse(payloadString);
+    }
+    catch {
+        throw new BillingWebhookVerificationError('webhook_payload_invalid', 'Webhook payload must be valid JSON.');
+    }
+    if (!parsedPayload ||
+        typeof parsedPayload !== 'object' ||
+        !('id' in parsedPayload) ||
+        !('type' in parsedPayload)) {
+        throw new BillingWebhookVerificationError('webhook_payload_invalid', 'Webhook payload is missing the required event envelope fields.');
+    }
+    return parsedPayload;
+}
+function generateWebhookTestHeaderString(payload, secret, timestamp = Math.floor(Date.now() / 1000)) {
+    const payloadString = toWebhookPayloadString(payload);
+    const signature = computeWebhookSignature(secret, payloadString, timestamp);
+    return `t=${timestamp},${WEBHOOK_SIGNATURE_SCHEME}=${signature}`;
+}
+function toWebhookPayloadString(payload) {
+    if (typeof payload === 'string') {
+        return payload;
+    }
+    if (payload instanceof Uint8Array) {
+        return new TextDecoder().decode(payload);
+    }
+    return new TextDecoder().decode(new Uint8Array(payload));
+}
+function parseWebhookSignatureHeader(signatureHeader) {
+    const parts = signatureHeader.split(',').map((part) => part.trim());
+    const timestampPart = parts.find((part) => part.startsWith('t='));
+    const signatures = parts
+        .filter((part) => part.startsWith(`${WEBHOOK_SIGNATURE_SCHEME}=`))
+        .map((part) => part.slice(`${WEBHOOK_SIGNATURE_SCHEME}=`.length))
+        .filter(Boolean);
+    const timestamp = timestampPart ? Number.parseInt(timestampPart.slice(2), 10) : Number.NaN;
+    if (!Number.isFinite(timestamp) || signatures.length === 0) {
+        throw new BillingWebhookVerificationError('webhook_header_invalid', 'Webhook signature header must contain a valid t= timestamp and at least one v1 signature.');
+    }
+    return { timestamp, signatures };
+}
+function computeWebhookSignature(secret, payload, timestamp) {
+    return createHmac('sha256', secret).update(`${timestamp}.${payload}`, 'utf8').digest('hex');
+}
+function secureCompareHex(left, right) {
+    const leftBytes = hexToBytes(left);
+    const rightBytes = hexToBytes(right);
+    if (leftBytes.length === 0 || leftBytes.length !== rightBytes.length) {
+        return false;
+    }
+    return timingSafeEqual(leftBytes, rightBytes);
+}
+function hexToBytes(value) {
+    if (value.length === 0 || value.length % 2 !== 0 || !/^[0-9a-f]+$/i.test(value)) {
+        return new Uint8Array();
+    }
+    const bytes = new Uint8Array(value.length / 2);
+    for (let index = 0; index < value.length; index += 2) {
+        bytes[index / 2] = Number.parseInt(value.slice(index, index + 2), 16);
+    }
+    return bytes;
+}
+export { DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS, REQUEST_ID_HEADER, SDK_PACKAGE_NAME, SDK_VERSION, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_DEFAULT_TOLERANCE_SECONDS, };

package/examples/quickstart.ts

@@ -0,0 +1,60 @@
+import { MegaBilling } from '../src/index.js';
+
+const apiKey = process.env.BILLING_API_KEY;
+const appUrl = process.env.APP_URL ?? 'http://localhost:3000';
+const workspaceId = process.env.WORKSPACE_ID ?? 'ws_quickstart';
+const workspaceEmail = process.env.WORKSPACE_EMAIL ?? 'owner@example.com';
+const workspaceName = process.env.WORKSPACE_NAME ?? 'Quickstart Workspace';
+const priceId = process.env.BILLING_PRICE_ID ?? 'price_pro_monthly';
+
+if (!apiKey) {
+  throw new Error('Set BILLING_API_KEY before running the quickstart');
+}
+
+const billing = new MegaBilling({
+  apiKey,
+});
+
+const customer = await billing.customers.create(
+  {
+    externalType: 'workspace',
+    externalId: workspaceId,
+    email: workspaceEmail,
+    name: workspaceName,
+  },
+  {
+    idempotencyKey: `customer:${workspaceId}`,
+  }
+);
+
+const checkout = await billing.checkout.sessions.create(
+  {
+    customer: customer.id,
+    price: priceId,
+    successUrl: `${appUrl}/billing/success`,
+    cancelUrl: `${appUrl}/billing`,
+  },
+  {
+    idempotencyKey: `checkout:${workspaceId}:${priceId}:v1`,
+  }
+);
+
+const access = await billing.access.retrieve(customer.id);
+
+console.log(
+  JSON.stringify(
+    {
+      customerId: customer.id,
+      customerLivemode: customer.livemode,
+      customerRequestId: customer.requestId,
+      confirmationUrl: checkout.confirmationUrl,
+      checkoutLivemode: checkout.livemode,
+      checkoutRequestId: checkout.requestId,
+      accessStatus: access.status,
+      accessLivemode: access.livemode,
+      accessRequestId: access.requestId,
+    },
+    null,
+    2
+  )
+);

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@openaisdk/billing-sdk-node",
+  "version": "1.3.0",
+  "description": "Handwritten public Node SDK for Mega-Billing Wave 1 API",
+  "license": "MIT",
+  "author": "Anatoliy Tukov <openaisdk@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MegaRetroHQ/saas-billing.git",
+    "directory": "packages/billing-sdk-node"
+  },
+  "bugs": {
+    "url": "https://github.com/MegaRetroHQ/saas-billing/issues"
+  },
+  "homepage": "https://www.npmjs.com/package/@openaisdk/billing-sdk-node",
+  "keywords": [
+    "billing",
+    "sdk",
+    "node",
+    "typescript",
+    "checkout",
+    "saas",
+    "megabilling"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "examples/quickstart.ts"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "lint": "eslint .",
+    "test": "pnpm run build && node --test ./test/**/*.test.mjs",
+    "quickstart": "tsx ./examples/quickstart.ts",
+    "prepack": "pnpm run test"
+  },
+  "devDependencies": {
+    "@saas-billing/eslint-config": "workspace:*",
+    "@saas-billing/typescript-config": "workspace:*",
+    "@types/node": "^20",
+    "eslint": "^9.31.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.7.0"
+  }
+}