run402-mcp
Version:
MCP server for Run402 — full-stack backend infrastructure for AI agents: Postgres, auth, storage, serverless functions and atomic deploys. Paid with x402/MPP. Includes $0.03 image generation.
234 lines • 9.5 kB
TypeScript
/**
* `billing` namespace — organizations and Stripe checkouts.
*
* Organizations are addressed by their canonical `org_id` (UUID). A
* wallet or email is resolved to that id through the
* `GET /orgs/v1/lookup?wallet=|?email=` lookup; `getOrganization` / `history`
* accept any of the three identifier forms and resolve internally. Organization
* reads require SIWX from a wallet linked to the organization (or matching the
* looked-up `?wallet`), or an admin key; email lookups are admin-only.
* Mutations such as link-wallet, checkout creation, and auto-recharge require
* an org credential (or admin).
*/
import type { Client } from "../kernel.js";
import type { ProjectTier } from "./projects.types.js";
export interface OrganizationDetail {
/** Canonical organization id (UUID). */
org_id: string;
/** The organization's allowance: its Run402-held prepaid balance. */
allowance_usd_micros: number;
/** Held/reserved portion of the allowance; absent on gateways that predate the field. */
held_usd_micros?: number;
email_credits_remaining: number;
tier: ProjectTier | null;
lease_expires_at: string | null;
auto_recharge_enabled: boolean;
auto_recharge_threshold: number;
}
export interface BillingHistoryEntry {
id: string;
direction: "credit" | "debit";
kind: string;
amount_usd_micros: number;
balance_after_available: number;
balance_after_held: number;
reference_type: string | null;
reference_id: string | null;
metadata: Record<string, unknown>;
created_at: string;
}
export interface BillingHistoryResult {
/** Canonical organization id (UUID) the entries belong to. */
org_id: string;
entries: BillingHistoryEntry[];
has_more: boolean;
next_cursor: string | null;
}
/** Options for {@link Billing.history} / {@link Billing.getHistory}. */
export interface BillingHistoryOptions {
/** Page size; gateway default applies when omitted. */
limit?: number;
/** Opaque keyset cursor — page forward from a prior page's `next_cursor`. */
after?: string;
}
export interface CreateCheckoutResult {
org_id: string;
product: CheckoutProduct;
checkout_url: string;
topup_id: string;
}
/**
* A Lightning allowance top-up. `amount_usd_micros` is a
* QUOTE fixed at mint (`usd_value_is_quote: true`) and is what settlement
* credits. Never carries the provider's credential.
*/
export interface LightningTopup {
org_id: string;
product: "balance_topup";
rail: "lightning";
topup_id: string;
/** The payable invoice, verbatim. */
bolt11: string | null;
payment_hash: string | null;
amount_sats: number | null;
amount_usd_micros: number;
usd_value_is_quote: true;
quoted_rate: {
usd_per_btc: number;
source: string;
observed_at: string;
amount_sats: number;
} | null;
invoice_expires_at: string | null;
status: "pending" | "paid" | "paid_late" | "expired";
paid_at: string | null;
credited_ledger_id: string | null;
created_at: string | null;
next_actions: Array<{
type: string;
method: string;
path: string;
why: string;
}>;
}
export interface CreateLightningTopupOptions {
/** Whole satoshis, 100–1,000,000. */
amountSats: number;
/** Replay-safe create: the same key returns the same top-up. */
idempotencyKey?: string;
}
export interface WaitForTopupOptions {
pollMs?: number;
timeoutMs?: number;
onPoll?: (state: LightningTopup) => void;
}
export interface EmailOrganization {
id: string;
email: string;
email_credits_remaining: number;
verification_sent: boolean;
}
/**
* Pool impact of a wallet-link operation (v1.46+). Returned in the
* `link-wallet` response so the caller knows the freshly-shared pool's
* tier, current usage, and configured limits at the moment of linking.
*/
export interface LinkWalletPoolImplications {
tier: ProjectTier | null;
projects_in_pool_count: number;
org_api_calls_current: number;
org_storage_bytes_current: number;
tier_limits: {
api_calls: number;
storage_bytes: number;
/** `storage_bytes` as a human string ("250 MB"). */
storage: string;
};
over_limit: boolean;
}
export interface LinkWalletResult {
status: string;
org_id: string;
wallet: string;
/** Present on v1.46+ gateways; undefined when the gateway predates the field. */
pool_implications?: LinkWalletPoolImplications;
}
export type OrganizationIdentifier = string;
export type CheckoutProduct = "balance_topup" | "tier" | "email_pack";
export type CreateCheckoutOptions = {
product: "balance_topup";
amountUsdMicros: number;
successUrl?: string;
cancelUrl?: string;
} | {
/** lightning-cash-topup: a bolt11 invoice instead of a Stripe session. */
product?: "balance_topup";
rail: "lightning";
amountSats: number;
} | {
product: "tier";
tier: ProjectTier;
successUrl?: string;
cancelUrl?: string;
} | {
product: "email_pack";
successUrl?: string;
cancelUrl?: string;
};
export interface AutoRechargeOptions {
organizationId: string;
enabled: boolean;
threshold?: number;
}
export declare class Billing {
private readonly client;
readonly balance: (identifier: OrganizationIdentifier) => Promise<OrganizationDetail>;
readonly createEmail: (email: string) => Promise<EmailOrganization>;
readonly autoRecharge: (opts: AutoRechargeOptions) => Promise<void>;
constructor(client: Client);
/** Check a organization by organization id (UUID), wallet, or email. */
checkBalance(identifier: OrganizationIdentifier): Promise<OrganizationDetail>;
/**
* Read a organization's financial detail by organization id (UUID), wallet,
* or email. An organization id reads `GET /orgs/v1/:org_id/billing`
* directly; a wallet/email is resolved through the
* `GET /orgs/v1/lookup?wallet=|?email=` lookup. Requires SIWX from a
* wallet linked to the organization (or matching the looked-up `?wallet`), or an
* admin key; email lookups are admin-only.
*/
getOrganization(identifier: OrganizationIdentifier): Promise<OrganizationDetail>;
/**
* Resolve a wallet or email to its organization detail — including the
* canonical `org_id` — via `GET /orgs/v1/lookup?wallet=|?email=`.
* An org-id (UUID) argument is read directly instead. SIWX must match the
* `?wallet`; email lookups are admin-only.
*/
lookupOrganization(identifier: OrganizationIdentifier): Promise<OrganizationDetail>;
/**
* Fetch billing history by organization id (UUID), wallet, or email. Pass
* `{ limit, after }` to page; `after` is the opaque keyset cursor
* (`next_cursor` from a prior page).
*/
history(identifier: OrganizationIdentifier, opts?: BillingHistoryOptions): Promise<BillingHistoryResult>;
/**
* Fetch ledger history for a organization. History is keyed by organization id
* (UUID): a wallet/email identifier is first resolved to its organization via the
* lookup, then `GET /orgs/v1/:org_id/billing/history` is read.
* Requires SIWX from a wallet linked to the organization, or an admin key.
* Pass `{ limit, after }` to page; `after` is the opaque keyset cursor
* (`next_cursor` from a prior page). Returns `{ org_id, entries, has_more,
* next_cursor }`.
*/
getHistory(identifier: OrganizationIdentifier, opts?: BillingHistoryOptions): Promise<BillingHistoryResult>;
/** Create a Stripe checkout URL for an organization. */
createCheckout(organizationId: string, checkout: CreateCheckoutOptions): Promise<CreateCheckoutResult>;
/**
* lightning-cash-topup: mint a bolt11 invoice that tops up the org's cash
* balance when paid. No funds move at creation; any active org member or a
* grant key for one of the org's projects may call it.
*/
createLightningTopup(organizationId: string, options: CreateLightningTopupOptions): Promise<LightningTopup>;
/** Read one top-up (the waiting client's poll). */
getTopup(organizationId: string, topupId: string): Promise<LightningTopup>;
/**
* Poll a top-up until it is paid, paid late, or expired (or the timeout
* elapses, in which case the last observed state is returned).
*/
waitForTopup(organizationId: string, topupId: string, options?: WaitForTopupOptions): Promise<LightningTopup>;
/** Create an email-only (no-wallet) organization. Sends a verification email. */
createEmailOrganization(email: string): Promise<EmailOrganization>;
/**
* Link a wallet to an existing email organization to enable hybrid
* Stripe + x402 payments. `organizationId` is the canonical
* `org_id` (UUID) returned by `createEmailOrganization` /
* `lookupOrganization`; the gateway addresses the route as
* `POST /orgs/v1/:org_id/wallets`. Returns the gateway
* response; v1.46+ gateways include a {@link LinkWalletPoolImplications}
* block describing the freshly-shared pool's tier, current usage, and limits
* so callers can warn before the merge pushes usage `over_limit`.
*/
linkWallet(organizationId: string, wallet: string): Promise<LinkWalletResult>;
/** Enable/disable email-pack auto-recharge. */
setAutoRecharge(opts: AutoRechargeOptions): Promise<void>;
}
//# sourceMappingURL=billing.d.ts.map