@toloka-platform/sdk 0.1.0-preview.3

package/src/client.ts

@@ -0,0 +1,510 @@
+import { assert } from "es-toolkit";
+
+import * as wire from "../openapi/gen/api";
+import type {
+  AddDatasetItemsBody,
+  AttachPipelineDatasetBody,
+  CheckJob as GeneratedCheckJob,
+  CopyPipelineBody,
+  CreateDatasetBody,
+  CreateDatasetExportBody,
+  CreateDatasetFieldBodyAnyOf,
+  CreateDatasetUploadBody,
+  CreatePipelineCheckBody,
+  CreateProjectBody,
+  CreateProjectFileUploadBody,
+  Dataset as GeneratedDataset,
+  DatasetField as GeneratedDatasetField,
+  DatasetItem as GeneratedDatasetItem,
+  ExportJob as GeneratedExportJob,
+  EstimatePipelineCostBody,
+  ImportPipelineBody,
+  InferredField as GeneratedInferredField,
+  ListDatasetFieldsParams,
+  ListDatasetItemsParams,
+  ListPipelineRunItemsParams,
+  ListPipelineRunsParams,
+  ListProjectDatasetsParams,
+  ListProjectPipelinesParams,
+  ListProjectsParams,
+  Pipeline as GeneratedPipeline,
+  PatchPipelineNodeBody,
+  PipelineGraphSnapshot,
+  Project as GeneratedProject,
+  ProjectFile as GeneratedProjectFile,
+  ProjectSecretName,
+  ReplacePipelineGraphBody,
+  RunItem as GeneratedRunItem,
+  RunJob as GeneratedRunJob,
+  RunSummary as GeneratedRunSummary,
+  SetProjectSecretBody,
+  UpdatePipelineBody,
+  UpdateProjectBody,
+  UploadJob as GeneratedUploadJob,
+  ValidatePipelineGraphBody,
+} from "../openapi/gen/models";
+import { listAllPages } from "./pagination";
+import { createRequestOptions } from "./transport";
+import { pollUntilTerminal, type WaitForOptions } from "./wait-for";
+
+declare const __brand: unique symbol;
+
+type Brand<B> = { [__brand]: B };
+export type Branded<T extends string, B> = T & Brand<B>;
+
+export type CheckRunId = Branded<string, "CheckRunId">;
+export type DatasetFieldId = Branded<string, "DatasetFieldId">;
+export type DatasetId = Branded<string, "DatasetId">;
+export type DatasetItemId = Branded<string, "DatasetItemId">;
+export type ExportId = Branded<string, "ExportId">;
+export type PipelineId = Branded<string, "PipelineId">;
+export type ProjectFileId = Branded<string, "ProjectFileId">;
+export type ProjectId = Branded<string, "ProjectId">;
+export type RunId = Branded<string, "RunId">;
+export type RunItemId = Branded<string, "RunItemId">;
+export type UploadId = Branded<string, "UploadId">;
+
+type ResourceIdInput<T extends Branded<string, unknown>> = string & {
+  [__brand]?: T[typeof __brand];
+};
+
+type ResourceIdsByProperty = {
+  checkRunId: CheckRunId;
+  datasetFieldId: DatasetFieldId;
+  datasetId: DatasetId;
+  datasetItemId: DatasetItemId;
+  exportId: ExportId;
+  fieldId: DatasetFieldId;
+  fileId: ProjectFileId;
+  goldenDatasetId: DatasetId;
+  itemId: RunItemId;
+  pipelineId: PipelineId;
+  projectFileId: ProjectFileId;
+  projectId: ProjectId;
+  runId: RunId;
+  runItemId: RunItemId;
+  uploadId: UploadId;
+};
+
+type ResourceIdInputsByProperty = {
+  [K in keyof ResourceIdsByProperty]: ResourceIdInput<ResourceIdsByProperty[K]>;
+};
+
+type BrandIdValue<T, Id> = T extends string ? Id : T;
+
+type BrandResourceReferences<T> = {
+  [K in keyof T]: K extends keyof ResourceIdsByProperty
+    ? BrandIdValue<T[K], ResourceIdsByProperty[K]>
+    : T[K];
+};
+
+type BrandedResource<T extends { id: string }, Id extends string> = Omit<
+  BrandResourceReferences<T>,
+  "id"
+> & {
+  id: Id;
+};
+
+type PublicInput<T> = T extends readonly unknown[]
+  ? { [K in keyof T]: PublicInput<T[K]> }
+  : T extends object
+    ? {
+        [K in keyof T]: K extends keyof ResourceIdInputsByProperty
+          ? BrandIdValue<T[K], ResourceIdInputsByProperty[K]>
+          : PublicInput<T[K]>;
+      }
+    : T;
+
+export type CheckJob = BrandedResource<GeneratedCheckJob, CheckRunId>;
+export type Dataset = BrandedResource<GeneratedDataset, DatasetId>;
+export type DatasetField = BrandedResource<GeneratedDatasetField, DatasetFieldId>;
+export type DatasetItem = BrandedResource<GeneratedDatasetItem, DatasetItemId>;
+export type ExportJob = BrandedResource<GeneratedExportJob, ExportId>;
+export type InferredField = GeneratedInferredField;
+export type Pipeline = BrandedResource<GeneratedPipeline, PipelineId>;
+export type Project = BrandedResource<GeneratedProject, ProjectId>;
+export type ProjectFile = BrandedResource<GeneratedProjectFile, ProjectFileId>;
+export type RunItem = BrandedResource<GeneratedRunItem, RunItemId>;
+export type RunJob = BrandedResource<GeneratedRunJob, RunId>;
+export type RunSummary = BrandedResource<GeneratedRunSummary, RunId>;
+export type UploadJob = BrandedResource<GeneratedUploadJob, UploadId>;
+
+type PipelineGraphNode = PipelineGraphSnapshot["graph"]["nodes"][number];
+type NodeSettingsPatch<Node> = Node extends { settings: infer Settings }
+  ? Partial<Settings>
+  : never;
+type PipelineNodeSettingsPatch = NodeSettingsPatch<PipelineGraphNode>;
+type PatchPipelineNodeInput = Omit<PatchPipelineNodeBody, "settings"> & {
+  nodeId: PipelineGraphNode["id"];
+  settings: PipelineNodeSettingsPatch;
+};
+
+export type TerminalJob<T extends { status: string }> = Omit<T, "status"> & {
+  status: Extract<T["status"], "succeeded" | "failed">;
+};
+
+export type ClientConfig = {
+  readonly baseUrl: string;
+  readonly apiKey: string;
+  readonly fetch?: typeof globalThis.fetch;
+};
+
+export type DatasetUploadWaitTarget = {
+  readonly type: "datasetUpload";
+  readonly uploadId: ResourceIdInput<UploadId>;
+};
+
+export type DatasetExportWaitTarget = {
+  readonly type: "datasetExport";
+  readonly exportId: ResourceIdInput<ExportId>;
+};
+
+export type PipelineCheckWaitTarget = {
+  readonly type: "pipelineCheck";
+  readonly checkRunId: ResourceIdInput<CheckRunId>;
+};
+
+export type PipelineRunWaitTarget = {
+  readonly type: "pipelineRun";
+  readonly runId: ResourceIdInput<RunId>;
+};
+
+export type WaitForTarget =
+  | DatasetUploadWaitTarget
+  | DatasetExportWaitTarget
+  | PipelineCheckWaitTarget
+  | PipelineRunWaitTarget;
+
+const createClientImplementation = (config: ClientConfig) => {
+  const requestOptions = createRequestOptions(config.baseUrl, config.apiKey, config.fetch);
+
+  function waitFor(
+    target: DatasetUploadWaitTarget,
+    options?: WaitForOptions,
+  ): Promise<TerminalJob<UploadJob>>;
+  function waitFor(
+    target: DatasetExportWaitTarget,
+    options?: WaitForOptions,
+  ): Promise<TerminalJob<ExportJob>>;
+  function waitFor(
+    target: PipelineCheckWaitTarget,
+    options?: WaitForOptions,
+  ): Promise<TerminalJob<CheckJob>>;
+  function waitFor(
+    target: PipelineRunWaitTarget,
+    options?: WaitForOptions,
+  ): Promise<TerminalJob<RunJob>>;
+  async function waitFor(
+    target: WaitForTarget,
+    options?: WaitForOptions,
+  ): Promise<GeneratedUploadJob | GeneratedExportJob | GeneratedCheckJob | GeneratedRunJob> {
+    switch (target.type) {
+      case "datasetUpload":
+        return pollUntilTerminal(
+          (signal) => wire.getDatasetUpload(target.uploadId, { ...requestOptions, signal }),
+          (job) => job.status === "succeeded" || job.status === "failed",
+          options,
+        );
+      case "datasetExport":
+        return pollUntilTerminal(
+          (signal) => wire.getDatasetExport(target.exportId, { ...requestOptions, signal }),
+          (job) => job.status === "succeeded",
+          options,
+        );
+      case "pipelineCheck":
+        return pollUntilTerminal(
+          (signal) => wire.getPipelineCheck(target.checkRunId, { ...requestOptions, signal }),
+          (job) => job.status === "succeeded" || job.status === "failed",
+          options,
+        );
+      case "pipelineRun":
+        return pollUntilTerminal(
+          (signal) => wire.getPipelineRun(target.runId, { ...requestOptions, signal }),
+          (job) => job.status === "succeeded" || job.status === "failed",
+          options,
+        );
+    }
+  }
+
+  const projects = {
+    create: (input: CreateProjectBody) => wire.createProject(input, requestOptions),
+    get: ({ projectId }: { projectId: ProjectId }) =>
+      wire.getProjectById(projectId, requestOptions),
+    update: ({ projectId, ...body }: { projectId: ProjectId } & UpdateProjectBody) =>
+      wire.updateProject(projectId, body, requestOptions),
+    listPage: (params: ListProjectsParams = {}) => wire.listProjects(params, requestOptions),
+    listAll: (params: ListProjectsParams = {}) =>
+      listAllPages(async (pageOptions) => {
+        const page = await wire.listProjects({ ...params, ...pageOptions }, requestOptions);
+        return { items: page.projects, pagination: page.pagination };
+      }, params),
+  };
+
+  const pipelines = {
+    import: ({ projectId, ...body }: { projectId: ProjectId } & ImportPipelineBody) =>
+      wire.importPipeline(projectId, body, requestOptions),
+    get: ({ pipelineId }: { pipelineId: PipelineId }) =>
+      wire.getPipelineById(pipelineId, requestOptions),
+    update: ({ pipelineId, ...body }: { pipelineId: PipelineId } & UpdatePipelineBody) =>
+      wire.updatePipeline(pipelineId, body, requestOptions),
+    listPage: ({ projectId, ...params }: { projectId: ProjectId } & ListProjectPipelinesParams) =>
+      wire.listProjectPipelines(projectId, params, requestOptions),
+    listAll: ({ projectId, ...params }: { projectId: ProjectId } & ListProjectPipelinesParams) =>
+      listAllPages(async (pageOptions) => {
+        const page = await wire.listProjectPipelines(
+          projectId,
+          { ...params, ...pageOptions },
+          requestOptions,
+        );
+        return { items: page.pipelines, pagination: page.pagination };
+      }, params),
+    getGraph: ({ pipelineId }: { pipelineId: PipelineId }) =>
+      wire.getPipelineGraphSnapshot(pipelineId, requestOptions),
+    replaceGraph: ({
+      pipelineId,
+      ...body
+    }: { pipelineId: PipelineId } & (ReplacePipelineGraphBody | PipelineGraphSnapshot)) =>
+      wire.replacePipelineGraph(
+        pipelineId,
+        "version" in body ? { graph: body.graph, expectedVersion: body.version } : body,
+        requestOptions,
+      ),
+    validateGraph: ({
+      pipelineId,
+      ...body
+    }: { pipelineId: PipelineId } & ValidatePipelineGraphBody) =>
+      wire.validatePipelineGraph(pipelineId, body, requestOptions),
+    estimateCost: ({
+      pipelineId,
+      ...body
+    }: { pipelineId: PipelineId } & EstimatePipelineCostBody) =>
+      wire.estimatePipelineCost(pipelineId, body, requestOptions),
+    patchNode: ({
+      pipelineId,
+      nodeId,
+      ...body
+    }: { pipelineId: PipelineId } & PatchPipelineNodeInput) =>
+      wire.patchPipelineNode(pipelineId, nodeId, body, requestOptions),
+    attachDataset: ({
+      pipelineId,
+      ...body
+    }: { pipelineId: PipelineId } & AttachPipelineDatasetBody) =>
+      wire.attachPipelineDataset(pipelineId, body, requestOptions),
+    export: ({ pipelineId }: { pipelineId: PipelineId }) =>
+      wire.exportPipeline(pipelineId, requestOptions),
+    copy: ({ pipelineId, ...body }: { pipelineId: PipelineId } & CopyPipelineBody) =>
+      wire.copyPipeline(pipelineId, body, requestOptions),
+  };
+
+  const datasets = {
+    create: ({ projectId, ...body }: { projectId: ProjectId } & CreateDatasetBody) =>
+      wire.createDataset(projectId, body, requestOptions),
+    get: ({ datasetId }: { datasetId: DatasetId }) =>
+      wire.getDatasetById(datasetId, requestOptions),
+    listPage: ({ projectId, ...params }: { projectId: ProjectId } & ListProjectDatasetsParams) =>
+      wire.listProjectDatasets(projectId, params, requestOptions),
+    listAll: ({ projectId, ...params }: { projectId: ProjectId } & ListProjectDatasetsParams) =>
+      listAllPages(async (pageOptions) => {
+        const page = await wire.listProjectDatasets(
+          projectId,
+          { ...params, ...pageOptions },
+          requestOptions,
+        );
+        return { items: page.datasets, pagination: page.pagination };
+      }, params),
+    createField: async ({
+      datasetId,
+      ...body
+    }: { datasetId: DatasetId } & CreateDatasetFieldBodyAnyOf) => {
+      const created = await wire.createDatasetField(datasetId, body, requestOptions);
+      assert(!("fields" in created), "Creating one field must return that field");
+      return created;
+    },
+    createFields: async ({
+      datasetId,
+      fields,
+    }: {
+      datasetId: DatasetId;
+      fields: CreateDatasetFieldBodyAnyOf[];
+    }) => {
+      const created = await wire.createDatasetField(datasetId, { fields }, requestOptions);
+      assert("fields" in created, "Creating several fields must return those fields");
+      return created.fields;
+    },
+    listFieldsPage: ({
+      datasetId,
+      ...params
+    }: { datasetId: DatasetId } & ListDatasetFieldsParams) =>
+      wire.listDatasetFields(datasetId, params, requestOptions),
+    getInferredFields: ({ datasetId }: { datasetId: DatasetId }) =>
+      wire.getDatasetInferredFields(datasetId, requestOptions),
+    listAllFields: ({ datasetId, ...params }: { datasetId: DatasetId } & ListDatasetFieldsParams) =>
+      listAllPages(async (pageOptions) => {
+        const page = await wire.listDatasetFields(
+          datasetId,
+          { ...params, ...pageOptions },
+          requestOptions,
+        );
+        return { items: page.fields, pagination: page.pagination };
+      }, params),
+    appendItems: ({ datasetId, ...body }: { datasetId: DatasetId } & AddDatasetItemsBody) =>
+      wire.addDatasetItems(datasetId, body, requestOptions),
+    listItemsPage: ({ datasetId, ...params }: { datasetId: DatasetId } & ListDatasetItemsParams) =>
+      wire.listDatasetItems(datasetId, params, requestOptions),
+    listAllItems: ({ datasetId, ...params }: { datasetId: DatasetId } & ListDatasetItemsParams) =>
+      listAllPages(async (pageOptions) => {
+        const page = await wire.listDatasetItems(
+          datasetId,
+          { ...params, ...pageOptions },
+          requestOptions,
+        );
+        return { items: page.items, pagination: page.pagination };
+      }, params),
+    startUpload: ({ datasetId, ...body }: { datasetId: DatasetId } & CreateDatasetUploadBody) =>
+      wire.createDatasetUpload(datasetId, body, requestOptions),
+    finalizeUpload: ({ uploadId }: { uploadId: UploadId }) =>
+      wire.finalizeDatasetUpload(uploadId, requestOptions),
+    getUpload: ({ uploadId }: { uploadId: UploadId }) =>
+      wire.getDatasetUpload(uploadId, requestOptions),
+    startExport: ({ datasetId, ...body }: { datasetId: DatasetId } & CreateDatasetExportBody) =>
+      wire.createDatasetExport(datasetId, body, requestOptions),
+    getExport: ({ exportId }: { exportId: ExportId }) =>
+      wire.getDatasetExport(exportId, requestOptions),
+  };
+
+  const runs = {
+    start: ({ pipelineId }: { pipelineId: PipelineId }) => {
+      const headers = new Headers(requestOptions.headers);
+      headers.set("Content-Type", "application/json");
+      return wire.createPipelineRun(pipelineId, {
+        ...requestOptions,
+        headers,
+        body: "{}",
+      });
+    },
+    get: ({ runId }: { runId: RunId }) => wire.getPipelineRun(runId, requestOptions),
+    cancel: ({ runId }: { runId: RunId }) => wire.cancelPipelineRun(runId, requestOptions),
+    listPage: ({ pipelineId, ...params }: { pipelineId: PipelineId } & ListPipelineRunsParams) =>
+      wire.listPipelineRuns(pipelineId, params, requestOptions),
+    listAll: ({ pipelineId, ...params }: { pipelineId: PipelineId } & ListPipelineRunsParams) =>
+      listAllPages(async (pageOptions) => {
+        const page = await wire.listPipelineRuns(
+          pipelineId,
+          { ...params, ...pageOptions },
+          requestOptions,
+        );
+        return { items: page.runs, pagination: page.pagination };
+      }, params),
+    listItemsPage: ({ runId, ...params }: { runId: RunId } & ListPipelineRunItemsParams) =>
+      wire.listPipelineRunItems(runId, params, requestOptions),
+    listAllItems: ({ runId, ...params }: { runId: RunId } & ListPipelineRunItemsParams) =>
+      listAllPages(async (pageOptions) => {
+        const page = await wire.listPipelineRunItems(
+          runId,
+          { ...params, ...pageOptions },
+          requestOptions,
+        );
+        return { items: page.items, pagination: page.pagination };
+      }, params),
+    getItem: ({ runId, itemId }: { runId: RunId; itemId: RunItemId }) =>
+      wire.getPipelineRunItem(runId, itemId, requestOptions),
+  };
+
+  const secrets = {
+    list: async ({ projectId }: { projectId: ProjectId }) =>
+      (await wire.listProjectSecrets(projectId, requestOptions)).secrets,
+    set: ({
+      projectId,
+      name,
+      ...body
+    }: { projectId: ProjectId; name: ProjectSecretName } & SetProjectSecretBody) =>
+      wire.setProjectSecret(projectId, name, body, requestOptions),
+  };
+
+  const files = {
+    list: async ({ projectId }: { projectId: ProjectId }) =>
+      (await wire.listProjectFiles(projectId, requestOptions)).files,
+    startUpload: ({ projectId, ...body }: { projectId: ProjectId } & CreateProjectFileUploadBody) =>
+      wire.createProjectFileUpload(projectId, body, requestOptions),
+    finalizeUpload: ({ projectId, fileId }: { projectId: ProjectId; fileId: ProjectFileId }) =>
+      wire.finalizeProjectFileUpload(projectId, fileId, requestOptions),
+    delete: ({ projectId, fileId }: { projectId: ProjectId; fileId: ProjectFileId }) =>
+      wire.deleteProjectFile(projectId, fileId, requestOptions),
+  };
+
+  const checks = {
+    list: async ({ pipelineId }: { pipelineId: PipelineId }) =>
+      (await wire.listPipelineChecks(pipelineId, requestOptions)).checks,
+    start: ({ pipelineId, ...body }: { pipelineId: PipelineId } & CreatePipelineCheckBody) =>
+      wire.createPipelineCheck(pipelineId, body, requestOptions),
+    get: ({ checkRunId }: { checkRunId: CheckRunId }) =>
+      wire.getPipelineCheck(checkRunId, requestOptions),
+  };
+
+  return {
+    me: () => wire.getCurrentUser(requestOptions),
+    projects,
+    pipelines,
+    datasets,
+    runs,
+    secrets,
+    files,
+    checks,
+    waitFor,
+  };
+};
+
+type PublicOutput<T> = T extends GeneratedCheckJob
+  ? CheckJob
+  : T extends GeneratedRunJob
+    ? RunJob
+    : T extends GeneratedExportJob
+      ? ExportJob
+      : T extends GeneratedUploadJob
+        ? UploadJob
+        : T extends GeneratedProject
+          ? Project
+          : T extends GeneratedPipeline
+            ? Pipeline
+            : T extends GeneratedDataset
+              ? Dataset
+              : T extends GeneratedDatasetField
+                ? DatasetField
+                : T extends GeneratedDatasetItem
+                  ? DatasetItem
+                  : T extends GeneratedProjectFile
+                    ? ProjectFile
+                    : T extends GeneratedRunItem
+                      ? RunItem
+                      : T extends GeneratedRunSummary
+                        ? RunSummary
+                        : T extends Promise<infer Value>
+                          ? Promise<PublicOutput<Value>>
+                          : T extends AsyncGenerator<infer Value, infer Return, infer Next>
+                            ? AsyncGenerator<PublicOutput<Value>, PublicOutput<Return>, Next>
+                            : T extends readonly unknown[]
+                              ? { [K in keyof T]: PublicOutput<T[K]> }
+                              : T extends object
+                                ? { [K in keyof T]: PublicOutput<T[K]> }
+                                : T;
+
+type PublicClientMember<T> = T extends (...args: infer Args) => infer Result
+  ? (...args: { [K in keyof Args]: PublicInput<Args[K]> }) => PublicOutput<Result>
+  : T extends object
+    ? { [K in keyof T]: PublicClientMember<T[K]> }
+    : T;
+
+type PublicClient<T extends (...args: never[]) => unknown> = T extends (
+  ...args: never[]
+) => infer Client
+  ? Client extends { waitFor: unknown }
+    ? Omit<PublicClientMember<Client>, "waitFor"> & { waitFor: Client["waitFor"] }
+    : never
+  : never;
+
+export type PotatoClient = PublicClient<typeof createClientImplementation>;
+
+export function createClient(config: ClientConfig): PotatoClient;
+export function createClient(config: ClientConfig) {
+  return createClientImplementation(config);
+}

