@subscriptonarc/sdk 1.0.0

package/README.md

@@ -0,0 +1,67 @@
+# @subscriptonarc/sdk
+
+Typed SubScript API client for Arc USDC payments — payment intents, subscriptions, metered usage, and webhook verification. Zero runtime dependencies (uses native `fetch` and `node:crypto`).
+
+```bash
+npm install @subscriptonarc/sdk
+```
+
+## Quick start
+
+```ts
+import { SubScript, usdc } from "@subscriptonarc/sdk";
+
+const subscript = new SubScript({ secretKey: process.env.SUBSCRIPT_SECRET_KEY! });
+
+// One-time payment
+const intent = await subscript.intents.create({
+  title: "Order #1042",
+  amountUsdcMicros: usdc(15),            // 15 USDC -> "15000000"
+  successUrl: "https://example.com/thanks",
+});
+console.log(intent.checkoutUrl);
+
+// Subscription
+const sub = await subscript.subscriptions.create({
+  amountUsdcMicros: usdc(9.99),
+  interval: "monthly",
+});
+
+// Metered usage
+await subscript.usage.report({ userAddress: "0x…", amountUsdcMicros: usdc(0.5) });
+
+// Check status
+const status = await subscript.intents.retrieve(intent.id);
+```
+
+## Webhooks
+
+```ts
+import { SubScript } from "@subscriptonarc/sdk";
+
+// In your webhook route (rawBody is the unparsed request body string):
+const event = subscript.webhooks.constructEvent(
+  rawBody,
+  request.headers["x-subscript-signature"],
+  process.env.SUBSCRIPT_WEBHOOK_SECRET!,
+);
+// throws if the signature is invalid; otherwise returns the parsed event
+switch (event.type) {
+  case "payment.succeeded": /* … */ break;
+  case "subscription.renewed": /* … */ break;
+  case "subscription.payment_failed": /* dunning */ break;
+  case "subscription.canceled": /* … */ break;
+}
+```
+
+## API
+
+- `subscript.intents.create(params)` / `.retrieve(id)`
+- `subscript.subscriptions.create(params)` / `.retrieve(id)` / `.list({ subscriber })` / `.cancel(id)`
+- `subscript.usage.report({ userAddress, amountUsdcMicros })`
+- `subscript.webhooks.verify(rawBody, sigHeader, secret)` / `.constructEvent(...)`
+- Helpers: `usdc(decimal)` → micro-USDC string, `fromMicros(micros)` → decimal string
+
+All amounts are integer **micro-USDC** (1 USDC = 1,000,000). The full contract is published as an [OpenAPI 3.1 spec](https://www.subscriptonarc.com/openapi.json).
+
+Non-2xx responses throw `SubScriptError` (`.status`, `.body`).

package/dist/index.d.ts

@@ -0,0 +1,127 @@
+/** Error thrown for any non-2xx API response. `body` holds the parsed error payload. */
+export declare class SubScriptError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+export interface SubScriptOptions {
+    /** Secret API key: `sk_test_…` (sandbox) or `sk_live_…` (production). */
+    secretKey: string;
+    /** Override the API base URL (defaults to https://www.subscriptonarc.com). */
+    baseUrl?: string;
+    /** Custom fetch implementation (defaults to global fetch; Node >=18). */
+    fetchImpl?: typeof fetch;
+}
+/** Convert a decimal USDC amount (e.g. 15 or "15.50") to canonical integer micro-USDC. */
+export declare function usdc(amount: number | string): string;
+/** Convert integer micro-USDC to a decimal USDC string. */
+export declare function fromMicros(micros: string | bigint | number): string;
+/** Verify an `x-subscript-signature` header (`t=…,v1=…`) against the raw body and secret. */
+export declare function verifyWebhookSignature(rawBody: string, signatureHeader: string, secret: string, toleranceSeconds?: number): boolean;
+export interface Intent {
+    id: string;
+    checkoutSessionId?: string;
+    title: string;
+    description?: string | null;
+    amountUsdcMicros: string;
+    amountUsdc: string;
+    status: string;
+    merchantAddress: string;
+    receiptToken?: string | null;
+    checkoutUrl: string;
+    chainId: number;
+    usdcAddress: string;
+    returnUrls?: {
+        successUrl?: string;
+        cancelUrl?: string;
+    };
+    latestPayment?: {
+        txHash: string | null;
+        payerAddress: string;
+        credited: boolean;
+        explorerUrl?: string | null;
+    } | null;
+    [key: string]: unknown;
+}
+export interface CreateIntentParams {
+    title: string;
+    amountUsdcMicros: string | bigint | number;
+    description?: string;
+    externalReference?: string;
+    maxUses?: number;
+    expiresAt?: number | string;
+    successUrl?: string;
+    cancelUrl?: string;
+    idempotencyKey?: string;
+    sandbox?: boolean;
+}
+export interface Subscription {
+    id: string;
+    object: "subscription";
+    status: "incomplete" | "active" | "inactive" | "past_due" | "canceled";
+    merchantAddress?: string;
+    subscriber?: string | null;
+    amountUsdcMicros: string;
+    amountUsdc: string;
+    intervalSeconds?: number;
+    intervalCount?: number;
+    interval?: string | null;
+    checkoutUrl?: string;
+    cancelAtPeriodEnd?: boolean;
+    [key: string]: unknown;
+}
+export interface CreateSubscriptionParams {
+    amountUsdcMicros?: string | bigint | number;
+    planId?: string;
+    interval?: "daily" | "weekly" | "monthly" | "yearly";
+    intervalSeconds?: number;
+    intervalCount?: number;
+    subscriber?: string;
+    title?: string;
+    externalReference?: string;
+    idempotencyKey?: string;
+    sandbox?: boolean;
+}
+export interface ReportUsageParams {
+    userAddress: string;
+    amountUsdcMicros: string | bigint | number;
+}
+export interface WebhookEvent {
+    id: string;
+    type: string;
+    event?: string;
+    created: number;
+    data: Record<string, unknown>;
+}
+export declare class SubScript {
+    private readonly secretKey;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(options: SubScriptOptions);
+    private request;
+    /** One-time payment intents (hosted checkout). */
+    readonly intents: {
+        create: (params: CreateIntentParams) => Promise<Intent>;
+        retrieve: (id: string) => Promise<Intent>;
+    };
+    /** Recurring subscriptions. */
+    readonly subscriptions: {
+        create: (params: CreateSubscriptionParams) => Promise<Subscription>;
+        retrieve: (id: string) => Promise<Subscription>;
+        list: (params?: {
+            subscriber?: string;
+        }) => Promise<Subscription[]>;
+        cancel: (id: string) => Promise<Subscription>;
+    };
+    /** Metered usage reporting. */
+    readonly usage: {
+        report: (params: ReportUsageParams) => Promise<Record<string, unknown>>;
+    };
+    /** Webhook signature verification (no network calls). */
+    readonly webhooks: {
+        verify: typeof verifyWebhookSignature;
+        /** Verify the signature and return the parsed event; throws SubScriptError if invalid. */
+        constructEvent: (rawBody: string, signatureHeader: string, secret: string) => WebhookEvent;
+    };
+}
+export default SubScript;

package/dist/index.js

@@ -0,0 +1,125 @@
+import crypto from "node:crypto";
+const DEFAULT_BASE_URL = "https://www.subscriptonarc.com";
+/** Error thrown for any non-2xx API response. `body` holds the parsed error payload. */
+export class SubScriptError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.name = "SubScriptError";
+        this.status = status;
+        this.body = body;
+    }
+}
+/* ------------------------------- Amount helpers ------------------------------ */
+/** Convert a decimal USDC amount (e.g. 15 or "15.50") to canonical integer micro-USDC. */
+export function usdc(amount) {
+    const n = typeof amount === "number" ? amount : Number(amount);
+    if (!Number.isFinite(n) || n < 0)
+        throw new Error(`Invalid USDC amount: ${amount}`);
+    return BigInt(Math.round(n * 1_000_000)).toString();
+}
+/** Convert integer micro-USDC to a decimal USDC string. */
+export function fromMicros(micros) {
+    const b = typeof micros === "bigint" ? micros : BigInt(micros);
+    const whole = b / 1000000n;
+    const frac = (b % 1000000n).toString().padStart(6, "0").replace(/0+$/, "");
+    return frac ? `${whole}.${frac}` : whole.toString();
+}
+/* ------------------------------ Webhook helpers ------------------------------ */
+/** Verify an `x-subscript-signature` header (`t=…,v1=…`) against the raw body and secret. */
+export function verifyWebhookSignature(rawBody, signatureHeader, secret, toleranceSeconds = 300) {
+    if (!signatureHeader || !secret)
+        return false;
+    let t = "";
+    let v1 = "";
+    for (const part of signatureHeader.split(",")) {
+        const [k, val] = part.split("=");
+        if (k === "t")
+            t = val;
+        if (k === "v1")
+            v1 = val;
+    }
+    if (!t || !v1)
+        return false;
+    const ts = Number.parseInt(t, 10);
+    if (Number.isNaN(ts) || Math.abs(Math.floor(Date.now() / 1000) - ts) > toleranceSeconds)
+        return false;
+    const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
+    const a = Buffer.from(v1, "hex");
+    const b = Buffer.from(expected, "hex");
+    return a.length === b.length && crypto.timingSafeEqual(a, b);
+}
+function stringifyMicros(params) {
+    if (params && params.amountUsdcMicros != null && typeof params.amountUsdcMicros !== "string") {
+        return { ...params, amountUsdcMicros: String(params.amountUsdcMicros) };
+    }
+    return params;
+}
+/* --------------------------------- Client ------------------------------------ */
+export class SubScript {
+    secretKey;
+    baseUrl;
+    fetchImpl;
+    constructor(options) {
+        if (!options?.secretKey)
+            throw new Error("SubScript: `secretKey` is required");
+        this.secretKey = options.secretKey;
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+        const f = options.fetchImpl ?? globalThis.fetch;
+        if (!f)
+            throw new Error("SubScript: no global fetch available — pass `fetchImpl` or use Node >=18");
+        this.fetchImpl = f;
+    }
+    async request(method, path, body) {
+        const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+            method,
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${this.secretKey}`,
+            },
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        const text = await res.text();
+        let json;
+        try {
+            json = text ? JSON.parse(text) : {};
+        }
+        catch {
+            json = { raw: text };
+        }
+        if (!res.ok) {
+            const message = json?.error ?? `SubScript request failed (${res.status})`;
+            throw new SubScriptError(message, res.status, json);
+        }
+        return json;
+    }
+    /** One-time payment intents (hosted checkout). */
+    intents = {
+        create: (params) => this.request("POST", "/api/intent", stringifyMicros(params)).then((r) => r.intent),
+        retrieve: (id) => this.request("GET", `/api/intent/status?id=${encodeURIComponent(id)}`).then((r) => r.intent),
+    };
+    /** Recurring subscriptions. */
+    subscriptions = {
+        create: (params) => this.request("POST", "/api/v1/subscriptions", stringifyMicros(params)).then((r) => r.subscription),
+        retrieve: (id) => this.request("GET", `/api/v1/subscriptions?id=${encodeURIComponent(id)}`),
+        list: (params) => this.request("GET", `/api/v1/subscriptions${params?.subscriber ? `?subscriber=${encodeURIComponent(params.subscriber)}` : ""}`).then((r) => r.data),
+        cancel: (id) => this.request("DELETE", `/api/v1/subscriptions?id=${encodeURIComponent(id)}`),
+    };
+    /** Metered usage reporting. */
+    usage = {
+        report: (params) => this.request("POST", "/api/user/vault/report-usage", stringifyMicros(params)),
+    };
+    /** Webhook signature verification (no network calls). */
+    webhooks = {
+        verify: verifyWebhookSignature,
+        /** Verify the signature and return the parsed event; throws SubScriptError if invalid. */
+        constructEvent: (rawBody, signatureHeader, secret) => {
+            if (!verifyWebhookSignature(rawBody, signatureHeader, secret)) {
+                throw new SubScriptError("Invalid webhook signature", 400, null);
+            }
+            return JSON.parse(rawBody);
+        },
+    };
+}
+export default SubScript;

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@subscriptonarc/sdk",
+  "version": "1.0.0",
+  "description": "Typed SubScript API client — payment intents, subscriptions, usage reporting, and webhook verification for Arc USDC payments.",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "subscript",
+    "arc",
+    "usdc",
+    "payments",
+    "stablecoin",
+    "subscriptions",
+    "usage-billing",
+    "webhooks",
+    "sdk"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KristienOWeb3/SubScript.git",
+    "directory": "packages/sdk"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "typescript": "^5"
+  }
+}