@paneui/core 0.0.9 → 0.0.10

package/README.md

@@ -16,7 +16,7 @@ that the browser `WebSocket` does not, and the relay protocol relies on it.
 Because of this, `@paneui/core` is **not** intended to run in a browser or other
 non-Node runtime as-is.
 
-The HTTP surface (`PaneClient`, `registerAgent`) uses the standard `fetch` API
+The HTTP pane (`PaneClient`, `registerAgent`) uses the standard `fetch` API
 and is runtime-agnostic; only `openStream` carries the Node constraint.
 
 If you need a browser client, treat that as separate future work — it would
@@ -28,4 +28,4 @@ need a `ws`-vs-global-`WebSocket` abstraction rather than the unconditional
 - `PaneClient` / `PaneApiError` — typed HTTP operations against a relay.
 - `openStream` — WebSocket stream (replay-on-connect, then live). **Node only.**
 - `registerAgent` — agent registration helper.
-- `artifactSchema`, `callbackSchema`, `createSessionSchema` — Zod schemas.
+- `artifactSchema`, `callbackSchema`, `createPaneSchema` — Zod schemas.

package/dist/client.d.ts

@@ -1,5 +1,5 @@
-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";
+import type { TemplateRecord, TemplateSummary, TemplateType, TemplateVersion, CreateArtifactResponse, CreatePaneRequest, CreatePaneResponse, EventsPage, FeedbackPage, FeedbackSubmission, FeedbackType, KeyInfo, MintParticipantResponse, PaneEvent, ParticipantsList, SerializedRecord, PaneState, PanesPage, TasteInfo, TrashListResponse } from "./types.js";
+import type { ListPanesQuery } from "./schemas.js";
 export interface ClientOptions {
     /** Relay base URL, e.g. https://pane.example.com. Trailing slash is trimmed. */
     url: string;
@@ -27,6 +27,22 @@ export interface RelayResponse {
  * Request body for POST /v1/templates — create a named, reusable template plus
  * its v1 content. Mirrors `createArtifactSchema` from ./schemas.js.
  */
+/** Response from POST /v1/query. */
+export interface QueryResponse {
+    /** Ordered column names exactly as DuckDB returned them. */
+    columns: string[];
+    /** Result rows; each row is an array of values aligned to `columns`. */
+    rows: unknown[][];
+    /** True if the result was capped by the relay's per-query row cap. */
+    truncated: boolean;
+    /** Tells the caller which panes the query saw and how it was scoped. */
+    scope: {
+        kind: "human" | "agent";
+        pane_count: number;
+    };
+    /** Wall-clock milliseconds the relay spent serving the query. */
+    elapsed_ms: number;
+}
 export interface CreateArtifactRequest {
     name: string;
     slug?: string;
@@ -36,6 +52,9 @@ export interface CreateArtifactRequest {
     type: TemplateType;
     event_schema?: unknown;
     input_schema?: Record<string, unknown>;
+    /** Optional template icon emoji (a single emoji grapheme). Image icons are
+     *  set post-create via `updateArtifact({ icon_attachment_id })`. */
+    icon_emoji?: string;
 }
 /**
  * Request body for POST /v1/templates/:id/versions — append a new immutable
@@ -56,6 +75,11 @@ export interface PatchArtifactMetadataRequest {
     slug?: string;
     description?: string;
     tags?: string[];
+    /** Set a single-grapheme emoji icon, or `null` to clear it. */
+    icon_emoji?: string | null;
+    /** Set the icon to a ready, template-scoped raster image attachment, or
+     *  `null` to clear it. */
+    icon_attachment_id?: string | null;
 }
 /**
  * An error thrown by the typed operations when the relay returns a non-2xx
@@ -98,21 +122,134 @@ export declare class PaneClient {
     private asObject;
     /** Throw a PaneApiError from a failed RelayResponse. */
     private fail;
-    /** POST /v1/surfaces — create a surface. */
-    createSession(req: CreateSessionRequest): Promise<CreateSessionResponse>;
-    /** GET /v1/surfaces/:id — non-blocking surface metadata. */
-    getSession(surfaceId: string): Promise<SurfaceState>;
+    /** POST /v1/panes — create a pane. */
+    createPane(req: CreatePaneRequest): Promise<CreatePaneResponse>;
+    /** GET /v1/panes/:id — non-blocking pane metadata. */
+    getPane(paneId: string): Promise<PaneState>;
     /**
-     * GET /v1/surfaces/:id/events — fetch the event log.
+     * GET /v1/panes/: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(surfaceId: string, opts?: {
+    getEvents(paneId: string, opts?: {
         since?: string | null;
         waitSeconds?: number;
     }): Promise<EventsPage>;
-    /** POST /v1/surfaces/:id/events — append an agent event. */
-    sendEvent(surfaceId: string, ev: {
+    /**
+     * POST /v1/query — run a read-only SQL query against the agent's own
+     * scoped data (panes, records, events). The relay scopes the result at
+     * the view layer; the agent can never see rows whose pane.owner_human_id
+     * does not match the caller's scope. Three generic views (panes, records,
+     * events) are always exposed; per-collection / per-event-type views are
+     * also materialized for any schemas declared on the caller's templates.
+     *
+     * `opts.paneId` narrows the scope to a single pane — handy when two of
+     * the caller's panes declare the same collection with incompatible types
+     * and the materializer would otherwise raise view_conflict.
+     *
+     * `data` is a JSON column — use Postgres-style operators (->>, ->) to
+     * project into it. Cap: 10,000 result rows (response.truncated=true
+     * signals the cap was hit); statement timeout: 10 seconds.
+     */
+    query(sql: string, opts?: {
+        paneId?: string;
+    }): Promise<QueryResponse>;
+    /**
+     * GET /v1/panes/:id/records/:collection — cursor-paginated list.
+     * Includes tombstones (`deleted_at` set) so reconnecting clients can
+     * observe deletions.
+     */
+    listRecords(paneId: string, collection: string, opts?: {
+        since?: number;
+        limit?: number;
+    }): Promise<{
+        records: SerializedRecord[];
+        next_since: number;
+        has_more: boolean;
+    }>;
+    /**
+     * Convenience: walk listRecords until the named recordKey is found OR
+     * the collection is exhausted. The relay has no dedicated single-get
+     * route today; this client-side scan trades round trips for not adding
+     * a route. Fine for typical CLI use; not appropriate for hot paths.
+     */
+    getRecord(paneId: string, collection: string, recordKey: string): Promise<SerializedRecord | null>;
+    /**
+     * POST /v1/panes/:id/records/:collection — create-or-return-existing.
+     * Duplicate `recordKey` returns the existing row with `deduped: true`.
+     */
+    upsertRecord(paneId: string, collection: string, body: {
+        record_key?: string;
+        data: unknown;
+    }): Promise<{
+        record: SerializedRecord;
+        deduped: boolean;
+    }>;
+    /**
+     * PATCH /v1/panes/:id/records/:collection/:recordKey — optimistic
+     * update. On 409 the relay returns the current row in `details.current`.
+     */
+    updateRecord(paneId: string, collection: string, recordKey: string, body: {
+        data: unknown;
+        if_match?: number;
+    }): Promise<{
+        record: SerializedRecord;
+    }>;
+    /**
+     * DELETE /v1/panes/:id/records/:collection/:recordKey — soft-delete.
+     * Optional `if_match` returns 409 + `details.current` on mismatch.
+     */
+    deleteRecord(paneId: string, collection: string, recordKey: string, opts?: {
+        ifMatch?: number;
+    }): Promise<void>;
+    /**
+     * GET /v1/templates/:id/template-records/:collection — owner-only list of
+     * a template's curated records. Same wire shape as listRecords, separate
+     * route so the relay can route owner-vs-page access independently.
+     */
+    listTemplateRecords(templateIdOrSlug: string, collection: string, opts?: {
+        since?: number;
+        limit?: number;
+    }): Promise<{
+        records: SerializedRecord[];
+        next_since: number;
+        has_more: boolean;
+    }>;
+    /**
+     * Client-side scan helper — same shape as `getRecord` but for template
+     * records. Walks listTemplateRecords until the key matches.
+     */
+    getTemplateRecord(templateIdOrSlug: string, collection: string, recordKey: string): Promise<SerializedRecord | null>;
+    /**
+     * POST /v1/templates/:id/template-records/:collection — owner-only
+     * create-or-return-existing.
+     */
+    upsertTemplateRecord(templateIdOrSlug: string, collection: string, body: {
+        record_key?: string;
+        data: unknown;
+    }): Promise<{
+        record: SerializedRecord;
+        deduped: boolean;
+    }>;
+    /**
+     * PATCH /v1/templates/:id/template-records/:collection/:recordKey —
+     * optimistic-locked update.
+     */
+    updateTemplateRecord(templateIdOrSlug: string, collection: string, recordKey: string, body: {
+        data: unknown;
+        if_match?: number;
+    }): Promise<{
+        record: SerializedRecord;
+    }>;
+    /**
+     * DELETE /v1/templates/:id/template-records/:collection/:recordKey —
+     * soft-delete.
+     */
+    deleteTemplateRecord(templateIdOrSlug: string, collection: string, recordKey: string, opts?: {
+        ifMatch?: number;
+    }): Promise<void>;
+    /** POST /v1/panes/:id/events — append an agent event. */
+    sendEvent(paneId: string, ev: {
         type: string;
         data: unknown;
         causationId?: string;
@@ -168,7 +305,7 @@ export declare class PaneClient {
      * 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
+     * but the agent (and its panes/templates) now belong to the
      * claiming human. One-way operation — there is no unclaim in v1.
      */
     claimAgent(code: string): Promise<{
@@ -205,7 +342,7 @@ export declare class PaneClient {
     submitFeedback(req: {
         type: FeedbackType;
         message: string;
-        surfaceId?: string;
+        paneId?: string;
     }): Promise<FeedbackSubmission>;
     /**
      * GET /v1/feedback — the calling agent's own submissions, newest first.
@@ -216,67 +353,143 @@ export declare class PaneClient {
         before?: string;
     }): Promise<FeedbackPage>;
     /**
-     * GET /v1/surfaces — list the calling agent's surfaces. Default filter is
+     * GET /v1/panes — list the calling agent's panes. 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>;
+    listPanes(opts?: ListPanesQuery): Promise<PanesPage>;
     /**
-     * GET /v1/surfaces/:id/participants — list every participant on one
-     * surface (active and revoked). Bounded by MAX_PARTICIPANTS_PER_SESSION
+     * GET /v1/panes/:id/participants — list every participant on one
+     * pane (active and revoked). Bounded by MAX_PARTICIPANTS_PER_PANE
      * 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>;
+    listParticipants(paneId: 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.
+     * POST /v1/panes/:id/participants — mint a fresh participant URL for an
+     * existing pane. The one-shot recovery primitive when the original URL
+     * was dropped: the pane 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?: {
+    mintParticipant(paneId: 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
+     * DELETE /v1/panes/:id/participants/:participant_id — revoke a single
+     * participant URL. The pane'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.
+     * via this endpoint — use {@link deletePane} 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>;
+    revokeParticipant(paneId: string, participantId: string): Promise<void>;
+    /**
+     * DELETE /v1/panes/:id — close/delete a pane. Idempotent on the relay
+     * side (an already-closed pane still returns 204 with no body).
+     */
+    deletePane(id: string): Promise<void>;
+    /**
+     * GET /v1/trash — list soft-deleted panes + templates in the caller's
+     * agent-scope. The trash UI / `pane trash list` lives off this. (#306)
+     */
+    listTrash(): Promise<TrashListResponse>;
+    /**
+     * POST /v1/trash/panes/:id/restore — un-trash a soft-deleted pane (clear
+     * deletedAt + audit row). (#306)
+     */
+    restorePane(id: 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).
+     * POST /v1/trash/templates/:id/restore — un-trash a soft-deleted template. (#306)
      */
-    deleteSession(id: string): Promise<void>;
+    restoreTemplate(id: string): Promise<void>;
+    /**
+     * DELETE /v1/trash/panes/:id — permanently hard-delete a trashed pane
+     * (bypass retention window). (#306)
+     */
+    permanentDeletePane(id: string): Promise<void>;
+    /**
+     * DELETE /v1/trash/templates/:id — permanently hard-delete a trashed
+     * template. Refused 409 if a live pane still references one of its
+     * versions. (#306)
+     */
+    permanentDeleteTemplate(id: string): Promise<void>;
     /**
      * DELETE /v1/templates/:id — remove an template and (server-side) all its
      * versions. Strict cascade: the relay refuses with 409 conflict if any
-     * 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
+     * pane in any state still references one of the template's versions —
+     * pane that as a typed PaneApiError so the CLI can render a hint
      * instead of swallowing it.
      */
     deleteArtifact(idOrSlug: string): Promise<void>;
+    /**
+     * POST /v1/templates/:id/publish — enter the public catalog. The optional
+     * `scopes` list locks the permissions the template will request from
+     * installers at this version (see Phase F §4.5 / §8). Passing an empty
+     * array clears the stored scopes; omitting `scopes` keeps the existing
+     * ones.
+     */
+    publishTemplate(idOrSlug: string, body?: {
+        scopes?: string[];
+    }): Promise<{
+        id: string;
+        slug: string | null;
+        name: string | null;
+        published_at: string | null;
+        scopes: string[];
+        install_count: number;
+    }>;
+    /**
+     * POST /v1/templates/:id/unpublish — leave the public catalog. Existing
+     * installs are unaffected (humans keep their pinned version), but the
+     * template no longer appears in `searchPublicTemplates` results.
+     */
+    unpublishTemplate(idOrSlug: string): Promise<{
+        id: string;
+        published_at: string | null;
+    }>;
+    /**
+     * GET /v1/templates/catalog?q=... — agent-side public catalog search.
+     * Lets an agent discover already-published apps before authoring a
+     * duplicate. Sorted by install_count desc, then publish recency.
+     */
+    searchPublicTemplates(query?: string, opts?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        items: Array<{
+            id: string;
+            slug: string | null;
+            name: string | null;
+            description: string | null;
+            tags: string[] | null;
+            shape: string;
+            scopes: string[];
+            published_at: string | null;
+            install_count: number;
+            latest_version: number;
+        }>;
+        total: number;
+        offset: number;
+        limit: number;
+    }>;
     /**
      * 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;
+     * Scope defaults to "agent" (reusable across the agent's panes). For
+     * `scope: "pane"` pass `paneId`; for `scope: "template"` pass
+     * `templateId`. The agent must own the referenced pane / template;
      * cross-tenant attempts return attachment_not_found.
      *
      * MIME is inferred from `mime` if supplied; otherwise the relay sniffs
@@ -307,7 +520,7 @@ export declare class PaneClient {
     }>;
     /**
      * Mint a `/b/<token>` capability URL for `attachmentId`. Default TTL is set by
-     * the relay (24h agent, surface-TTL surface, 30d template). `once: true`
+     * the relay (24h agent, pane-TTL pane, 30d template). `once: true`
      * tokens self-delete on first GET.
      */
     mintBlobToken(attachmentId: string, opts?: {
@@ -354,7 +567,7 @@ export declare class PaneClient {
 /** Per-attachment metadata as returned by `POST /v1/attachments` and friends. */
 export interface AttachmentRef {
     attachment_id: string;
-    scope: "agent" | "surface" | "template";
+    scope: "agent" | "pane" | "template";
     mime: string;
     size: number;
     sha256: string;
@@ -363,15 +576,15 @@ export interface AttachmentRef {
     height?: number | null;
     filename?: string | null;
     status?: string;
-    surface_id?: string | null;
+    pane_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;
+    scope?: "agent" | "pane" | "template";
+    paneId?: string;
     templateId?: string;
     /** Declared Content-Type. Defaults to `application/octet-stream`. The
      *  relay sniffs leading bytes and may reject with `mime_mismatch`. */
@@ -383,8 +596,8 @@ export interface PresignBlobOptions {
     mime: string;
     size: number;
     sha256: string;
-    scope?: "agent" | "surface" | "template";
-    surfaceId?: string;
+    scope?: "agent" | "pane" | "template";
+    paneId?: string;
     templateId?: string;
     filename?: string;
 }