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.
202 lines • 8.39 kB
TypeScript
/**
* `tier` namespace — set (start / renew / upgrade) the organization's tier
* lease against `/tiers/v1*`. Requires wallet SIWX auth; `set` flows through x402
* for the actual payment.
*/
import type { Client } from "../kernel.js";
export type TierName = "prototype" | "hobby" | "team";
export interface TierFunctionLimits {
max_function_timeout_seconds?: number;
max_function_memory_mb?: number;
max_scheduled_functions?: number;
min_cron_interval_minutes?: number;
current_scheduled_functions?: number;
[key: string]: unknown;
}
/**
* Per-project summary returned in `TierStatusResult.projects[]`. Mirrors the
* gateway's `WalletTierInfo.projects[]` shape. Pre-v1.57 gateways may omit
* `effective_status` / `organization_lifecycle_state` / `lease_perpetual`; pre-v1.59
* gateways omit `secrets_rotation_advised`. Unknown future fields are preserved
* via the index signature so callers can branch on them.
*/
export interface TierStatusProject {
id: string;
name: string;
tier: string;
status: string;
pinned: boolean;
created_at: string;
effective_status?: string;
organization_lifecycle_state?: string;
lease_perpetual?: boolean;
/**
* v1.77 (org-owned control plane): owning org (organization) id and the
* provisioning principal. A wallet authenticates; the org owns the project.
* Present on the canonical project object (`GET /projects/v1`); the
* tier-status list does not include them today, so both are optional and
* forward-compatible (preserved via the index signature regardless).
*/
org_id?: string;
created_by?: string;
/**
* v1.59 (add-project-transfer): set on a project after an accepted transfer
* stamped `projects.secrets_rotation_advised_at`. Clears automatically once
* B has re-written every previously-inherited secret name (or via the
* explicit acknowledge route). Surfaced so agents can guide rotation.
*/
secrets_rotation_advised?: {
advised_at: string;
reason: string;
};
[key: string]: unknown;
}
/**
* v1.59 (add-project-transfer): summary of a pending transfer OFFERED TO the
* authenticated wallet. Exposed at the top level of `TierStatusResult` so the
* inbox is visible without a separate API call. Each entry carries
* `preview_path` for deep-linking into `GET /agent/v1/transfers/<transfer_id>`.
*/
export interface TierStatusIncomingTransfer {
transfer_id: string;
project_id: string;
project_name_snapshot: string | null;
from_wallet: string;
billing_policy: "migrate";
message: string | null;
initiated_at: string;
expires_at: string;
kysigned_record_id: string | null;
preview_path: string;
}
export interface TierStatusResult {
wallet: string;
tier: string | null;
lease_started_at: string | null;
lease_expires_at: string | null;
active: boolean;
/**
* Lifecycle state of the owning organization. `null` only when the
* wallet has no organization row (orphan wallet).
*/
organization_lifecycle_state: "active" | "past_due" | "frozen" | "dormant" | "purged" | null;
/**
* Staff escape hatch flag on the owning organization. When `true`,
* the organization never advances past `active` regardless of lease expiry.
* `null` only for orphan wallets with no organization row.
*/
lease_perpetual: boolean | null;
/**
* Organization-pooled usage against the tier limits. Every byte count sits
* beside its human string under the same name with `_bytes` removed
* (`storage_bytes_limit: 250000000` + `storage_limit: "250 MB"`); quotas are
* decimal, derived from the tier constant.
*/
pool_usage: {
projects: number;
total_api_calls: number;
/** Project bytes PLUS `vault_source_bytes` — what the storage limit applies to. */
total_storage_bytes: number;
total_storage: string;
/** The vault half of `total_storage_bytes`, compared against `source_bytes_limit`. */
vault_source_bytes: number;
vault_source: string;
api_calls_limit: number;
storage_bytes_limit: number;
storage_limit: string;
/** The vault pool's own limit, separate from `storage_bytes_limit`. */
source_bytes_limit: number;
source_limit: string;
[key: string]: unknown;
};
/**
* Per-project summary across all projects on the wallet's organization.
* Always present on v1.46+ gateways. Pre-v1.59 entries lack
* `secrets_rotation_advised`.
*/
projects?: TierStatusProject[];
/**
* v1.59 (add-project-transfer): pending transfers offered TO this wallet.
* Empty array when none. Absent on pre-v1.59 gateways. Each entry carries
* `preview_path` so callers can deep-link into the full preview document
* without a second list call.
*/
incoming_transfers?: TierStatusIncomingTransfer[];
/** Function authoring caps returned by newer gateways. Unknown future
* limit fields are preserved so callers can display or branch on them. */
function_limits?: TierFunctionLimits;
/** Compatibility slot for gateways that nest caps under limits.functions. */
limits?: {
functions?: TierFunctionLimits;
[key: string]: unknown;
};
/**
* Org-level advisories (recovery-event-reachability). Present only when at
* least one applies; absent on older gateways. `owner_unreachable`
* means the owning organization resolves to ZERO verified notification
* recipients — mandatory recovery/security events currently reach nobody —
* with the registration remedy carried in `next_actions[]`
* (`register_contact`, `POST /agent/v1/contact`).
*/
advisories?: Array<{
type: "owner_unreachable" | "contact_email_stale" | (string & {});
summary: string;
next_actions: Array<{
type: string;
method?: string;
path?: string;
why?: string;
}>;
}>;
}
/**
* What `set` did: `start` begins a lease (or activates the free prototype
* tier), `renew` extends the same tier from its current expiry, `upgrade`
* moves to a higher tier with a prorated refund to the allowance. The open
* tail keeps a future action the gateway may report (a downgrade it accepts)
* from being a type error.
*/
export type TierSetAction = "start" | "renew" | "upgrade" | (string & {});
export interface TierSetResult {
wallet: string;
action: TierSetAction;
tier: string;
previous_tier: string | null;
lease_started_at: string;
lease_expires_at: string;
/** The organization's allowance after this purchase. */
allowance_remaining_usd_micros: number;
/**
* What settled the purchase. `allowance` means the organization's allowance
* paid, ahead of the paywall: no 402, no signed authorization, and no USDC
* needed in the wallet.
*/
paid_with?: "allowance" | "x402" | "mpp";
/** Allowance consumed by this purchase (0 unless `paid_with` is `allowance`). */
allowance_used_usd_micros?: number;
}
export interface TierSetOptions {
/**
* Idempotency key for safe retries (durable-side-effects doctrine). When set,
* the SDK sends it as the `Idempotency-Key` header so retrying the same
* start/renew intent does not double-charge. The key is caller-supplied:
* it represents one payment intent, a boundary only the caller knows (a
* deliberate second renewal must use a fresh key). The SDK does not
* auto-derive one — that cannot distinguish a retry from a new renewal.
*/
idempotencyKey?: string;
}
export declare class Tier {
private readonly client;
constructor(client: Client);
/** Check the organization's current tier — tier name, status, and lease expiry. */
status(): Promise<TierStatusResult>;
/**
* Set the organization's tier: start, renew, or upgrade the lease. The
* gateway auto-detects the action from the current tier state. Payment flows through the injected fetch (x402 in
* Node with a wallet). Throws {@link PaymentRequired} when the
* wrapper cannot fund the call.
*/
set(tier: TierName, opts?: TierSetOptions): Promise<TierSetResult>;
}
//# sourceMappingURL=tier.d.ts.map