@paneui/core 0.0.5 → 0.0.7

package/dist/types.d.ts

@@ -4,7 +4,7 @@ export type AuthorKind = "human" | "agent" | "system";
 /** A single event envelope as emitted by the relay. */
 export interface PaneEvent {
     id: string;
-    session_id: string;
+    surface_id: string;
     author: {
         kind: AuthorKind;
         id: string;
@@ -15,14 +15,14 @@ export interface PaneEvent {
     causation_id: string | null;
     idempotency_key: string | null;
 }
-/** The artifact content type. `html-ref` is rejected by the relay for now. */
-export type ArtifactType = "html-inline" | "html-ref";
+/** The template content type. `html-ref` is rejected by the relay for now. */
+export type TemplateType = "html-inline" | "html-ref";
 /**
- * An artifact: discriminated on `type`. `html-inline` carries raw HTML in
+ * An template: discriminated on `type`. `html-inline` carries raw HTML in
  * `source`; `html-ref` carries a URL the relay/shell fetches on the human's
  * behalf. The discriminant keeps the type↔source coupling explicit.
  */
-export type Artifact = {
+export type Template = {
     type: "html-inline";
     source: string;
 } | {
@@ -36,13 +36,13 @@ export interface Callback {
     secret: string;
 }
 /**
- * Request body for POST /v1/sessions. Derived from `createSessionSchema` so the
+ * Request body for POST /v1/surfaces. Derived from `createSessionSchema` so the
  * runtime validator and the static type cannot drift.
  */
 export type CreateSessionRequest = z.infer<typeof createSessionSchema>;
-/** Response from POST /v1/sessions. */
+/** Response from POST /v1/surfaces. */
 export interface CreateSessionResponse {
-    session_id: string;
+    surface_id: string;
     tokens: {
         humans: string[];
         agent: string;
@@ -52,36 +52,101 @@ export interface CreateSessionResponse {
         agent_stream: string;
     };
     expires_at: string;
+    /** The resolved tab title persisted on the surface (the agent's value, or
+     * the Template.name fallback). */
+    title: string;
 }
-/** Response from GET /v1/sessions/:id. */
-export interface SessionState {
-    session_id: string;
+/** Response from GET /v1/surfaces/:id. */
+export interface SurfaceState {
+    surface_id: string;
     status: string;
-    /** The artifact version this session is pinned to. */
-    artifact_id: string;
-    artifact_version_id: string;
-    artifact_version: number;
+    /** The template version this surface is pinned to. */
+    template_id: string;
+    template_version_id: string;
+    template_version: number;
+    /** The tab title this surface was created with (frozen for its lifetime). */
+    title: string;
     metadata: Record<string, unknown> | null;
     input_data: Record<string, unknown> | null;
     created_at: string;
     expires_at: string;
 }
-/** Response from GET /v1/sessions/:id/events. */
+/** Response from GET /v1/surfaces/:id/events. */
 export interface EventsPage {
     events: PaneEvent[];
     next_cursor: string | null;
 }
-/** One immutable version of an artifact's content. */
-export interface ArtifactVersion {
+/** A non-secret summary of one participant on a surface — safe to list. */
+export interface ParticipantSummary {
+    /** The revoke handle (Participant.id). */
+    participant_id: string;
+    /** "agent" or "human". The agent's own participant is always present. */
+    kind: "agent" | "human";
+    /** Short, non-secret correlator for a saved URL ("tok_h_..." / "tok_a_..."). */
+    token_prefix: string;
+    /** ISO timestamp of first WebSocket connect, or null if never joined. */
+    joined_at: string | null;
+    /** ISO timestamp the participant was revoked; null while still active. */
+    revoked_at: string | null;
+}
+/** A row in the GET /v1/surfaces list response (no secrets, lean). */
+export interface SurfaceSummary {
+    surface_id: string;
+    /** Tab title (required column; agent input or Template.name fallback). */
+    title: string;
+    /** Effective status — respects expiresAt projection (the column may say
+     *  "open" while `expires_at` is in the past; the projection reports "closed"). */
+    status: "open" | "closed";
+    /** Owning template's head id. Null for inline (anonymous) templates. */
+    template_id: string | null;
+    template_version_id: string;
+    template_version: number;
+    /** Count of active (non-revoked) human participants. The full participant
+     *  array is intentionally NOT inlined here — agents with many surfaces
+     *  would pay the bandwidth on every list call. Fetch
+     *  `GET /v1/surfaces/:id/participants` when you need the rows. */
+    active_human_participants: number;
+    created_at: string;
+    expires_at: string;
+    /** Whether the surface has a webhook callback configured (URL is NOT
+     *  returned — it may carry a secret in the path). */
+    has_callback: boolean;
+}
+/** Response from GET /v1/surfaces/:id/participants — every participant on
+ *  one surface (active and revoked). Bounded by MAX_PARTICIPANTS_PER_SESSION
+ *  on the relay so no pagination is needed. */
+export interface ParticipantsList {
+    surface_id: string;
+    items: ParticipantSummary[];
+}
+/** Response from GET /v1/surfaces. */
+export interface SurfacesPage {
+    items: SurfaceSummary[];
+    /** Opaque cursor for the next page; null when no more rows. */
+    next_cursor: string | null;
+}
+/** Response from POST /v1/surfaces/:id/participants — one-shot, includes the
+ *  plaintext token exactly once. The relay stores only the hash. */
+export interface MintParticipantResponse {
+    participant_id: string;
+    kind: "human";
+    /** The plaintext participant token. Returned ONCE — not recoverable. */
+    token: string;
+    /** The shareable human URL containing the token. */
+    url: string;
+    created_at: string;
+}
+/** One immutable version of an template's content. */
+export interface TemplateVersion {
     id: string;
     version: number;
-    type: ArtifactType;
+    type: TemplateType;
     source: string;
     event_schema: unknown;
     input_schema: Record<string, unknown> | null;
     created_at: string;
 }
-/** A full artifact — head metadata plus its version list. */
+/** A full template — head metadata plus its version list. */
 export interface Artifact_ {
     id: string;
     slug: string | null;
@@ -92,18 +157,18 @@ export interface Artifact_ {
     last_used_at: string | null;
     created_at: string;
     updated_at: string;
-    versions: ArtifactVersion[];
+    versions: TemplateVersion[];
 }
 /**
- * A full artifact — head metadata plus its version list. (`ArtifactRecord` is
- * the public name; `Artifact` is kept as the older inline-artifact union.)
+ * A full template — head metadata plus its version list. (`TemplateRecord` is
+ * the public name; `Template` is kept as the older inline-template union.)
  */
-export type ArtifactRecord = Artifact_;
+export type TemplateRecord = Artifact_;
 /**
- * A lean artifact summary for list/search responses — head metadata only, no
- * `source` blob. See GET /v1/artifacts.
+ * A lean template summary for list/search responses — head metadata only, no
+ * `source` attachment. See GET /v1/templates.
  */
-export interface ArtifactSummary {
+export interface TemplateSummary {
     id: string;
     slug: string | null;
     name: string | null;
@@ -112,9 +177,9 @@ export interface ArtifactSummary {
     latest_version: number;
     last_used_at: string | null;
 }
-/** Response from POST /v1/artifacts and POST /v1/artifacts/:id/versions. */
+/** Response from POST /v1/templates and POST /v1/templates/:id/versions. */
 export interface CreateArtifactResponse {
-    artifact_id: string;
+    template_id: string;
     version: number;
 }
 /**
@@ -132,7 +197,7 @@ export interface KeyInfo {
 }
 /**
  * Response from GET /v1/taste, PUT /v1/taste — the calling agent's freeform
- * "taste notes" markdown blob (presentation preferences the agent has picked
+ * "taste notes" markdown attachment (presentation preferences the agent has picked
  * up from human feedback over time). `taste` and `updated_at` are null when
  * the agent has never written notes; `bytes` is the utf8 byte length and 0
  * when `taste` is null.
@@ -155,7 +220,7 @@ export interface FeedbackRecord {
     id: string;
     type: FeedbackType;
     message: string;
-    session_id: string | null;
+    surface_id: string | null;
     created_at: string;
 }
 /** Response from GET /v1/feedback — page of the calling agent's own submissions. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paneui/core",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "Pane relay client: typed HTTP + WebSocket operations against a Pane relay. Framework-free.",
   "license": "MIT",
   "type": "module",
@@ -47,12 +47,12 @@
   },
   "dependencies": {
     "ws": "^8.20.1",
-    "zod": "^3.23.0"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^22.7.0",
+    "@types/node": "^25.9.1",
     "@types/ws": "^8.18.1",
-    "typescript": "^5.6.0",
+    "typescript": "^6.0.3",
     "vitest": "^4.1.6"
   }
 }