@paneui/core 0.0.6 → 0.0.8

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { ArtifactRecord, ArtifactSummary, ArtifactType, ArtifactVersion, CreateArtifactResponse, CreateSessionRequest, CreateSessionResponse, EventsPage, FeedbackPage, FeedbackSubmission, FeedbackType, KeyInfo, MintParticipantResponse, PaneEvent, ParticipantsList, SessionState, SessionsPage, 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. */
@@ -24,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 {
@@ -33,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 {
@@ -98,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;
@@ -122,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.
@@ -165,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).
@@ -193,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.
@@ -204,38 +216,38 @@ export declare class PaneClient {
         before?: string;
     }): Promise<FeedbackPage>;
     /**
-     * GET /v1/sessions — list the calling agent's sessions. Default filter is
+     * 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<SessionsPage>;
+    listSessions(opts?: ListSessionsQuery): Promise<SurfacesPage>;
     /**
-     * GET /v1/sessions/:id/participants — list every participant on one
-     * session (active and revoked). Bounded by MAX_PARTICIPANTS_PER_SESSION
+     * 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(sessionId: string): Promise<ParticipantsList>;
+    listParticipants(surfaceId: string): Promise<ParticipantsList>;
     /**
-     * POST /v1/sessions/:id/participants — mint a fresh participant URL for an
-     * existing session. The one-shot recovery primitive when the original URL
-     * was dropped: the session keeps its event log, artifact pin, and created_at.
+     * 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(sessionId: string, opts?: {
+    mintParticipant(surfaceId: string, opts?: {
         kind?: "human";
     }): Promise<MintParticipantResponse>;
     /**
-     * DELETE /v1/sessions/:id/participants/:participant_id — revoke a single
-     * participant URL. The session's other participants (and the agent's own
+     * 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.
@@ -243,106 +255,106 @@ export declare class PaneClient {
      * Existing WebSocket connections held under the revoked token are NOT
      * actively kicked in v1; new HTTP and WS connections are refused.
      */
-    revokeParticipant(sessionId: string, participantId: string): Promise<void>;
+    revokeParticipant(surfaceId: string, participantId: string): Promise<void>;
     /**
-     * DELETE /v1/sessions/:id — close/delete a session. Idempotent on the relay
-     * side (an already-closed session still returns 204 with no body).
+     * 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 blob to the relay. Returns a `BlobRef` that can be referenced
-     * in event payloads (the relay's `format: pane-blob-id` schema vocab
+     * 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 sessions). For
-     * `scope: "session"` pass `sessionId`; for `scope: "artifact"` pass
-     * `artifactId`. The agent must own the referenced session / artifact;
-     * cross-tenant attempts return blob_not_found.
+     * 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/blobs` (the fallback path).
+     * 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<BlobRef>;
-    /** GET /v1/blobs/:id — download bytes as an ArrayBuffer. */
-    downloadBlob(blobId: string): Promise<ArrayBuffer>;
+    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 blob's metadata only — useful before downloading large blobs, or
-     * for `pane blob show <id>` which doesn't want the bytes. Returns the full
-     * BlobRef (the same shape POST /v1/blobs returns): id, scope, mime, size,
+     * 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/blobs/:id/metadata which serves the JSON BlobRef
+     * 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(blobId: string): Promise<BlobRef>;
-    /** DELETE /v1/blobs/:id — soft-delete (idempotent). */
-    deleteBlob(blobId: string): Promise<{
+    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 `blobId`. Default TTL is set by
-     * the relay (24h agent, session-TTL session, 30d artifact). `once: 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(blobId: string, opts?: {
+    mintBlobToken(attachmentId: string, opts?: {
         ttlSeconds?: number;
         once?: boolean;
-    }): Promise<BlobTokenMintResponse>;
+    }): Promise<AttachmentTokenMintResponse>;
     /** Revoke a previously-minted token. Idempotent. */
-    revokeBlobToken(blobId: string, tokenId: string): Promise<{
+    revokeBlobToken(attachmentId: string, tokenId: string): Promise<{
         token_id: string;
         revoked: true;
     }>;
     /**
-     * GET /v1/blobs — list YOUR agent's non-deleted blobs (newest first).
+     * 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: BlobRef[];
+        items: AttachmentRef[];
         next_cursor: string | null;
     }>;
     /**
-     * GET /v1/blobs/:id/tokens — enumerate the capability tokens minted
-     * against one blob, including revoked rows (for audit). The plaintext
+     * 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(blobId: string): Promise<BlobTokenListResponse>;
+    listBlobTokens(attachmentId: string): Promise<AttachmentTokenListResponse>;
     /**
      * Issue a presigned PUT URL for direct-to-storage upload. Returns the
-     * upload URL + the blob_id (already reserved in the relay's DB with
+     * 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(blob_id)` to finalise.
+     * `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<{
-        blob_id: string;
+        attachment_id: string;
         upload_url: string;
         expires_at: string;
     }>;
     /** Finalise a presigned upload — relay HEADs the bytes, verifies, flips ready. */
-    confirmBlob(blobId: string): Promise<BlobRef>;
+    confirmBlob(attachmentId: string): Promise<AttachmentRef>;
 }
-/** Per-blob metadata as returned by `POST /v1/blobs` and friends. */
-export interface BlobRef {
-    blob_id: string;
-    scope: "agent" | "session" | "artifact";
+/** 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;
@@ -351,16 +363,16 @@ export interface BlobRef {
     height?: number | null;
     filename?: string | null;
     status?: string;
-    session_id?: string | null;
-    artifact_id?: string | null;
+    surface_id?: string | null;
+    template_id?: string | null;
     created_at?: string;
     confirmed_at?: string | null;
     deleted_at?: string | null;
 }
 export interface UploadBlobOptions {
-    scope?: "agent" | "session" | "artifact";
-    sessionId?: string;
-    artifactId?: string;
+    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;
@@ -371,12 +383,12 @@ export interface PresignBlobOptions {
     mime: string;
     size: number;
     sha256: string;
-    scope?: "agent" | "session" | "artifact";
-    sessionId?: string;
-    artifactId?: string;
+    scope?: "agent" | "surface" | "template";
+    surfaceId?: string;
+    templateId?: string;
     filename?: string;
 }
-export interface BlobTokenMintResponse {
+export interface AttachmentTokenMintResponse {
     token_id: string;
     token: string;
     token_prefix: string;
@@ -392,7 +404,7 @@ export interface ListBlobsOptions {
     limit?: number;
 }
 /** One row in the response from `listBlobTokens()`. */
-export interface BlobTokenAuditEntry {
+export interface AttachmentTokenAuditEntry {
     token_id: string;
     token_prefix: string;
     expires_at: string;
@@ -406,7 +418,7 @@ export interface BlobTokenAuditEntry {
     revoked_at: string | null;
 }
 /** Shape returned by `listBlobTokens()`. */
-export interface BlobTokenListResponse {
-    blob_id: string;
-    items: BlobTokenAuditEntry[];
+export interface AttachmentTokenListResponse {
+    attachment_id: string;
+    items: AttachmentTokenAuditEntry[];
 }