@to11ai/sdk 0.0.2 → 0.1.1

package/src/prompts/resource.ts

@@ -5,14 +5,26 @@ import { buildCacheKey, PromptCache } from "./cache";
 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,
@@ -24,6 +36,8 @@ import type {
 	PaginatedResult,
 	ResolvePromptInput,
 	ResolvePromptResult,
+	UpdateProjectPromptLabelInput,
+	UpdateProjectPromptLabelResult,
 	UpdatePromptInput,
 	UpdatePromptResult,
 } from "./types";
@@ -34,14 +48,26 @@ 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,
@@ -52,15 +78,26 @@ export type {
 	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";
@@ -80,6 +117,38 @@ function getProjectPromptPath(projectId: string, promptId: string): string {
 	return `${getProjectPromptsPath(projectId)}/${encodeURIComponent(promptId)}`;
 }
 
+function getProjectPromptLabelsPath(projectId: string): string {
+	return `/v1/projects/${encodeURIComponent(projectId)}/prompt-labels`;
+}
+
+function getProjectPromptLabelPath(projectId: string, label: string): string {
+	return `${getProjectPromptLabelsPath(projectId)}/${encodeURIComponent(label)}`;
+}
+
+/**
+ * Builds the query string for `listLabelEvents`. Scope-specific filters:
+ *   - `label` is forwarded for `"prompt"` and `"project"` scopes only
+ *     (it's already encoded in the path for `"label"` scope).
+ *   - `promptId` is forwarded for `"project"` scope only.
+ *
+ * `undefined` values are omitted so the wire request stays minimal.
+ */
+function buildLabelEventsQuery(input: ListLabelEventsInput): string {
+	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();
+}
+
 export class PromptResource {
 	private readonly transport: Transport;
 	private readonly cache: PromptCache;
@@ -276,4 +345,167 @@ export class PromptResource {
 			throw err;
 		}
 	}
+
+	// ─── Project Label Registry (TO11-666 / phase 2) ─────────────────────────
+
+	/**
+	 * 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.
+	 */
+	async listProjectLabels(
+		input: ListProjectPromptLabelsInput,
+	): Promise<ListProjectPromptLabelsResult> {
+		const { projectId, includeArchived } = input;
+		const envelope =
+			await this.transport.request<ListProjectPromptLabelsResult>(
+				"GET",
+				getProjectPromptLabelsPath(projectId),
+				{
+					query: includeArchived ? { includeArchived: "true" } : undefined,
+				},
+			);
+		return unwrap(envelope);
+	}
+
+	/**
+	 * 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).
+	 */
+	async createProjectLabel(
+		input: CreateProjectPromptLabelInput,
+	): Promise<CreateProjectPromptLabelResult> {
+		const { projectId, ...body } = input;
+		const envelope =
+			await this.transport.request<CreateProjectPromptLabelResult>(
+				"POST",
+				getProjectPromptLabelsPath(projectId),
+				{ body },
+			);
+		return unwrap(envelope);
+	}
+
+	async getProjectLabel(
+		input: GetProjectPromptLabelInput,
+	): Promise<GetProjectPromptLabelResult> {
+		const envelope = await this.transport.request<GetProjectPromptLabelResult>(
+			"GET",
+			getProjectPromptLabelPath(input.projectId, input.label),
+		);
+		return unwrap(envelope);
+	}
+
+	/**
+	 * 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).
+	 */
+	async updateProjectLabel(
+		input: UpdateProjectPromptLabelInput,
+	): Promise<UpdateProjectPromptLabelResult> {
+		const { projectId, label, ...rest } = input;
+		const body: Record<string, unknown> = {};
+		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<UpdateProjectPromptLabelResult>(
+				"PATCH",
+				getProjectPromptLabelPath(projectId, label),
+				{ body },
+			);
+		return unwrap(envelope);
+	}
+
+	/**
+	 * 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.
+	 */
+	async deleteProjectLabel(
+		input: DeleteProjectPromptLabelInput,
+	): Promise<DeleteProjectPromptLabelResult> {
+		const envelope =
+			await this.transport.request<DeleteProjectPromptLabelResult>(
+				"DELETE",
+				getProjectPromptLabelPath(input.projectId, input.label),
+			);
+		return unwrap(envelope);
+	}
+
+	// ─── Reverse lookup (TO11-667 / phase 3) ─────────────────────────────────
+
+	/**
+	 * List every prompt currently pointed at by `label`.
+	 *
+	 * Returns an empty list if no prompt references the label. Gated on
+	 * `prompt:read` server-side.
+	 */
+	async listProjectLabelUsages(
+		input: ListProjectPromptLabelUsagesInput,
+	): Promise<ListProjectPromptLabelUsagesResult> {
+		const envelope =
+			await this.transport.request<ListProjectPromptLabelUsagesResult>(
+				"GET",
+				`${getProjectPromptLabelPath(input.projectId, input.label)}/usages`,
+			);
+		return unwrap(envelope);
+	}
+
+	// ─── Event history (TO11-668 / phase 4) ──────────────────────────────────
+
+	/**
+	 * 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.
+	 */
+	async listLabelEvents(
+		input: ListLabelEventsInput,
+	): Promise<ListLabelEventsResult> {
+		const projectSeg = encodeURIComponent(input.projectId);
+		let path: string;
+		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<ListLabelEventsResult>(
+			"GET",
+			query ? `${path}?${query}` : path,
+		);
+		return unwrap(envelope);
+	}
 }

package/src/prompts/types.ts

@@ -1,13 +1,91 @@
+/**
+ * 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;
+}
+
 // ─── Shared primitives ─────────────────────────────────────────────────────
 
 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;
+
 // ─── Prompt ────────────────────────────────────────────────────────────────
 
 export interface Prompt {
@@ -50,9 +128,22 @@ export interface PromptLabelPointer {
 
 // ─── ResolvedPrompt ────────────────────────────────────────────────────────
 
+/**
+ * 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[] };
+	| { format: "chat"; messages: RenderedChatMessage[] };
 
 export interface ResolvedPrompt {
 	promptId: string;
@@ -200,3 +291,179 @@ export interface ResolvePromptInput {
 }
 
 export type ResolvePromptResult = ResolvedPrompt;
+
+// ─── Project label registry (TO11-666 / phase 2) ───────────────────────────
+//
+// Wire shapes mirror the API's `ProjectPromptLabel`, `ProjectPromptLabelUsage`,
+// and `PromptLabelEvent` schemas. The palette token enum is kept in lockstep
+// with the DB CHECK constraint introduced in the prompt-label-registry
+// migration.
+
+/** 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;
+}
+
+// ─── Project label registry inputs ─────────────────────────────────────────
+
+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[];
+
+// ─── Label event history (TO11-668 / phase 4) ──────────────────────────────
+//
+// One polymorphic SDK method `listLabelEvents` covers all three URL shapes
+// the server exposes. The `scope` discriminator selects between:
+//   - `"label"`   → `/v1/projects/:p/prompts/:pp/labels/:l/events`
+//   - `"prompt"`  → `/v1/projects/:p/prompts/:pp/label-events`
+//   - `"project"` → `/v1/projects/:p/label-events`
+
+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>;