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.
86 lines • 4.7 kB
TypeScript
/**
* `blobs` namespace — direct-to-S3 blob storage.
*
* `put` encapsulates the 3-step upload flow (init → PUT parts to S3 →
* complete). The S3 PUT uses `client.fetch` directly (not the gateway's
* `request`) so it bypasses gateway auth and path-rewriting. The client's
* configured fetch still flows through any wrappers (e.g. test mocks).
*/
import type { Client } from "../kernel.js";
import type { BlobDiagnoseEnvelope, BlobLsOptions, BlobLsResult, BlobRmResult, BlobPutOptions, BlobPutResult, BlobPutSource, BlobSignOptions, BlobSignResult, BlobWaitFreshOptions, BlobWaitFreshResult } from "./assets.types.js";
export declare class Assets {
private readonly client;
constructor(client: Client);
/**
* Upload a blob via the 3-step direct-to-S3 flow. The bytes are PUT to
* presigned S3 URLs — they do NOT pass through the gateway, so uploads
* are not double-billed as API calls and large files stream efficiently.
*
* Pass `immutable: true` to produce a content-addressed URL. The SDK always
* computes the SHA-256 digest required by the upload API; `immutable` only
* controls URL/cache semantics.
*
* @throws {ProjectNotFound} if `projectId` is not in the provider.
*/
put(projectId: string, key: string, source: BlobPutSource, opts?: BlobPutOptions): Promise<BlobPutResult>;
/**
* Diagnose a public blob URL. Returns a JSON envelope describing the live
* CDN state (expected vs observed SHA, cache headers, recent invalidation
* status, vantage). The gateway probes the URL once from us-east-1 with
* `Range: bytes=0-0` and returns within 5 s even if the inner probe is
* slow.
*
* **Vantage caveat:** the result reflects ONE CloudFront PoP at the time
* of the call. Other PoPs may serve different cached states. The
* `probeMayHaveWarmedCache: true` field reminds the agent that the probe
* itself populates the cache, so a subsequent read may differ.
*
* The URL must belong to the requesting project — cross-project URLs are
* rejected by the gateway with `403`. SSRF is enforced gateway-side: only
* `*.run402.com` and the project's active custom domains are accepted.
*
* @example
* const diag = await client.blobs.diagnoseUrl("prj_abc", "https://app.run402.com/_blob/avatar.png");
* if (diag.observedSha256 !== diag.expectedSha256) console.log(diag.hint);
*/
diagnoseUrl(projectId: string, url: string): Promise<BlobDiagnoseEnvelope>;
/**
* Poll the CDN until a mutable URL serves the expected SHA-256, or the
* timeout elapses. **For mutable URLs only** — for immutable URLs (the
* `immutableUrl` returned by `put`) no waiting is needed; they're bound
* at upload time and never previously cached.
*
* Default `timeoutMs` is 60_000 (60 s). The helper polls the gateway's
* diagnose endpoint with exponential backoff bounded by 1 s; each poll
* may itself warm the cache for the probed PoP, so subsequent reads from
* other PoPs may still be stale until invalidation propagation completes.
*
* @example
* await client.blobs.waitFresh("prj_abc", {
* url: result.url, // the mutable URL from blobs.put
* sha256: result.contentSha256,
* timeoutMs: 30_000,
* });
*/
waitFresh(projectId: string, opts: BlobWaitFreshOptions): Promise<BlobWaitFreshResult>;
/**
* Download a blob. Returns the raw `Response` so callers can stream to
* disk, pipe to another sink, or buffer with `.bytes()` / `.arrayBuffer()`.
* This avoids forcing large blobs through a JS buffer.
*
* @throws {ProjectNotFound} if `projectId` is not in the provider.
* @throws {ApiError} on non-2xx (includes the error text from the response body).
*/
get(projectId: string, key: string): Promise<Response>;
/** List blobs with optional prefix + pagination + (v1.50) sort + filter.
* Unknown filter keys, invalid sort values, and other structural issues
* are rejected client-side BEFORE any HTTP call. */
ls(projectId: string, opts?: BlobLsOptions): Promise<BlobLsResult>;
/** Delete a blob and decrement the project's storage_bytes. Revokes the
* key's immutable URLs (including image variants) and queues a CDN
* invalidation for a public key. */
rm(projectId: string, key: string): Promise<BlobRmResult>;
/** Generate a time-boxed S3 presigned GET URL for a blob. Default TTL 1 hour, max 7 days. */
sign(projectId: string, key: string, opts?: BlobSignOptions): Promise<BlobSignResult>;
}
//# sourceMappingURL=assets.d.ts.map