@paneui/core 0.0.11 → 0.0.13

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-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 { TemplateRecord, TemplateSummary, TemplateType, TemplateVersion, CreateArtifactResponse, CreatePaneRequest, CreatePaneResponse, EventsPage, FeedbackPage, FeedbackSubmission, FeedbackType, KeyInfo, MintParticipantResponse, PaneEvent, ParticipantsList, SerializedRecord, PaneState, PanesPage, TasteInfo, TrashListResponse, UpgradePaneResponse } 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. */
@@ -81,6 +81,37 @@ export interface PatchArtifactMetadataRequest {
      *  `null` to clear it. */
     icon_attachment_id?: string | null;
 }
+/** One identity-share grant as returned by the grants endpoints. */
+export interface PaneGrant {
+    id: string;
+    /** Set once the invitee logs in and the grant binds; null while pending. */
+    human_id: string | null;
+    /** The invited email, or null for a grant created directly against a human. */
+    invite_email: string | null;
+    /** "participant" (read + emit) | "viewer" (read-only). */
+    role: string;
+    /** ISO timestamp the grant was bound to a human, or null while pending. */
+    accepted_at: string | null;
+}
+/**
+ * The pane-id (`/p/:paneId`) access mode. Governs ONLY the pane-id path; token
+ * (`/s/<token>`) links are unaffected and keep working in every mode.
+ *   - "invite_only" — only invited emails (after login) may open /p.
+ *   - "link"        — anyone with the /p URL opens it read-only, no login.
+ *   - "public"      — anyone opens it read-only, no login (discovery TBD).
+ */
+export type AccessMode = "invite_only" | "link" | "public";
+/** Response from GET /v1/panes/:id/grants. */
+export interface PaneGrantsList {
+    pane_id: string;
+    access_mode: AccessMode;
+    items: PaneGrant[];
+}
+/** Response from PATCH /v1/panes/:id/visibility. */
+export interface PaneVisibility {
+    pane_id: string;
+    access_mode: AccessMode;
+}
 /**
  * An error thrown by the typed operations when the relay returns a non-2xx
  * response (or the request fails outright). Carries the HTTP status and the
@@ -382,6 +413,28 @@ export declare class PaneClient {
     mintParticipant(paneId: string, opts?: {
         kind?: "human";
     }): Promise<MintParticipantResponse>;
+    /**
+     * POST /v1/panes/:id/upgrade — re-pin a live pane to another version of the
+     * SAME template (#267), swapping its HTML and schemas in place without
+     * minting a new pane (the human keeps the same URL). Events already on disk
+     * are never rewritten — each carries the template version it was authored
+     * under (#268).
+     *
+     * `opts.template_version` defaults to the template head's latest version.
+     * `opts.compat` defaults to `"strict"`: the relay refuses with a 422
+     * `schema_incompatible_upgrade` (its `details.breaks` lists the offending
+     * paths) when the target schema narrows the current one — i.e. when events
+     * written under the old schema would no longer validate. Pass `"force"` to
+     * apply the upgrade anyway, accepting that old events may no longer match
+     * the new schema.
+     *
+     * Returns `{ upgraded: false }` (idempotent no-op) when the pane is already
+     * on the target version.
+     */
+    upgradePane(paneId: string, opts?: {
+        template_version?: number;
+        compat?: "strict" | "force";
+    }): Promise<UpgradePaneResponse>;
     /**
      * DELETE /v1/panes/:id/participants/:participant_id — revoke a single
      * participant URL. The pane's other participants (and the agent's own
@@ -393,6 +446,33 @@ export declare class PaneClient {
      * actively kicked in v1; new HTTP and WS connections are refused.
      */
     revokeParticipant(paneId: string, participantId: string): Promise<void>;
