foldrun 14.1.3 → 14.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/docs/api.md +9 -1
- package/docs/budgets-and-billing.md +38 -0
- package/package.json +2 -2
- package/src/commands.mjs +8 -12
package/docs/api.md
CHANGED
|
@@ -15,6 +15,7 @@ One funnel for every caller. A route either takes an authenticated tenant or
|
|
|
15
15
|
refuses — there is no separate "browser API". The exceptions carry their own
|
|
16
16
|
proof instead of a key: a token or signature (`/s/<token>`, `/api/hooks`,
|
|
17
17
|
`/api/inbox`, `/api/events`, `/api/approve`, `/api/unsubscribe`, `/api/billing/stripe`,
|
|
18
|
+
`/api/billing/partner/…` (a storefront's signature),
|
|
18
19
|
`/api/billing/confirm`), the sign-in and recovery steps (`/api/auth/signup`,
|
|
19
20
|
`login`, `forgot`, `reset`, `verify`, `mfa/verify`, `session`, `/api/cli/login`,
|
|
20
21
|
`/api/cli/login/<id>`, `/api/cli/authorize` GET, `/api/oauth/callback`), `/api/healthz`, `/api/status`, `/api/status/history`, `/api/version` and `/api/openapi.json` — and an AI app's OAuth sign-in to `/api/mcp`: `/api/mcp/oauth/register` (open, as the protocol needs) and `/api/mcp/oauth/token` (its code and PKCE verifier, or its refresh token, are the proof).
|
|
@@ -419,10 +420,17 @@ person: a key names an account, never a who.
|
|
|
419
420
|
| `/api/billing/details` | GET, PUT | who the invoices are made out to — GET `{ details, stripe, customer, tax }` for anyone who can see billing and every workspace (403 to a member or key scoped to some, as for the statement); PUT (the owner) `legalName` (required), `email`, `abn` (checked against the ABN rule), `address` `{ line1, line2, city, state, postcode, country }` (two-letter country) or `null`. Every problem comes back at once as `errors` with a `400`. Kept first, then sent to the Stripe customer (name, address, the ABN as its `au_abn` tax id): answers `synced`, and `syncError` with Stripe's words when Stripe refused — the details stand either way |
|
|
420
421
|
| `/api/billing/portal` | POST | a Stripe Billing Portal session for the account's customer (the owner): answers `url`. Optional `returnTo`, a `/dashboard/…` path to come back to. `501` without Stripe |
|
|
421
422
|
| `/api/billing/statement?month=&format=` | GET | one month of the ledger as a statement. JSON by default; `format=csv` downloads it with the month, the account and the spent and added totals in its header. `month` is `YYYY-MM`, default the current month. What the customer sees is the charge; the platform's provider cost is not on it. The whole account's money, so refused (403) to a member or key scoped to some workspaces, as the audit log is |
|
|
422
|
-
| `/api/billing/wallet` | GET, PUT | the balance summary (burn, runway, daily spend, month to date, the suggested top-up), the refill rule and the low-balance email — GET `{ enabled, stripe, summary, cardSaved, autoTopUp, email, dunning }`, PUT `autoTopUp`, `email`. `dunning.status` is `none`, `grace` (a plan invoice failed; runs go on until `graceUntil`) or `suspended` (new runs paused until it is paid), with `payUrl`, `amountDue` (minor units) and `currency` |
|
|
423
|
+
| `/api/billing/wallet` | GET, PUT | the balance summary (burn, runway, daily spend, month to date, the suggested top-up), the refill rule and the low-balance email — GET `{ enabled, stripe, summary, cardSaved, autoTopUp, email, dunning, tomanTopUp }`, PUT `autoTopUp`, `email`. `dunning.status` is `none`, `grace` (a plan invoice failed; runs go on until `graceUntil`) or `suspended` (new runs paused until it is paid), with `payUrl`, `amountDue` (minor units) and `currency`. `tomanTopUp` is `{ url }` — foldrun.ir's charge page with this account filled in — or null where foldrun.ir cannot sell now |
|
|
423
424
|
| `/api/billing/plans` | GET | the catalogue (four plans: fee, credits, per-credit price, runs at once, workspaces, lane), where this account stands (plan, status, this cycle's credits and what is left, when it resets), the balance in dollars and credits, and any overdraft the platform has allowed |
|
|
424
425
|
| `/api/billing/subscribe` | POST, DELETE | POST `plan` — starter, creator, pro or scale. With no subscription yet, answers `url`: a Stripe Checkout in subscription mode; the return trip starts the first cycle. With a live one, changes it at Stripe at once, prorated (an upgrade is invoiced today and the bigger bundle lands with it; a downgrade comes back as credit on the next invoice), and answers `changed: true` — only once its prorated invoice is paid: when the payment needs the customer (a declined card, 3-D Secure) the change waits at Stripe as a pending update, nothing about the plan moves, and the answer is 402 `{ pending: true, payUrl }` — paying that invoice applies it; unpaid, Stripe drops it and voids the invoice after 23 hours. A plan set to stop and changed this way stays set to stop once paid — resuming it is the customer's own choice (`resume: true`); nothing resumes on its own. A plan set to stop at the period's end is still that live subscription: choosing a plan takes the stop off (and changes it if it is another plan) — never a second Checkout. With no subscription known here but one still billing at Stripe for the account's customer, 409: a second is not started. POST `resume: true` takes a pending cancellation off — nothing is charged and no cycle moves. DELETE ends the plan with the current cycle: the credits stand until then, and credits bought on top are kept |
|
|
425
426
|
| `/api/billing/stripe` | POST | Stripe's webhook — signature-verified, not for you. Every delivery is logged. Beside top-ups it turns plan cycles: one grant per (subscription, plan, period), whichever of the checkout, `invoice.paid` (either invoice shape) or `customer.subscription.updated` arrives first; `invoice.payment_failed` marks the plan past due and starts dunning (an email, a grace period, then new runs paused — see budgets-and-billing.md), `invoice.paid` and `invoice.voided` end it, `customer.subscription.deleted` ends the plan that subscription paid for — what is left of the bundle expires, the levers come off, money the customer added stays. `charge.refunded` debits a refunded top-up (never a plan fee), `charge.dispute.created` debits a chargeback and `charge.dispute.closed` returns it when won. Answers 500 — so Stripe redelivers — only when a lookup the event needs failed. The full event list is in budgets-and-billing.md |
|
|
427
|
+
| `/api/billing/partner/topups/rate` | GET | foldrun.ir only, HMAC-signed (see [Paying in Toman](budgets-and-billing#paying-in-toman-foldrunir)) — the Toman rate it sells at: `{ tomanPerUsd, setAt, min, max }`; `503` while no rate is set or it has gone stale |
|
|
428
|
+
| `/api/billing/partner/topups/quote` | POST | foldrun.ir only — `{ account, usd }` (account: a sign-in email or the account id) → `{ account: { label }, usd, toman, rial, tomanPerUsd, setAt }`. Nothing written; `label` is masked (`o•••r@a•••e.co · ac••`). `404` no such account, `400` an amount outside $5–$500 or over the gateway's 100,000,000 Toman |
|
|
429
|
+
| `/api/billing/partner/topups` | POST | foldrun.ir only — `{ account, usd, toman }` opens an order with the Toman figure locked for 30 minutes: `201 { order: { id, label, usd, toman, rial, tomanPerUsd, status, authority, refId, expiresAt, creditedAt } }`. `409 { error, quote }` when the rate moved since the customer saw `toman`; `429` past the daily ceiling (`billing.ir_daily_usd`, counting open, paid and failed orders) |
|
|
430
|
+
| `/api/billing/partner/topups/<id>` | GET | foldrun.ir only — one of its orders; `status` pending, credited or failed |
|
|
431
|
+
| `/api/billing/partner/topups/<id>/authority` | POST | foldrun.ir only — `{ authority }`, the Zarinpal session the customer is sent to. Once per order (`409` for another; a retry is a new order) |
|
|
432
|
+
| `/api/billing/partner/topups/<id>/paid` | POST | foldrun.ir only, after Zarinpal verified the payment — `{ authority, refId, cardPan?, fee? }` credits the ORDER's dollars (never a figure in the request) as a top-up noted `zarinpal:<refId> order:<id>`, once per authority: `{ order, credited }`, credited false on a repeat. A failed or expired order is still credited — the money arrived — up to a day after it was made; later is `409` and the platform team credits it by hand |
|
|
433
|
+
| `/api/billing/partner/topups/<id>/failed` | POST | foldrun.ir only — `{ reason }`: the customer cancelled or the gateway refused. A credited order stays credited |
|
|
426
434
|
|
|
427
435
|
## Versions
|
|
428
436
|
|
|
@@ -423,6 +423,44 @@ surprise. With billing on, an empty balance refuses *new* runs — runs in
|
|
|
423
423
|
flight finish. Every run is charged exactly once; the ledger is a database
|
|
424
424
|
table with that as a constraint, not a promise.
|
|
425
425
|
|
|
426
|
+
### Paying in Toman (foldrun.ir)
|
|
427
|
+
|
|
428
|
+
People who pay with an Iranian (Shetab) card top up at
|
|
429
|
+
[foldrun.ir](https://foldrun.ir) in Toman, through Zarinpal. It is the same
|
|
430
|
+
wallet: the payment adds dollars of credit to the account, exactly like a
|
|
431
|
+
card top-up here — it does not buy a plan. Billing → Balance (and
|
|
432
|
+
`foldrun billing wallet`) links to foldrun.ir's charge page with the
|
|
433
|
+
account filled in, wherever foldrun.ir is selling.
|
|
434
|
+
|
|
435
|
+
1. On foldrun.ir the customer types the account's sign-in email (any
|
|
436
|
+
member's) or its account id, and an amount in dollars ($5–$500).
|
|
437
|
+
foldrun.ir shows the account masked (`o•••r@a•••e.co · ac••`) and the
|
|
438
|
+
price in Toman at today's rate.
|
|
439
|
+
2. Confirming opens an order here with that Toman figure locked for 30
|
|
440
|
+
minutes, and sends the customer to Zarinpal to pay it.
|
|
441
|
+
3. When Zarinpal has verified the payment, the order's dollars land as a
|
|
442
|
+
top-up (`zarinpal:<receipt> order:<id>` on the statement) — once,
|
|
443
|
+
however many times the confirmation arrives. A payment that clears after
|
|
444
|
+
the 30 minutes, or after the customer pressed back, is still credited —
|
|
445
|
+
within a day of the order; later than that the platform team credits it
|
|
446
|
+
by hand (Zarinpal returns a payment nobody verified within 72 hours).
|
|
447
|
+
|
|
448
|
+
The credit is bought credit like any other: it expires 12 months after
|
|
449
|
+
purchase if unused. The platform operator sets, in the console's Settings
|
|
450
|
+
under Billing:
|
|
451
|
+
|
|
452
|
+
| Setting | |
|
|
453
|
+
|---|---|
|
|
454
|
+
| `billing.ir_toman_per_usd` | Toman per dollar of credit — the market rate plus the gateway's fee and any margin. Empty: foldrun.ir does not sell |
|
|
455
|
+
| `billing.ir_rate_max_age_hours` | hours before a saved rate goes stale and sales stop (default 48; 0 never) |
|
|
456
|
+
| `billing.ir_daily_usd` | most foldrun.ir may open orders for in 24 hours, open, paid and failed together (default 1000; 0 no ceiling) |
|
|
457
|
+
| `billing.ir_site_url` | foldrun.ir's address, for the Billing page link |
|
|
458
|
+
|
|
459
|
+
foldrun.ir signs every call with `FOLDRUN_PARTNER_IR_SECRET` (32 characters
|
|
460
|
+
or more, in the platform's secret store and foldrun.ir's own). It can only
|
|
461
|
+
open orders and report them paid; it never names an amount to credit. The
|
|
462
|
+
routes are in [api.md](api#billing).
|
|
463
|
+
|
|
426
464
|
## How the money is kept straight
|
|
427
465
|
|
|
428
466
|
The bookkeeping rules behind the numbers, for whoever has to answer "why is
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "foldrun",
|
|
3
|
-
"version": "14.1
|
|
3
|
+
"version": "14.2.1",
|
|
4
4
|
"description": "Agents are just folders. Write them, check them, run them — on your machine.",
|
|
5
5
|
"license": "FSL-1.1-ALv2",
|
|
6
6
|
"type": "module",
|
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
"node": ">=22"
|
|
12
12
|
},
|
|
13
13
|
"dependencies": {
|
|
14
|
-
"@foldrun/core": "^14.3.
|
|
14
|
+
"@foldrun/core": "^14.3.3"
|
|
15
15
|
},
|
|
16
16
|
"files": [
|
|
17
17
|
"bin",
|
package/src/commands.mjs
CHANGED
|
@@ -8970,22 +8970,16 @@ function ownSandboxOf(agent) {
|
|
|
8970
8970
|
return /** @type {{ sandbox?: string } | undefined} */ (agent)?.sandbox === "own";
|
|
8971
8971
|
}
|
|
8972
8972
|
|
|
8973
|
-
/** An agent file's frontmatter as a run reads it, from its text.
|
|
8974
|
-
* the four job blocks' keys up to the top (
|
|
8975
|
-
*
|
|
8976
|
-
*
|
|
8977
|
-
* and `network`, both in an agent's `guardrail:` block — so it lifts just
|
|
8978
|
-
* those, the same way a run does: a top-level value wins, else the block's is
|
|
8979
|
-
* lifted. {} when it does not parse. */
|
|
8973
|
+
/** An agent file's frontmatter as a run reads it, from its text. Core's
|
|
8974
|
+
* readFrontmatter folds the four job blocks' keys up to the top (its
|
|
8975
|
+
* configMatter), so `guardrail: { sandbox: own }` reads as `sandbox: own`.
|
|
8976
|
+
* The CLI keeps no fold rule of its own (FOL-93). {} when it does not parse. */
|
|
8980
8977
|
async function effectiveFront(raw) {
|
|
8981
8978
|
const { readFrontmatter } = await core();
|
|
8982
8979
|
const dir = fs.mkdtempSync(path.join(os.tmpdir(), "foldrun-front-"));
|
|
8983
8980
|
try {
|
|
8984
8981
|
fs.writeFileSync(path.join(dir, "agent.md"), raw);
|
|
8985
|
-
|
|
8986
|
-
const guardrail = front.guardrail && typeof front.guardrail === "object" ? front.guardrail : {};
|
|
8987
|
-
for (const key of ["sandbox", "network"]) if (!(key in front) && key in guardrail) front[key] = guardrail[key];
|
|
8988
|
-
return front;
|
|
8982
|
+
return /** @type {Record<string, any>} */ (readFrontmatter(path.join(dir, "agent.md")) ?? {});
|
|
8989
8983
|
} catch {
|
|
8990
8984
|
return {};
|
|
8991
8985
|
} finally {
|
|
@@ -9234,7 +9228,7 @@ async function agentNetworkCmd(positional, flags, layout) {
|
|
|
9234
9228
|
inTree(desk, files, async (dir) => {
|
|
9235
9229
|
const { listAgents } = await core();
|
|
9236
9230
|
// The folded view a run reads: `network` set inside a `guardrail:` block
|
|
9237
|
-
// counts the same as a top-level one (
|
|
9231
|
+
// counts the same as a top-level one (core folds it).
|
|
9238
9232
|
const front = await effectiveFront(fs.readFileSync(path.join(dir, rel), "utf8"));
|
|
9239
9233
|
const info = listAgents("default", "workspace").find((a) => a.name === name);
|
|
9240
9234
|
// May it browse? Core answers it (network.browses, with web: inherited
|
|
@@ -10502,6 +10496,8 @@ async function billingVerbCmd(positional, flags) {
|
|
|
10502
10496
|
const a = w.autoTopUp;
|
|
10503
10497
|
console.log(` auto top-up ${a?.enabled ? `${usd(a.amountUsd)} when the balance falls below ${usd(a.thresholdUsd)}` : c.dim("off")}${w.cardSaved ? "" : c.dim(" · no card saved")}`);
|
|
10504
10498
|
if (w.email) console.log(` receipts ${w.email}`);
|
|
10499
|
+
// foldrun.ir (3 Nov 2026): paying with an Iranian card, in Toman.
|
|
10500
|
+
if (w.tomanTopUp?.url) console.log(` in Toman ${w.tomanTopUp.url}`);
|
|
10505
10501
|
if (w.dunning && w.dunning.state && w.dunning.state !== "ok") console.log(` ${c.red("✗")} plan invoice unpaid — ${w.dunning.state}`);
|
|
10506
10502
|
console.log(`\n ${c.dim("foldrun billing wallet set auto-top-up --threshold 10 --amount 50 · set auto-top-up off")}\n`);
|
|
10507
10503
|
return 0;
|