@paneui/core 0.0.5 → 0.0.7

package/dist/client.d.ts

@@ -1,4 +1,5 @@
-import type { ArtifactRecord, ArtifactSummary, ArtifactType, ArtifactVersion, CreateArtifactResponse, CreateSessionRequest, CreateSessionResponse, EventsPage, FeedbackPage, FeedbackSubmission, FeedbackType, KeyInfo, PaneEvent, SessionState, TasteInfo } from "./types.js";
+import type { TemplateRecord, TemplateSummary, TemplateType, TemplateVersion, CreateArtifactResponse, CreateSessionRequest, CreateSessionResponse, EventsPage, FeedbackPage, FeedbackSubmission, FeedbackType, KeyInfo, MintParticipantResponse, PaneEvent, ParticipantsList, SurfaceState, SurfacesPage, TasteInfo } from "./types.js";
+import type { ListSessionsQuery } from "./schemas.js";
 export interface ClientOptions {
     /** Relay base URL, e.g. https://pane.example.com. Trailing slash is trimmed. */
     url: string;
@@ -23,7 +24,7 @@ export interface RelayResponse {
     data: unknown;
 }
 /**
- * Request body for POST /v1/artifacts — create a named, reusable artifact plus
+ * Request body for POST /v1/templates — create a named, reusable template plus
  * its v1 content. Mirrors `createArtifactSchema` from ./schemas.js.
  */
 export interface CreateArtifactRequest {
@@ -32,22 +33,22 @@ export interface CreateArtifactRequest {
     description?: string;
     tags?: string[];
     source: string;
-    type: ArtifactType;
+    type: TemplateType;
     event_schema?: unknown;
     input_schema?: Record<string, unknown>;
 }
 /**
- * Request body for POST /v1/artifacts/:id/versions — append a new immutable
+ * Request body for POST /v1/templates/:id/versions — append a new immutable
  * version (content only). Mirrors `createArtifactVersionSchema`.
  */
 export interface CreateArtifactVersionRequest {
     source: string;
-    type: ArtifactType;
+    type: TemplateType;
     event_schema?: unknown;
     input_schema?: Record<string, unknown>;
 }
 /**
- * Request body for PATCH /v1/artifacts/:id — head metadata only (never
+ * Request body for PATCH /v1/templates/:id — head metadata only (never
  * content). Mirrors `patchArtifactMetadataSchema`.
  */
 export interface PatchArtifactMetadataRequest {
@@ -97,21 +98,21 @@ export declare class PaneClient {
     private asObject;
     /** Throw a PaneApiError from a failed RelayResponse. */
     private fail;
-    /** POST /v1/sessions — create a session. */
+    /** POST /v1/surfaces — create a surface. */
     createSession(req: CreateSessionRequest): Promise<CreateSessionResponse>;
-    /** GET /v1/sessions/:id — non-blocking session metadata. */
-    getSession(sessionId: string): Promise<SessionState>;
+    /** GET /v1/surfaces/:id — non-blocking surface metadata. */
+    getSession(surfaceId: string): Promise<SurfaceState>;
     /**
-     * GET /v1/sessions/:id/events — fetch the event log.
+     * GET /v1/surfaces/:id/events — fetch the event log.
      * `since` is an opaque cursor; `waitSeconds` enables the relay long-poll
      * (0 = non-blocking, capped at 30 by the relay).
      */
-    getEvents(sessionId: string, opts?: {
+    getEvents(surfaceId: string, opts?: {
         since?: string | null;
         waitSeconds?: number;
     }): Promise<EventsPage>;
-    /** POST /v1/sessions/:id/events — append an agent event. */
-    sendEvent(sessionId: string, ev: {
+    /** POST /v1/surfaces/:id/events — append an agent event. */
+    sendEvent(surfaceId: string, ev: {
         type: string;
         data: unknown;
         causationId?: string;
@@ -121,37 +122,37 @@ export declare class PaneClient {
         deduped: boolean;
     }>;
     /**
-     * POST /v1/artifacts — create a named, reusable artifact and its v1 content.
-     * Returns the new `artifact_id` and `version` (1).
+     * POST /v1/templates — create a named, reusable template and its v1 content.
+     * Returns the new `template_id` and `version` (1).
      */
     createArtifact(req: CreateArtifactRequest): Promise<CreateArtifactResponse>;
     /**
-     * POST /v1/artifacts/:id/versions — append a new immutable version to an
-     * existing artifact. `idOrSlug` accepts the artifact id or its slug.
+     * POST /v1/templates/:id/versions — append a new immutable version to an
+     * existing template. `idOrSlug` accepts the template id or its slug.
      * Returns the new `version` number.
      */
     createArtifactVersion(idOrSlug: string, req: CreateArtifactVersionRequest): Promise<CreateArtifactResponse>;
     /**
-     * PATCH /v1/artifacts/:id — update head metadata (name / slug / description /
+     * PATCH /v1/templates/:id — update head metadata (name / slug / description /
      * tags); never the content. Returns the updated lean summary.
      */
-    updateArtifact(idOrSlug: string, metadata: PatchArtifactMetadataRequest): Promise<ArtifactSummary>;
+    updateArtifact(idOrSlug: string, metadata: PatchArtifactMetadataRequest): Promise<TemplateSummary>;
     /**
-     * GET /v1/artifacts?q=... — search/list the agent's named artifacts. The
-     * response is lean (no `source` blob), ranked by `last_used_at`. Omit `query`
-     * to list every named artifact.
+     * GET /v1/templates?q=... — search/list the agent's named templates. The
+     * response is lean (no `source` attachment), ranked by `last_used_at`. Omit `query`
+     * to list every named template.
      */
-    searchArtifacts(query?: string): Promise<ArtifactSummary[]>;
+    searchArtifacts(query?: string): Promise<TemplateSummary[]>;
     /**
-     * GET /v1/artifacts/:id — fetch a full artifact (head metadata + version
-     * list). `idOrSlug` accepts the artifact id or its slug.
+     * GET /v1/templates/:id — fetch a full template (head metadata + version
+     * list). `idOrSlug` accepts the template id or its slug.
      */
-    getArtifact(idOrSlug: string): Promise<ArtifactRecord>;
+    getArtifact(idOrSlug: string): Promise<TemplateRecord>;
     /**
-     * GET /v1/artifacts/:id/versions/:version — fetch one version's full
+     * GET /v1/templates/:id/versions/:version — fetch one version's full
      * content (HTML, event schema, input schema).
      */
-    getArtifactVersion(idOrSlug: string, version: number): Promise<ArtifactVersion>;
+    getArtifactVersion(idOrSlug: string, version: number): Promise<TemplateVersion>;
     /**
      * GET /v1/keys — the calling agent's own key info. The relay scopes this to
      * the authenticated agent: it returns one key (the caller's), not a list.
@@ -164,15 +165,27 @@ export declare class PaneClient {
      */
     revokeKey(id: string): Promise<void>;
     /**
-     * GET /v1/taste — the calling agent's freeform "taste notes" markdown blob:
+     * POST /v1/agents/claim — bind this agent to a human via a one-shot
+     * claim code the human generated in their settings UI. After a
+     * successful claim the agent's existing API key continues to work,
+     * but the agent (and its surfaces/templates) now belong to the
+     * claiming human. One-way operation — there is no unclaim in v1.
+     */
+    claimAgent(code: string): Promise<{
+        ok: true;
+        owner_human_id: string;
+        claimed_at: string;
+    }>;
+    /**
+     * GET /v1/taste — the calling agent's freeform "taste notes" markdown attachment:
      * presentation preferences the agent has picked up from human feedback over
      * time. Returns `{ taste: null, updated_at: null, bytes: 0 }` when the
-     * agent has never written notes. Read this before generating an artifact so
+     * agent has never written notes. Read this before generating an template so
      * the agent applies prior feedback.
      */
     getTaste(): Promise<TasteInfo>;
     /**
-     * PUT /v1/taste — whole-blob replace of the calling agent's taste notes.
+     * PUT /v1/taste — whole-attachment replace of the calling agent's taste notes.
      * Empty/whitespace-only values are rejected by the relay; callers asking to
      * clear must use {@link clearTaste}. The relay caps the payload at the
      * server's `MAX_TASTE_BYTES` (utf8 bytes).
@@ -192,7 +205,7 @@ export declare class PaneClient {
     submitFeedback(req: {
         type: FeedbackType;
         message: string;
-        sessionId?: string;
+        surfaceId?: string;
     }): Promise<FeedbackSubmission>;
     /**
      * GET /v1/feedback — the calling agent's own submissions, newest first.
@@ -203,16 +216,209 @@ export declare class PaneClient {
         before?: string;
     }): Promise<FeedbackPage>;
     /**
-     * DELETE /v1/sessions/:id — close/delete a session. Idempotent on the relay
-     * side (an already-closed session still returns 204 with no body).
+     * GET /v1/surfaces — list the calling agent's surfaces. Default filter is
+     * `status=open` (effective status — respects expiresAt). Response items
+     * carry NO secrets: no participant token plaintext, no callback URL, no
+     * metadata or input_data. Use `participant_id` from the list as the handle
+     * for {@link revokeParticipant}; use {@link mintParticipant} to issue a
+     * fresh URL when the original was lost.
+     */
+    listSessions(opts?: ListSessionsQuery): Promise<SurfacesPage>;
+    /**
+     * GET /v1/surfaces/:id/participants — list every participant on one
+     * surface (active and revoked). Bounded by MAX_PARTICIPANTS_PER_SESSION
+     * on the relay, so the full list is returned with no pagination.
+     * Use this to find the `participant_id` you need to pass to
+     * {@link revokeParticipant}, or to audit revoked rows.
+     */
+    listParticipants(surfaceId: string): Promise<ParticipantsList>;
+    /**
+     * POST /v1/surfaces/:id/participants — mint a fresh participant URL for an
+     * existing surface. The one-shot recovery primitive when the original URL
+     * was dropped: the surface keeps its event log, template pin, and created_at.
+     * v1 supports `kind: "human"` only.
+     *
+     * The plaintext token is returned EXACTLY ONCE in the response — the relay
+     * stores only the hash. Save the response (e.g. pipe to a JSONL log) before
+     * delivering the URL to the human.
+     */
+    mintParticipant(surfaceId: string, opts?: {
+        kind?: "human";
+    }): Promise<MintParticipantResponse>;
+    /**
+     * DELETE /v1/surfaces/:id/participants/:participant_id — revoke a single
+     * participant URL. The surface's other participants (and the agent's own
+     * WebSocket) are untouched. Idempotent: revoking an unknown or already-
+     * revoked participant returns 204. The agent participant cannot be revoked
+     * via this endpoint — use {@link deleteSession} instead.
+     *
+     * Existing WebSocket connections held under the revoked token are NOT
+     * actively kicked in v1; new HTTP and WS connections are refused.
+     */
+    revokeParticipant(surfaceId: string, participantId: string): Promise<void>;
+    /**
+     * DELETE /v1/surfaces/:id — close/delete a surface. Idempotent on the relay
+     * side (an already-closed surface still returns 204 with no body).
      */
     deleteSession(id: string): Promise<void>;
     /**
-     * DELETE /v1/artifacts/:id — remove an artifact and (server-side) all its
+     * DELETE /v1/templates/:id — remove an template and (server-side) all its
      * versions. Strict cascade: the relay refuses with 409 conflict if any
-     * session in any state still references one of the artifact's versions —
+     * surface in any state still references one of the template's versions —
      * surface that as a typed PaneApiError so the CLI can render a hint
      * instead of swallowing it.
      */
     deleteArtifact(idOrSlug: string): Promise<void>;
+    /**
+     * Upload a attachment to the relay. Returns a `AttachmentRef` that can be referenced
+     * in event payloads (the relay's `format: pane-attachment-id` schema vocab
+     * validates the id) or in `pane create --input-data`.
+     *
+     * Scope defaults to "agent" (reusable across the agent's surfaces). For
+     * `scope: "surface"` pass `surfaceId`; for `scope: "template"` pass
+     * `templateId`. The agent must own the referenced surface / template;
+     * cross-tenant attempts return attachment_not_found.
+     *
+     * MIME is inferred from `mime` if supplied; otherwise the relay sniffs
+     * leading bytes and may reject with mime_mismatch / mime_disallowed.
+     *
+     * Backed by the relay's multipart `POST /v1/attachments` (the fallback path).
+     * For large uploads (>1 MB on hosted Azure) call `presignBlob()` +
+     * `confirmBlob()` instead — those use SAS direct-to-storage and don't
+     * stream bytes through the relay.
+     */
+    uploadBlob(file: Blob | Buffer | Uint8Array, opts?: UploadBlobOptions): Promise<AttachmentRef>;
+    /** GET /v1/attachments/:id — download bytes as an ArrayBuffer. */
+    downloadBlob(attachmentId: string): Promise<ArrayBuffer>;
+    /**
+     * GET a attachment's metadata only — useful before downloading large attachments, or
+     * for `pane attachment show <id>` which doesn't want the bytes. Returns the full
+     * AttachmentRef (the same shape POST /v1/attachments returns): id, scope, mime, size,
+     * sha256, filename, width, height, status, scope FKs, timestamps.
+     *
+     * Backed by GET /v1/attachments/:id/metadata which serves the JSON AttachmentRef
+     * without streaming the bytes — cheap on the relay and avoids the
+     * encrypt-at-rest decrypt cost when only the metadata is needed.
+     */
+    getBlob(attachmentId: string): Promise<AttachmentRef>;
+    /** DELETE /v1/attachments/:id — soft-delete (idempotent). */
+    deleteBlob(attachmentId: string): Promise<{
+        deleted: true;
+    }>;
+    /**
+     * Mint a `/b/<token>` capability URL for `attachmentId`. Default TTL is set by
+     * the relay (24h agent, surface-TTL surface, 30d template). `once: true`
+     * tokens self-delete on first GET.
+     */
+    mintBlobToken(attachmentId: string, opts?: {
+        ttlSeconds?: number;
+        once?: boolean;
+    }): Promise<AttachmentTokenMintResponse>;
+    /** Revoke a previously-minted token. Idempotent. */
+    revokeBlobToken(attachmentId: string, tokenId: string): Promise<{
+        token_id: string;
+        revoked: true;
+    }>;
+    /**
+     * GET /v1/attachments — list YOUR agent's non-deleted attachments (newest first).
+     * Paginated via opaque cursor: when `next_cursor` is non-null, pass it
+     * back as `cursor` on the next call.
+     */
+    listBlobs(opts?: ListBlobsOptions): Promise<{
+        items: AttachmentRef[];
+        next_cursor: string | null;
+    }>;
+    /**
+     * GET /v1/attachments/:id/tokens — enumerate the capability tokens minted
+     * against one attachment, including revoked rows (for audit). The plaintext
+     * token is NEVER returned — it isn't stored, only its sha256 is.
+     */
+    listBlobTokens(attachmentId: string): Promise<AttachmentTokenListResponse>;
+    /**
+     * Issue a presigned PUT URL for direct-to-storage upload. Returns the
+     * upload URL + the attachment_id (already reserved in the relay's DB with
+     * status=pending) + expiry. After PUTting the bytes to the URL, call
+     * `confirmBlob(attachment_id)` to finalise.
+     *
+     * Filesystem backend returns 501 not_implemented — use uploadBlob()
+     * (multipart fallback) instead. Azure backend returns a SAS URL.
+     */
+    presignBlob(opts: PresignBlobOptions): Promise<{
+        attachment_id: string;
+        upload_url: string;
+        expires_at: string;
+    }>;
+    /** Finalise a presigned upload — relay HEADs the bytes, verifies, flips ready. */
+    confirmBlob(attachmentId: string): Promise<AttachmentRef>;
+}
+/** Per-attachment metadata as returned by `POST /v1/attachments` and friends. */
+export interface AttachmentRef {
+    attachment_id: string;
+    scope: "agent" | "surface" | "template";
+    mime: string;
+    size: number;
+    sha256: string;
+    url?: string;
+    width?: number | null;
+    height?: number | null;
+    filename?: string | null;
+    status?: string;
+    surface_id?: string | null;
+    template_id?: string | null;
+    created_at?: string;
+    confirmed_at?: string | null;
+    deleted_at?: string | null;
+}
+export interface UploadBlobOptions {
+    scope?: "agent" | "surface" | "template";
+    surfaceId?: string;
+    templateId?: string;
+    /** Declared Content-Type. Defaults to `application/octet-stream`. The
+     *  relay sniffs leading bytes and may reject with `mime_mismatch`. */
+    mime?: string;
+    /** Optional display name (the relay records it for UX; never a path component). */
+    filename?: string;
+}
+export interface PresignBlobOptions {
+    mime: string;
+    size: number;
+    sha256: string;
+    scope?: "agent" | "surface" | "template";
+    surfaceId?: string;
+    templateId?: string;
+    filename?: string;
+}
+export interface AttachmentTokenMintResponse {
+    token_id: string;
+    token: string;
+    token_prefix: string;
+    url: string;
+    expires_at: string;
+    once: boolean;
+}
+/** Options for `listBlobs()` — opaque cursor + page-size knob. */
+export interface ListBlobsOptions {
+    /** Opaque pagination cursor from a prior `next_cursor`. */
+    cursor?: string;
+    /** Page size; relay clamps to 1..100. Defaults to the relay default (50). */
+    limit?: number;
+}
+/** One row in the response from `listBlobTokens()`. */
+export interface AttachmentTokenAuditEntry {
+    token_id: string;
+    token_prefix: string;
+    expires_at: string;
+    once: boolean;
+    created_at: string;
+    last_used_at: string | null;
+    use_count: number;
+    /** Non-null when the token has been revoked. Expired-but-unrevoked rows
+     *  carry `revoked_at: null` and an `expires_at` in the past — both are
+     *  useful for audit. */
+    revoked_at: string | null;
+}
+/** Shape returned by `listBlobTokens()`. */
+export interface AttachmentTokenListResponse {
+    attachment_id: string;
+    items: AttachmentTokenAuditEntry[];
 }