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.
223 lines • 12.5 kB
TypeScript
/**
* `projects` namespace — project lifecycle, introspection, and admin.
*
* Covers:
* - remote: provision, delete, list, getUsage, getSchema, getQuote
* - local: info, keys, use (require provider support for persistence methods)
*
* Staff-only project actions live on the {@link Admin} namespace:
* - `admin.archiveProject` / `admin.reactivateProject` — moderate-archive
* - `admin.setLeasePerpetual` — organization-level escape hatch (replaces the
* v1.56 `projects.pin` removed in v1.57)
*/
import { ProjectStripe } from "./stripe.js";
import type { Client } from "../kernel.js";
import type { ProjectKeys } from "../credentials.js";
import type { ExposeManifest } from "./deploy.types.js";
import type { SqlBatchOptions, SqlBatchResult, SqlBatchStatement, SqlOptions, SqlResult, ExposeManifestValidationInput, ExposeManifestValidationResult, ListProjectsOptions, ListProjectsResult, ProjectDetail, ProjectInfo, ProjectRestOptions, ProjectRestResponse, ProvisionOptions, ProvisionResult, QuoteResult, RenameProjectResult, SetRepoNameResult, SchemaReport, ListTenantPaymentsOptions, TenantPaymentListResult, UsageReport, ValidateExposeOptions } from "./projects.types.js";
export declare class Projects {
private readonly client;
readonly schema: (id: string) => Promise<SchemaReport>;
readonly usage: (id: string) => Promise<UsageReport>;
readonly quote: () => Promise<QuoteResult>;
readonly promoteUser: (id: string, email: string) => Promise<void>;
readonly demoteUser: (id: string, email: string) => Promise<void>;
/** The organization's Stripe account and Checkout / portal sessions for a project's app. */
readonly stripe: ProjectStripe;
constructor(client: Client);
/**
* Provision a new Postgres project. Requires SIWX auth; payment
* flows through the configured fetch wrapper (x402 in Node, session
* budget in sandbox). Returned keys are persisted to the local store
* when the credential provider supports it.
*
* @throws {PaymentRequired} when the wallet has insufficient balance and
* the fetch wrapper cannot sign the 402 retry.
*/
provision(opts?: ProvisionOptions): Promise<ProvisionResult>;
/**
* Immediately and irreversibly delete a project. Triggers the full
* destructive cascade (drop tenant schema, delete Lambda functions,
* release subdomains, tombstone mailbox, wipe secrets). Local keystore
* is cleaned via the credential provider when supported.
*
* @throws {ProjectCredentialNotFound} if local project credentials are absent.
*/
delete(id: string): Promise<void>;
/**
* List projects in the named, domain-aware inventory (gateway
* `project-findability`). Each row carries `name`, `site_url`,
* `custom_domains`, `org_id` (the owning org), `status`, and
* `created_at`.
*
* Membership-scoped by default (`GET /projects/v1`): returns every project
* owned by an org the caller's principal is an active member of. This is the
* cold-start lone-agent path — `list()` with no options, authenticated with
* SIWX wallet auth from the credential provider.
*
* - `{ org }` narrows to one owning org (authorize-before-reveal: a non-member
* or guessed id is a 403, a non-UUID id a 400).
* - `{ all: true }` reads every project the caller can reach across all its
* organizations (`GET /agent/v1/me/projects`). Pass `{ all: true, token }`
* with a sign-in session token for the person's account; without `token`,
* `all` uses the credential provider (a SIWX wallet reads its own slice).
* The response echoes the resolved `scope` (`"principal"` or `"wallet"`)
* and is unpaged.
* - `{ limit, cursor }` paginate the membership-scoped read (server default
* 50, max 200).
*
* @throws {Run402Error} with `context: "listing projects"` on the usual
* auth/network failures (e.g. `Unauthorized` when no local wallet is
* configured and the gateway rejects the missing SIWX header).
*/
list(opts?: ListProjectsOptions): Promise<ListProjectsResult>;
/**
* Rename a project (gateway `project-findability`, `PATCH /projects/v1/:id`).
* Surfaces the project's `name` so a human can fix an auto-generated label.
*
* Authorization is org-membership based (`admin`+ on the owning org, or a
* `project:write` grant) and authorize-before-reveal — an unauthorized caller
* (including a guessed id) gets the same `Unauthorized` as a real-but-
* unauthorized project, never a not-found oracle. The server validates the
* name (non-empty, ≤ 200 chars, no control characters).
*
* Uses the caller's SIWX wallet auth (or a control-plane session) from the
* credential provider — not a project service key — so it works without the
* project being in the local keystore.
*
* @throws {Unauthorized} when the caller is not authorized for the project.
* @throws {ApiError} (HTTP 400) when the new name is invalid.
*/
rename(projectId: string, name: string): Promise<RenameProjectResult>;
/**
* Claim or rename this project's per-org-unique, address-form name
* (`POST /projects/v1/:id/repo-name`) — the
* `<name>` half of `run402::<org-slug>/<name>`. Distinct from
* {@link rename} (the free-text display name, unchanged): the address-form
* name is charset-restricted (`[a-z0-9-]`, ≤63 chars) and per-org-unique.
* No fee, unlike the org-slug namespace. Same authority as `rename`
* (`project.rename`).
*/
setRepoName(projectId: string, name: string): Promise<SetRepoNameResult>;
/**
* List redacted tenant x402 payment records for priced function web routes
* (`GET /projects/v1/:project_id/tenant-payments`). Requires
* project.tenant_payments.read server-side: org developer+ or read-scoped
* project grant or grant key.
*/
listTenantPayments(projectId: string, opts?: ListTenantPaymentsOptions): Promise<TenantPaymentListResult>;
/**
* Get usage metrics for a project — API calls, storage, tier limits,
* lease expiry.
*/
getUsage(id: string): Promise<UsageReport>;
/**
* Introspect the project's database schema — tables, columns, types,
* constraints, and RLS policies. Uses the cached service key when this
* machine has one, otherwise your own authority (`project.database.read`:
* org role viewer or higher, or a `database:read` grant). A cached key the
* gateway refuses is retried once as you, like {@link sql}.
*/
getSchema(id: string): Promise<SchemaReport>;
/** Run SQL against the project's database (`POST /projects/v1/:project_id/sql`).
* Uses the cached service key when this machine has one; otherwise the
* request goes as you (wallet, sign-in session, or grant key) and the
* gateway authorizes it by your role: `project.database.read` (viewer or
* higher, or `database:read`) runs read-only, enforced by PostgreSQL;
* `project.database.write` (developer or higher, or `database:write`) can
* write. A cached key the gateway refuses (expired, revoked, unknown) is
* retried once as you; with no principal to retry as, the refusal names
* `run402 credentials project-keys delete --project <id>` as its first next
* action. `{ readOnly: true }` runs the call read-only for any caller (one
* statement, a write answers `DATABASE_READ_ONLY`). Returns the gateway envelope
* verbatim: `{ status, schema, rows, row_count, fields, statements,
* warnings }`. `rows` and `fields` come from the last statement and
* `row_count` is that statement's count; `statements[]` carries each
* statement's `{ command, row_count }` for a multi-statement text.
* `warnings[]` never changes the result: `SCHEMA_CHANGE_OUTSIDE_MIGRATION`
* means a schema change on a released project belongs in a migration, and
* `MULTI_STATEMENT_TEXT_BODY` points at {@link sqlBatch}. */
sql(id: string, sql: string, params?: unknown[], opts?: SqlOptions): Promise<SqlResult>;
/** Run several statements (1 to 100, one statement each) with an explicit
* transaction (`POST /projects/v1/:project_id/sql/batch`). With
* `transaction: "all"` (default) the first failure rolls back the batch and
* throws `SQL_BATCH_STATEMENT_FAILED` naming the statement's index; with
* `"each"` every statement commits on its own and `results[i].status` says
* how each went. */
sqlBatch(id: string, statements: SqlBatchStatement[], opts?: SqlBatchOptions): Promise<SqlBatchResult>;
/** Query or mutate a project table through PostgREST. */
rest<T = unknown>(id: string, table: string, options?: ProjectRestOptions): Promise<T>;
/** Query or mutate a project table through PostgREST and preserve HTTP status. */
restResponse<T = unknown>(id: string, table: string, options?: ProjectRestOptions): Promise<ProjectRestResponse<T>>;
/** Apply the project's declarative expose manifest. */
applyExpose(id: string, manifest: ExposeManifest): Promise<unknown>;
/**
* Validate an authorization/expose manifest without applying it.
*
* When `opts.project` / `opts.project_id` is supplied, the gateway validates
* against that project's live schema using its service key. Otherwise it
* performs projectless wallet-auth validation. `migrationSql` is validation
* context only and is never executed.
*/
validateExpose(manifest: ExposeManifestValidationInput, opts?: ValidateExposeOptions): Promise<ExposeManifestValidationResult>;
/** Fetch the project's current expose manifest. */
getExpose(id: string): Promise<ExposeManifest>;
/**
* Get tier pricing — prices, lease durations, storage limits, API-call
* limits. Public, no auth, no payment.
*/
getQuote(): Promise<QuoteResult>;
/**
* Authoritative single-project read — `GET /projects/v1/:id` (gateway
* `project.read`). Returns the server-side {@link ProjectDetail} (identity,
* owning org, tier, lifecycle, site_url + custom domains, active-release
* pointer, mailbox addresses, usage vs. tier limits). Carries no secrets.
*
* Uses the default credential (wallet SIWX or control-plane session) and does
* NOT require the project to be in the local keystore — read a project you own
* via org membership without provisioning it locally. Authorize-before-reveal:
* a forbidden or absent project both surface as `Unauthorized`, never a 404.
* For the local anon/service keys use {@link Projects.keys} instead.
*/
get(id: string): Promise<ProjectDetail>;
/**
* Inspect a project from local state. Combines the project id with the
* stored keys. Does not make an API call.
*
* @throws {ProjectCredentialNotFound} if local project credentials are absent.
*/
info(id: string): Promise<ProjectInfo>;
/**
* Return the stored anon/service keys for a project from local state.
* Does not make an API call.
*
* @throws {ProjectCredentialNotFound} if local project credentials are absent.
*/
keys(id: string): Promise<ProjectKeys>;
/**
* Set the active/default project in local state. Requires the credential
* provider to support `setActiveProject`.
*
* Returns `void`. To both persist the active project AND get a project-scoped
* client in one call, use {@link Run402.useProject} instead:
*
* const p = await r.useProject("prj_xxx");
* await p.apply.apply({ site: { ... } });
*
* @throws {Run402Error} if the authoritative project read is not allowed.
* @throws {LocalError} if the provider does not support active-project state.
*/
use(id: string): Promise<void>;
/**
* Return the active/default project id in local state, or null when none
* is set or the provider does not track active-project state.
*
* To resolve the active project AND build a scoped sub-client in one call,
* use {@link Run402.project} (no arg):
*
* const p = await r.project(); // throws if no active project is set
* await p.functions.list();
*/
active(): Promise<string | null>;
}
//# sourceMappingURL=projects.d.ts.map