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.
207 lines • 12.3 kB
TypeScript
import type { Client } from "../kernel.js";
import type { BuzzEventRoute, BuzzEventRouteDetail, BuzzRouteDelivery, BuzzRouteDeliveryList, BuzzRouteRotation, BuzzRouteTestDelivery, CreateBuzzEventRouteInput, CreatedBuzzEventRoute, ListBuzzRouteDeliveriesOptions, RevokedBuzzEventRoute, TestAndWaitBuzzRouteOptions, UpdateBuzzEventRoutePatch } from "./buzz-notifications.types.js";
import type { BuzzAgentEnrollment, BuzzAgentEnrollmentApprovalInput, BuzzAgentEnrollmentCreateInput, BuzzAgentEnrollmentStatus, BuzzCapabilityStatus, BuzzCommunityInstallation, BuzzCommunityInstallationCreateInput, BuzzCommunityInstallationUpdateInput, BuzzTeammateJoin, BuzzTeammateJoinInput, BuzzHumanAdoption, BuzzHumanAdoptionAttemptCreateInput, BuzzHumanAdoptionCreateInput, BuzzHumanAdoptionOffer, BuzzHumanAdoptionOfferCreateInput, BuzzPublicCommunityDescriptor } from "./buzz.types.js";
export declare class BuzzHumanAdoptions {
private readonly client;
constructor(client: Client);
create(input: BuzzHumanAdoptionCreateInput): Promise<BuzzHumanAdoption>;
list(organizationId: string): Promise<BuzzHumanAdoption[]>;
get(id: string): Promise<BuzzHumanAdoption>;
complete(id: string, ownerProofEvent: unknown, idempotencyKey?: string): Promise<BuzzHumanAdoption>;
cancel(id: string, idempotencyKey?: string): Promise<BuzzHumanAdoption>;
}
/** Durable agent-created HTTPS offer pages. Creating an offer is inert; the human
* receives authority only after a separately authenticated, passkey-stepped-up
* browser attempt completes with the exact Buzz proof. */
export declare class BuzzHumanAdoptionOffers {
private readonly client;
constructor(client: Client);
create(input: BuzzHumanAdoptionOfferCreateInput): Promise<BuzzHumanAdoptionOffer>;
get(id: string): Promise<BuzzHumanAdoptionOffer>;
cancel(id: string, idempotencyKey?: string): Promise<BuzzHumanAdoptionOffer>;
createAttempt(id: string, input: BuzzHumanAdoptionAttemptCreateInput): Promise<BuzzHumanAdoption>;
}
export declare class BuzzCommunityInstallations {
private readonly client;
constructor(client: Client);
create(input: BuzzCommunityInstallationCreateInput): Promise<BuzzCommunityInstallation>;
list(organizationId: string): Promise<BuzzCommunityInstallation[]>;
get(id: string): Promise<BuzzCommunityInstallation>;
/**
* The invite front door: `invite` is the one-use relay invite a Buzz
* community owner or admin minted in Buzz Desktop — the bare code, an
* `https://<relay>/invite/<code>` link, or a `buzz://join?…` link. Run402
* claims it as the installation identity; no Nostr key leaves Desktop.
*/
activate(id: string, invite: string, idempotencyKey?: string): Promise<BuzzCommunityInstallation>;
/**
* The teammate door (`POST /buzz-community-installations/v1/:id/teammates`):
* a Buzz-launched agent presents the NIP-OA owner attestation Buzz injected
* as `BUZZ_AUTH_TAG` and, when the installation's policy opens the door
* (`owner_attested_agents: "developer"`) and the attesting owner is a
* current community owner/admin, joins the installed organization as a
* developer under its own principal. 201 on join, 200 when already a
* teammate. The attestation is public data (owner pubkey + signature).
*/
joinAsTeammate(id: string, input: BuzzTeammateJoinInput): Promise<BuzzTeammateJoin>;
update(id: string, input: BuzzCommunityInstallationUpdateInput): Promise<BuzzCommunityInstallation>;
revoke(id: string, idempotencyKey?: string): Promise<BuzzCommunityInstallation>;
discoverPublicDescriptors(buzzCommunitySubject: string): Promise<BuzzPublicCommunityDescriptor[]>;
getPublicDescriptor(id: string): Promise<BuzzPublicCommunityDescriptor>;
}
export declare class BuzzAgentEnrollments {
private readonly client;
constructor(client: Client);
request(input: BuzzAgentEnrollmentCreateInput): Promise<BuzzAgentEnrollment>;
list(options?: {
organizationId?: string;
status?: BuzzAgentEnrollmentStatus;
}): Promise<BuzzAgentEnrollment[]>;
get(id: string): Promise<BuzzAgentEnrollment>;
approve(id: string, input: BuzzAgentEnrollmentApprovalInput): Promise<BuzzAgentEnrollment>;
deny(id: string, reason?: string, idempotencyKey?: string): Promise<BuzzAgentEnrollment>;
revoke(id: string, idempotencyKey?: string): Promise<BuzzAgentEnrollment>;
}
/**
* `buzz.notifications` — project-event routing into a Buzz community channel
* (gateway `add-buzz-project-event-routing`).
*
* A route is an owner-declared destination: one active community
* installation, an explicit 1–50 project scope, reviewed event filters, one
* NIP-29 channel. Run402's project-event feed stays authoritative — Buzz
* relay state never creates, acknowledges, or advances a Run402 event, and
* Buzz is NEVER a deadman channel: mandatory notification classes keep their
* human paths regardless of route state.
*
* The workflow is **configure → authorize → test → live**:
*
* ```ts
* const created = await r.buzz.notifications.createRoute(orgId, {
* installationId: "buzzci_…",
* routeName: "deploys",
* buzzChannelId: "<nip-29 channel id>",
* projectIds: ["prj_…"],
* });
* if (created.authorization.status === "pending_buzz_authorization") {
* // The ONE non-secret handoff: a Buzz community owner adds
* // created.authorization.notification_pubkey as a relay member
* // (created.authorization.instructions says exactly how), then:
* const delivery = await r.buzz.notifications.testAndWait(
* created.buzz_project_event_route_id,
* );
* // delivered ⇒ live. Still queued ⇒ the tick publishes ~every 60s —
* // silence here is cadence, not failure; keep polling deliveries.
* }
* ```
*
* Load-bearing semantics:
* - Only three reviewed event types are routable (`deploy_activated`,
* `error_fingerprints_observed`, `platform_incident`); the classes
* `security` / `billing_critical` / `destructive_lifecycle` /
* `verification` / `recovery` may never be routed.
* - Filters: omitted/`null` = everything registered; an explicit `[]` is a
* 422, never a wildcard and never a silent match-nothing.
* - Every mutation carries an `Idempotency-Key` (auto-generated when not
* given) and requires fresh `buzz.event_route` step-up server-side (a SIWX
* wallet is inherently fresh).
* - No response ever contains the signing secret — `notification_pubkey` +
* `signing_generation` are the only credential material on the wire.
* - Routes deliver NEW events only (`start_after_event_id` floor); delivery
* is at-least-once with byte-identical republish, backing off to
* `dead_letter` after 8 attempts / 48h — visible in `deliveries()`.
*/
export declare class BuzzNotifications {
private readonly client;
constructor(client: Client);
/**
* Create a route (`POST /buzz-project-event-routes/v1`, 201). The response
* carries an `authorization` block: the installation's first route is
* `pending_buzz_authorization` with the exact non-secret connect handoff a
* Buzz community owner completes; later routes on an already-authorized
* installation come back `authorized` and active.
*/
createRoute(organizationId: string, input: CreateBuzzEventRouteInput): Promise<CreatedBuzzEventRoute>;
/** List the organization's routes, including retained revoked ones. */
list(organizationId: string): Promise<BuzzEventRoute[]>;
/**
* Route detail: the route plus honest `health` (derived from route +
* credential state, never queue emptiness), `delivery_counts`, the oldest
* pending time, and the shared `consumer_cursor`.
*/
get(routeId: string): Promise<BuzzEventRouteDetail>;
/**
* Update name / channel / project scope / filters
* (`PATCH /:id` with `expected_revision`). A stale revision fails
* `409 BUZZ_ROUTE_REVISION_STALE` without mutating — re-read, re-decide,
* re-send with the current `revision`.
*/
update(routeId: string, patch: UpdateBuzzEventRoutePatch, expectedRevision: number): Promise<BuzzEventRoute>;
/**
* Stop matching new events (`POST /:id/pause`). Non-terminal deliveries
* freeze; events occurring while paused are never retroactively delivered.
*/
pause(routeId: string, idempotencyKey?: string): Promise<BuzzEventRoute>;
/**
* Re-arm delivery and reset the hard-failure counter (`POST /:id/resume`).
* Requires a live signing credential NOW — resuming into
* signing-unavailable fails `503 BUZZ_NOTIFICATION_SIGNING_UNAVAILABLE`
* rather than fabricating an "active" route whose every attempt fails.
*/
resume(routeId: string, idempotencyKey?: string): Promise<BuzzEventRoute>;
/**
* Revoke (`DELETE /:id`): queued deliveries are cancelled, sanitized history
* stays readable, and `notification_credential_destroyed` reports whether
* this was the installation's last live route (only then does its
* notification credential die — never out from under a sibling).
*/
revoke(routeId: string, idempotencyKey?: string): Promise<RevokedBuzzEventRoute>;
/**
* Stage the NEXT signing generation (`POST /:id/rotate`, 202). The current
* key keeps signing; the swap activates only after the next pubkey's own
* Buzz-side NIP-43 membership verifies — the `rotation` block carries the
* next pubkey, the authorize hint, and the `verify_path` to poke.
*/
rotate(routeId: string, idempotencyKey?: string): Promise<BuzzRouteRotation>;
/**
* Queue one signed test delivery (`POST /:id/test`, 202 + Retry-After).
* On a `pending_authorization` route this FIRST re-checks the Buzz-side
* NIP-43 membership and activates the route when it landed — the test
* endpoint doubles as the authorization poll. The 202 is queued-not-
* delivered (Faithful): poll `poll.path` (or use {@link testAndWait}).
*/
test(routeId: string, idempotencyKey?: string): Promise<BuzzRouteTestDelivery>;
/** Keyset newest-first delivery history — dead letters included, the signed envelope never. */
deliveries(routeId: string, opts?: ListBuzzRouteDeliveriesOptions): Promise<BuzzRouteDeliveryList>;
/**
* Queue a test delivery, then poll it until it settles — the whole
* verify-the-route flow in one call.
*
* Returns as soon as the delivery reaches a terminal status
* (`delivered` | `dead_letter` | `cancelled` | `suppressed`). On timeout
* the still-queued delivery is RETURNED, never thrown (the shared `waitFor`
* contract) — and unlike an unanswered escalation, a not-yet-delivered test
* here is usually just cadence: the single-consumer tick publishes ~every
* 60s, so keep polling `deliveries()` before concluding anything is wrong.
*/
testAndWait(routeId: string, opts?: TestAndWaitBuzzRouteOptions): Promise<BuzzRouteTestDelivery | BuzzRouteDelivery>;
}
export declare class Buzz {
private readonly client;
readonly humanAdoptions: BuzzHumanAdoptions;
readonly humanAdoptionOffers: BuzzHumanAdoptionOffers;
readonly communityInstallations: BuzzCommunityInstallations;
readonly enrollments: BuzzAgentEnrollments;
readonly notifications: BuzzNotifications;
constructor(client: Client);
/** Capability-detecting status. Older gateways return a safe supported:false result. */
status(): Promise<BuzzCapabilityStatus>;
/** Goal-shaped alias for the canonical adoption initiation. */
adopt(input: BuzzHumanAdoptionCreateInput): Promise<BuzzHumanAdoption>;
/** Create the canonical conversational HTTPS offer without starting consent. */
offerAdoption(input: BuzzHumanAdoptionOfferCreateInput): Promise<BuzzHumanAdoptionOffer>;
/** Goal-shaped alias for the canonical community installation initiation. */
install(input: BuzzCommunityInstallationCreateInput): Promise<BuzzCommunityInstallation>;
/** Goal-shaped alias for the canonical agent enrollment request. */
enroll(input: BuzzAgentEnrollmentCreateInput): Promise<BuzzAgentEnrollment>;
}
//# sourceMappingURL=buzz.d.ts.map