kredo 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,124 @@
-# Temporary Holding Version
+# kredo
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Charge Kredo credits from your server. Your users buy credits once and spend them in every app on the network. You're paid in USDT on Whitechain for what they spend with you.
+
+No dependencies. Node 18+.
+
+## Quick start
+
+```ts
+import { Credits } from "kredo";
+
+const credits = new Credits({ apiKey: process.env.CREDITS_API_KEY! });
+
+// Prices in credits. 1 credit = $0.01.
+await credits.setPrices({
+  "chat.message": { price: 1 },
+  "video.render": { rate: 6, unit: "second" },
+});
+
+// One-off actions: charge right away.
+await credits.charge({ user, action: "chat.message", ref: messageId });
+
+// Long jobs: hold the worst case, then charge what was used.
+const hold = await credits.hold({ user, action: "video.render", quantity: 12 });
+try {
+  const seconds = await render(job);
+  await credits.capture(hold.holdId, { credits: seconds * 6 });   // the rest goes back
+} catch {
+  await credits.release(hold.holdId);                             // the user keeps everything
+}
+```
+
+Keep the API key on your server. Never ship it to a browser.
+
+## Test mode
+
+Every app also gets a test key, `uc_test_...`, from the dashboard. Use it in place of the live key and the same calls run against fake credits, with nothing onchain: every test user starts with 1,000 credits and a 500 credit limit for your app, and limits, holds, captures and refunds follow the vault's rules exactly, refusals included. Responses carry `test: true`.
+
+```ts
+const credits = new Credits({ apiKey: process.env.CREDITS_TEST_KEY! });
+const { user } = await credits.exchangeCode(`cc_test_${someAddress}`);   // any address, no hosted page
+await credits.charge({ user, credits: 10 });
+```
+
+Payouts, webhooks and reporting need the live key. `POST /v1/sandbox/reset` puts every test user back to the start.
+
+## Connecting a user
+
+A user has to approve a spending limit for your app before you can charge them. The vault contract enforces that limit, so not even the network's own operator can charge more.
+
+1. Send them to the connect page: `await credits.connectUrl({ credits: 200, returnTo })`.
+2. They sign in with email, approve the limit, and come back to `returnTo?code=...`.
+3. On your server, swap the code for their address and keep it in your session:
+
+```ts
+const { user } = await credits.exchangeCode(req.query.code);
+req.session.creditsUser = user;
+```
+
+Never take a user's address from the browser. The code works once, only for your app, for 10 minutes.
+
+The React kit ([`kredo-react`](../react)) does this in a popup, and `credits.session(user)` returns exactly what the kit renders.
+
+## Calls
+
+| Call | What it does |
+|---|---|
+| `quote({ action, quantity })` | Price in credits and dollars, and what you keep after the network fee |
+| `user(address)` | Balance, whether they connected you, the limit left, and what's spendable now |
+| `charge({ user, action \| credits, ref })` | Charges now |
+| `hold({ user, action \| credits, ref, ttlSeconds })` | Reserves credits for a job, price locked |
+| `capture(holdId, { credits? })` | Charges all or part of a hold, returns the rest |
+| `release(holdId)` | Returns the whole hold |
+| `refund({ user, credits, ref })` | Gives credits back, up to what they spent with you |
+| `setExchangeRate(rate)`, `convert({ user, credits })` | Light mode: sell your own credits for ours |
+| `payout()` | Pays your unpaid earnings in USDT to your payout address |
+| `activity()`, `exportCsv()`, `gas()` | Reporting. Gas is paid by the network, never by you or your users |
+| `setWebhook(url)`, `webhookDeliveries()` | Signed event delivery |
+| `connectUrl()`, `buyUrl()`, `accountUrl()` | Links to the hosted pages |
+| `exchangeCode(code)`, `session(user)` | Connecting users, and state for the React kit |
+
+`CreditsNetwork` reads public data with no key: `health()`, `reserves()`, `stats()`, `directory()`.
+
+## Retries and errors
+
+Every write carries a `ref`. Pass your own (an order or message id), or the SDK makes one. The same ref always returns the first result, so retrying after a timeout can never charge twice. The SDK retries network failures and rate limits for you.
+
+Failures throw a `CreditsError`:
+
+```ts
+try {
+  await credits.charge({ user, action: "chat.message", ref });
+} catch (err) {
+  if (err instanceof CreditsError && err.isDeclined) {
+    // Over their limit or out of credits: show the buy or connect flow.
+    return redirect(credits.buyUrl({ returnTo }));
+  }
+  throw err;
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `code` | `OverLimit`, `InsufficientBalance`, `LimitExpired`, `rate_limited`, `DailyBudgetReached`, ... |
+| `isDeclined` | The user can't pay this. Retrying won't help |
+| `isRetryable` | A rate limit, gas budget pause or network failure. Try again later with the same ref |
+
+## Webhooks
+
+```ts
+import { verifyWebhook } from "kredo";
+
+app.post("/credits-webhook", express.raw({ type: "application/json" }), (req, res) => {
+  const event = verifyWebhook(req.body, req.header("x-credits-signature"), process.env.CREDITS_WEBHOOK_SECRET!);
+  if (event.type === "hold.released") markJobRefunded(event.data.holdId);
+  res.sendStatus(200);
+});
+```
+
+Events: `charge.succeeded`, `hold.created`, `hold.captured`, `hold.released`, `refund.succeeded`, `connection.approved`, `connection.revoked`, `payout.paid`. Each is signed with HMAC-SHA256 over `timestamp.body`, and `verifyWebhook` rejects anything older than 5 minutes. Failed deliveries are retried with backoff.
+
+## Try it
+
+`npm run e2e -w kredo` runs the whole flow against a local network: register, set prices, connect, charge, hold and capture, release, refund, payout. It prints every transaction.

package/dist/client.d.ts

@@ -0,0 +1,137 @@
+import type { ActivityItem, Amount, CreditsSession, AmountInput, AppInfo, Capture, Conversion, Credits as CreditAmount, GasReport, Hold, HoldStatus, Operation, Payout, PriceList, PriceListInput, Quote, UserState, WebhookDelivery } from "./types.js";
+export type CreditsOptions = {
+    /** Your app's API key, `uc_live_...`. */
+    apiKey: string;
+    /** The network's API. Defaults to https://kredo-api.onrender.com. */
+    baseUrl?: string;
+    /** The network's hosted pages (connect, buy, wallet). Defaults to https://kredo-omega.vercel.app. */
+    pagesUrl?: string;
+    /** Extra tries after a network failure or a rate limit. Writes are safe to retry: each carries a ref. Default 2. */
+    retries?: number;
+    /** Per-request timeout. Default 60s, long enough for a transaction to confirm. */
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+};
+type Query = Record<string, string | number | undefined>;
+export declare class Credits {
+    readonly baseUrl: string;
+    readonly pagesUrl: string;
+    private readonly apiKey;
+    private appId?;
+    private appInfo?;
+    private readonly retries;
+    private readonly timeoutMs;
+    private readonly fetchFn;
+    constructor(opts: CreditsOptions);
+    /** Your app: payout address, fee, unpaid earnings, prices and webhook. */
+    app(): Promise<AppInfo>;
+    prices(): Promise<PriceList>;
+    /** Replaces your price list, in credits: `{ "chat.message": { price: 2 }, "video.render": { rate: 8, unit: "second" } }`. */
+    setPrices(prices: PriceListInput): Promise<PriceList>;
+    /** What an action costs the user, and what you keep after the network fee. Show it before the job starts. */
+    quote(input: AmountInput): Promise<Quote>;
+    /** A user's balance, whether they've connected your app, and the most you can charge them now. */
+    user(address: string): Promise<UserState>;
+    /**
+     * Charges the user now. Pass your own `ref` (an order or message id) to make retries safe:
+     * the same ref always returns the first result. Throws a CreditsError with `isDeclined` when
+     * the user's limit or balance doesn't cover it.
+     */
+    charge(input: {
+        user: string;
+        ref?: string;
+    } & AmountInput): Promise<Operation>;
+    /** Reserves credits at the start of a long job. The price is locked now. Capture or release it when the job ends. */
+    hold(input: {
+        user: string;
+        ref?: string;
+        ttlSeconds?: number;
+    } & AmountInput): Promise<Hold>;
+    getHold(holdId: string): Promise<HoldStatus>;
+    /** The job succeeded. Charges the whole hold, or only `credits` of it, and returns the rest to the user. */
+    capture(holdId: string, opts?: {
+        credits?: CreditAmount;
+    }): Promise<Capture>;
+    /** The job failed. Everything held goes back to the user. */
+    release(holdId: string): Promise<Operation>;
+    /** Gives credits back, up to what this user has spent with you. Comes out of your unpaid earnings. */
+    refund(input: {
+        user: string;
+        credits: CreditAmount;
+        ref?: string;
+    }): Promise<Operation>;
+    /** Light mode: how many of our credits buy one of yours. Pass null to turn it off. */
+    setExchangeRate(rate: CreditAmount | null): Promise<{
+        exchangeRate: string | null;
+    }>;
+    /** Light mode: spends `credits` of ours. Add the returned `appCredits` to the user's balance in your own system. */
+    convert(input: {
+        user: string;
+        credits: CreditAmount;
+        ref?: string;
+    }): Promise<Conversion>;
+    /**
+     * A link to the network's connect page. The user signs in with email, approves a spending
+     * limit for your app, and comes back to `returnTo`. Nobody can charge them until they do.
+     */
+    connectUrl(opts: {
+        credits: CreditAmount;
+        returnTo?: string;
+        expiresInDays?: number;
+    }): Promise<string>;
+    /** A link to the buy page, for a user who is out of credits. */
+    buyUrl(opts?: {
+        credits?: CreditAmount;
+        returnTo?: string;
+    }): string;
+    /** The user's account page, where they see their balance and can disconnect any app. */
+    accountUrl(): string;
+    /** @deprecated Use accountUrl(). */
+    walletUrl(): string;
+    /**
+     * Swaps the one-time code from the connect page for the user's address and email. Call it from
+     * your server, then keep both in your own session. Never take an address from the browser.
+     */
+    exchangeCode(code: string): Promise<{
+        user: string;
+        email: string | null;
+        limit: Amount;
+    }>;
+    /**
+     * What the React kit shows for one of your users: your app, and their balance and limit.
+     * Pass undefined for a visitor who hasn't connected yet, and the email from `exchangeCode()` to
+     * show it in the UI.
+     */
+    session(user: string | undefined, opts?: {
+        email?: string | null;
+    }): Promise<CreditsSession>;
+    /** Pays all your unpaid earnings in USDT to your payout address, on Whitechain. */
+    payout(): Promise<Payout>;
+    /** Every vault event for your app, newest first. */
+    activity(opts?: {
+        limit?: number;
+    }): Promise<ActivityItem[]>;
+    /** Charges, holds, refunds and payouts as CSV text, for your accountant. */
+    exportCsv(): Promise<string>;
+    /** Gas the network spent on your transactions. You never pay it: the network fee covers it. */
+    gas(opts?: {
+        since?: Date;
+    }): Promise<GasReport>;
+    /**
+     * Sends every event about your app to `url` as a signed POST. Returns the signing secret once;
+     * check each delivery with `verifyWebhook`. Pass null to stop.
+     */
+    setWebhook(url: string | null): Promise<{
+        url: string | null;
+        secret: string | null;
+    }>;
+    webhookDeliveries(): Promise<WebhookDelivery[]>;
+    private page;
+    /** @internal Shared by every call. Retries network failures and rate limits; throws CreditsError. */
+    request<T>(method: string, path: string, opts?: {
+        query?: Query;
+        body?: unknown;
+        raw?: boolean;
+    }): Promise<T>;
+}
+export {};

package/dist/client.js

@@ -0,0 +1,238 @@
+/**
+ * Server kit for a company backend. Keep the API key on your server, never in a browser.
+ *
+ *   const credits = new Credits({ apiKey: process.env.CREDITS_API_KEY });
+ *
+ *   await credits.charge({ user, action: "chat.message" });
+ *
+ *   const hold = await credits.hold({ user, action: "video.render", quantity: 12 });
+ *   // ...run the job...
+ *   await credits.capture(hold.holdId);        // or credits.release(hold.holdId)
+ */
+import { randomUUID } from "node:crypto";
+import { CreditsError } from "./errors.js";
+/** Longest wait we'll sit through for a rate limit before giving up and throwing. */
+const MAX_RETRY_WAIT_MS = 10_000;
+export class Credits {
+    baseUrl;
+    pagesUrl;
+    apiKey;
+    appId;
+    appInfo;
+    retries;
+    timeoutMs;
+    fetchFn;
+    constructor(opts) {
+        if (!opts.apiKey)
+            throw new Error("Credits: apiKey is required");
+        this.apiKey = opts.apiKey;
+        this.baseUrl = (opts.baseUrl ?? "https://kredo-api.onrender.com").replace(/\/+$/, "");
+        this.pagesUrl = (opts.pagesUrl ?? "https://kredo-omega.vercel.app").replace(/\/+$/, "");
+        this.retries = opts.retries ?? 2;
+        this.timeoutMs = opts.timeoutMs ?? 60_000;
+        this.fetchFn = opts.fetch ?? globalThis.fetch;
+    }
+    // ---------------------------------------------------------------- your app
+    /** Your app: payout address, fee, unpaid earnings, prices and webhook. */
+    async app() {
+        const app = await this.request("GET", "/v1/app");
+        this.appId = app.id;
+        return app;
+    }
+    prices() {
+        return this.request("GET", "/v1/prices");
+    }
+    /** Replaces your price list, in credits: `{ "chat.message": { price: 2 }, "video.render": { rate: 8, unit: "second" } }`. */
+    setPrices(prices) {
+        return this.request("PUT", "/v1/prices", { body: { prices } });
+    }
+    // ---------------------------------------------------------------- prices and users
+    /** What an action costs the user, and what you keep after the network fee. Show it before the job starts. */
+    quote(input) {
+        return this.request("GET", "/v1/quote", { query: amountQuery(input) });
+    }
+    /** A user's balance, whether they've connected your app, and the most you can charge them now. */
+    user(address) {
+        return this.request("GET", `/v1/users/${encodeURIComponent(address)}`);
+    }
+    // ---------------------------------------------------------------- charging
+    /**
+     * Charges the user now. Pass your own `ref` (an order or message id) to make retries safe:
+     * the same ref always returns the first result. Throws a CreditsError with `isDeclined` when
+     * the user's limit or balance doesn't cover it.
+     */
+    charge(input) {
+        return this.request("POST", "/v1/charges", { body: withRef(input) });
+    }
+    /** Reserves credits at the start of a long job. The price is locked now. Capture or release it when the job ends. */
+    hold(input) {
+        return this.request("POST", "/v1/holds", { body: withRef(input) });
+    }
+    getHold(holdId) {
+        return this.request("GET", `/v1/holds/${encodeURIComponent(holdId)}`);
+    }
+    /** The job succeeded. Charges the whole hold, or only `credits` of it, and returns the rest to the user. */
+    capture(holdId, opts = {}) {
+        return this.request("POST", `/v1/holds/${encodeURIComponent(holdId)}/capture`, { body: opts });
+    }
+    /** The job failed. Everything held goes back to the user. */
+    release(holdId) {
+        return this.request("POST", `/v1/holds/${encodeURIComponent(holdId)}/release`, { body: {} });
+    }
+    /** Gives credits back, up to what this user has spent with you. Comes out of your unpaid earnings. */
+    refund(input) {
+        return this.request("POST", "/v1/refunds", { body: withRef(input) });
+    }
+    // ---------------------------------------------------------------- light mode
+    /** Light mode: how many of our credits buy one of yours. Pass null to turn it off. */
+    setExchangeRate(rate) {
+        return this.request("PUT", "/v1/exchange-rate", { body: { rate } });
+    }
+    /** Light mode: spends `credits` of ours. Add the returned `appCredits` to the user's balance in your own system. */
+    convert(input) {
+        return this.request("POST", "/v1/convert", { body: withRef(input) });
+    }
+    // ---------------------------------------------------------------- connecting users
+    /**
+     * A link to the network's connect page. The user signs in with email, approves a spending
+     * limit for your app, and comes back to `returnTo`. Nobody can charge them until they do.
+     */
+    async connectUrl(opts) {
+        const app = this.appId ?? (await this.app()).id;
+        return this.page("/connect", { app, credits: String(opts.credits), days: opts.expiresInDays, returnTo: opts.returnTo });
+    }
+    /** A link to the buy page, for a user who is out of credits. */
+    buyUrl(opts = {}) {
+        return this.page("/buy", { credits: opts.credits === undefined ? undefined : String(opts.credits), returnTo: opts.returnTo });
+    }
+    /** The user's account page, where they see their balance and can disconnect any app. */
+    accountUrl() {
+        return this.page("/account", {});
+    }
+    /** @deprecated Use accountUrl(). */
+    walletUrl() {
+        return this.accountUrl();
+    }
+    /**
+     * Swaps the one-time code from the connect page for the user's address and email. Call it from
+     * your server, then keep both in your own session. Never take an address from the browser.
+     */
+    exchangeCode(code) {
+        return this.request("POST", "/v1/connect/exchange", { body: { code } });
+    }
+    /**
+     * What the React kit shows for one of your users: your app, and their balance and limit.
+     * Pass undefined for a visitor who hasn't connected yet, and the email from `exchangeCode()` to
+     * show it in the UI.
+     */
+    async session(user, opts = {}) {
+        const app = this.appInfo ?? (this.appInfo = await this.app().then((a) => ({ id: a.id, name: a.name })));
+        if (!user)
+            return { app, user: null };
+        const u = await this.user(user);
+        return {
+            app,
+            user: { address: u.user, email: opts.email ?? null, balance: u.balance, connected: u.connected, limit: u.limit, spendable: u.spendable },
+        };
+    }
+    // ---------------------------------------------------------------- money out and reporting
+    /** Pays all your unpaid earnings in USDT to your payout address, on Whitechain. */
+    payout() {
+        return this.request("POST", "/v1/payout", { body: {} });
+    }
+    /** Every vault event for your app, newest first. */
+    activity(opts = {}) {
+        return this.request("GET", "/v1/activity", { query: { limit: opts.limit } });
+    }
+    /** Charges, holds, refunds and payouts as CSV text, for your accountant. */
+    exportCsv() {
+        return this.request("GET", "/v1/export.csv", { raw: true });
+    }
+    /** Gas the network spent on your transactions. You never pay it: the network fee covers it. */
+    gas(opts = {}) {
+        return this.request("GET", "/v1/gas", { query: { since: opts.since?.toISOString() } });
+    }
+    /**
+     * Sends every event about your app to `url` as a signed POST. Returns the signing secret once;
+     * check each delivery with `verifyWebhook`. Pass null to stop.
+     */
+    setWebhook(url) {
+        return this.request("PUT", "/v1/webhook", { body: { url } });
+    }
+    webhookDeliveries() {
+        return this.request("GET", "/v1/webhook/deliveries");
+    }
+    // ---------------------------------------------------------------- transport
+    page(path, params) {
+        const url = new URL(this.pagesUrl + path);
+        for (const [k, v] of Object.entries(params))
+            if (v !== undefined)
+                url.searchParams.set(k, String(v));
+        return url.toString();
+    }
+    /** @internal Shared by every call. Retries network failures and rate limits; throws CreditsError. */
+    async request(method, path, opts = {}) {
+        const url = new URL(this.baseUrl + path);
+        for (const [k, v] of Object.entries(opts.query ?? {}))
+            if (v !== undefined)
+                url.searchParams.set(k, String(v));
+        for (let attempt = 0;; attempt++) {
+            let res;
+            try {
+                res = await this.fetchFn(url, {
+                    method,
+                    headers: {
+                        authorization: `Bearer ${this.apiKey}`,
+                        ...(opts.body === undefined ? {} : { "content-type": "application/json" }),
+                    },
+                    body: opts.body === undefined ? undefined : JSON.stringify(opts.body),
+                    signal: AbortSignal.timeout(this.timeoutMs),
+                });
+            }
+            catch (err) {
+                if (attempt < this.retries) {
+                    await sleep(backoff(attempt));
+                    continue;
+                }
+                throw new CreditsError(`Couldn't reach ${this.baseUrl}: ${err.message}`, 0, "network");
+            }
+            if (res.status === 429 && attempt < this.retries) {
+                const wait = Number(res.headers.get("retry-after")) * 1000 || backoff(attempt);
+                if (wait <= MAX_RETRY_WAIT_MS) {
+                    await sleep(wait);
+                    continue;
+                }
+            }
+            if (opts.raw && res.ok)
+                return (await res.text());
+            const text = await res.text();
+            const data = text ? safeJson(text) : undefined;
+            if (!res.ok) {
+                const d = (data ?? {});
+                throw new CreditsError(d.error ?? `HTTP ${res.status}`, res.status, d.code ?? "error", d.txHash);
+            }
+            return data;
+        }
+    }
+}
+function amountQuery(input) {
+    return {
+        action: input.action,
+        quantity: input.quantity === undefined ? undefined : String(input.quantity),
+        credits: input.credits === undefined ? undefined : String(input.credits),
+    };
+}
+/** Every write carries a ref, so a retry after a dropped connection can never charge twice. */
+function withRef(input) {
+    return { ...input, ref: input.ref ?? randomUUID() };
+}
+function safeJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { error: text };
+    }
+}
+const backoff = (attempt) => 250 * 2 ** attempt;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

