@to11ai/sdk 0.0.2 → 0.1.1

package/dist/projectEnvironments/types.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Project-scoped environment row as returned by
+ * `GET /v1/projects/:projectId/environments/:slug`.
+ *
+ * Notes:
+ *  - `isSystem: true` for the seeded `prod` / `staging` rows. Those rows
+ *    cannot be renamed, archived, or have their `slug`/`isSystem` mutated.
+ *  - `isGatewayFallback: true` marks the env the gateway routes to when no
+ *    `x-to11-env` header is supplied. At most one env per project may carry
+ *    this flag; clearing the only fallback is rejected with 409
+ *    `CANNOT_CLEAR_ONLY_GATEWAY_FALLBACK`.
+ *  - `archivedAt` is `null` for live envs and an ISO-8601 timestamp for
+ *    soft-archived ones.
+ */
+export interface ProjectEnvironment {
+    id: string;
+    projectId: string;
+    slug: string;
+    name: string;
+    color: string | null;
+    description: string | null;
+    isPointer: boolean;
+    requiresApproval: boolean;
+    isDefault: boolean;
+    isGatewayFallback: boolean;
+    sortOrder: number;
+    isSystem: boolean;
+    archivedAt: string | null;
+    createdBy: string;
+    updatedBy: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Pointer-count payload attached to archive responses. `prompts` is real
+ * today; `rules` / `providers` are 0 in v1 (reserved for Wave 6+ specs to
+ * keep the response shape stable when those domains land).
+ */
+export interface LivePointerCounts {
+    prompts: number;
+    rules: number;
+    providers: number;
+}
+/**
+ * Response body for `POST /v1/projects/:projectId/environments/:slug/archive`.
+ * Carries the soft-archived environment plus the count of live pointers
+ * cascade-cleared by the archive operation (informational, for the
+ * confirmation modal in the web UI).
+ */
+export interface ArchiveProjectEnvironmentResult {
+    environment: ProjectEnvironment;
+    livePointerCounts: LivePointerCounts;
+}
+export interface ListProjectEnvironmentsInput {
+    projectId: string;
+    /**
+     * When `true`, the response includes archived envs (those with a
+     * non-null `archivedAt`). Default behavior excludes them.
+     */
+    includeArchived?: boolean;
+}
+export type ListProjectEnvironmentsResult = ProjectEnvironment[];
+export interface GetProjectEnvironmentInput {
+    projectId: string;
+    slug: string;
+}
+export type GetProjectEnvironmentResult = ProjectEnvironment;
+/**
+ * Create input — must specify a unique `slug` matching lowercase-kebab
+ * (a-z, 0-9, hyphen, 1..63 chars). Reserved system slugs (`prod`,
+ * `staging`) are rejected by the API with `ENVIRONMENT_SLUG_TAKEN`.
+ *
+ * Setting `isGatewayFallback: true` here additionally requires the
+ * `project:manage_default_environment` capability; the create use case
+ * atomically clears the flag on any other env in the same project.
+ */
+export interface CreateProjectEnvironmentInput {
+    projectId: string;
+    slug: string;
+    name: string;
+    color?: string | null;
+    description?: string | null;
+    isPointer?: boolean;
+    requiresApproval?: boolean;
+    isDefault?: boolean;
+    isGatewayFallback?: boolean;
+    sortOrder?: number;
+}
+export type CreateProjectEnvironmentResult = ProjectEnvironment;
+/**
+ * PATCH input — every field is optional. `slug` rename triggers a 7-day
+ * alias row server-side. System envs (`isSystem: true`) reject `slug`,
+ * `isSystem`, and other immutable-field mutations with
+ * `SYSTEM_ENV_IMMUTABLE`.
+ *
+ * As with `create`, mutating `isGatewayFallback` requires the additional
+ * `project:manage_default_environment` capability.
+ */
+export interface UpdateProjectEnvironmentInput {
+    projectId: string;
+    slug: string;
+    newSlug?: string;
+    name?: string;
+    color?: string | null;
+    description?: string | null;
+    isPointer?: boolean;
+    requiresApproval?: boolean;
+    isDefault?: boolean;
+    isGatewayFallback?: boolean;
+    sortOrder?: number;
+}
+export type UpdateProjectEnvironmentResult = ProjectEnvironment;
+export interface ArchiveProjectEnvironmentInput {
+    projectId: string;
+    slug: string;
+}
+export interface RestoreProjectEnvironmentInput {
+    projectId: string;
+    slug: string;
+}
+export type RestoreProjectEnvironmentResult = ProjectEnvironment;

package/dist/prompts/resource.cjs

@@ -56,6 +56,33 @@ function getProjectPromptsPath(projectId) {
 function getProjectPromptPath(projectId, promptId) {
   return `${getProjectPromptsPath(projectId)}/${encodeURIComponent(promptId)}`;
 }
+function getProjectPromptLabelsPath(projectId) {
+  return `/v1/projects/${encodeURIComponent(projectId)}/prompt-labels`;
+}
+function getProjectPromptLabelPath(projectId, label) {
+  return `${getProjectPromptLabelsPath(projectId)}/${encodeURIComponent(label)}`;
+}
+function buildLabelEventsQuery(input) {
+  const params = new URLSearchParams;
+  if (input.page !== undefined)
+    params.set("page", String(input.page));
+  if (input.limit !== undefined)
+    params.set("limit", String(input.limit));
+  if (input.since !== undefined)
+    params.set("since", input.since);
+  if (input.until !== undefined)
+    params.set("until", input.until);
+  if (input.scope === "prompt" && input.label !== undefined) {
+    params.set("label", input.label);
+  }
+  if (input.scope === "project") {
+    if (input.label !== undefined)
+      params.set("label", input.label);
+    if (input.promptId !== undefined)
+      params.set("promptId", input.promptId);
+  }
+  return params.toString();
+}
 
 class PromptResource {
   transport;
@@ -157,4 +184,58 @@ class PromptResource {
       throw err;
     }
   }
+  async listProjectLabels(input) {
+    const { projectId, includeArchived } = input;
+    const envelope = await this.transport.request("GET", getProjectPromptLabelsPath(projectId), {
+      query: includeArchived ? { includeArchived: "true" } : undefined
+    });
+    return unwrap(envelope);
+  }
+  async createProjectLabel(input) {
+    const { projectId, ...body } = input;
+    const envelope = await this.transport.request("POST", getProjectPromptLabelsPath(projectId), { body });
+    return unwrap(envelope);
+  }
+  async getProjectLabel(input) {
+    const envelope = await this.transport.request("GET", getProjectPromptLabelPath(input.projectId, input.label));
+    return unwrap(envelope);
+  }
+  async updateProjectLabel(input) {
+    const { projectId, label, ...rest } = input;
+    const body = {};
+    if (rest.isDefault !== undefined)
+      body.isDefault = rest.isDefault;
+    if (rest.description !== undefined)
+      body.description = rest.description;
+    if (rest.displayColor !== undefined)
+      body.displayColor = rest.displayColor;
+    const envelope = await this.transport.request("PATCH", getProjectPromptLabelPath(projectId, label), { body });
+    return unwrap(envelope);
+  }
+  async deleteProjectLabel(input) {
+    const envelope = await this.transport.request("DELETE", getProjectPromptLabelPath(input.projectId, input.label));
+    return unwrap(envelope);
+  }
+  async listProjectLabelUsages(input) {
+    const envelope = await this.transport.request("GET", `${getProjectPromptLabelPath(input.projectId, input.label)}/usages`);
+    return unwrap(envelope);
+  }
+  async listLabelEvents(input) {
+    const projectSeg = encodeURIComponent(input.projectId);
+    let path;
+    switch (input.scope) {
+      case "label":
+        path = `/v1/projects/${projectSeg}/prompts/${encodeURIComponent(input.promptId)}/labels/${encodeURIComponent(input.label)}/events`;
+        break;
+      case "prompt":
+        path = `/v1/projects/${projectSeg}/prompts/${encodeURIComponent(input.promptId)}/label-events`;
+        break;
+      case "project":
+        path = `/v1/projects/${projectSeg}/label-events`;
+        break;
+    }
+    const query = buildLabelEventsQuery(input);
+    const envelope = await this.transport.request("GET", query ? `${path}?${query}` : path);
+    return unwrap(envelope);
+  }
 }

package/dist/prompts/resource.d.ts

@@ -1,8 +1,8 @@
 import type { Transport } from "../transport";
 import type { CacheConfig } from "./cache";
-import type { ArchivePromptInput, ArchivePromptResult, CreatePromptInput, CreatePromptResult, CreatePromptVersionInput, CreatePromptVersionResult, GetPromptInput, GetPromptResult, GetPromptVersionInput, GetPromptVersionResult, ListPromptLabelsInput, ListPromptLabelsResult, ListPromptsInput, ListPromptsResult, ListPromptVersionsInput, ListPromptVersionsResult, MovePromptLabelInput, MovePromptLabelResult, PaginatedResult, ResolvePromptInput, ResolvePromptResult, UpdatePromptInput, UpdatePromptResult } from "./types";
+import type { ArchivePromptInput, ArchivePromptResult, CreateProjectPromptLabelInput, CreateProjectPromptLabelResult, CreatePromptInput, CreatePromptResult, CreatePromptVersionInput, CreatePromptVersionResult, DeleteProjectPromptLabelInput, DeleteProjectPromptLabelResult, GetProjectPromptLabelInput, GetProjectPromptLabelResult, GetPromptInput, GetPromptResult, GetPromptVersionInput, GetPromptVersionResult, ListLabelEventsInput, ListLabelEventsResult, ListProjectPromptLabelsInput, ListProjectPromptLabelsResult, ListProjectPromptLabelUsagesInput, ListProjectPromptLabelUsagesResult, ListPromptLabelsInput, ListPromptLabelsResult, ListPromptsInput, ListPromptsResult, ListPromptVersionsInput, ListPromptVersionsResult, MovePromptLabelInput, MovePromptLabelResult, PaginatedResult, ResolvePromptInput, ResolvePromptResult, UpdateProjectPromptLabelInput, UpdateProjectPromptLabelResult, UpdatePromptInput, UpdatePromptResult } from "./types";
 export type { CacheConfig } from "./cache";
-export type { ArchivePromptInput, ArchivePromptResult, ChatMessage, CreatePromptInput, CreatePromptResult, CreatePromptVersionInput, CreatePromptVersionResult, GetPromptInput, GetPromptResult, GetPromptVersionInput, GetPromptVersionResult, ListPromptLabelsInput, ListPromptLabelsResult, ListPromptsInput, ListPromptsResult, ListPromptVersionsInput, ListPromptVersionsResult, MovePromptLabelInput, MovePromptLabelResult, PaginatedResult, PaginationInfo, Prompt, PromptFormat, PromptLabelPointer, PromptStatus, PromptVersion, RenderedPrompt, ResolvedPrompt, ResolvePromptInput, ResolvePromptResult, UpdatePromptInput, UpdatePromptResult, } from "./types";
+export type { ArchivePromptInput, ArchivePromptResult, ChatMessage, CreateProjectPromptLabelInput, CreateProjectPromptLabelResult, CreatePromptInput, CreatePromptResult, CreatePromptVersionInput, CreatePromptVersionResult, DeleteProjectPromptLabelInput, DeleteProjectPromptLabelResult, GetProjectPromptLabelInput, GetProjectPromptLabelResult, GetPromptInput, GetPromptResult, GetPromptVersionInput, GetPromptVersionResult, ListLabelEventsInput, ListLabelEventsResult, ListProjectPromptLabelsInput, ListProjectPromptLabelsResult, ListProjectPromptLabelUsagesInput, ListProjectPromptLabelUsagesResult, ListPromptLabelsInput, ListPromptLabelsResult, ListPromptsInput, ListPromptsResult, ListPromptVersionsInput, ListPromptVersionsResult, MovePromptLabelInput, MovePromptLabelResult, PaginatedResult, PaginationInfo, PaletteToken, ProjectPromptLabel, ProjectPromptLabelUsage, Prompt, PromptFormat, PromptLabelEvent, PromptLabelPointer, PromptStatus, PromptVersion, RenderedChatMessage, RenderedPrompt, ResolvedPrompt, ResolvePromptInput, ResolvePromptResult, RowError, TextChatMessage, TextChatRole, ToolChatMessage, UpdateProjectPromptLabelInput, UpdateProjectPromptLabelResult, UpdatePromptInput, UpdatePromptResult, } from "./types";
 export declare class PromptResource {
     private readonly transport;
     private readonly cache;
@@ -18,4 +18,63 @@ export declare class PromptResource {
     moveLabel(input: MovePromptLabelInput): Promise<MovePromptLabelResult>;
     listLabels(input: ListPromptLabelsInput): Promise<ListPromptLabelsResult>;
     resolve(input: ResolvePromptInput): Promise<ResolvePromptResult>;
+    /**
+     * List the project-level label registry.
+     *
+     * Excludes archived entries by default. Pass `includeArchived: true` to
+     * include rows with a non-null `archivedAt` (useful for admin / history
+     * affordances). Gated on `prompt:read` server-side.
+     */
+    listProjectLabels(input: ListProjectPromptLabelsInput): Promise<ListProjectPromptLabelsResult>;
+    /**
+     * Create a new project label.
+     *
+     * Requires the `project:manage_labels` permission. Returns the canonical
+     * row as written to the registry (including server-assigned
+     * `displayColor` if not supplied).
+     */
+    createProjectLabel(input: CreateProjectPromptLabelInput): Promise<CreateProjectPromptLabelResult>;
+    getProjectLabel(input: GetProjectPromptLabelInput): Promise<GetProjectPromptLabelResult>;
+    /**
+     * PATCH a project label.
+     *
+     * Note on `description` semantics: `undefined` means "do not change" —
+     * the SDK omits the field from the body in that case. Pass
+     * `description: ""` (empty string) or `description: null` to explicitly
+     * clear it (the server normalises both).
+     */
+    updateProjectLabel(input: UpdateProjectPromptLabelInput): Promise<UpdateProjectPromptLabelResult>;
+    /**
+     * Archive (soft-delete) a project label.
+     *
+     * Returns the archived row (matches the `archive` pattern — the API
+     * returns 200 with the soft-deleted record so call sites can show
+     * "archived just now" without a follow-up GET). System labels
+     * (`isSystem: true`) cannot be archived; the server returns 409
+     * `PROJECT_LABEL_SYSTEM_NOT_DELETABLE` for those.
+     */
+    deleteProjectLabel(input: DeleteProjectPromptLabelInput): Promise<DeleteProjectPromptLabelResult>;
+    /**
+     * List every prompt currently pointed at by `label`.
+     *
+     * Returns an empty list if no prompt references the label. Gated on
+     * `prompt:read` server-side.
+     */
+    listProjectLabelUsages(input: ListProjectPromptLabelUsagesInput): Promise<ListProjectPromptLabelUsagesResult>;
+    /**
+     * List immutable label-movement events at one of three scopes.
+     *
+     * - `scope: "label"`   — narrows to a single label on a single prompt.
+     *   Requires `promptId` and `label`.
+     * - `scope: "prompt"`  — all label moves on the prompt. Requires
+     *   `promptId`. `label` is an optional server-side filter.
+     * - `scope: "project"` — all label moves in the project. `label` and
+     *   `promptId` are optional filters.
+     *
+     * `since` / `until` are ISO-8601 timestamps. The server returns 422
+     * `INVALID_DATE_RANGE` if `since` is after `until`.
+     *
+     * Gated on `prompt:read` server-side.
+     */
+    listLabelEvents(input: ListLabelEventsInput): Promise<ListLabelEventsResult>;
 }

package/dist/prompts/resource.js

@@ -13,6 +13,33 @@ function getProjectPromptsPath(projectId) {
 function getProjectPromptPath(projectId, promptId) {
   return `${getProjectPromptsPath(projectId)}/${encodeURIComponent(promptId)}`;
 }
+function getProjectPromptLabelsPath(projectId) {
+  return `/v1/projects/${encodeURIComponent(projectId)}/prompt-labels`;
+}
+function getProjectPromptLabelPath(projectId, label) {
+  return `${getProjectPromptLabelsPath(projectId)}/${encodeURIComponent(label)}`;
+}
+function buildLabelEventsQuery(input) {
+  const params = new URLSearchParams;
+  if (input.page !== undefined)
+    params.set("page", String(input.page));
+  if (input.limit !== undefined)
+    params.set("limit", String(input.limit));
+  if (input.since !== undefined)
+    params.set("since", input.since);
+  if (input.until !== undefined)
+    params.set("until", input.until);
+  if (input.scope === "prompt" && input.label !== undefined) {
+    params.set("label", input.label);
+  }
+  if (input.scope === "project") {
+    if (input.label !== undefined)
+      params.set("label", input.label);
+    if (input.promptId !== undefined)
+      params.set("promptId", input.promptId);
+  }
+  return params.toString();
+}
 
 class PromptResource {
   transport;
@@ -114,6 +141,60 @@ class PromptResource {
       throw err;
     }
   }
+  async listProjectLabels(input) {
+    const { projectId, includeArchived } = input;
+    const envelope = await this.transport.request("GET", getProjectPromptLabelsPath(projectId), {
+      query: includeArchived ? { includeArchived: "true" } : undefined
+    });
+    return unwrap(envelope);
+  }
+  async createProjectLabel(input) {
+    const { projectId, ...body } = input;
+    const envelope = await this.transport.request("POST", getProjectPromptLabelsPath(projectId), { body });
+    return unwrap(envelope);
+  }
+  async getProjectLabel(input) {
+    const envelope = await this.transport.request("GET", getProjectPromptLabelPath(input.projectId, input.label));
+    return unwrap(envelope);
+  }
+  async updateProjectLabel(input) {
+    const { projectId, label, ...rest } = input;
+    const body = {};
+    if (rest.isDefault !== undefined)
+      body.isDefault = rest.isDefault;
+    if (rest.description !== undefined)
+      body.description = rest.description;
+    if (rest.displayColor !== undefined)
+      body.displayColor = rest.displayColor;
+    const envelope = await this.transport.request("PATCH", getProjectPromptLabelPath(projectId, label), { body });
+    return unwrap(envelope);
+  }
+  async deleteProjectLabel(input) {
+    const envelope = await this.transport.request("DELETE", getProjectPromptLabelPath(input.projectId, input.label));
+    return unwrap(envelope);
+  }
+  async listProjectLabelUsages(input) {
+    const envelope = await this.transport.request("GET", `${getProjectPromptLabelPath(input.projectId, input.label)}/usages`);
+    return unwrap(envelope);
+  }
+  async listLabelEvents(input) {
+    const projectSeg = encodeURIComponent(input.projectId);
+    let path;
+    switch (input.scope) {
+      case "label":
+        path = `/v1/projects/${projectSeg}/prompts/${encodeURIComponent(input.promptId)}/labels/${encodeURIComponent(input.label)}/events`;
+        break;
+      case "prompt":
+        path = `/v1/projects/${projectSeg}/prompts/${encodeURIComponent(input.promptId)}/label-events`;
+        break;
+      case "project":
+        path = `/v1/projects/${projectSeg}/label-events`;
+        break;
+    }
+    const query = buildLabelEventsQuery(input);
+    const envelope = await this.transport.request("GET", query ? `${path}?${query}` : path);
+    return unwrap(envelope);
+  }
 }
 export {
   PromptResource

package/dist/prompts/types.d.ts

@@ -1,9 +1,83 @@
+/**
+ * Per-row pointer carried on 422 validation envelopes.
+ *
+ * The published `@to11ai/sdk` package does NOT depend on the internal
+ * `@to11/shared-kernel` workspace package (it would pull workspace-only
+ * types into a public npm release). The shape below is therefore
+ * declared identically to `RowError` in
+ * `packages/shared-kernel/src/schemas/api-schemas.ts` — keep them in
+ * lockstep when adding new fields.
+ *
+ * 422 responses for prompt-version writes carry an optional
+ * `error.rowErrors` array — one entry per failing field. Each row
+ * carries:
+ *
+ *   - `path`: JSON-pointer-equivalent array, e.g.
+ *     `["messages", 3, "name"]`.
+ *   - `code`: stable identifier such as `tool_name_invalid_charset`
+ *     or `messages_empty` — see the platform spec for the full set.
+ *   - `message`: a human-readable summary.
+ *
+ * SDK consumers can detect the structured shape by inspecting
+ * `error.code === "validation_failed"` and walking `error.rowErrors`
+ * (always optional; absent on non-validation 422s).
+ */
+export interface RowError {
+    path: ReadonlyArray<string | number>;
+    code: string;
+    message: string;
+}
 export type PromptStatus = "active" | "archived";
 export type PromptFormat = "text" | "chat";
-export interface ChatMessage {
-    role: "system" | "user" | "assistant" | "tool";
+/**
+ * Roles supported by `TextChatMessage`.
+ *
+ * V1 server contract: `developer` is accepted at the wire boundary and
+ * rendered as `user` in `:resolve` responses. The literal is preserved
+ * here so SDK consumers can author developer-tagged messages today and
+ * V2 can flip the rendered role without a wire-level break.
+ */
+export type TextChatRole = "system" | "user" | "assistant" | "developer";
+/**
+ * Text-style chat message. Carries a Liquid template body in `content`.
+ *
+ * `disabled` skips the message at render time but preserves it through
+ * edit / list / get round-trips so authors can toggle messages without
+ * losing them.
+ */
+export interface TextChatMessage {
+    role: TextChatRole;
     content: string;
+    disabled?: boolean;
+}
+/**
+ * Tool-call chat message. Structurally distinct from text messages: it
+ * carries `name` / `description` / `parameters` instead of `content`.
+ *
+ * - `name`: 1..200 chars, matches the tool name the gateway exposes to
+ *   providers.
+ * - `description`: optional human-readable summary surfaced in the
+ *   provider's tool-choice UI.
+ * - `parameters`: JSON Schema (an object) describing the tool's
+ *   arguments. Not validated against the JSON Schema meta-schema at
+ *   edit time — the gateway is the source of truth.
+ */
+export interface ToolChatMessage {
+    role: "tool";
+    name: string;
+    description?: string;
+    parameters: unknown;
+    disabled?: boolean;
 }
+/**
+ * Discriminated union of text and tool chat messages.
+ *
+ * Legacy `{role: "tool", content: "..."}` rows are auto-upgraded by the
+ * server on read: they decode as `{role: "tool", name: "(unnamed)",
+ * description: <legacy content>, parameters: {}}`. Writes always emit
+ * the new shape.
+ */
+export type ChatMessage = TextChatMessage | ToolChatMessage;
 export interface Prompt {
     id: string;
     projectId: string;
@@ -35,12 +109,24 @@ export interface PromptLabelPointer {
     updatedByUserId: string;
     updatedAt: string;
 }
+/**
+ * A single message in a rendered chat prompt returned by `:resolve`.
+ *
+ * Always carries a flat `{role, content}` shape — even tool/developer
+ * messages, since the server normalises them at render time
+ * (V1 contract: tool messages are filtered, developer is mapped to user).
+ * The `role` literal stays wide so V2 changes are wire-compatible.
+ */
+export interface RenderedChatMessage {
+    role: "system" | "user" | "assistant" | "developer" | "tool";
+    content: string;
+}
 export type RenderedPrompt = {
     format: "text";
     text: string;
 } | {
     format: "chat";
-    messages: ChatMessage[];
+    messages: RenderedChatMessage[];
 };
 export interface ResolvedPrompt {
     promptId: string;
@@ -140,3 +226,131 @@ export interface ResolvePromptInput {
     fallback?: ResolvedPrompt;
 }
 export type ResolvePromptResult = ResolvedPrompt;
+/** Palette token assigned to a project label for UI rendering. */
+export type PaletteToken = "accent" | "red" | "orange" | "amber" | "green" | "teal" | "blue" | "indigo" | "purple" | "pink";
+/**
+ * Project-level label registry entry.
+ *
+ * System labels (`isSystem: true`) cannot be archived. `archivedAt` is
+ * non-null for soft-deleted entries; the list endpoint excludes archived
+ * entries by default — pass `includeArchived: true` if the call site needs
+ * them (e.g. admin / history affordances).
+ */
+export interface ProjectPromptLabel {
+    projectId: string;
+    label: string;
+    isSystem: boolean;
+    isDefault: boolean;
+    description: string | null;
+    displayColor: PaletteToken;
+    createdByUserId: string;
+    createdAt: string;
+    updatedAt: string;
+    archivedAt: string | null;
+}
+/**
+ * A single prompt currently pointed at by a given project label.
+ *
+ * Returned by `GET /v1/projects/:projectId/prompt-labels/:label/usages`.
+ * `updatedAt` / `updatedByUserId` carry the last-move metadata so the UI
+ * can render a "moved 3 days ago by …" affordance without a second
+ * roundtrip.
+ */
+export interface ProjectPromptLabelUsage {
+    promptId: string;
+    promptSlug: string;
+    promptName: string;
+    versionId: string;
+    version: number;
+    updatedAt: string;
+    updatedByUserId: string;
+}
+/**
+ * An immutable history row for a single label movement.
+ *
+ * `fromVersionId` is `null` for the first time the label is pointed at a
+ * version (no prior pointer). `reason` is the optional caller-supplied
+ * audit string.
+ */
+export interface PromptLabelEvent {
+    id: string;
+    promptId: string;
+    label: string;
+    fromVersionId: string | null;
+    toVersionId: string;
+    movedByUserId: string;
+    movedAt: string;
+    reason: string | null;
+}
+export interface ListProjectPromptLabelsInput {
+    projectId: string;
+    /** Set true to include archived (soft-deleted) entries. Default: false. */
+    includeArchived?: boolean;
+}
+export type ListProjectPromptLabelsResult = ProjectPromptLabel[];
+export interface CreateProjectPromptLabelInput {
+    projectId: string;
+    label: string;
+    isDefault?: boolean;
+    description?: string;
+    displayColor?: PaletteToken;
+}
+export type CreateProjectPromptLabelResult = ProjectPromptLabel;
+export interface GetProjectPromptLabelInput {
+    projectId: string;
+    label: string;
+}
+export type GetProjectPromptLabelResult = ProjectPromptLabel;
+export interface UpdateProjectPromptLabelInput {
+    projectId: string;
+    label: string;
+    isDefault?: boolean;
+    description?: string | null;
+    displayColor?: PaletteToken;
+}
+export type UpdateProjectPromptLabelResult = ProjectPromptLabel;
+export interface DeleteProjectPromptLabelInput {
+    projectId: string;
+    label: string;
+}
+/**
+ * The DELETE endpoint returns 200 with the archived row (mirrors the
+ * `archivePrompt` pattern — call sites can show "archived just now"
+ * without a follow-up GET). System labels (`isSystem: true`) cannot be
+ * archived; the server returns 409 `PROJECT_LABEL_SYSTEM_NOT_DELETABLE`.
+ */
+export type DeleteProjectPromptLabelResult = ProjectPromptLabel;
+export interface ListProjectPromptLabelUsagesInput {
+    projectId: string;
+    label: string;
+}
+export type ListProjectPromptLabelUsagesResult = ProjectPromptLabelUsage[];
+export type ListLabelEventsInput = {
+    scope: "label";
+    projectId: string;
+    promptId: string;
+    label: string;
+    page?: number;
+    limit?: number;
+    since?: string;
+    until?: string;
+} | {
+    scope: "prompt";
+    projectId: string;
+    promptId: string;
+    label?: string;
+    page?: number;
+    limit?: number;
+    since?: string;
+    until?: string;
+} | {
+    scope: "project";
+    projectId: string;
+    promptId?: string;
+    label?: string;
+    page?: number;
+    limit?: number;
+    since?: string;
+    until?: string;
+};
+export type ListLabelEventsResult = PaginatedResult<PromptLabelEvent>;