@tidblink/server 0.0.0-stage → 0.4.0-rc.0

package/dist/session.d.ts

@@ -0,0 +1,165 @@
+import { type AudioTurnInput, type AudioTurnEvent, type AudioTurnResult } from "./audio.js";
+import { type ClientToolDeclaration, type ClientToolSet, type ReplaceClientToolsOptions } from "./client-tools.js";
+import { type TurnCommandInput, type RetryReceipt } from "./control.js";
+import { type SwitchTemplateInput, type TemplateSwitchReceipt } from "./template-switch.js";
+import type { RequestOptions } from "./organization.js";
+import { type ConnectOptions, type SessionConnection } from "./session-connection.js";
+import { HttpClient } from "./http.js";
+import { type OpenRealtimeConnectionInput, type OpenRealtimeConnectionResult, type RealtimeConnectGrant, type RealtimeConnection, type RealtimeModelSelection } from "./realtime.js";
+import { type CreateTurnInput, type TurnResult, type WaitForResultOptions } from "./turn.js";
+import { type SessionInteraction, type SessionInteractionPage, type TurnRecord, type TurnPage, type SessionTimelinePage } from "./history.js";
+import type { ListOptions } from "./http.js";
+/** Model IDs come from the deployment catalog, including newly published models. */
+export type SelectableSessionModel = string;
+export type SessionModel = string;
+/** The Sandbox a Session runs in, chosen at creation. */
+export interface SessionSandboxSelection {
+    /** A selectable Sandbox profile; omitted or null uses the Template's profile. */
+    profileId?: string | null;
+    /** A Drive-relative working directory; defaults to `.`. Creation does not make it. */
+    workingDirectory?: string;
+}
+export interface CreateSessionOptions extends RequestOptions {
+    /** The active Template the Session runs. Required: there is no default Template. */
+    templateId: string;
+    /** Keep the same key and input when recovering an uncertain creation. */
+    idempotencyKey: string;
+    model?: string;
+    realtimeModel?: string;
+    billingTag?: BillingTag | null;
+    tools?: ClientToolDeclaration[];
+    /** Added to the Template instructions for this Session only; at most 4096 UTF-8 bytes. */
+    additionalInstructions?: string | null;
+    sandbox?: SessionSandboxSelection;
+    /** Required as `true` when the Template enables cross-Session Recall. */
+    acknowledgeSessionRecall?: boolean;
+}
+export interface SuggestSessionNameInput {
+    userText: string;
+    assistantText?: string;
+}
+export interface BillingTag {
+    key: string;
+    value: string;
+}
+export interface SessionRecord {
+    organizationId: string;
+    sessionId: string;
+    name: string | null;
+    autoTitle: string | null;
+    ownerUserId: string;
+    startedByUserId: string;
+    createdByType: "user" | "scheduler" | "template_preview";
+    readOnly: boolean;
+    sourceSchedulerId: string | null;
+    sourceSchedulerFireId: string | null;
+    billingTag: BillingTag | null;
+    model: SessionModel;
+    modelRevision: number;
+    realtimeModel: string | null;
+    realtimeModelRevision: number;
+    realtimeModelEtag: string;
+    realtimeVoice: import("./realtime.js").RealtimeVoiceSetting | null;
+    template?: {
+        templateId: string;
+        contentDigest: string;
+    } | null;
+    realtime: {
+        id: string;
+        status: "connecting" | "active" | "paused";
+        audio: import("./realtime.js").RealtimeAudioFormats;
+        startedAt: string;
+    } | null;
+    /** Current Session Configuration Epoch; null for read-only or provider-owned snapshots. */
+    configurationEpoch: number | null;
+    /** True while a Template switch fences new interaction. */
+    switching: boolean;
+    modelPolicyStatus: "allowed" | "organization_disallowed";
+    status: "active" | "deleted";
+    activeTurnId: string | null;
+    createdAt: string;
+    updatedAt: string;
+    deletedAt: string | null;
+}
+export type ClarificationItem = {
+    prompt: string;
+    selectionMode: "single";
+    answerChoices: [string, string, string?];
+    response?: {
+        answers: [string];
+        responseTurnId: string;
+    };
+} | {
+    prompt: string;
+    selectionMode: "multiple";
+    answerChoices: [string, string, ...string[]];
+    response?: {
+        answers: [string, ...string[]];
+        responseTurnId: string;
+    };
+};
+export declare class Session {
+    #private;
+    readonly id: string;
+    constructor(http: HttpClient, id: string, record?: SessionRecord, etag?: string);
+    get data(): Readonly<SessionRecord> | undefined;
+    get model(): SessionModel | undefined;
+    refresh(options?: RequestOptions): Promise<this>;
+    setModel(model: SelectableSessionModel, options?: RequestOptions): Promise<this>;
+    rename(name: string, options?: RequestOptions): Promise<this>;
+    suggestName(input: SuggestSessionNameInput, options?: RequestOptions): Promise<this>;
+    setBillingTag(billingTag: BillingTag | null, options?: RequestOptions): Promise<this>;
+    delete(options?: RequestOptions): Promise<this>;
+    openRealtimeConnection(input?: OpenRealtimeConnectionInput, options?: {
+        signal?: AbortSignal;
+    }): Promise<OpenRealtimeConnectionResult>;
+    getRealtimeConnection(options?: {
+        signal?: AbortSignal;
+    }): Promise<RealtimeConnection>;
+    createRealtimeConnectToken(options?: {
+        signal?: AbortSignal;
+    }): Promise<RealtimeConnectGrant>;
+    endRealtimeConnection(options?: {
+        signal?: AbortSignal;
+    }): Promise<RealtimeConnection>;
+    getRealtimeModelSelection(options?: {
+        signal?: AbortSignal;
+    }): Promise<RealtimeModelSelection>;
+    setRealtimeModel(model: string, options: {
+        ifMatch: string;
+        signal?: AbortSignal;
+    }): Promise<RealtimeModelSelection>;
+    /**
+     * Move this idle Session to another Template. After a lost response, repeat
+     * with the same input to recover the receipt. The receipt holds no Session,
+     * so `data` is not updated: call `refresh()` to read the new Template.
+     */
+    switchTemplate(input: SwitchTemplateInput): Promise<TemplateSwitchReceipt>;
+    /**
+     * Attach this Session to the process's Backend Connection: receive its
+     * events and, unless `observe` is set, declare and execute its Client
+     * Tools. Resolves once the attach took effect. One connection per Session
+     * per OrganizationClient; a connection on another process or client takes
+     * the Session over and this one ends with `superseded`.
+     */
+    connect(options?: ConnectOptions): Promise<SessionConnection>;
+    streamAudio(input: AudioTurnInput): AsyncGenerator<AudioTurnEvent>;
+    audio(input: AudioTurnInput): Promise<AudioTurnResult>;
+    getClientTools(options?: RequestOptions): Promise<ClientToolSet>;
+    replaceClientTools(tools: readonly ClientToolDeclaration[], options: ReplaceClientToolsOptions): Promise<ClientToolSet>;
+    history(options?: ListOptions): Promise<TurnPage>;
+    getTurn(turnId: string, options?: RequestOptions): Promise<TurnRecord>;
+    timeline(options?: ListOptions): Promise<SessionTimelinePage>;
+    listInteractions(options?: ListOptions): Promise<SessionInteractionPage>;
+    getInteraction(inputId: string, options?: RequestOptions): Promise<SessionInteraction>;
+    reconcileInteraction(clientEventId: string, options?: RequestOptions): Promise<SessionInteraction | null>;
+    /** Acceptance requests cancellation; read the receipt for the eventual outcome. */
+    cancel(input: TurnCommandInput): Promise<SessionInteraction>;
+    /** Explicit checkpoint retry has its own identity and original execution result. */
+    retry(input: TurnCommandInput): Promise<RetryReceipt>;
+    submitMessage(input: CreateTurnInput): Promise<SessionInteraction>;
+    waitForResult(inputId: string, options?: WaitForResultOptions): Promise<TurnResult>;
+    turn(input: CreateTurnInput, options?: WaitForResultOptions): Promise<TurnResult>;
+}
+export declare const createSession: (http: HttpClient, options: CreateSessionOptions) => Promise<Session>;
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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"}

