@usebillow/sdk 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# @usebillow/sdk
+
+## 0.5.0
+
+### Minor Changes
+
+- c6c114a: Prepaid credits can be sold as Credit Packs. `credits.packs.list(currency)` lists the packs a customer can buy in one currency, cheapest first, with each pack's price, tax and total (Money), its credits and bonus (decimal strings of microcredits), `pricePerCredit` and `savingsBps`; `credits.packs.create`, `get` and `update` configure them. `credits.topUps.create(input, { idempotencyKey })` buys a pack and answers the top-up with its `checkoutUrl` and `replayed` flag, `credits.topUps.get` reads one, and `credits.topUps.list(customer, { status })` pages a customer's top-ups by cursor. Webhook payload types cover the new `credit_top_up.succeeded`, `credit_top_up.failed`, `credit_top_up.refunded` and `credit_top_up.unfulfilled` events, the customer data export types carry `topUps` and `reversals`, and `reversal_exceeds_consumption` joins the error codes.
+- 6bf89c8: First public release on npm as `@usebillow/sdk`, under the MIT license. Ships dual ESM and CommonJS builds with complete type declarations for every entry point: `@usebillow/sdk`, `/config`, `/server`, `/react`, `/webhooks`, `/ingestion` and `/status`.
+- 6bf89c8: A client with no `baseUrl` option and no `BILLOW_URL` environment variable now talks to the hosted API at `https://api.usebillow.com`, instead of `http://localhost:4001` with a warning. Local development and self-hosted servers set `baseUrl` (or `BILLOW_URL`).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DevCoat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,274 @@
+# @usebillow/sdk
+
+The official client SDK for [Billow](https://usebillow.com) - a self-hostable billing
+layer over Paymob & Stripe. Fully typed, ESM + CJS, with first-class React support.
+
+```bash
+npm install @usebillow/sdk
+```
+
+## Server client
+
+The core client holds your **secret** key and is used server-side only.
+
+```ts
+import { Billow } from "@usebillow/sdk";
+
+const billow = new Billow(process.env.BILLOW_SECRET_KEY!);
+
+const allowed = await billow.check({ customerId, featureId: "projects" });
+await billow.track({ customerId, featureId: "api_calls", value: 1 });
+const { entitlements } = await billow.entitlements(customerId);
+```
+
+The client talks to the hosted API, `https://api.usebillow.com`. For local development or a
+self-hosted server, set the `baseUrl` option (or the `BILLOW_URL` environment variable, which the
+option overrides):
+
+```ts
+const billow = new Billow(process.env.BILLOW_SECRET_KEY!, {
+  baseUrl: "http://localhost:4001", // your local Billow server
+});
+```
+
+For a server-controlled off-session payment, charge the customer's active default saved card
+with a required idempotency key:
+
+```ts
+await billow.charges.createMerchantInitiated(
+  {
+    customerId,
+    paymentMethodId,
+    amount: 5_000,
+    currency: "EGP",
+    items: [{ name: "Automatic top-up", amount: 5_000, quantity: 1 }],
+  },
+  { idempotencyKey: `topup:${attemptId}` },
+);
+```
+
+Refunds take a required idempotency key too: retrying under the same key (after a timeout, say)
+returns the same refund instead of refunding twice, with `replayed: true`. Pass `{}` instead of
+`{ amount }` to refund the whole remaining balance:
+
+```ts
+const refund = await billow.charges.refund(
+  chargeId,
+  { amount: 2_000 },
+  { idempotencyKey: `refund:${requestId}` },
+);
+if (refund.status === "failed") {
+  // The provider declined it: nothing was refunded. Ask again under a new key.
+}
+```
+
+Check `status` even when the call resolves. A refund the provider declines answers
+`502 provider_error`, which throws by default; with `maxRetries` above 0 the SDK retries that 502
+under the same key and resolves with the declined refund (`status: "failed"`, `replayed: true`).
+
+Prepaid credit grants take a required idempotency key as well; a retry under it returns the same
+grant with `replayed: true`. Credit quantities are decimal strings of microcredits
+(1 credit = 1,000,000), never numbers - use `BigInt` for arithmetic:
+
+```ts
+const grant = await billow.credits.grants.create(
+  { customerId, kind: "promotional", amount: "5000000" },
+  { idempotencyKey: `welcome:${customerId}` },
+);
+```
+
+Read a customer's credits back - the balance (true at its `asOf`), the ledger newest first (it
+pages by cursor, so entries arriving mid-walk are never skipped or repeated), and daily usage:
+
+```ts
+const balance = await billow.credits.balance.get(customerId);
+for await (const entry of billow.credits.ledger.list(customerId)) {
+  // entry.type, entry.availableDelta, entry.availableAfter, ...
+}
+const usage = await billow.credits.usage.get(customerId, { groupBy: "category" });
+```
+
+## Auto-metering (LLM tokens & any usage source)
+
+Stop hand-instrumenting usage. `@usebillow/sdk/ingestion` wraps your calls and reports
+usage to `track()` for you - **server-side only** (a browser can't be trusted to
+self-report) and **non-blocking** (metering can never delay or break the wrapped
+call; a failed `track()` retries under an idempotency key, then drops silently).
+
+```ts
+import { Billow } from "@usebillow/sdk";
+import { createUsageMeter, meterOpenAI } from "@usebillow/sdk/ingestion";
+import OpenAI from "openai";
+
+const billow = new Billow(process.env.BILLOW_SECRET_KEY!);
+const meter = createUsageMeter(billow);
+
+// Every completion now auto-meters its token usage (read from the provider response).
+const openai = meterOpenAI(new OpenAI(), {
+  meter,
+  feature: "tokens",
+  customer: (params) => params.user as string, // your billow customer id
+});
+
+await openai.chat.completions.create({ model: "gpt-4o", messages, user: "cus_123" });
+// For a STREAMED call, add stream_options:{ include_usage:true } so tokens can be counted.
+// Streamed calls are metered when consumed the normal way (await, then `for await`).
+// Consuming via `.tee()` / `.toReadableStream()` / `.withResponse()` still works but
+// bypasses the token tap.
+```
+
+Vercel AI SDK - meter the result of `generateText`/`streamText` (never touches the
+stream). Works with v4 and v5 usage shapes:
+
+```ts
+import { meterAIResult } from "@usebillow/sdk/ingestion";
+
+const result = streamText({ model, prompt });
+meterAIResult(result, { meter, feature: "tokens", customer: "cus_123" });
+return result.toDataStreamResponse();
+```
+
+Any other source - wrap any async function with the generic primitive:
+
+```ts
+import { meterFunction } from "@usebillow/sdk/ingestion";
+
+const upload = meterFunction(putObject, meter, (res, [file]) => ({
+  customerId: file.ownerId,
+  featureId: "storage_bytes",
+  value: res.size,
+}));
+```
+
+In serverless handlers with a **non-streamed** response (`generateText`, a blocking
+completion), `await meter.flush()` before returning so buffered records aren't lost
+when the process freezes. Do **not** await `flush()` before returning a **streamed**
+response - a stream's usage resolves only after the client consumes it, so blocking
+on flush first would hang the response. There, flush after the stream finishes (the
+AI SDK's `onFinish`, or your platform's `waitUntil`); `meterAIResult` already tracks
+the pending usage so it's recorded in the background.
+
+## React (Next.js, Remix, …)
+
+Mount the server handler so the browser never sees your secret key, then use the hooks.
+The customer is resolved from **your** session - never chosen by the browser.
+
+```ts
+// app/api/billow/[...billow]/route.ts
+import { createBillowHandler } from "@usebillow/sdk/server";
+import { billow } from "@/lib/billow";
+
+const handler = createBillowHandler(billow, {
+  identify: async (req) => getUserIdFromSession(req),
+});
+export { handler as GET, handler as POST };
+```
+
+```tsx
+// app/providers.tsx
+"use client";
+import { BillowProvider, useCheck, useEntitlements } from "@usebillow/sdk/react";
+
+export function Providers({ children }) {
+  return <BillowProvider basePath="/api/billow">{children}</BillowProvider>;
+}
+```
+
+## Pricing table (publishable key, no backend)
+
+Read the public catalog straight from the browser with a **publishable** key
+(`bl_<env>_pk_…`) - CORS is enabled for the catalog, so a pure SPA needs no backend:
+
+```tsx
+import { usePublishableProducts } from "@usebillow/sdk/react";
+
+function Pricing() {
+  const { products, isLoading } = usePublishableProducts({
+    publishableKey: "bl_live_pk_…",
+    baseUrl: "https://api.usebillow.com",
+  });
+  if (isLoading) return null;
+  return products.map((p) => /* render p.name + p.prices */ null);
+}
+```
+
+Publishable keys read only public product/price data. Customer entitlements and
+checkout still go through the server handler (above) or a portal session.
+
+## Verify webhooks
+
+Verification is async (Web Crypto) so it runs in Node, edge, and Workers alike.
+Always pass the **raw** request body.
+
+```ts
+import { constructEvent } from "@usebillow/sdk/webhooks";
+
+const event = await constructEvent(rawBody, req.headers["billow-signature"], endpointSecret);
+switch (event.type) {
+  case "invoice.paid": // event.data is typed
+    break;
+}
+```
+
+`constructEvent` throws `WebhookVerificationError` on a bad signature or a timestamp
+outside the freshness window (default 5 min). Use `verifySignature(...)` for a
+boolean check.
+
+## Config as code
+
+```ts
+import { defineConfig, syncConfig } from "@usebillow/sdk/config";
+
+const config = defineConfig({ features: [/* … */], products: [/* … */] });
+await syncConfig(billow, config); // additive - never deletes
+```
+
+
+## Pay an outstanding invoice
+
+Call from your backend with a secret key after checking that the signed-in customer owns the invoice:
+
+```ts
+const payment = await billow.invoices.pay(invoiceId, {
+  returnUrl: "https://your-app.example/billing",
+});
+// Redirect the customer to payment.checkoutUrl.
+```
+
+REST: `POST /v1/invoices/:id/pay` with `{ "returnUrl": "https://your-app.example/billing" }`.
+The response contains `invoiceId`, `chargeId`, `checkoutUrl`, `status: "processing"`, and `expiresAt`.
+The amount comes from the existing open invoice, including tax. An active checkout is reused;
+conflicting or unresolved payments return HTTP 409. Never put a secret key in a browser link.
+
+For a customer-scoped portal session, use `portal.invoices.pay(invoiceId)` or
+`POST /portal/invoices/:id/pay`. Billow enforces invoice ownership for that session.
+The hosted portal also offers Pay now on its overview and invoice list.
+
+A redirect back to your application does not prove payment. Refresh the invoice/subscription or
+handle the signed `invoice.paid` and subscription events. Confirmed payment settles the same invoice
+and restores a past-due subscription through Billow's normal settlement process.
+
+### Saved card management
+
+List, choose a default, or remove a customer's saved cards from your server:
+
+```ts
+const cards = await billow.customers.paymentMethods.list(customerId);
+await billow.customers.paymentMethods.setDefault(customerId, cardId);
+await billow.customers.paymentMethods.remove(customerId, cardId);
+```
+
+A `BillowPortal` client offers the same operations as `portal.paymentMethods.list()`,
+`portal.paymentMethods.setDefault(cardId)`, and `portal.paymentMethods.remove(cardId)`.
+Its session fixes the customer identity. Responses include masked card details,
+`expiryStatus`, `canSetDefault`, `canRemove`, and `removalBlockedReason`; never card tokens.
+
+Choosing a default updates renewal cards on active, trialing, and past-due subscriptions.
+A default or subscription renewal card cannot be removed until a replacement is selected.
+Once those subscriptions have ended, every card can be removed, including the default.
+Cards remain valid through their expiry month and are flagged during their last three
+calendar months. Missing expiry data is reported as `unknown`.
+
+## License
+
+MIT. See the `LICENSE` file shipped with this package.