/** * @run402/sdk — typed TypeScript client for the Run402 API. * * This is the isomorphic entry point. Works in Node 22, Deno, Bun, and V8 * isolates with no filesystem. For Node consumers that want zero-config * defaults (keystore + wallet + x402), use `@run402/sdk/node` instead. */ import { type ClientCapabilities, type ClientStats, type Run402ClientMetadata } from "./kernel.js"; import type { CredentialsProvider } from "./credentials.js"; import { Projects } from "./namespaces/projects.js"; import { Assets } from "./namespaces/assets.js"; import { Functions } from "./namespaces/functions.js"; import { Secrets } from "./namespaces/secrets.js"; import { Cache } from "./namespaces/cache.js"; import { Subdomains } from "./namespaces/subdomains.js"; import { Domains } from "./namespaces/domains.js"; import { Sites } from "./namespaces/sites.js"; import { Service } from "./namespaces/service.js"; import { Tier } from "./namespaces/tier.js"; import { Ai } from "./namespaces/ai.js"; import { Auth } from "./namespaces/auth.js"; import { Billing } from "./namespaces/billing.js"; import { Vouchers } from "./namespaces/vouchers.js"; import { Wallets, ScopedWallet } from "./namespaces/wallets.js"; import { Apps } from "./namespaces/apps.js"; import { Email } from "./namespaces/email.js"; import { Contracts } from "./namespaces/contracts.js"; import { Credentials } from "./namespaces/credentials.js"; import { Admin } from "./namespaces/admin.js"; import { Deploy } from "./namespaces/deploy.js"; import { Ci } from "./namespaces/ci.js"; import { Jobs } from "./namespaces/jobs.js"; import { Archives } from "./namespaces/archives.js"; import { Snapshots } from "./namespaces/snapshots.js"; import { Branches } from "./namespaces/branches.js"; import { Session } from "./namespaces/session.js"; import { WriteApproval } from "./namespaces/write-approval.js"; import { Me } from "./namespaces/me.js"; import { Orgs, ScopedOrg } from "./namespaces/org.js"; import { Grants } from "./namespaces/grants.js"; import { Events } from "./namespaces/events.js"; import { Live } from "./namespaces/live.js"; import { Rooms } from "./namespaces/rooms.js"; import { Escalations } from "./namespaces/escalations.js"; import { Errors } from "./namespaces/errors.js"; import { Pay, type PayExecutor } from "./namespaces/pay.js"; import { IdentityLinks } from "./namespaces/identity-links.js"; import { Buzz } from "./namespaces/buzz.js"; import { Agent } from "./namespaces/agent.js"; import { Repos } from "./namespaces/repos.js"; import type { ContentSource, FileSet } from "./namespaces/deploy.types.js"; import { ScopedRun402 } from "./scoped.js"; export interface Run402Options { /** API base URL, e.g. `https://api.run402.com`. */ apiBase: string; /** Credential provider. Required — there is no default in the isomorphic entry. */ credentials: CredentialsProvider; /** * Custom fetch implementation. Defaults to `globalThis.fetch`. Node consumers * typically pass an x402-wrapped fetch; sandbox consumers may pass a * session-bound fetch provided by their supervisor. */ fetch?: typeof globalThis.fetch; /** Optional arbitrary-URL payment executor. Node wires this automatically. */ payExecutor?: PayExecutor; /** * Optional bounded client-version metadata for Node/supervised runtimes. * The SDK does not set this automatically in the isomorphic entry point, so * browser clients avoid surprise CORS preflights unless the caller explicitly * opts in. */ clientMetadata?: Run402ClientMetadata | false; /** * What this client may hand back to its caller. Omitted fields take the * defaults (`returnSecrets: true`). `@run402/sdk/node` sets * `returnSecrets: false` for the `sandbox` surface. */ capabilities?: Partial; } export declare class Run402 { #private; readonly apiBase: string; readonly projects: Projects; readonly assets: Assets; readonly functions: Functions; readonly secrets: Secrets; readonly cache: Cache; readonly subdomains: Subdomains; readonly domains: Domains; readonly sites: Sites; readonly service: Service; readonly tier: Tier; readonly ai: Ai; readonly image: Ai; readonly auth: Auth; readonly billing: Billing; readonly vouchers: Vouchers; readonly wallets: Wallets; readonly apps: Apps; readonly email: Email; readonly contracts: Contracts; readonly credentials: Credentials; readonly admin: Admin; /** * Internal engine. Unified apply has no public `r.deploy` or `r.apply` * root surface — the sole hero is `r.project(id).apply`. * This property exists only so the scoped sub-client can delegate to the * engine implementation; do not call directly from user code. * @internal */ readonly _applyEngine: Deploy; readonly ci: Ci; readonly jobs: Jobs; readonly archives: Archives; readonly snapshots: Snapshots; readonly branches: Branches; /** * A person's sign-in session: the browser, loopback (`run402 login`), and * device (`run402 login --device`, read-only) mints, plus refresh, revoke, * step-up, passkey enrollment, and authenticators. Distinct from the agent's * per-wallet SIWX identity. */ readonly session: Session; /** * The passkey-signed, target-scoped write approval a signed-in person needs * to provision, deploy, or write secrets from the command line * (`r.writeApproval.requestChallenge` + `exchangeClaimCode`). */ readonly writeApproval: WriteApproval; /** The caller's own account reads: `r.me.overview()` and `r.me.status()`. */ readonly me: Me; /** * Org collection + identity (gateway v1.77+, first-class in v1.82): * `r.orgs.create()` / `list()` / `whoami()`. For operations on a single org by * id use the scoped sub-client {@link Run402.org} (`r.org(id).get()` / * `rename()` / `members.*` / `invites.*` / `audit()`). Distinct from the local, * network-free {@link Run402.whoami}. */ readonly orgs: Orgs; /** * Per-project capability grants for agent/CI principals, and the grant keys * minted against them — scoped, revocable credentials an owner hands an * agent without a wallet of its own, and the supported way back in when a * project's API keys are lost (they are issued once at create and never * re-issued). Also available project-scoped as `r.project(id).grants`. */ readonly grants: Grants; /** * Cursored project events feed — "what happened since I last looked". * Also available project-scoped as `r.project(id).events`. */ readonly events: Events; /** * tenant-live-changes: change hints for live tables (`tables[].live: true`), * as a reconnecting SSE subscription or a held read. Also project-scoped as * `r.project(id).live`. */ readonly live: Live; /** * Agent-messaging coordination rooms — presence, room-visible addressed * messages, advisory claims. Org-scoped; a project id names its default * room (`r.rooms.forProject(projectId)` is the zero-config rendezvous). */ readonly rooms: Rooms; /** * The agent→human hotline: raise an escalation when YOU judge a person is * needed, then poll it until a named human takes ownership. Mandatory * delivery, confidential (never mirrored into a feed or a room), and it * climbs to the next contact level if nobody answers. */ readonly escalations: Escalations; /** Pay arbitrary x402-priced URLs with a spend ceiling and structured receipt. */ readonly pay: Pay; /** * Release-error-rollup query surface — verdict-first, grouped error * fingerprints with a gateway-computed promote-vs-revert verdict, plus the * `watch` promote-gate poll loop. Also available project-scoped as * `r.project(id).errors`. */ readonly errors: Errors; /** Public dual-proof associations between the active agent principal and external identities. */ readonly identityLinks: IdentityLinks; /** The calling agent's own facts: its Lightning wallet. */ readonly agent: Agent; /** Buzz human adoption, community installation, and bounded agent enrollment workflows. */ readonly buzz: Buzz; /** * vault — the host-blind encrypted Git remote (`r402s/v0`). Vault reads * (record, heads listing, policy) run anywhere; the verbs that touch a git * tree or the on-disk keystore (`init`, `push`, `compact`, `verify`, * `deploy`, `restore`) are Node-only and load `@run402/sdk/node` lazily. * * This namespace is where ALL vault protocol logic lives: the CLI's * `run402 repos …`, `git-remote-run402`, and the MCP tools are adapters * over it and add no behaviour of their own. * * Durability is keystore-qualified: the vault protects source history from * host-side loss while a principal keystore survives. */ readonly repos: Repos; readonly idempotency: { fromParts: typeof fromParts; }; constructor(opts: Run402Options); /** * Return a project-scoped sub-client where every project-id-bearing namespace * method has the id pre-bound. Methods on the scoped client drop their * `id`/`project_id`/`project` argument; caller-supplied values still win * (so you can address a different project ad-hoc through a scoped handle). * * Resolution rules: * - Explicit `id`: scope is bound to that id immediately and SYNCHRONOUSLY — * `r.project(id).apply(spec)` is the documented hero and needs no `await` * (an `await` on the returned client is a harmless no-op, so existing * awaiting callers keep working). The keystore is NOT consulted at * construction; the first method call that needs keys will throw * `ProjectNotFound` if the id is unknown. * - No argument: the SDK calls `credentials.getActiveProject()`, which is * async, so this form returns a Promise. Throws `LocalError` (context: * "scoping client to project") when the provider does not implement * `getActiveProject` or returns `null`. * * Until 4.90.x both forms returned a Promise, so a plain-JavaScript caller * writing the documented `r.project(id).apply.plan(...)` got * `undefined.plan` at runtime while TypeScript callers were saved only by the * Promise type. The overload makes the explicit-id contract match its docs. * * `project()` does NOT mutate keystore state — use {@link useProject} for * the persist-then-scope shorthand. */ project(id: string): ScopedRun402; project(): Promise; /** * Persist `id` as the active project (via `r.projects.use(id)`) AND return a * project-scoped sub-client in one call. Equivalent to: * * await r.projects.use(id); * return r.project(id); * * Note: this mutates the credential provider's persistent active-project * state (the keystore on Node). Concurrent CLI runs share that state. For * transient in-script scoping that does not change the user's CLI default, * use {@link project} instead. */ useProject(id: string): Promise; /** * Return an org-scoped sub-client with `id` pre-bound — the org analog of * {@link Run402.project}. Instance operations (`get`, `rename`, `members.*`, * `invites.*`, `audit`) drop their org-id argument. Synchronous: an org id is * always explicit (there is no "active org" fallback). Collection/identity * operations (`create`, `list`, `whoami`) live on {@link Run402.orgs}. */ org(id: string): ScopedOrg; /** * Return a wallet-scoped sub-client with `address` pre-bound — the wallet * analog of {@link Run402.project}. Exposes `getLabel()` / `setLabel(label)` * without the address as a swappable positional. Lazy and synchronous (no key * or network access at construction). */ wallet(address: string): ScopedWallet; /** * Identify the active wallet and project: `{ local_label, server_label, * address, activeProject }`. `local_label` is the local wallet/profile * selector (e.g. "kychon", or "default"); `server_label` is the server-side * display name (null when unknown/offline); `address` is the wallet address; * `activeProject` is the currently-selected project id (null if none). * * Degrades gracefully: providers that don't implement `getWalletIdentity` * (sandbox/session) still get `address` from `readWallet` when available. */ whoami(): Promise; /** * Cumulative request-kernel observability for this SDK instance: round * trips, wire time, and bytes transferred, across every namespace call * this instance has made. Monotonic — never resets — and reflects only * THIS `Run402` instance (a fresh one, e.g. from a fresh `getSdk()` call, * starts back at zero). See `RUN402_TRACE` in `kernel.ts` for the matching * per-request stderr trace line. */ stats(): ClientStats; /** * What this client may hand back to its caller. `returnSecrets` is false on * the `sandbox` surface, where every method that would return or consume a * one-time secret refuses with `SECRET_REQUIRES_CLI`. */ get capabilities(): Readonly; } /** Result of {@link Run402.whoami}. */ export interface WhoAmI { /** Local wallet/profile selector name (e.g. "kychon", "default"), or null. */ local_label: string | null; /** Server-side display label, cached locally; null when unknown/offline. */ server_label: string | null; /** Wallet address, or null when no local wallet is configured. */ address: string | null; /** Active project id, or null when none is selected. */ activeProject: string | null; } /** * Build a `FileSet` from a path-keyed record of byte sources. A passthrough * convenience: the SDK can consume the same shape whether you call this or * pass the literal directly. Useful for IDE autocomplete on the * `ContentSource` union and for keeping deploy specs declarative. * * @example * await (await r.project(project)).apply({ * project, * site: { replace: files({ * "index.html": "

hi

", * "logo.png": logoBytes, * "data.json": new Blob([JSON.stringify(d)], { type: "application/json" }), * })}, * }); */ export declare function files(record: Record): FileSet; export declare function fromParts(...parts: Array): string; /** * Factory wrapper equivalent to `new Run402(opts)`. Reads better in code-mode * sandbox examples: `const r = run402({ ... })`. */ export declare function run402(opts: Run402Options): Run402; export type { ClientCapabilities, Run402ClientMetadata } from "./kernel.js"; export { DEFAULT_CLIENT_CAPABILITIES } from "./kernel.js"; export { Run402Error, PaymentRequired, ProjectCredentialNotFound, ProjectNotFound, Unauthorized, NotAuthorizedError, ApiError, NetworkError, PaymentAttemptError, LocalError, SecretRequiresCliError, ValueTransferRequiresCliError, Run402DeployError, TransferFreezeError, StepUpRequiredError, WriteApprovalRequiredError, PROJECT_CREDENTIAL_ERROR_CODES, isRun402Error, isPaymentRequired, isProjectCredentialError, isProjectCredentialExpired, isProjectCredentialInvalid, isProjectCredentialNotFound, isProjectCredentialProjectMismatch, isProjectNotFound, isUnauthorized, isNotAuthorized, isApiError, isNetworkError, isPaymentAttemptError, isLocalError, isSecretRequiresCli, isDeployError, isTransferFreezeError, isStepUpRequired, isWriteApprovalRequired, isRetryableRun402Error, getQuotaScope, } from "./errors.js"; export type { Run402DeployErrorCode, Run402DeployErrorFix, Run402ErrorKind, Run402QuotaScope, ProjectCredentialErrorCode, NextAction, NextActionType, PaymentAttemptPhase, PaymentAttemptMutationState, } from "./errors.js"; export { withRetry } from "./retry.js"; export { SECRET_RETURNING_METHODS } from "./secret-gate.js"; export type { SecretGateEntry, SecretReturningMethod } from "./secret-gate.js"; export type * from "./retry.js"; export { Run402Action } from "./actions.js"; export type * from "./actions.js"; export { defineConfig, dir, emailTrigger, file, nodeFunction, scheduleTrigger, sqlFile, } from "./config.js"; export type * from "./config.js"; export type * from "./credentials.js"; export type * from "./kernel.js"; export { PROJECT_OPERATION_AUTH_CLASSIFICATIONS, projectOperationAuthClassification, } from "./project-auth-classification.js"; export type * from "./project-auth-classification.js"; export { CI_SESSION_CREDENTIALS, createCiSessionCredentials, githubActionsCredentials, isCiSessionCredentials, } from "./ci-credentials.js"; export type * from "./ci-credentials.js"; export { GRANT_KEY_CREDENTIALS, GRANT_KEY_ENV, grantKeyFromEnv, isGrantKeyCredentials, } from "./grant-key-credentials.js"; export type * from "./grant-key-credentials.js"; export * from "./app-up.js"; export { CONTROL_PLANE_SESSION_CREDENTIALS, controlPlaneSessionCredentials, isControlPlaneSessionCredentials, } from "./control-plane-credentials.js"; export type * from "./control-plane-credentials.js"; export { EMPTY_STATIC_MANIFEST_METADATA, ROUTE_HTTP_METHODS, buildDeployResolveSummary, isDeployResolveRouteHit, isDeployResolveStaticHit, normalizeDeployResolveRequest, normalizeStaticManifestMetadata, summarizeDeployResult, } from "./namespaces/deploy.types.js"; export { Ci, CI_AUDIENCE, CI_BINDING_REVOKED_ERROR, CI_GITHUB_ACTIONS_ISSUER, CI_GITHUB_ACTIONS_PROVIDER, DEFAULT_CI_DELEGATION_CHAIN_ID, V1_CI_ALLOWED_ACTIONS, V1_CI_ALLOWED_EVENTS_DEFAULT, assertCiDeployableSpec, buildCiDelegationResourceUri, buildCiDelegationStatement, isCiBindingRevoked, normalizeCiRouteScopes, normalizeCiDelegationValues, validateCiNonce, validateCiRouteScope, validateCiSubjectMatch, } from "./namespaces/ci.js"; export { ScopedRun402 } from "./scoped.js"; export type * from "./namespaces/admin.js"; export type * from "./namespaces/transfers.js"; export { Transfers } from "./namespaces/transfers.js"; export type * from "./namespaces/ai.js"; export type * from "./namespaces/apps.js"; export type * from "./namespaces/auth.js"; export type * from "./namespaces/billing.js"; export type * from "./namespaces/cache.js"; export type * from "./namespaces/assets.types.js"; export type * from "./namespaces/ci.types.js"; export type * from "./namespaces/contracts.js"; export type * from "./namespaces/credentials.js"; export type * from "./namespaces/credentials.types.js"; export type * from "./namespaces/deploy.types.js"; export type { SiteRemovalSummary } from "./namespaces/site-removal-summary.js"; export { Deploy } from "./namespaces/deploy.js"; export type { ByteReader } from "./namespaces/deploy.js"; export type * from "./namespaces/domains.js"; export type * from "./namespaces/email.js"; export { FunctionRunTerminalError, FunctionRuns, classifyFunctionLogLine } from "./namespaces/functions.js"; export type * from "./namespaces/functions.types.js"; export type * from "./namespaces/jobs.js"; export { Session } from "./namespaces/session.js"; export type * from "./namespaces/session.js"; export { WriteApproval } from "./namespaces/write-approval.js"; export type * from "./namespaces/write-approval.js"; export { Me } from "./namespaces/me.js"; export type * from "./namespaces/me.js"; export { Orgs, ScopedOrg, OrgMembers, OrgInvites, OrgAdopt, OrgLightningReceiver } from "./namespaces/org.js"; export type { AdoptChallenge, AdoptChallengeInput, AdoptSubmitInput, AdoptResult, SelectableOrg, LightningReceiver, SetLightningReceiverInput, LightningReceiverRemoved } from "./namespaces/org.js"; export type * from "./namespaces/org.types.js"; export { Grants } from "./namespaces/grants.js"; export type * from "./namespaces/grants.types.js"; export { Events } from "./namespaces/events.js"; export type * from "./namespaces/events.types.js"; export type * from "./namespaces/live.types.js"; export { Rooms, ScopedRoom } from "./namespaces/rooms.js"; export { Escalations } from "./namespaces/escalations.js"; export { waitFor, type WaitForOptions, type WaitForResult } from "./wait.js"; export type * from "./namespaces/rooms.types.js"; export type * from "./namespaces/escalations.types.js"; export { Errors } from "./namespaces/errors.js"; export type * from "./namespaces/errors.types.js"; export { Vouchers } from "./namespaces/vouchers.js"; export type * from "./namespaces/vouchers.js"; export { Pay, PaymentBuyerError, PaymentPolicyError, DEFAULT_PAYMENT_MAX_USD_MICROS, X402_COMMERCE_RESULT_SCHEMA_VERSION, X402_EVIDENCE_STATUSES, X402_GATEWAY_AVAILABILITY_ERROR_CODE, X402_MUTATION_STATES, X402_PAYMENT_POLICY_ERROR_CODES, X402_RECOVERY_ACTIONS, RUN402_PENDING_CLASSIFIER_VERSION, isPaymentBuyerError, isPaymentPolicyError, isTrustedRun402PaymentUrl, isTrustedRun402PendingResponse, payFetchResultToJson, } from "./namespaces/pay.js"; export type * from "./namespaces/pay.js"; export { Archives } from "./namespaces/archives.js"; export type * from "./namespaces/archives.types.js"; export { Snapshots } from "./namespaces/snapshots.js"; export type * from "./namespaces/snapshots.types.js"; export { Branches } from "./namespaces/branches.js"; export type * from "./namespaces/branches.types.js"; export type * from "./namespaces/projects.types.js"; export { IdentityLinks, NostrIdentityLinks } from "./namespaces/identity-links.js"; export type * from "./namespaces/identity-links.js"; export type * from "./namespaces/identity-links.types.js"; export { Agent, AgentLightningWallets } from "./namespaces/agent.js"; export type * from "./namespaces/agent.types.js"; export { Buzz, BuzzHumanAdoptions, BuzzHumanAdoptionOffers, BuzzCommunityInstallations, BuzzAgentEnrollments, BuzzNotifications } from "./namespaces/buzz.js"; export type * from "./namespaces/buzz.types.js"; export type * from "./namespaces/buzz-notifications.types.js"; export type * from "./namespaces/secrets.js"; export type * from "./namespaces/service.js"; export type * from "./namespaces/sites.js"; export type * from "./namespaces/subdomains.js"; export type * from "./namespaces/stripe.js"; export type * from "./namespaces/tier.js"; export { ScopedWallet } from "./namespaces/wallets.js"; export type * from "./namespaces/wallets.js"; export * from "./namespaces/vault.crypto.js"; export type * from "./namespaces/vault.crypto.js"; export type * from "./namespaces/vault.types.js"; export { Repos, vaultRemoteUrl, vaultRemoteUrlForRepo, parseVaultRemoteUrl, vaultRemoteAddressForm, vaultSlugReleasedInfo, VAULT_LOSS_WARNING_THRESHOLDS, vaultLossWarningTrip, vaultLossWarningTripped, vaultLossWarningMessage, vaultUnmirroredFinding, vaultDegradedReadNote, handoffVaultFromWire, handoffMembershipFromWire, } from "./namespaces/repos.js"; export type * from "./namespaces/repos.js"; export { normalizeEdgeEvidence, mergeEdgeVerification } from "./namespaces/edge-evidence.js"; export { RestPermissionDenied } from "./rest-diagnostics.js"; //# sourceMappingURL=index.d.ts.map