package/dist/errors.d.ts

@@ -0,0 +1,17 @@
+export declare class CreditsError extends Error {
+    /** HTTP status, or 0 when the network failed before any response. */
+    readonly status: number;
+    /** Machine-readable code, like "OverLimit", "rate_limited" or "DailyBudgetReached". */
+    readonly code: string;
+    readonly txHash?: string | undefined;
+    name: string;
+    constructor(message: string, 
+    /** HTTP status, or 0 when the network failed before any response. */
+    status: number, 
+    /** Machine-readable code, like "OverLimit", "rate_limited" or "DailyBudgetReached". */
+    code: string, txHash?: string | undefined);
+    /** The user can't pay this: over their limit, out of credits, or the app is off. Show them the buy or connect flow. */
+    get isDeclined(): boolean;
+    /** Safe to try again later with the same ref: rate limits, gas budget pauses and network failures. */
+    get isRetryable(): boolean;
+}

package/dist/errors.js

@@ -0,0 +1,35 @@
+/** Contract refusals: the user's limit, balance or the app's settings said no. Retrying won't help. */
+const DECLINED = new Set([
+    "OverLimit",
+    "LimitExpired",
+    "InsufficientBalance",
+    "OverMaxCharge",
+    "AppInactive",
+    "OverHeld",
+    "OverSpent",
+    "HoldExpired",
+]);
+export class CreditsError extends Error {
+    status;
+    code;
+    txHash;
+    name = "CreditsError";
+    constructor(message, 
+    /** HTTP status, or 0 when the network failed before any response. */
+    status, 
+    /** Machine-readable code, like "OverLimit", "rate_limited" or "DailyBudgetReached". */
+    code, txHash) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.txHash = txHash;
+    }
+    /** The user can't pay this: over their limit, out of credits, or the app is off. Show them the buy or connect flow. */
+    get isDeclined() {
+        return DECLINED.has(this.code);
+    }
+    /** Safe to try again later with the same ref: rate limits, gas budget pauses and network failures. */
+    get isRetryable() {
+        return this.status === 0 || this.status === 429 || this.status === 502 || this.status === 503;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { Credits, type CreditsOptions } from "./client.js";
+export { CreditsError } from "./errors.js";
+export { CreditsNetwork, type ClaimPreview, type Health } from "./network.js";
+export { verifyWebhook, WebhookSignatureError } from "./webhooks.js";
+export type * from "./types.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { Credits } from "./client.js";
+export { CreditsError } from "./errors.js";
+export { CreditsNetwork } from "./network.js";
+export { verifyWebhook, WebhookSignatureError } from "./webhooks.js";

package/dist/network.d.ts

@@ -0,0 +1,45 @@
+import type { Amount, DirectoryEntry, NetworkStats, Reserves } from "./types.js";
+export type Health = {
+    ok: boolean;
+    chainId: number;
+    block: number;
+    vault: string;
+    usdt: string;
+    relayer: {
+        address: string;
+        balance: string;
+        symbol: string;
+    };
+    login: "privy" | "disabled";
+    indexer: {
+        block: number;
+        head: number;
+        lag: number;
+        backed: boolean;
+        events: number;
+        pendingWebhooks: number;
+        error: string | null;
+    };
+};
+export type ClaimPreview = {
+    claimKey: string;
+    amount: Amount;
+    status: "open" | "claimed" | "cancelled" | "expired";
+    expiresAt: string;
+};
+export declare class CreditsNetwork {
+    readonly baseUrl: string;
+    private readonly fetchFn;
+    constructor(opts?: {
+        baseUrl?: string;
+        fetch?: typeof fetch;
+    });
+    health(): Promise<Health>;
+    /** The vault's USDT next to everything it owes. `backed` is checked onchain on every call. */
+    reserves(): Promise<Reserves>;
+    stats(): Promise<NetworkStats>;
+    /** Every app that accepts credits, with its prices. */
+    directory(): Promise<DirectoryEntry[]>;
+    claim(claimKey: string): Promise<ClaimPreview>;
+    private get;
+}

package/dist/network.js

@@ -0,0 +1,40 @@
+/** Calls anyone can make, with no API key: health, live reserves, network stats and the app directory. */
+import { CreditsError } from "./errors.js";
+export class CreditsNetwork {
+    baseUrl;
+    fetchFn;
+    constructor(opts = {}) {
+        this.baseUrl = (opts.baseUrl ?? "https://kredo-api.onrender.com").replace(/\/+$/, "");
+        this.fetchFn = opts.fetch ?? globalThis.fetch;
+    }
+    health() {
+        return this.get("/v1/health");
+    }
+    /** The vault's USDT next to everything it owes. `backed` is checked onchain on every call. */
+    reserves() {
+        return this.get("/v1/reserves");
+    }
+    stats() {
+        return this.get("/v1/stats");
+    }
+    /** Every app that accepts credits, with its prices. */
+    directory() {
+        return this.get("/v1/directory");
+    }
+    claim(claimKey) {
+        return this.get(`/v1/claims/${encodeURIComponent(claimKey)}`);
+    }
+    async get(path) {
+        let res;
+        try {
+            res = await this.fetchFn(this.baseUrl + path, { signal: AbortSignal.timeout(15_000) });
+        }
+        catch (err) {
+            throw new CreditsError(`Couldn't reach ${this.baseUrl}: ${err.message}`, 0, "network");
+        }
+        const data = (await res.json().catch(() => ({})));
+        if (!res.ok)
+            throw new CreditsError(data.error ?? `HTTP ${res.status}`, res.status, data.code ?? "error");
+        return data;
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,187 @@
+/** Every amount comes back exact, in USDT units, with both display forms. 1 credit = $0.01. */
+export type Amount = {
+    units: string;
+    credits: string;
+    usd: string;
+};
+/** Credits as a number or an exact decimal string, like 2 or "0.5". */
+export type Credits = number | string;
+/** What to charge: an action from your price list (times `quantity` for per-unit prices), or credits. */
+export type AmountInput = {
+    action: string;
+    quantity?: number | string;
+    credits?: never;
+} | {
+    credits: Credits;
+    action?: never;
+    quantity?: never;
+};
+export type TxInfo = {
+    txHash: string;
+    explorer?: string;
+};
+export type Quote = {
+    label: string;
+    price: Amount;
+    networkFee: Amount;
+    youEarn: Amount;
+};
+export type Operation = TxInfo & {
+    kind: "charge" | "hold" | "capture" | "release" | "refund" | "payout" | "convert";
+    ref?: string;
+    user?: string;
+    amount: Amount;
+    fee?: Amount;
+    label?: string;
+    holdId?: string;
+    at: string;
+    /** True when this ref was already used, and this is the first result again. Nothing was charged twice. */
+    replayed?: boolean;
+};
+export type Hold = Operation & {
+    kind: "hold";
+    holdId: string;
+    expiresAt: string;
+};
+export type HoldStatus = TxInfo & {
+    holdId: string;
+    user: string;
+    amount: Amount;
+    label: string;
+    status: "open" | "captured" | "released";
+    expiresAt: string;
+};
+export type Capture = Operation & {
+    kind: "capture";
+    returned: Amount;
+};
+export type UserState = {
+    user: string;
+    balance: Amount;
+    /** The user approved this app and the limit isn't used up or expired. */
+    connected: boolean;
+    /** What this app may still charge. */
+    limit: Amount;
+    limitExpiresAt: string | null;
+    /** The smaller of balance and limit: the most a charge can be right now. */
+    spendable: Amount;
+};
+/** Flat price, or a per-unit rate that's multiplied by `quantity`. In credits. */
+export type PriceEntry = {
+    price: string;
+} | {
+    rate: string;
+    unit: string;
+};
+export type PriceList = Record<string, PriceEntry>;
+export type PriceListInput = Record<string, {
+    price: Credits;
+} | {
+    rate: Credits;
+    unit: string;
+}>;
+export type AppInfo = {
+    id: string;
+    name: string;
+    payout: string;
+    feeBps: number;
+    maxCharge: Amount | null;
+    active: boolean;
+    unpaidEarnings: Amount;
+    prices: PriceList;
+    exchangeRate: string | null;
+    webhookUrl: string | null;
+    apiKeyPrefix: string;
+};
+export type Conversion = Operation & {
+    kind: "convert";
+    appCredits: string;
+};
+export type Payout = Operation & {
+    kind: "payout";
+    to: string;
+    usdt: string;
+};
+export type GasReport = {
+    transactions: number;
+    wei: string;
+    gas: string;
+    symbol: string;
+    paidBy: "network";
+};
+/** One vault event, newest first in every feed. */
+export type ActivityItem = {
+    id: string;
+    type: string;
+    at: string;
+    user?: string;
+    app?: string;
+    appName?: string;
+    from?: string;
+    to?: string;
+    amount?: Amount;
+    fee?: Amount;
+    returned?: Amount;
+    ref?: string;
+    label?: string;
+    holdId?: string;
+    claimKey?: string;
+    block: number;
+    txHash: string;
+    explorer?: string;
+};
+export type WebhookDelivery = {
+    id: string;
+    type: string;
+    status: "pending" | "delivered" | "failed";
+    attempts: number;
+    lastStatus: number | null;
+    lastError: string | null;
+};
+export type WebhookEvent = {
+    id: string;
+    type: "charge.succeeded" | "hold.created" | "hold.captured" | "hold.released" | "refund.succeeded" | "connection.approved" | "connection.revoked" | "payout.paid";
+    createdAt: string;
+    data: ActivityItem;
+};
+export type Reserves = {
+    backed: boolean;
+    usdtInVault: Amount;
+    owed: Amount;
+    surplus: Amount;
+    breakdown: Record<"userBalances" | "held" | "claimLinks" | "companyEarnings" | "networkFees", Amount>;
+    vault: string;
+    explorer?: string;
+};
+export type NetworkStats = {
+    apps: number;
+    users: number;
+    events: number;
+    deposited: Amount;
+    spent: Amount;
+    networkFees: Amount;
+    refunded: Amount;
+    paidOut: Amount;
+    indexedToBlock: number;
+};
+export type DirectoryEntry = {
+    id: string;
+    name: string;
+    prices: PriceList;
+    exchangeRate: string | null;
+};
+/** The state the React kit renders, as your backend returns it from `credits.session()`. */
+export type CreditsSession = {
+    app: {
+        id: string;
+        name: string;
+    };
+    user: {
+        address: string;
+        email: string | null;
+        balance: Amount;
+        connected: boolean;
+        limit: Amount;
+        spendable: Amount;
+    } | null;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/webhooks.d.ts

@@ -0,0 +1,8 @@
+import type { WebhookEvent } from "./types.js";
+export declare class WebhookSignatureError extends Error {
+    name: string;
+}
+export declare function verifyWebhook(rawBody: string | Buffer, signatureHeader: string | null | undefined, secret: string, opts?: {
+    toleranceSeconds?: number;
+    now?: number;
+}): WebhookEvent;

package/dist/webhooks.js

@@ -0,0 +1,39 @@
+/**
+ * Checks a webhook really came from the network, then parses it.
+ *
+ *   app.post("/credits-webhook", express.raw({ type: "application/json" }), (req, res) => {
+ *     const event = verifyWebhook(req.body, req.header("x-credits-signature"), process.env.CREDITS_WEBHOOK_SECRET);
+ *     if (event.type === "hold.released") refundTheJob(event.data.holdId);
+ *     res.sendStatus(200);
+ *   });
+ *
+ * Pass the raw body, exactly as received: re-serialised JSON won't match the signature.
+ */
+import { createHmac, timingSafeEqual } from "node:crypto";
+export class WebhookSignatureError extends Error {
+    name = "WebhookSignatureError";
+}
+/** Rejects deliveries signed more than 5 minutes ago, so a captured request can't be replayed later. */
+const DEFAULT_TOLERANCE_SECONDS = 300;
+export function verifyWebhook(rawBody, signatureHeader, secret, opts = {}) {
+    if (!signatureHeader)
+        throw new WebhookSignatureError("Missing x-credits-signature header");
+    const parts = Object.fromEntries(signatureHeader.split(",").map((p) => {
+        const i = p.indexOf("=");
+        return [p.slice(0, i).trim(), p.slice(i + 1).trim()];
+    }));
+    const t = Number(parts.t);
+    if (!Number.isInteger(t) || !parts.v1)
+        throw new WebhookSignatureError("Malformed x-credits-signature header");
+    const now = opts.now ?? Math.floor(Date.now() / 1000);
+    if (Math.abs(now - t) > (opts.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS)) {
+        throw new WebhookSignatureError("Webhook timestamp is too old");
+    }
+    const body = typeof rawBody === "string" ? rawBody : rawBody.toString("utf8");
+    const expected = createHmac("sha256", secret).update(`${t}.${body}`).digest();
+    const given = Buffer.from(parts.v1, "hex");
+    if (given.length !== expected.length || !timingSafeEqual(given, expected)) {
+        throw new WebhookSignatureError("Webhook signature doesn't match");
+    }
+    return JSON.parse(body);
+}

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "kredo",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Server kit for charging Kredo credits from a company backend",
+  "license": "MIT",
+  "homepage": "https://kredo-omega.vercel.app/docs/sdk",
+  "keywords": [
+    "kredo",
+    "credits",
+    "payments",
+    "usdt",
+    "whitechain",
+    "sdk"
+  ],
+  "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"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test \"test/**/*.test.ts\"",
+    "e2e": "tsx examples/e2e.ts"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.43",
+    "tsx": "^4.23.15",
+    "typescript": "^5.9.3",
+    "viem": "^2.57.16"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}