perly-pay 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Perly
+
+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

@@ -1,3 +1,209 @@
-# Temporary Holding Version
+# perly-pay
 
-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.
+Crypto payments straight to your wallet — bitcoin and dollar stablecoins,
+0% of volume. The server SDK for the [Perly Pay API](https://pay.perly.io/docs/api).
+
+- TypeScript, **zero dependencies**, plain `fetch` (Node 18+, Deno, Bun, workers, edge)
+- every POST carries an **Idempotency-Key**, reused across retries
+- retries on 429 / 5xx / network errors with backoff, honouring `Retry-After`
+- `webhooks.verify` checks `Perly-Signature` in constant time, synchronously
+
+## Five minutes
+
+**1. Install and make a client** with your secret key (Dashboard → Developers).
+A `sk_test_…` key works in test mode: test networks, nothing real moves.
+
+```bash
+npm install perly-pay
+```
+
+```ts
+import { PerlyPay } from "perly-pay";
+
+const pay = new PerlyPay(process.env.PERLY_PAY_SECRET_KEY!);
+```
+
+**2. Sell something.**
+
+```ts
+const product = await pay.products.create({ name: "Pro plan" });
+const price = await pay.prices.create({
+  product: product.id,
+  model: "one_time",
+  unit_amount: 4900, // $49.00 — always integers, in cents
+});
+```
+
+**3. Take a payment.** Make a checkout session and send the buyer to its `url`
+(or open it over your page with [pay.js](#on-your-page)).
+
+```ts
+const session = await pay.checkoutSessions.create({
+  line_items: [{ price: price.id, quantity: 1 }],
+  return_url: "https://shop.example/thanks",
+});
+redirect(session.url);
+```
+
+The buyer picks bitcoin or USDC/USDT, pays from any wallet, and the money lands
+in **your** wallet. Perly Pay never holds it.
+
+**4. Hear about it.** Add an endpoint once and keep its secret:
+
+```ts
+const endpoint = await pay.webhookEndpoints.create({
+  url: "https://shop.example/webhooks/perly",
+  enabled_events: ["invoice.paid", "invoice.fulfilled", "refund.confirmed"],
+});
+// endpoint.secret — "whsec_…", shown only now
+```
+
+Then verify every delivery on the **raw** body:
+
+```ts
+// Next.js route handler
+export async function POST(request: Request) {
+  const raw = await request.text();
+  const event = pay.webhooks.verify(raw, request.headers.get("perly-signature"), process.env.PERLY_PAY_WEBHOOK_SECRET!);
+  if (event.type === "invoice.fulfilled") await grantAccess(event.object_id);
+  return new Response(null, { status: 204 });
+}
+```
+
+A signature older than five minutes is refused (replays), and any change to the body breaks it.
+With Express, take the raw bytes: `express.raw({ type: "application/json" })`, then `pay.webhooks.verify(req.body, req.header("Perly-Signature"), secret)`.
+
+**5. Try it without a wallet** (test keys only):
+
+```ts
+const invoice = await pay.invoices.create({ line_items: [{ price: price.id }], customer_email: "ada@example.com" });
+await pay.invoices.simulate(invoice.id); // paid, fulfilled, receipt, webhooks ({ outcome: "short" | "over" } too)
+```
+
+## More
+
+```ts
+// Does this customer have access right now?
+const { has_access } = await pay.entitlements.check({ customer_email: "ada@example.com", product: product.id });
+
+// Subscriptions renew by invoice — no auto-debit.
+const sub = await pay.subscriptions.create({ customer: "cus_…", price: "price_…" });
+await pay.subscriptions.update(sub.id, { cancel_at_period_end: true });
+
+// Refunds are non-custodial: the buyer gives an address, you send from your wallet.
+const quote = await pay.refunds.quote({ invoice: invoice.id });
+const refund = await pay.refunds.create({ invoice: invoice.id });
+// …when refund.status is "ready_to_send", send refund.amount_to_send to refund.refund_address, then:
+await pay.refunds.markSent(refund.id, { txid: "0x…" });
+
+// Every page of a list
+for await (const inv of pay.invoices.listAll({ status: "paid", limit: 100 })) console.log(inv.id);
+
+// A receipt as PDF
+const pdf = await pay.receipts.pdf("rcpt_…");
+```
+
+### Credits
+
+Sell credits for an API or an AI service: the buyer tops up on their own page and pays — never an auto-debit — and your server spends them a call at a time. The customer is a `cus_…` id, an email, or your own id for them (`external_id`).
+
+```ts
+const { balance, low, top_up_url } = await pay.credits.balance("user_42");
+
+// Never below zero; a retry with the same key never spends twice.
+try {
+  await pay.credits.consume("user_42", 3, { action: "chat", idempotencyKey: requestId });
+} catch (e) {
+  if (e instanceof InvalidRequestError && e.code === "insufficient_credits") return sendTopUp(await pay.credits.topUpUrl("user_42"));
+  throw e;
+}
+```
+
+Webhooks `credits.low` (the product's threshold, set in the dashboard) and `credits.depleted` arrive once per crossing.
+
+### License keys from your app
+
+Your app never holds a secret key. `LicenseClient` calls the public license endpoints with the buyer's key alone:
+
+```ts
+import { LicenseClient } from "perly-pay";
+
+const licenses = new LicenseClient();
+const result = await licenses.activate({ key: userKey, product: "prod_…", instance_name: os.hostname() });
+if (!result.valid) showWhy(result.reason); // "limit_reached", "revoked", "expired", …
+```
+
+## Errors
+
+Every failure throws a `PerlyPayError` (`InvalidRequestError`, `AuthenticationError`,
+`PermissionError`, `RateLimitError`, `IdempotencyError`, `APIError`, `ConnectionError`) carrying the
+API's `type`, `code`, `message`, `param`, the HTTP `status` and the `requestId` to quote to support.
+
+```ts
+try {
+  await pay.invoices.create({ line_items: [] });
+} catch (e) {
+  if (e instanceof InvalidRequestError) console.log(e.code, e.param); // "parameter_invalid", "line_items"
+}
+```
+
+## Amounts
+
+Fiat amounts are integers in minor units (`4900` = $49.00). On-chain amounts are integer **strings** in the
+asset's smallest unit (`"10000000"` USDC = 10.00 USDC; satoshis for bitcoin) — use `BigInt`, never floats.
+
+## Options
+
+```ts
+new PerlyPay(key, {
+  baseUrl: "https://pay.perly.io", // or http://localhost:3200 against a local stack
+  maxRetries: 2,
+  timeoutMs: 30_000,
+  fetch: customFetch,
+});
+await pay.invoices.create(params, { idempotencyKey: `order-${orderId}` });
+```
+
+## Testing your webhook handler
+
+```ts
+import { webhooks } from "perly-pay";
+const { body, headers } = webhooks.testRequest({ id: "evt_1", type: "invoice.paid", /* … */ }, secret);
+await handler(new Request("http://localhost/webhooks", { method: "POST", body, headers }));
+```
+
+## On your page
+
+pay.js opens the hosted checkout over your page. Load it pinned, with its
+`integrity`, so a changed file never runs on your page:
+
+<!-- pay.js snippet: generated by packages/embed/build.mjs -->
+```html
+<script src="https://pay.perly.io/pay/v1.999bed6b66c7.js"
+  integrity="sha384-mZvta2bHoZN4yW6xg4DvV5Jb9jS7TPg+Pq1Upm5VFEOFdgubm8MmsAYgVHNNW45N"
+  crossorigin="anonymous" defer></script>
+```
+<!-- /pay.js snippet -->
+
+```html
+<button data-perly-pay data-session="cs_…">Pay</button>
+<script>
+  addEventListener("perlypay:paid", (e) => location.assign("/thanks?invoice=" + e.detail.invoice));
+</script>
+```
+
+Add your site's origin under Dashboard → Settings → Checkout so the checkout may be framed there.
+
+## Links
+
+- Docs: <https://pay.perly.io/docs> · API reference: <https://pay.perly.io/docs/api> · SDKs: <https://pay.perly.io/docs/sdks>
+- OpenAPI: <https://pay.perly.io/api/v1/openapi.json>
+- PHP: [`perly/perly-pay`](https://pay.perly.io/docs/sdks) on Composer, the same calls and the same webhook check
+
+## Build
+
+`npm run build` (in `packages/sdk`) writes ESM + `.d.ts` to `dist/`. Node 18.17+.
+
+## License
+
+MIT. The SDK is open source; the Perly Pay service it talks to is not.

package/dist/cli/bin.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/** `npx perly-pay …` lands here. */
+import { main, nodeIO } from "./main.js";
+main({ argv: process.argv.slice(2), cwd: process.cwd(), io: nodeIO() }).then(
+// exitCode, not exit(): on macOS a piped stdout is written asynchronously, and exit() would cut it short.
+(code) => {
+    process.exitCode = code;
+}, (error) => {
+    process.stderr.write(`perly-pay: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`);
+    process.exitCode = 1;
+});

package/dist/cli/detect.js

@@ -0,0 +1,168 @@
+/**
+ * What kind of project `npx perly-pay init` is standing in: the framework,
+ * the package manager, TypeScript or not, ES modules or CommonJS, and
+ * where the code and the keys go. Reads files only — never runs anything.
+ */
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+export const FRAMEWORKS = ["next", "express", "hono", "laravel", "node"];
+export const FRAMEWORK_NAMES = {
+    next: "Next.js (App Router)",
+    express: "Express",
+    hono: "Hono",
+    laravel: "Laravel",
+    node: "Node.js",
+};
+export class DetectError extends Error {
+}
+function readJson(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        return parsed && typeof parsed === "object" ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function isDir(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function depsOf(pkg, ...fields) {
+    const out = {};
+    for (const field of fields) {
+        const deps = pkg?.[field];
+        if (deps && typeof deps === "object")
+            Object.assign(out, deps);
+    }
+    return out;
+}
+/** The framework the files say, or null when nothing here looks like a project. */
+export function detectFramework(dir) {
+    const composer = readJson(join(dir, "composer.json"));
+    if (existsSync(join(dir, "artisan")) || "laravel/framework" in depsOf(composer, "require"))
+        return "laravel";
+    const pkg = readJson(join(dir, "package.json"));
+    if (!pkg)
+        return null;
+    const deps = depsOf(pkg, "dependencies", "devDependencies");
+    if ("next" in deps)
+        return "next";
+    if ("hono" in deps)
+        return "hono";
+    if ("express" in deps)
+        return "express";
+    return "node";
+}
+export function detectPackageManager(dir, framework) {
+    if (framework === "laravel")
+        return "composer";
+    const declared = readJson(join(dir, "package.json"))?.packageManager;
+    if (typeof declared === "string") {
+        const name = declared.split("@")[0];
+        if (name === "pnpm" || name === "yarn" || name === "bun" || name === "npm")
+            return name;
+    }
+    if (existsSync(join(dir, "pnpm-lock.yaml")))
+        return "pnpm";
+    if (existsSync(join(dir, "yarn.lock")))
+        return "yarn";
+    if (existsSync(join(dir, "bun.lockb")) || existsSync(join(dir, "bun.lock")))
+        return "bun";
+    return "npm";
+}
+/** The tsconfig's `module`, lower-case, when it says one (comments and trailing commas tolerated). */
+function tsModule(dir) {
+    try {
+        const text = readFileSync(join(dir, "tsconfig.json"), "utf8");
+        const match = /"module"\s*:\s*"([^"]+)"/i.exec(text);
+        return match?.[1]?.toLowerCase() ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+export function detectProject(dir, forced) {
+    const found = detectFramework(dir);
+    const framework = forced ?? found;
+    if (!framework) {
+        throw new DetectError("No package.json or composer.json here. Run this in your project's folder, or pass --framework.");
+    }
+    const notes = [];
+    if (forced && found && forced !== found)
+        notes.push(`This looks like ${FRAMEWORK_NAMES[found]}; using ${FRAMEWORK_NAMES[forced]} as asked.`);
+    const packageManager = detectPackageManager(dir, framework);
+    const pkg = readJson(join(dir, "package.json"));
+    const deps = depsOf(pkg, "dependencies", "devDependencies");
+    if (framework === "laravel") {
+        const composer = readJson(join(dir, "composer.json"));
+        return {
+            dir,
+            framework,
+            packageManager,
+            style: "esm",
+            base: "",
+            appDir: "",
+            envFile: ".env",
+            hasSdk: "perly/perly-pay" in depsOf(composer, "require"),
+            loadsEnv: true,
+            notes,
+        };
+    }
+    const typescript = existsSync(join(dir, "tsconfig.json")) || "typescript" in deps;
+    const style = typescript ? "ts" : framework === "next" || pkg?.type === "module" ? "esm" : "cjs";
+    const mod = typescript ? tsModule(dir) : null;
+    if (typescript && framework !== "next" && mod === "commonjs") {
+        notes.push('tsconfig compiles to CommonJS, and perly-pay is an ES module: set "module": "nodenext" (or run with tsx).');
+    }
+    let base = "";
+    let appDir = "";
+    if (framework === "next") {
+        if (isDir(join(dir, "src", "app")))
+            appDir = "src/app";
+        else if (isDir(join(dir, "app")))
+            appDir = "app";
+        else if (isDir(join(dir, "src")))
+            appDir = "src/app";
+        else
+            appDir = "app";
+        base = appDir.startsWith("src/") ? "src/" : "";
+        if (!isDir(join(dir, appDir)) && (isDir(join(dir, "pages")) || isDir(join(dir, "src", "pages")))) {
+            notes.push(`No App Router yet: the routes go in ${appDir}/, which Next.js serves beside pages/.`);
+        }
+    }
+    else if (isDir(join(dir, "src"))) {
+        base = "src/";
+    }
+    return {
+        dir,
+        framework,
+        packageManager,
+        style,
+        base,
+        appDir,
+        envFile: framework === "next" ? ".env.local" : ".env",
+        hasSdk: "perly-pay" in deps,
+        // Next.js loads .env.local itself; elsewhere something must.
+        loadsEnv: framework === "next" || "dotenv" in deps || "@dotenvx/dotenvx" in deps,
+        notes,
+    };
+}
+export function installCommand(project) {
+    switch (project.packageManager) {
+        case "composer":
+            return "composer require perly/perly-pay";
+        case "pnpm":
+            return "pnpm add perly-pay";
+        case "yarn":
+            return "yarn add perly-pay";
+        case "bun":
+            return "bun add perly-pay";
+        default:
+            return "npm install perly-pay";
+    }
+}

package/dist/cli/env.js

@@ -0,0 +1,146 @@
+/**
+ * The keys file (`.env.local` / `.env`) and the `.gitignore` that keeps it
+ * out of git. Pure string work, so it is tested without a disk.
+ */
+export const KEY_VAR = "PERLY_PAY_SECRET_KEY";
+export const WEBHOOK_SECRET_VAR = "PERLY_PAY_WEBHOOK_SECRET";
+export const API_VAR = "PERLY_PAY_API";
+export const DEFAULT_API = "https://pay.perly.io";
+const line = (name) => new RegExp(`^[ \\t]*(?:export[ \\t]+)?${name}[ \\t]*=(.*)$`, "m");
+/** A variable's value in a dotenv file ("" when set empty), or null when absent. Quotes and a trailing comment are dropped. */
+export function readEnvValue(content, name) {
+    const match = line(name).exec(content);
+    if (!match)
+        return null;
+    let value = (match[1] ?? "").trim();
+    const quoted = /^(['"])(.*)\1$/.exec(value);
+    if (quoted)
+        return quoted[2] ?? "";
+    if (value.startsWith("#"))
+        return "";
+    value = value.replace(/\s+#.*$/, "");
+    return value;
+}
+/**
+ * Adds or fills each variable. A variable that already has a value is kept
+ * unless `force` (or its own `replace`) says otherwise; an empty one is filled.
+ */
+export function upsertEnv(content, entries, force = false) {
+    let out = content;
+    const outcomes = {};
+    const added = [];
+    for (const entry of entries) {
+        const current = readEnvValue(out, entry.name);
+        if (current === null) {
+            if (entry.comment)
+                added.push(`# ${entry.comment}`);
+            added.push(`${entry.name}=${entry.value}`);
+            outcomes[entry.name] = "added";
+        }
+        else if (current === entry.value) {
+            outcomes[entry.name] = "unchanged";
+        }
+        else if (current === "" || force || entry.replace) {
+            out = out.replace(line(entry.name), () => `${entry.name}=${entry.value}`);
+            outcomes[entry.name] = "replaced";
+        }
+        else {
+            outcomes[entry.name] = "kept";
+        }
+    }
+    if (added.length) {
+        const sep = out === "" ? "" : out.endsWith("\n") ? "\n" : "\n\n";
+        out = `${out}${sep}# Perly Pay (npx perly-pay init). Keep this file out of git.\n${added.join("\n")}\n`;
+    }
+    return { content: out, outcomes };
+}
+function globToRegex(glob) {
+    let re = "";
+    for (let i = 0; i < glob.length; i++) {
+        const c = glob[i];
+        if (c === "*") {
+            if (glob[i + 1] === "*") {
+                re += ".*";
+                i++;
+                if (glob[i + 1] === "/")
+                    i++;
+            }
+            else
+                re += "[^/]*";
+        }
+        else if (c === "?")
+            re += "[^/]";
+        else if (c === "[") {
+            const end = glob.indexOf("]", i + 1);
+            if (end > i) {
+                re += glob.slice(i, end + 1).replace(/^\[!/, "[^");
+                i = end;
+            }
+            else
+                re += "\\[";
+        }
+        else
+            re += c.replace(/[.+^${}()|\\]/g, "\\$&");
+    }
+    return re;
+}
+/**
+ * Whether a root `.gitignore` ignores the file at `path` (relative, "/"-separated).
+ * The common subset of git's rules: globs, `**`, a leading `/` anchors, a
+ * trailing `/` matches folders, `!` re-includes, the last match wins.
+ */
+export function gitignoreIgnores(gitignore, path) {
+    const parts = path.split("/");
+    let ignored = false;
+    for (const raw of gitignore.split(/\r?\n/)) {
+        let pattern = raw.replace(/(?<!\\)\s+$/, "");
+        if (!pattern || pattern.startsWith("#"))
+            continue;
+        const negate = pattern.startsWith("!");
+        if (negate)
+            pattern = pattern.slice(1);
+        const dirOnly = pattern.endsWith("/");
+        if (dirOnly)
+            pattern = pattern.slice(0, -1);
+        const anchored = pattern.includes("/");
+        pattern = pattern.replace(/^\//, "");
+        const re = new RegExp(`^${globToRegex(pattern)}$`);
+        let hit = false;
+        if (anchored) {
+            // The pattern names a path from the root: the file itself, or a folder above it.
+            for (let n = dirOnly ? parts.length - 1 : parts.length; n >= 1 && !hit; n--)
+                hit = re.test(parts.slice(0, n).join("/"));
+        }
+        else {
+            // A bare name matches at any depth: the file's name, or any folder above it.
+            const names = dirOnly ? parts.slice(0, -1) : parts;
+            hit = names.some((name) => re.test(name));
+        }
+        if (hit)
+            ignored = !negate;
+    }
+    return ignored;
+}
+/** `.gitignore` with the keys file added when it is not ignored yet; null when it already is. */
+export function ensureIgnored(gitignore, path) {
+    const current = gitignore ?? "";
+    if (gitignoreIgnores(current, path))
+        return null;
+    const sep = current === "" ? "" : current.endsWith("\n") ? "\n" : "\n\n";
+    return `${current}${sep}# Perly Pay keys (npx perly-pay init)\n${path}\n`;
+}
+/** `sk_test_kest…`: enough to recognise a key, never the key. */
+export function maskKey(key) {
+    return key.length > 12 ? `${key.slice(0, 12)}…` : `${key.slice(0, 8)}…`;
+}
+/** init takes test keys only: a live key moves real money and belongs in the dashboard's go-live step. */
+export function checkTestKey(raw) {
+    const key = (raw ?? "").trim();
+    if (!key)
+        return { ok: false, reason: "empty" };
+    if (key.startsWith("sk_live_"))
+        return { ok: false, reason: "live" };
+    if (!/^sk_test_[0-9A-Za-z]{32}$/.test(key))
+        return { ok: false, reason: "malformed" };
+    return { ok: true, key };
+}