@paneui/core 0.0.2 → 0.0.4

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { ArtifactRecord, ArtifactSummary, ArtifactType, ArtifactVersion, CreateArtifactResponse, CreateSessionRequest, CreateSessionResponse, EventsPage, KeyInfo, PaneEvent, SessionState } from "./types.js";
+import type { ArtifactRecord, ArtifactSummary, ArtifactType, ArtifactVersion, CreateArtifactResponse, CreateSessionRequest, CreateSessionResponse, EventsPage, FeedbackPage, FeedbackSubmission, FeedbackType, KeyInfo, PaneEvent, SessionState, TasteInfo } from "./types.js";
 export interface ClientOptions {
     /** Relay base URL, e.g. https://pane.example.com. Trailing slash is trimmed. */
     url: string;
@@ -6,6 +6,15 @@ export interface ClientOptions {
     apiKey: string;
     /** Optional fetch override (defaults to global fetch). */
     fetch?: typeof fetch;
+    /**
+     * Optional client version string sent as `x-pane-cli-version` on every
+     * request. The CLI passes its own `VERSION` constant here so a relay can
+     * detect version skew and respond with a `cli_upgrade_required` error
+     * (HTTP 426) when the CLI is below the relay's minimum supported version.
+     * Library callers (non-CLI) can leave this unset — the header is omitted
+     * and the relay treats the request as version-unknown.
+     */
+    cliVersion?: string;
 }
 /** Low-level relay response: ok flag, HTTP status, parsed JSON body. */
 export interface RelayResponse {
@@ -72,6 +81,7 @@ export declare class PaneClient {
     private readonly base;
     private readonly apiKey;
     private readonly fetchImpl;
+    private readonly cliVersion;
     constructor(opts: ClientOptions);
     /** Relay base URL (trailing slash trimmed). */
     get baseUrl(): string;
@@ -153,9 +163,56 @@ export declare class PaneClient {
      * self-destruct. Returns 204 with no body on success.
      */
     revokeKey(id: string): Promise<void>;
+    /**
+     * GET /v1/taste — the calling agent's freeform "taste notes" markdown blob:
+     * 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
+     * the agent applies prior feedback.
+     */
+    getTaste(): Promise<TasteInfo>;
+    /**
+     * PUT /v1/taste — whole-blob 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).
+     */
+    setTaste(taste: string): Promise<TasteInfo>;
+    /**
+     * DELETE /v1/taste — clear the calling agent's taste notes (idempotent on
+     * the relay; clearing already-empty notes still succeeds). Returns 204 with
+     * no body.
+     */
+    clearTaste(): Promise<void>;
+    /**
+     * POST /v1/feedback — submit a one-shot bug report, feature request, or
+     * note to the relay operator. Returns the new row's id, type, and
+     * created_at; the message is not echoed.
+     */
+    submitFeedback(req: {
+        type: FeedbackType;
+        message: string;
+        sessionId?: string;
+    }): Promise<FeedbackSubmission>;
+    /**
+     * GET /v1/feedback — the calling agent's own submissions, newest first.
+     * `before` is an opaque cursor from a previous page's `next_before`.
+     */
+    listFeedback(opts?: {
+        limit?: number;
+        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).
      */
     deleteSession(id: string): Promise<void>;
+    /**
+     * DELETE /v1/artifacts/:id — remove an artifact 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 that as a typed PaneApiError so the CLI can render a hint
+     * instead of swallowing it.
+     */
+    deleteArtifact(idOrSlug: string): Promise<void>;
 }

package/dist/client.js

@@ -31,10 +31,12 @@ export class PaneClient {
     base;
     apiKey;
     fetchImpl;
+    cliVersion;
     constructor(opts) {
         this.base = opts.url.replace(/\/$/, "");
         this.apiKey = opts.apiKey;
         this.fetchImpl = opts.fetch ?? fetch;
+        this.cliVersion = opts.cliVersion;
     }
     /** Relay base URL (trailing slash trimmed). */
     get baseUrl() {
@@ -60,6 +62,10 @@ export class PaneClient {
                 headers: {
                     authorization: "Bearer " + this.apiKey,
                     ...(body ? { "content-type": "application/json" } : {}),
+                    // x-pane-cli-version drives the relay's version-skew check. Header
+                    // is omitted entirely when no version was supplied so the relay
+                    // can distinguish "old CLI" from "non-CLI caller".
+                    ...(this.cliVersion ? { "x-pane-cli-version": this.cliVersion } : {}),
                 },
                 body: body ? JSON.stringify(body) : undefined,
             });
@@ -269,6 +275,72 @@ export class PaneClient {
         if (!r.ok)
             this.fail(r);
     }
+    /**
+     * GET /v1/taste — the calling agent's freeform "taste notes" markdown blob:
+     * 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
+     * the agent applies prior feedback.
+     */
+    async getTaste() {
+        const r = await this.call("GET", "/v1/taste");
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /**
+     * PUT /v1/taste — whole-blob 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).
+     */
+    async setTaste(taste) {
+        const r = await this.call("PUT", "/v1/taste", { taste });
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /**
+     * DELETE /v1/taste — clear the calling agent's taste notes (idempotent on
+     * the relay; clearing already-empty notes still succeeds). Returns 204 with
+     * no body.
+     */
+    async clearTaste() {
+        const r = await this.call("DELETE", "/v1/taste");
+        if (!r.ok)
+            this.fail(r);
+    }
+    /**
+     * POST /v1/feedback — submit a one-shot bug report, feature request, or
+     * note to the relay operator. Returns the new row's id, type, and
+     * created_at; the message is not echoed.
+     */
+    async submitFeedback(req) {
+        const r = await this.call("POST", "/v1/feedback", {
+            type: req.type,
+            message: req.message,
+            session_id: req.sessionId,
+        });
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /**
+     * GET /v1/feedback — the calling agent's own submissions, newest first.
+     * `before` is an opaque cursor from a previous page's `next_before`.
+     */
+    async listFeedback(opts = {}) {
+        const q = new URLSearchParams();
+        if (opts.limit != null)
+            q.set("limit", String(opts.limit));
+        if (opts.before != null && opts.before !== "")
+            q.set("before", opts.before);
+        const qs = q.toString();
+        const r = await this.call("GET", `/v1/feedback${qs ? "?" + qs : ""}`);
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
     /**
      * DELETE /v1/sessions/:id — close/delete a session. Idempotent on the relay
      * side (an already-closed session still returns 204 with no body).
@@ -278,4 +350,16 @@ export class PaneClient {
         if (!r.ok)
             this.fail(r);
     }
+    /**
+     * DELETE /v1/artifacts/:id — remove an artifact 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 that as a typed PaneApiError so the CLI can render a hint
+     * instead of swallowing it.
+     */
+    async deleteArtifact(idOrSlug) {
+        const r = await this.call("DELETE", `/v1/artifacts/${encodeURIComponent(idOrSlug)}`);
+        if (!r.ok)
+            this.fail(r);
+    }
 }

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { openStream } from "./stream.js";
 export type { OpenStreamOptions, StreamHandlers, StreamHandle, } from "./stream.js";
 export { registerAgent } from "./register.js";
 export type { RegisterAgentOptions, RegisterAgentResult } from "./register.js";
-export { artifactSchema, callbackSchema, createSessionSchema, artifactTypeSchema, createArtifactSchema, createArtifactVersionSchema, patchArtifactMetadataSchema, } from "./schemas.js";
+export { artifactSchema, callbackSchema, createSessionSchema, artifactTypeSchema, createArtifactSchema, createArtifactVersionSchema, patchArtifactMetadataSchema, feedbackTypeSchema, submitFeedbackSchema, } from "./schemas.js";
 export type { CreateSessionInput } from "./schemas.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, Artifact, ArtifactType, ArtifactVersion, ArtifactRecord, ArtifactSummary, CreateArtifactResponse, KeyInfo, Callback, CreateSessionRequest, CreateSessionResponse, SessionState, EventsPage, RelayError, } from "./types.js";
+export type { AuthorKind, PaneEvent, Artifact, ArtifactType, ArtifactVersion, ArtifactRecord, ArtifactSummary, CreateArtifactResponse, KeyInfo, TasteInfo, FeedbackType, FeedbackSubmission, FeedbackRecord, FeedbackPage, Callback, CreateSessionRequest, CreateSessionResponse, SessionState, EventsPage, RelayError, } from "./types.js";

package/dist/index.js

@@ -3,5 +3,5 @@
 export { PaneClient, PaneApiError } from "./client.js";
 export { openStream } from "./stream.js";
 export { registerAgent } from "./register.js";
-export { artifactSchema, callbackSchema, createSessionSchema, artifactTypeSchema, createArtifactSchema, createArtifactVersionSchema, patchArtifactMetadataSchema, } from "./schemas.js";
+export { artifactSchema, callbackSchema, createSessionSchema, artifactTypeSchema, createArtifactSchema, createArtifactVersionSchema, patchArtifactMetadataSchema, feedbackTypeSchema, submitFeedbackSchema, } from "./schemas.js";
 export { MAX_EVENT_TYPE_LENGTH, MAX_IDEMPOTENCY_KEY_LENGTH, MAX_RESPONSE_SNIPPET_LENGTH, MAX_FRAME_SNIPPET_LENGTH, } from "./limits.js";

package/dist/register.d.ts

@@ -11,6 +11,13 @@ export interface RegisterAgentOptions {
     secret?: string;
     /** Optional fetch override (defaults to global fetch). */
     fetch?: typeof fetch;
+    /**
+     * Optional client version string. Sent as `x-pane-cli-version` so the
+     * relay's version-skew check can flag a too-old CLI even on the
+     * un-authenticated register endpoint. See `PaneClient`'s `cliVersion`
+     * option for the parent contract.
+     */
+    cliVersion?: string;
 }
 export interface RegisterAgentResult {
     agent_id: string;

package/dist/register.js

@@ -26,6 +26,9 @@ export async function registerAgent(opts) {
     if (opts.secret !== undefined && opts.secret !== "") {
         headers["authorization"] = `Bearer ${opts.secret}`;
     }
+    if (opts.cliVersion !== undefined && opts.cliVersion !== "") {
+        headers["x-pane-cli-version"] = opts.cliVersion;
+    }
     let res;
     try {
         res = await fetchImpl(base + "/v1/register", {

package/dist/schemas.d.ts

@@ -193,5 +193,19 @@ export declare const patchArtifactMetadataSchema: z.ZodObject<{
     description?: string | undefined;
     tags?: string[] | undefined;
 }>;
+export declare const feedbackTypeSchema: z.ZodEnum<["bug", "feature", "note"]>;
+export declare const submitFeedbackSchema: z.ZodObject<{
+    type: z.ZodEnum<["bug", "feature", "note"]>;
+    message: z.ZodPipeline<z.ZodEffects<z.ZodString, string, string>, z.ZodString>;
+    session_id: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "bug" | "feature" | "note";
+    message: string;
+    session_id?: string | undefined;
+}, {
+    type: "bug" | "feature" | "note";
+    message: string;
+    session_id?: string | undefined;
+}>;
 /** @deprecated use `CreateSessionRequest` from ./types.js (same type). */
 export type CreateSessionInput = z.infer<typeof createSessionSchema>;

package/dist/schemas.js

@@ -80,3 +80,15 @@ export const patchArtifactMetadataSchema = z.object({
     description: z.string().optional(),
     tags: z.array(z.string().min(1)).optional(),
 });
+// POST /v1/feedback — an agent submits a bug report, feature request, or note
+// to the relay operator. Message is trimmed before length check so whitespace
+// padding cannot bypass the 1..4000 cap.
+export const feedbackTypeSchema = z.enum(["bug", "feature", "note"]);
+export const submitFeedbackSchema = z.object({
+    type: feedbackTypeSchema,
+    message: z
+        .string()
+        .transform((s) => s.trim())
+        .pipe(z.string().min(1).max(4000)),
+    session_id: z.string().min(1).optional(),
+});

package/dist/types.d.ts

@@ -130,6 +130,39 @@ export interface KeyInfo {
     last_used_at: string | null;
     revoked_at: string | null;
 }
+/**
+ * Response from GET /v1/taste, PUT /v1/taste — the calling agent's freeform
+ * "taste notes" markdown blob (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.
+ */
+export interface TasteInfo {
+    taste: string | null;
+    updated_at: string | null;
+    bytes: number;
+}
+/** A feedback `type` discriminant accepted by POST /v1/feedback. */
+export type FeedbackType = "bug" | "feature" | "note";
+/** Response from POST /v1/feedback — id, type, created_at only (no message echo). */
+export interface FeedbackSubmission {
+    id: string;
+    type: FeedbackType;
+    created_at: string;
+}
+/** A row from GET /v1/feedback — full record including message. */
+export interface FeedbackRecord {
+    id: string;
+    type: FeedbackType;
+    message: string;
+    session_id: string | null;
+    created_at: string;
+}
+/** Response from GET /v1/feedback — page of the calling agent's own submissions. */
+export interface FeedbackPage {
+    items: FeedbackRecord[];
+    next_before?: string;
+}
 /** A relay error envelope. */
 export interface RelayError {
     code: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paneui/core",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Pane relay client: typed HTTP + WebSocket operations against a Pane relay. Framework-free.",
   "license": "MIT",
   "type": "module",