package/src/errors.ts

@@ -0,0 +1,49 @@
+export type PotatoApiErrorCode = 'http' | 'wait_timeout';
+
+export class PotatoApiError extends Error {
+  readonly code: PotatoApiErrorCode;
+  readonly status: number | undefined;
+  readonly body: unknown;
+
+  private constructor(message: string, code: PotatoApiErrorCode, status: number | undefined, body: unknown) {
+    super(message);
+    this.name = 'PotatoApiError';
+    this.code = code;
+    this.status = status;
+    this.body = body;
+  }
+
+  static fromResponse(status: number, body: unknown) {
+    return new PotatoApiError(`Potato API request failed with status ${status}`, 'http', status, body);
+  }
+
+  static waitTimeout(timeoutMs: number) {
+    return new PotatoApiError(
+      `Potato API job did not reach a terminal status within ${timeoutMs} ms`,
+      'wait_timeout',
+      undefined,
+      { timeoutMs }
+    );
+  }
+}
+
+export type PipelineGraphValidationIssue = {
+  readonly path: string;
+  readonly reason: string;
+};
+
+export class PipelineGraphValidationError extends Error {
+  readonly code = 'invalid_pipeline_graph';
+  readonly issues: readonly PipelineGraphValidationIssue[];
+
+  private constructor(message: string, issues: readonly PipelineGraphValidationIssue[]) {
+    super(message);
+    this.name = 'PipelineGraphValidationError';
+    this.issues = issues;
+  }
+
+  static fromIssues(issues: readonly PipelineGraphValidationIssue[]) {
+    const details = issues.map(({ path, reason }) => `- ${path}: ${reason}`).join('\n');
+    return new PipelineGraphValidationError(`Pipeline graph validation failed\n${details}`, issues);
+  }
+}