package/dist/session.js

@@ -0,0 +1,253 @@
+import { audioTurn, streamAudio, } from "./audio.js";
+import { getClientTools, replaceClientTools, validateClientTools, } from "./client-tools.js";
+import { submitTurnCommand, } from "./control.js";
+import { OutcomeUnknownError } from "./errors.js";
+import { switchTemplate, } from "./template-switch.js";
+import { connectSession, } from "./session-connection.js";
+import { requestOptions, HttpClient, requireEtag, requireKnownKeys, requireCreationKey, requireTemplateId, } from "./http.js";
+import { realtimeModelSelectionFrom, requireOpenRealtimeConnectionReceipt, requireRealtimeConnectGrantReceipt, requireRealtimeConnectionReceipt, requireRealtimeModelSelectionReceipt, } from "./realtime.js";
+import { submitMessage, waitForResult, validateWaitOptions, } from "./turn.js";
+import { getInteraction, reconcileInteraction, listInteractions, history, getTurn, timeline, } from "./history.js";
+export class Session {
+    #http;
+    id;
+    #etag;
+    #record;
+    constructor(http, id, record, etag) {
+        if (!id)
+            throw new TypeError("Session id is required");
+        this.#http = http;
+        this.id = id;
+        this.#record = record;
+        this.#etag = etag;
+    }
+    get data() {
+        return this.#record;
+    }
+    get model() {
+        return this.#record?.model;
+    }
+    async refresh(options) {
+        options = requestOptions(options);
+        const result = await this.#http.getResponse(`/sessions/${encodeURIComponent(this.id)}`, options);
+        const etag = requireEtag(result);
+        this.#record = result.data.session;
+        this.#etag = etag;
+        return this;
+    }
+    async setModel(model, options) {
+        options = requestOptions(options);
+        if (!this.#etag)
+            await this.refresh(options);
+        const result = await this.#http.patchResponse(`/sessions/${encodeURIComponent(this.id)}/model`, { model }, {
+            ifMatch: this.#etag,
+            outcomeUnknown: true,
+            ...options,
+        });
+        if (!result.etag)
+            throw new OutcomeUnknownError("Session model update returned no model ETag; read the Session before changing it again", { requestId: result.requestId });
+        this.#record = sessionReceipt(result.data, result.requestId);
+        const etag = result.etag;
+        this.#etag = etag;
+        return this;
+    }
+    async rename(name, options) {
+        options = requestOptions(options);
+        const result = await this.#http.postResponse(`/sessions/${encodeURIComponent(this.id)}/name`, { name }, { ...options, outcomeUnknown: true });
+        this.#record = sessionReceipt(result.data, result.requestId);
+        return this;
+    }
+    async suggestName(input, options) {
+        options = requestOptions(options);
+        requireKnownKeys(input, ["userText", "assistantText"], "Session naming input");
+        const result = await this.#http.postResponse(`/sessions/${encodeURIComponent(this.id)}/name/suggest`, input, { ...options, outcomeUnknown: true });
+        this.#record = sessionReceipt(result.data, result.requestId);
+        return this;
+    }
+    async setBillingTag(billingTag, options) {
+        options = requestOptions(options);
+        const result = await this.#http.patchResponse(`/sessions/${encodeURIComponent(this.id)}/billing-tag`, { billingTag }, { ...options, outcomeUnknown: true });
+        this.#record = sessionReceipt(result.data, result.requestId);
+        return this;
+    }
+    async delete(options) {
+        options = requestOptions(options);
+        const result = await this.#http.deleteResponse(`/sessions/${encodeURIComponent(this.id)}`, { ...options, outcomeUnknown: true });
+        this.#record = sessionReceipt(result.data, result.requestId);
+        return this;
+    }
+    async openRealtimeConnection(input = {}, options) {
+        options = requestOptions(options);
+        requireKnownKeys(input, ["audio", "metadata"], "Realtime Connection input");
+        const result = await this.#http.postResponse(`/sessions/${encodeURIComponent(this.id)}/realtime`, input, {
+            outcomeUnknown: true,
+            ...(options?.signal ? { signal: options.signal } : {}),
+        });
+        return requireOpenRealtimeConnectionReceipt(result.data, result.requestId);
+    }
+    async getRealtimeConnection(options) {
+        options = requestOptions(options);
+        const response = await this.#http.get(`/sessions/${encodeURIComponent(this.id)}/realtime`, options);
+        return response.realtimeConnection;
+    }
+    async createRealtimeConnectToken(options) {
+        options = requestOptions(options);
+        const result = await this.#http.postResponse(`/sessions/${encodeURIComponent(this.id)}/realtime/connect-tokens`, undefined, {
+            outcomeUnknown: true,
+            ...(options?.signal ? { signal: options.signal } : {}),
+        });
+        return requireRealtimeConnectGrantReceipt(result.data, result.requestId);
+    }
+    async endRealtimeConnection(options) {
+        options = requestOptions(options);
+        const result = await this.#http.deleteResponse(`/sessions/${encodeURIComponent(this.id)}/realtime`, {
+            outcomeUnknown: true,
+            ...(options?.signal ? { signal: options.signal } : {}),
+        });
+        return requireRealtimeConnectionReceipt(result.data, result.requestId);
+    }
+    async getRealtimeModelSelection(options) {
+        options = requestOptions(options);
+        const response = await this.#http.get(`/sessions/${encodeURIComponent(this.id)}`, options);
+        return realtimeModelSelectionFrom(response.session);
+    }
+    async setRealtimeModel(model, options) {
+        requireKnownKeys(options, ["ifMatch", "signal"], "Realtime Model selection options");
+        if (!model || model.length > 128)
+            throw new TypeError("Realtime Model ID must contain 1-128 characters");
+        if (!options.ifMatch)
+            throw new TypeError("Realtime Model selection requires ifMatch");
+        const result = await this.#http.patchResponse(`/sessions/${encodeURIComponent(this.id)}/realtime-model`, { realtimeModel: model }, {
+            ifMatch: options.ifMatch,
+            outcomeUnknown: true,
+            ...(options.signal ? { signal: options.signal } : {}),
+        });
+        const receipt = result.data;
+        return requireRealtimeModelSelectionReceipt(receipt?.session, result.requestId);
+    }
+    /**
+     * Move this idle Session to another Template. After a lost response, repeat
+     * with the same input to recover the receipt. The receipt holds no Session,
+     * so `data` is not updated: call `refresh()` to read the new Template.
+     */
+    switchTemplate(input) {
+        return switchTemplate(this.#http, this.id, input);
+    }
+    /**
+     * Attach this Session to the process's Backend Connection: receive its
+     * events and, unless `observe` is set, declare and execute its Client
+     * Tools. Resolves once the attach took effect. One connection per Session
+     * per OrganizationClient; a connection on another process or client takes
+     * the Session over and this one ends with `superseded`.
+     */
+    connect(options) {
+        return connectSession(this.#http, this.#http.backend, this.#http.userId, this.id, options);
+    }
+    streamAudio(input) {
+        return streamAudio(this.#http, this.id, input);
+    }
+    audio(input) {
+        return audioTurn(this.#http, this.id, input);
+    }
+    getClientTools(options) {
+        return getClientTools(this.#http, this.id, options);
+    }
+    replaceClientTools(tools, options) {
+        return replaceClientTools(this.#http, this.id, tools, options);
+    }
+    history(options) {
+        return history(this.#http, this.id, options);
+    }
+    getTurn(turnId, options) {
+        return getTurn(this.#http, this.id, turnId, options);
+    }
+    timeline(options) {
+        return timeline(this.#http, this.id, options);
+    }
+    listInteractions(options) {
+        return listInteractions(this.#http, this.id, options);
+    }
+    getInteraction(inputId, options) {
+        return getInteraction(this.#http, this.id, inputId, options);
+    }
+    reconcileInteraction(clientEventId, options) {
+        return reconcileInteraction(this.#http, this.id, clientEventId, options);
+    }
+    /** Acceptance requests cancellation; read the receipt for the eventual outcome. */
+    cancel(input) {
+        return submitTurnCommand(this.#http, this.id, "cancel", input);
+    }
+    /** Explicit checkpoint retry has its own identity and original execution result. */
+    retry(input) {
+        return submitTurnCommand(this.#http, this.id, "retry", input);
+    }
+    submitMessage(input) {
+        return submitMessage(this.#http, this.id, input);
+    }
+    waitForResult(inputId, options) {
+        return waitForResult(this.#http, this.id, inputId, options);
+    }
+    async turn(input, options) {
+        validateWaitOptions(options);
+        const waitOptions = {
+            ...(input.signal ? { signal: input.signal } : {}),
+            ...options,
+        };
+        const accepted = await this.submitMessage(input);
+        return this.waitForResult(accepted.inputId, waitOptions);
+    }
+}
+const sessionReceipt = (value, requestId) => {
+    if (typeof value?.session?.sessionId !== "string" ||
+        !value.session.sessionId) {
+        throw new OutcomeUnknownError("Session mutation returned no usable Session; reconcile before retrying", { requestId });
+    }
+    return value.session;
+};
+export const createSession = async (http, options) => {
+    requireKnownKeys(options, [
+        "templateId",
+        "idempotencyKey",
+        "model",
+        "realtimeModel",
+        "billingTag",
+        "tools",
+        "additionalInstructions",
+        "sandbox",
+        "acknowledgeSessionRecall",
+        "signal",
+        "requestId",
+    ], "Session options");
+    requireTemplateId(options.templateId, "Session creation");
+    requireCreationKey(options.idempotencyKey);
+    if (options.tools !== undefined)
+        validateClientTools(options.tools);
+    const instructions = options.additionalInstructions;
+    if (instructions !== undefined &&
+        instructions !== null &&
+        typeof instructions !== "string")
+        throw new TypeError("additionalInstructions must be text or null");
+    if (options.sandbox !== undefined) {
+        requireKnownKeys(options.sandbox, ["profileId", "workingDirectory"], "Session Sandbox selection");
+        const { profileId, workingDirectory } = options.sandbox;
+        if (profileId !== undefined &&
+            profileId !== null &&
+            typeof profileId !== "string")
+            throw new TypeError("sandbox.profileId must be text or null");
+        if (workingDirectory !== undefined && typeof workingDirectory !== "string")
+            throw new TypeError("sandbox.workingDirectory must be text");
+    }
+    const { templateId, idempotencyKey, signal, requestId, ...body } = options;
+    const result = await http.postResponse("/sessions", { agentTemplateId: templateId, ...body }, {
+        idempotencyKey,
+        idempotent: true,
+        outcomeUnknown: true,
+        ...(signal ? { signal } : {}),
+        ...(requestId ? { requestId } : {}),
+    });
+    const record = sessionReceipt(result.data, result.requestId);
+    if (!result.etag)
+        throw new OutcomeUnknownError("Session creation returned no model ETag; recover with the same creation key", { requestId: result.requestId });
+    return new Session(http, record.sessionId, record, result.etag);
+};
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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"}

package/dist/skills.d.ts

@@ -0,0 +1,103 @@
+import { HttpClient, type ListOptions } from "./http.js";
+import type { RequestOptions } from "./organization.js";
+export interface SkillSummary {
+    skillId: string;
+    name: string;
+    description: string;
+    revision: number;
+    /** The latest published version. */
+    headVersion: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface SkillVersion {
+    version: number;
+    name: string;
+    description: string;
+    packageDigest: string;
+    rawSize: number;
+    extractedSize: number;
+    loadable: boolean;
+    portable: boolean;
+    createdAt: string;
+}
+export interface SkillPage {
+    skills: SkillSummary[];
+    nextCursor: string | null;
+}
+/** A Skill with one page of its published versions, newest first. */
+export interface SkillDetail {
+    skill: SkillSummary;
+    versions: SkillVersion[];
+    nextCursor: string | null;
+}
+export type SkillUploadState = "uploading" | "pending" | "uploaded" | "fetching" | "validating" | "extracting" | "awaiting_confirmation" | "finalizing" | "done" | "failed" | "aborted";
+/**
+ * A Skill ZIP being validated and published. It reaches
+ * `awaiting_confirmation` once valid, then `done` with a `version` after
+ * publication; `failed` and `aborted` are final.
+ */
+export interface SkillUpload {
+    uploadId: string;
+    /** Every upload creates a new Skill. */
+    skillId: string;
+    state: SkillUploadState;
+    byteSize: number;
+    sha256: string;
+    /** Publish before this time. */
+    expiresAt: string | null;
+    validation: {
+        entriesTotal: number | null;
+        fileCount: number | null;
+        entriesDone: number;
+        declaredBytes: number | null;
+        bytesDone: number;
+        diagnostics: Record<string, unknown>[];
+        failureCode: string | null;
+        failurePath: string | null;
+    };
+    /** The published version once `state` is `done`. */
+    version: number | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface UploadSkillInput extends RequestOptions {
+    /** The Skill package as a ZIP archive (at most 200 MiB). */
+    bytes: Uint8Array;
+    /** Repeating the same bytes with the same key returns the original upload. */
+    idempotencyKey: string;
+}
+export interface PublishSkillOptions extends RequestOptions {
+    /** Repeating publication with the same key returns the same upload. */
+    idempotencyKey: string;
+}
+export interface WaitForSkillUploadOptions extends RequestOptions {
+    /** Stop waiting at one of these states. Defaults to `awaiting_confirmation`, `done`, `failed` and `aborted`. */
+    until?: readonly SkillUploadState[];
+    /** Local wait limit; default 120 seconds. */
+    timeoutMs?: number;
+    /** Delay between reads; default 1 second. */
+    intervalMs?: number;
+}
+/** Organization Skills that Templates can reference by `skillId` and `version`. */
+export declare class Skills {
+    #private;
+    constructor(http: HttpClient);
+    /** Published, loadable Organization Skills. */
+    list(options?: ListOptions): Promise<SkillPage>;
+    /** A Skill and its published versions, newest first. */
+    get(skillId: string, options?: ListOptions): Promise<SkillDetail>;
+    /** Upload a Skill ZIP for validation. It is not published until `publish`. */
+    upload(input: UploadSkillInput): Promise<SkillUpload>;
+    getUpload(uploadId: string, options?: RequestOptions): Promise<SkillUpload>;
+    /** Read the upload until it reaches a settled state. */
+    waitForUpload(uploadId: string, options?: WaitForSkillUploadOptions): Promise<SkillUpload>;
+    /** Cancel an upload that is not published. */
+    cancelUpload(uploadId: string, options?: RequestOptions): Promise<void>;
+    /**
+     * Publish a validated upload as the Skill's next version. Publication
+     * finishes asynchronously: wait for `done` to read the `version`.
+     */
+    publish(uploadId: string, options: PublishSkillOptions): Promise<SkillUpload>;
+}
+//# sourceMappingURL=skills.d.ts.map

package/dist/skills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"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"}

package/dist/skills.js

@@ -0,0 +1,98 @@
+import { OutcomeUnknownError, TiDBLinkError } from "./errors.js";
+import { HttpClient, paginationQuery, requireCreationKey, requireKnownKeys, requestOptions, sleep, } from "./http.js";
+const SETTLED = [
+    "awaiting_confirmation",
+    "done",
+    "failed",
+    "aborted",
+];
+const uploadPath = (id) => `/skills/uploads/${encodeURIComponent(id)}`;
+const uploadReceipt = (result) => {
+    if (typeof result.data?.upload?.uploadId !== "string" ||
+        !result.data.upload.uploadId)
+        throw new OutcomeUnknownError("Skill upload returned no usable state; repeat it with the same idempotency key", { requestId: result.requestId });
+    return result.data.upload;
+};
+/** Organization Skills that Templates can reference by `skillId` and `version`. */
+export class Skills {
+    #http;
+    constructor(http) {
+        this.#http = http;
+    }
+    /** Published, loadable Organization Skills. */
+    list(options) {
+        return this.#http.get(`/skills${paginationQuery(options)}`, options);
+    }
+    /** A Skill and its published versions, newest first. */
+    get(skillId, options) {
+        return this.#http.get(`/skills/${encodeURIComponent(skillId)}${paginationQuery(options)}`, options);
+    }
+    /** Upload a Skill ZIP for validation. It is not published until `publish`. */
+    async upload(input) {
+        requireKnownKeys(input, ["bytes", "idempotencyKey", "signal", "requestId"], "Skill upload");
+        if (!(input.bytes instanceof Uint8Array) || input.bytes.byteLength === 0)
+            throw new TypeError("Skill upload requires the ZIP bytes");
+        requireCreationKey(input.idempotencyKey);
+        const { response, requestId } = await this.#http.rawResponse("/skills/uploads", {
+            method: "POST",
+            body: Uint8Array.from(input.bytes),
+            headers: { "content-type": "application/octet-stream" },
+            idempotencyKey: input.idempotencyKey,
+            retry: "safe",
+            outcomeUnknown: true,
+            ...(input.signal ? { signal: input.signal } : {}),
+            ...(input.requestId ? { requestId: input.requestId } : {}),
+        });
+        let data;
+        try {
+            data = (await response.json());
+        }
+        catch (cause) {
+            throw new OutcomeUnknownError("Skill upload returned an unusable response; repeat it with the same idempotency key", { requestId, cause });
+        }
+        return uploadReceipt({ data, etag: undefined, requestId });
+    }
+    async getUpload(uploadId, options) {
+        const response = await this.#http.get(uploadPath(uploadId), requestOptions(options));
+        return response.upload;
+    }
+    /** Read the upload until it reaches a settled state. */
+    async waitForUpload(uploadId, options = {}) {
+        requireKnownKeys(options, ["until", "timeoutMs", "intervalMs", "signal", "requestId"], "Skill upload wait options");
+        const { until = SETTLED, timeoutMs = 120_000, intervalMs = 1_000 } = options;
+        for (const value of [timeoutMs, intervalMs])
+            if (!Number.isSafeInteger(value) || value < 0)
+                throw new TypeError("Wait durations must be non-negative integers");
+        const deadline = Date.now() + timeoutMs;
+        const request = {
+            ...(options.signal ? { signal: options.signal } : {}),
+            ...(options.requestId ? { requestId: options.requestId } : {}),
+        };
+        while (true) {
+            const upload = await this.getUpload(uploadId, request);
+            if (until.includes(upload.state))
+                return upload;
+            if (Date.now() + intervalMs > deadline)
+                throw new TiDBLinkError(`Skill upload is still ${upload.state}; read it again later`);
+            await sleep(intervalMs, options.signal);
+        }
+    }
+    /** Cancel an upload that is not published. */
+    async cancelUpload(uploadId, options) {
+        await this.#http.deleteResponse(uploadPath(uploadId), {
+            ...requestOptions(options),
+            outcomeUnknown: true,
+        });
+    }
+    /**
+     * Publish a validated upload as the Skill's next version. Publication
+     * finishes asynchronously: wait for `done` to read the `version`.
+     */
+    async publish(uploadId, options) {
+        requireKnownKeys(options, ["idempotencyKey", "signal", "requestId"], "Skill publication options");
+        requireCreationKey(options.idempotencyKey);
+        const { idempotencyKey, ...request } = options;
+        return uploadReceipt(await this.#http.postResponse(`${uploadPath(uploadId)}/publish`, undefined, { idempotencyKey, idempotent: true, outcomeUnknown: true, ...request }));
+    }
+}
+//# sourceMappingURL=skills.js.map