@crediball/sdk 0.1.0

package/README.md

@@ -0,0 +1,49 @@
+# @crediball/sdk
+
+TypeScript SDK for [Crediball](https://github.com/filipporezzadore/Crediball) —
+usage-based credit billing for AI apps. Charge users per action; let prices live
+in the dashboard, not your code.
+
+```bash
+npm install @crediball/sdk
+```
+
+## Quick start (server-side)
+
+```ts
+import { Crediball } from "@crediball/sdk";
+
+const meter = new Crediball({
+  apiKey: process.env.CREDIBALL_API_KEY!,   // cb_live_…
+  baseUrl: process.env.CREDIBALL_API_URL!,  // https://crediball.app/api
+});
+
+// Seed prices once (create-if-absent — never overwrites dashboard edits):
+await meter.defineActions([{ action: "generate_poem", credits: 5 }]);
+
+// Wrap an AI call: deduct → run → auto-refund if it throws.
+const poem = await meter.wrapAction("u123", "generate_poem", () => callAI());
+```
+
+## API
+
+| Method | Description |
+|---|---|
+| `new Crediball({ apiKey, baseUrl?, fetch? })` | Create a client. `baseUrl` is required (or set `CREDIBALL_API_URL`). |
+| `defineActions([{ action, credits, label?, force? }])` | Seed action prices. Create-if-absent unless `force`. |
+| `charge({ userId, action, amount?, metadata? })` | Deduct credits. Price from the catalog unless `amount` is given. |
+| `wrapAction(userId, action, fn)` | Charge by action, run `fn`, refund on failure. **Recommended.** |
+| `wrap(userId, amount, fn, action?)` | Same with an explicit hardcoded amount (advanced). |
+| `topup({ userId, amount, action?, metadata? })` | Add credits to a user's balance. |
+| `getBalance(userId)` | Return the user's current balance. |
+| `listActions()` | List the app's action catalog. |
+
+### Errors
+- `InsufficientCreditsError` — balance too low (catch it to show your paywall).
+- `CrediballApiError` — any other non-2xx response (`.status`, `.body`).
+
+## Principles
+- **Don't hardcode prices.** Reference actions by key; set credits in the dashboard.
+- **Server-side only.** Never ship your `cb_live_` key to the browser.
+- Pair with [`@crediball/react`](https://www.npmjs.com/package/@crediball/react)
+  for drop-in, unbranded credit UI.

package/dist/index.d.ts

@@ -0,0 +1,151 @@
+/**
+ * @crediball/sdk
+ *
+ * Usage-based credit billing for AI apps. Initialize once with your app API key,
+ * then charge users per action or wrap an AI call so credits are deducted
+ * automatically.
+ *
+ *   import { Crediball } from "@crediball/sdk";
+ *
+ *   const meter = new Crediball({ apiKey: "cb_live_xxx" });
+ *
+ *   await meter.charge({ userId: "u123", amount: 5, action: "ai_request" });
+ *
+ *   const result = await meter.wrap("u123", 3, async () => callAI());
+ */
+export interface CrediballOptions {
+    /** Your app API key, e.g. "cb_live_xxx". Find it in the Crediball dashboard. */
+    apiKey: string;
+    /**
+     * Base URL of your Crediball API, e.g. "https://crediball.app/api".
+     * Required — falls back to the CREDIBALL_API_URL env var if omitted.
+     */
+    baseUrl?: string;
+    /** Optional custom fetch implementation (e.g. for Node < 18 or testing). */
+    fetch?: typeof fetch;
+    /**
+     * Escape hatch to allow constructing the client in a browser. DON'T use this in
+     * production: your `cb_live_` key is a secret and must never reach the browser.
+     * By default the constructor throws if it detects a browser environment.
+     */
+    allowBrowser?: boolean;
+}
+export interface ChargeParams {
+    userId: string;
+    /** The action key — priced in the dashboard. Recommended over a hardcoded amount. */
+    action: string;
+    /**
+     * Optional. When omitted, the price is taken from the dashboard action catalog
+     * (recommended — lets the price change without a redeploy). When provided, it
+     * overrides the catalog (advanced / dynamic pricing).
+     */
+    amount?: number;
+    metadata?: Record<string, unknown>;
+}
+export interface ActionDef {
+    /** Stable action key referenced from code (e.g. "generate_poem"). */
+    action: string;
+    /** Default price in credits. */
+    credits: number;
+    /** Human-friendly name shown in the dashboard. */
+    label?: string;
+    /**
+     * By default this is create-if-absent: an existing action's dashboard-owned
+     * price is left untouched. Set force=true to overwrite from code (advanced).
+     */
+    force?: boolean;
+}
+export interface ActionRecord {
+    action: string;
+    label: string;
+    credits: number;
+    needsPricing: boolean;
+    active: boolean;
+}
+export interface TopupParams {
+    userId: string;
+    amount: number;
+    action?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface BalanceResult {
+    userId: string;
+    balance: number;
+}
+export interface ChargeResult {
+    userId: string;
+    balance: number;
+    charged: number;
+    ledgerId: string;
+}
+export interface TopupResult {
+    userId: string;
+    balance: number;
+    added: number;
+    ledgerId: string;
+}
+/** Thrown when a charge or wrap fails because the user lacks sufficient credits. */
+export declare class InsufficientCreditsError extends Error {
+    readonly code = "insufficient_credits";
+    readonly balance: number;
+    readonly required: number;
+    constructor(balance: number, required: number);
+}
+/** Thrown for any non-2xx API response that isn't an insufficient-credits 402. */
+export declare class CrediballApiError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, message: string, body: unknown);
+}
+export declare class Crediball {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(options: CrediballOptions);
+    /**
+     * Deduct credits from a user for an action. With no `amount`, the price comes
+     * from the dashboard action catalog. Throws InsufficientCreditsError if too low.
+     */
+    charge(params: ChargeParams): Promise<ChargeResult>;
+    /**
+     * Define (seed) prices for actions. Create-if-absent by default: this never
+     * overwrites a price a human set in the dashboard unless `force` is true.
+     * Call this once at setup; change prices later in the dashboard.
+     *
+     *   await meter.defineActions([
+     *     { action: "generate_poem", credits: 5 },
+     *     { action: "refine_poem",   credits: 3 },
+     *   ]);
+     */
+    defineActions(defs: ActionDef[]): Promise<ActionRecord[]>;
+    /** Define a single action price (see defineActions). */
+    defineAction(def: ActionDef): Promise<ActionRecord>;
+    /** List the app's action catalog (keys, prices, labels). */
+    listActions(): Promise<ActionRecord[]>;
+    /** Add credits to a user's balance (e.g. after a purchase or grant). */
+    topup(params: TopupParams): Promise<TopupResult>;
+    /** Get a user's current credit balance. */
+    getBalance(userId: string): Promise<BalanceResult>;
+    /**
+     * Wrap an AI function so credits are charged before it runs.
+     *
+     *   await meter.wrap("u123", 3, async () => callAI());
+     *
+     * Behavior:
+     *  - checks balance and deducts `amount` first (throws InsufficientCreditsError if too low),
+     *  - executes `fn` only if the charge succeeded,
+     *  - if `fn` throws, refunds the charge so the user isn't billed for a failed call,
+     *  - logs every transaction in the ledger.
+     */
+    wrap<T>(userId: string, amount: number, fn: () => Promise<T> | T, action?: string): Promise<T>;
+    /**
+     * Like `wrap`, but the price comes from the dashboard action catalog instead of
+     * a hardcoded amount — the recommended pattern.
+     *
+     *   await meter.wrapAction("u123", "generate_poem", () => callAI());
+     */
+    wrapAction<T>(userId: string, action: string, fn: () => Promise<T> | T): Promise<T>;
+    private runWithRefund;
+    private request;
+}
+export default Crediball;

package/dist/index.js

@@ -0,0 +1,186 @@
+/**
+ * @crediball/sdk
+ *
+ * Usage-based credit billing for AI apps. Initialize once with your app API key,
+ * then charge users per action or wrap an AI call so credits are deducted
+ * automatically.
+ *
+ *   import { Crediball } from "@crediball/sdk";
+ *
+ *   const meter = new Crediball({ apiKey: "cb_live_xxx" });
+ *
+ *   await meter.charge({ userId: "u123", amount: 5, action: "ai_request" });
+ *
+ *   const result = await meter.wrap("u123", 3, async () => callAI());
+ */
+/** Read the API base URL from the environment when available (Node/edge), else undefined. */
+function envBaseUrl() {
+    const env = globalThis
+        .process?.env;
+    return env?.CREDIBALL_API_URL;
+}
+/** Thrown when a charge or wrap fails because the user lacks sufficient credits. */
+export class InsufficientCreditsError extends Error {
+    constructor(balance, required) {
+        super(`Insufficient credits: balance ${balance}, required ${required}.`);
+        this.code = "insufficient_credits";
+        this.name = "InsufficientCreditsError";
+        this.balance = balance;
+        this.required = required;
+    }
+}
+/** Thrown for any non-2xx API response that isn't an insufficient-credits 402. */
+export class CrediballApiError extends Error {
+    constructor(status, message, body) {
+        super(message);
+        this.name = "CrediballApiError";
+        this.status = status;
+        this.body = body;
+    }
+}
+export class Crediball {
+    constructor(options) {
+        if (!options || !options.apiKey) {
+            throw new Error("Crediball requires an apiKey.");
+        }
+        // Guard against the catastrophic mistake of shipping the secret key to the
+        // browser. The key authorizes charges — it must only live on your server.
+        if (!options.allowBrowser &&
+            typeof window !== "undefined" &&
+            typeof document !== "undefined") {
+            throw new Error("Crediball must run server-side: your cb_live_ key is a secret and must " +
+                "never reach the browser. Initialize it in a server route/action with " +
+                "process.env.CREDIBALL_API_KEY. (Set allowBrowser:true only if you " +
+                "really know what you're doing.)");
+        }
+        this.apiKey = options.apiKey;
+        const base = options.baseUrl ?? envBaseUrl();
+        if (!base) {
+            throw new Error("Crediball requires a baseUrl. Pass `baseUrl` (e.g. " +
+                '"https://crediball.app/api") or set CREDIBALL_API_URL.');
+        }
+        this.baseUrl = base.replace(/\/$/, "");
+        const f = options.fetch ?? globalThis.fetch;
+        if (!f) {
+            throw new Error("No fetch implementation available. Pass `fetch` in CrediballOptions.");
+        }
+        this.fetchImpl = f.bind(globalThis);
+    }
+    /**
+     * Deduct credits from a user for an action. With no `amount`, the price comes
+     * from the dashboard action catalog. Throws InsufficientCreditsError if too low.
+     */
+    async charge(params) {
+        return this.request("POST", "/credits/charge", params);
+    }
+    /**
+     * Define (seed) prices for actions. Create-if-absent by default: this never
+     * overwrites a price a human set in the dashboard unless `force` is true.
+     * Call this once at setup; change prices later in the dashboard.
+     *
+     *   await meter.defineActions([
+     *     { action: "generate_poem", credits: 5 },
+     *     { action: "refine_poem",   credits: 3 },
+     *   ]);
+     */
+    async defineActions(defs) {
+        const res = await this.request("POST", "/actions", { actions: defs });
+        return res.actions;
+    }
+    /** Define a single action price (see defineActions). */
+    async defineAction(def) {
+        const [record] = await this.defineActions([def]);
+        return record;
+    }
+    /** List the app's action catalog (keys, prices, labels). */
+    async listActions() {
+        const res = await this.request("GET", "/actions");
+        return res.actions;
+    }
+    /** Add credits to a user's balance (e.g. after a purchase or grant). */
+    async topup(params) {
+        return this.request("POST", "/credits/topup", params);
+    }
+    /** Get a user's current credit balance. */
+    async getBalance(userId) {
+        return this.request("GET", `/user/${encodeURIComponent(userId)}/balance`);
+    }
+    /**
+     * Wrap an AI function so credits are charged before it runs.
+     *
+     *   await meter.wrap("u123", 3, async () => callAI());
+     *
+     * Behavior:
+     *  - checks balance and deducts `amount` first (throws InsufficientCreditsError if too low),
+     *  - executes `fn` only if the charge succeeded,
+     *  - if `fn` throws, refunds the charge so the user isn't billed for a failed call,
+     *  - logs every transaction in the ledger.
+     */
+    async wrap(userId, amount, fn, action = "ai_request") {
+        const { charged } = await this.charge({ userId, amount, action });
+        return this.runWithRefund(userId, charged, action, fn);
+    }
+    /**
+     * Like `wrap`, but the price comes from the dashboard action catalog instead of
+     * a hardcoded amount — the recommended pattern.
+     *
+     *   await meter.wrapAction("u123", "generate_poem", () => callAI());
+     */
+    async wrapAction(userId, action, fn) {
+        const { charged } = await this.charge({ userId, action });
+        return this.runWithRefund(userId, charged, action, fn);
+    }
+    async runWithRefund(userId, charged, action, fn) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            // Compensating refund: the AI call failed, so give the credits back.
+            if (charged > 0) {
+                try {
+                    await this.topup({
+                        userId,
+                        amount: charged,
+                        action: `${action}:refund`,
+                        metadata: { refund: true, reason: "wrapped_fn_threw" },
+                    });
+                }
+                catch {
+                    // Swallow refund errors so the original failure surfaces to the caller.
+                }
+            }
+            throw err;
+        }
+    }
+    async request(method, path, body) {
+        const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+            method,
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+                ...(body ? { "Content-Type": "application/json" } : {}),
+            },
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        const text = await res.text();
+        const data = text ? safeJson(text) : undefined;
+        if (res.status === 402) {
+            const d = (data ?? {});
+            throw new InsufficientCreditsError(d.balance ?? 0, d.required ?? 0);
+        }
+        if (!res.ok) {
+            const message = data?.error ??
+                `Crediball API error (${res.status})`;
+            throw new CrediballApiError(res.status, message, data);
+        }
+        return data;
+    }
+}
+function safeJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+export default Crediball;

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@crediball/sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for Crediball — usage-based credit billing for AI apps.",
+  "license": "MIT",
+  "author": "Filippo Rezzadore <filipporezzadore@gmail.com>",
+  "homepage": "https://crediball.app",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/filipporezzadore/Crediball.git",
+    "directory": "packages/sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/filipporezzadore/Crediball/issues"
+  },
+  "keywords": [
+    "billing",
+    "credits",
+    "usage-based",
+    "metering",
+    "pricing",
+    "ai",
+    "saas"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3"
+  }
+}