+    /**
+     * GET /v1/panes/:id/grants — list the pane's identity-share grants plus
+     * its current `access_mode`. Owner/agent-scope only.
+     */
+    listGrants(paneId: string): Promise<PaneGrantsList>;
+    /**
+     * POST /v1/panes/:id/grants — invite a human by email. Upserts by email,
+     * so re-inviting the same address adjusts the role in place. Role defaults
+     * to "participant" (read + emit); pass "viewer" for read-only.
+     */
+    createGrant(paneId: string, opts: {
+        email: string;
+        role?: "participant" | "viewer";
+    }): Promise<PaneGrant>;
+    /**
+     * DELETE /v1/panes/:id/grants/:grantId — revoke one grant. Idempotent: a
+     * missing/already-removed grant returns 204.
+     */
+    revokeGrant(paneId: string, grantId: string): Promise<void>;
+    /**
+     * PATCH /v1/panes/:id/visibility — set the pane's /p access mode.
+     *   - "invite_only" — only invited emails (after login) may open /p.
+     *   - "link"        — anyone with the /p URL opens it READ-ONLY, no login.
+     *   - "public"      — anyone opens it READ-ONLY, no login (discovery TBD).
+     * Token (`/s/<token>`) links are independent of this and keep working.
+     */
+    setPaneVisibility(paneId: string, accessMode: AccessMode): Promise<PaneVisibility>;
     /**
      * DELETE /v1/panes/:id — close/delete a pane. Idempotent on the relay
      * side (an already-closed pane still returns 204 with no body).

package/dist/client.js

@@ -578,6 +578,35 @@ export class PaneClient {
             this.fail(r);
         return this.asObject(r);
     }
+    /**
+     * POST /v1/panes/:id/upgrade — re-pin a live pane to another version of the
+     * SAME template (#267), swapping its HTML and schemas in place without
+     * minting a new pane (the human keeps the same URL). Events already on disk
+     * are never rewritten — each carries the template version it was authored
+     * under (#268).
+     *
+     * `opts.template_version` defaults to the template head's latest version.
+     * `opts.compat` defaults to `"strict"`: the relay refuses with a 422
+     * `schema_incompatible_upgrade` (its `details.breaks` lists the offending
+     * paths) when the target schema narrows the current one — i.e. when events
+     * written under the old schema would no longer validate. Pass `"force"` to
+     * apply the upgrade anyway, accepting that old events may no longer match
+     * the new schema.
+     *
+     * Returns `{ upgraded: false }` (idempotent no-op) when the pane is already
+     * on the target version.
+     */
+    async upgradePane(paneId, opts = {}) {
+        const body = {};
+        if (opts.template_version !== undefined)
+            body["template_version"] = opts.template_version;
+        if (opts.compat !== undefined)
+            body["compat"] = opts.compat;
+        const r = await this.call("POST", `/v1/panes/${encodeURIComponent(paneId)}/upgrade`, body);
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
     /**
      * DELETE /v1/panes/:id/participants/:participant_id — revoke a single
      * participant URL. The pane's other participants (and the agent's own
@@ -593,6 +622,51 @@ export class PaneClient {
         if (!r.ok)
             this.fail(r);
     }
+    /**
+     * GET /v1/panes/:id/grants — list the pane's identity-share grants plus
+     * its current `access_mode`. Owner/agent-scope only.
+     */
+    async listGrants(paneId) {
+        const r = await this.call("GET", `/v1/panes/${encodeURIComponent(paneId)}/grants`);
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /**
+     * POST /v1/panes/:id/grants — invite a human by email. Upserts by email,
+     * so re-inviting the same address adjusts the role in place. Role defaults
+     * to "participant" (read + emit); pass "viewer" for read-only.
+     */
+    async createGrant(paneId, opts) {
+        const r = await this.call("POST", `/v1/panes/${encodeURIComponent(paneId)}/grants`, opts.role
+            ? { email: opts.email, role: opts.role }
+            : { email: opts.email });
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /**
+     * DELETE /v1/panes/:id/grants/:grantId — revoke one grant. Idempotent: a
+     * missing/already-removed grant returns 204.
+     */
+    async revokeGrant(paneId, grantId) {
+        const r = await this.call("DELETE", `/v1/panes/${encodeURIComponent(paneId)}/grants/${encodeURIComponent(grantId)}`);
+        if (!r.ok)
+            this.fail(r);
+    }
+    /**
+     * PATCH /v1/panes/:id/visibility — set the pane's /p access mode.
+     *   - "invite_only" — only invited emails (after login) may open /p.
+     *   - "link"        — anyone with the /p URL opens it READ-ONLY, no login.
+     *   - "public"      — anyone opens it READ-ONLY, no login (discovery TBD).
+     * Token (`/s/<token>`) links are independent of this and keep working.
+     */
+    async setPaneVisibility(paneId, accessMode) {
+        const r = await this.call("PATCH", `/v1/panes/${encodeURIComponent(paneId)}/visibility`, { access_mode: accessMode });
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
     /**
      * DELETE /v1/panes/:id — close/delete a pane. Idempotent on the relay
      * side (an already-closed pane still returns 204 with no body).

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { PaneClient, PaneApiError } from "./client.js";
-export type { ClientOptions, RelayResponse, CreateArtifactRequest, CreateArtifactVersionRequest, PatchArtifactMetadataRequest, AttachmentRef, UploadBlobOptions, PresignBlobOptions, AttachmentTokenMintResponse, ListBlobsOptions, AttachmentTokenAuditEntry, AttachmentTokenListResponse, QueryResponse, } from "./client.js";
+export type { ClientOptions, RelayResponse, CreateArtifactRequest, CreateArtifactVersionRequest, PatchArtifactMetadataRequest, AttachmentRef, UploadBlobOptions, PresignBlobOptions, AttachmentTokenMintResponse, ListBlobsOptions, AttachmentTokenAuditEntry, AttachmentTokenListResponse, QueryResponse, PaneGrant, PaneGrantsList, PaneVisibility, AccessMode, } from "./client.js";
 export { openStream } from "./stream.js";
 export type { OpenStreamOptions, StreamHandlers, StreamHandle, } from "./stream.js";
 export { registerAgent } from "./register.js";
@@ -9,4 +9,4 @@ export type { CreatePaneInput, ListPanesStatus, ListPanesQuery, MintParticipantI
 export { validateIconEmoji, isValidIconEmoji, isRasterImageMime, RASTER_ICON_MIME_ALLOWLIST, MAX_ICON_EMOJI_BYTES, } from "./icons.js";
 export type { RasterIconMime } from "./icons.js";
 export { MAX_EVENT_TYPE_LENGTH, MAX_IDEMPOTENCY_KEY_LENGTH, MAX_RESPONSE_SNIPPET_LENGTH, MAX_FRAME_SNIPPET_LENGTH, } from "./limits.js";
-export type { AuthorKind, PaneEvent, SerializedRecord, DeletedRecordRef, RecordDeltaMessage, Template, TemplateType, TemplateVersion, TemplateRecord, TemplateSummary, CreateArtifactResponse, KeyInfo, TasteInfo, FeedbackType, FeedbackSubmission, FeedbackRecord, FeedbackPage, Callback, CreatePaneRequest, CreatePaneResponse, PaneState, EventsPage, ParticipantSummary, ParticipantsList, PaneSummary, PanesPage, MintParticipantResponse, TrashedPaneEntry, TrashedTemplateEntry, TrashListResponse, RelayError, } from "./types.js";
+export type { AuthorKind, PaneEvent, SerializedRecord, DeletedRecordRef, RecordDeltaMessage, Template, TemplateType, TemplateVersion, TemplateRecord, TemplateSummary, CreateArtifactResponse, KeyInfo, TasteInfo, FeedbackType, FeedbackSubmission, FeedbackRecord, FeedbackPage, Callback, CreatePaneRequest, CreatePaneResponse, PaneState, EventsPage, ParticipantSummary, ParticipantsList, PaneSummary, PanesPage, MintParticipantResponse, UpgradeBreak, UpgradePaneResponse, TrashedPaneEntry, TrashedTemplateEntry, TrashListResponse, RelayError, } from "./types.js";

package/dist/types.d.ts

@@ -209,6 +209,31 @@ export interface MintParticipantResponse {
     url: string;
     created_at: string;
 }
+/** One break flagged by the schema-compat gate when upgrading a pane to a
+ *  template version whose schema narrows the current one. */
+export interface UpgradeBreak {
+    /** JSON-pointer-ish path to the offending schema location. */
+    path: string;
+    /** Human-readable description of why the change is incompatible. */
+    message: string;
+}
+/** Response from POST /v1/panes/:id/upgrade — the result of re-pinning a live
+ *  pane to another version of the same template (#267). */
+export interface UpgradePaneResponse {
+    pane_id: string;
+    /** The version id the pane now points at. */
+    template_version_id: string;
+    /** Denormalised integer version number the pane now points at. */
+    template_version: number;
+    /** `false` when the pane was already on the target version (idempotent
+     *  no-op); `true` when the re-pin was applied. */
+    upgraded: boolean;
+    /** Schema-compat breaks detected against the target version. Empty on a
+     *  clean upgrade; populated (and applied anyway) on `compat: "force"`. */
+    breaks: UpgradeBreak[];
+    /** The compat mode the upgrade ran under. */
+    compat: "strict" | "force";
+}
 /** One immutable version of an template's content. */
 export interface TemplateVersion {
     id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paneui/core",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "description": "Pane relay client: typed HTTP + WebSocket operations against a Pane relay. Framework-free.",
   "license": "MIT",
   "type": "module",
@@ -53,6 +53,6 @@
     "@types/node": "^25.9.1",
     "@types/ws": "^8.18.1",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.6"
+    "vitest": "^4.1.8"
   }
 }