@toloka-platform/sdk 0.1.0-preview.3

package/src/state.ts

@@ -0,0 +1,121 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import Ajv2020, { type ErrorObject } from "ajv/dist/2020.js";
+import { assert } from "es-toolkit";
+
+export const TOLOKA_STATE_FILENAME = "toloka.json";
+
+export class TolokaStateError extends Error {
+  constructor(message: string, options?: { readonly cause?: unknown }) {
+    super(message, options);
+    this.name = "TolokaStateError";
+  }
+}
+
+export type TolokaPipelineBinding = {
+  readonly pipelineId: string;
+};
+
+export type TolokaDatasetBinding = {
+  readonly datasetId: string;
+};
+
+export type TolokaState = {
+  readonly projectId: string;
+  readonly pipelines: Readonly<Record<string, TolokaPipelineBinding>>;
+  readonly datasets: Readonly<Record<string, TolokaDatasetBinding>>;
+};
+
+const relativeSourceDirectoryPattern = "^(?!/)(?!.*\\\\)(?!.*(?:^|/)\\.\\.?(?:/|$))(?!.*//).+$";
+
+export const tolokaStateSchema = {
+  type: "object",
+  properties: {
+    projectId: { type: "string", minLength: 1 },
+    pipelines: {
+      type: "object",
+      propertyNames: { type: "string", pattern: relativeSourceDirectoryPattern },
+      additionalProperties: {
+        type: "object",
+        properties: { pipelineId: { type: "string", minLength: 1 } },
+        required: ["pipelineId"],
+        additionalProperties: false,
+      },
+    },
+    datasets: {
+      type: "object",
+      propertyNames: { type: "string", minLength: 1 },
+      additionalProperties: {
+        type: "object",
+        properties: { datasetId: { type: "string", minLength: 1 } },
+        required: ["datasetId"],
+        additionalProperties: false,
+      },
+    },
+  },
+  required: ["projectId", "pipelines", "datasets"],
+  additionalProperties: false,
+};
+
+const ajv = new Ajv2020({ allErrors: true, strict: false });
+const validateTolokaState = ajv.compile<TolokaState>(tolokaStateSchema);
+
+function validationIssue(error: ErrorObject): string {
+  const property =
+    error.keyword === "required"
+      ? error.params.missingProperty
+      : error.keyword === "additionalProperties"
+        ? error.params.additionalProperty
+        : undefined;
+  const path =
+    typeof property === "string"
+      ? `${error.instancePath}/${property.replaceAll("~", "~0").replaceAll("/", "~1")}`
+      : error.instancePath || "/";
+  return `${path}: ${error.message ?? `failed ${error.keyword} validation`}`;
+}
+
+function parseTolokaState(value: unknown): TolokaState {
+  if (validateTolokaState(value)) return value;
+  const errors = validateTolokaState.errors;
+  assert(errors, "toloka.json validation failed without errors");
+  throw new TolokaStateError(`Invalid toloka.json: ${errors.map(validationIssue).join("; ")}`);
+}
+
+export async function readTolokaState(sourceRoot: string): Promise<TolokaState | undefined> {
+  let source: string;
+  try {
+    source = await readFile(join(sourceRoot, TOLOKA_STATE_FILENAME), "utf8");
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") return undefined;
+    throw error;
+  }
+
+  try {
+    return parseTolokaState(JSON.parse(source));
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new TolokaStateError(`Invalid toloka.json: ${error.message}`, { cause: error });
+    }
+    throw error;
+  }
+}
+
+export async function writeTolokaState(sourceRoot: string, state: TolokaState): Promise<void> {
+  const validatedState = parseTolokaState(state);
+  const pipelines = Object.fromEntries(
+    Object.entries(validatedState.pipelines).sort(([left], [right]) =>
+      left < right ? -1 : left > right ? 1 : 0,
+    ),
+  );
+  const datasets = Object.fromEntries(
+    Object.entries(validatedState.datasets).sort(([left], [right]) =>
+      left < right ? -1 : left > right ? 1 : 0,
+    ),
+  );
+  await mkdir(sourceRoot, { recursive: true });
+  await writeFile(
+    join(sourceRoot, TOLOKA_STATE_FILENAME),
+    `${JSON.stringify({ projectId: validatedState.projectId, pipelines, datasets }, null, 2)}\n`,
+    "utf8",
+  );
+}

package/src/transport.ts

@@ -0,0 +1,53 @@
+import { assert } from 'es-toolkit';
+import { PotatoApiError } from './errors';
+
+const BASE_URL_HEADER = 'x-potato-sdk-base-url';
+
+type TransportRequestInit = RequestInit & {
+  readonly fetch?: typeof globalThis.fetch;
+};
+
+export const createRequestOptions = (
+  baseUrl: string,
+  apiKey: string,
+  fetch?: typeof globalThis.fetch
+): TransportRequestInit => {
+  assert(baseUrl.length > 0, 'The SDK base URL cannot be empty');
+  assert(apiKey.length > 0, 'The SDK API key cannot be empty');
+
+  return {
+    headers: {
+      Accept: 'application/json',
+      Authorization: `ApiKey ${apiKey}`,
+      [BASE_URL_HEADER]: new URL(baseUrl).toString()
+    },
+    fetch
+  };
+};
+
+export function potatoFetch<T>(url: string, options: TransportRequestInit): Promise<T>;
+export async function potatoFetch(url: string, options: TransportRequestInit): Promise<unknown> {
+  const { fetch: fetchImplementation = globalThis.fetch, ...requestOptions } = options;
+  const headers = new Headers(requestOptions.headers);
+  const baseUrl = headers.get(BASE_URL_HEADER);
+  assert(baseUrl, 'The SDK base URL is missing');
+  headers.delete(BASE_URL_HEADER);
+
+  const response = await fetchImplementation(new URL(url, baseUrl), { ...requestOptions, headers });
+  const text = await response.text();
+
+  if (!response.ok) {
+    let body: unknown = text;
+
+    if (text.length === 0) {
+      body = undefined;
+    } else if (response.headers.get('content-type')?.includes('application/json')) {
+      body = JSON.parse(text);
+    }
+
+    throw PotatoApiError.fromResponse(response.status, body);
+  }
+
+  return text.length === 0 ? undefined : JSON.parse(text);
+}
+

package/src/validate.ts

@@ -0,0 +1,42 @@
+import Ajv2020, { type ErrorObject } from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import { assert } from 'es-toolkit';
+import type { PipelineGraphV1 } from '../openapi/gen/models';
+import { PipelineGraphValidationError, type PipelineGraphValidationIssue } from './errors';
+import pipelineGraphV1Contract from './pipeline-graph-v1.contract.json' with { type: 'json' };
+
+const ajv = new Ajv2020({ strict: false });
+addFormats(ajv);
+const validatePipelineGraph = ajv.compile(pipelineGraphV1Contract);
+
+const toValidationIssue = (error: ErrorObject): PipelineGraphValidationIssue => {
+  const property =
+    error.keyword === 'required'
+      ? error.params.missingProperty
+      : error.keyword === 'additionalProperties'
+        ? error.params.additionalProperty
+        : undefined;
+  const path =
+    typeof property === 'string'
+      ? `${error.instancePath}/${property.replaceAll('~', '~0').replaceAll('/', '~1')}`
+      : error.instancePath || '/';
+
+  return { path, reason: error.message ?? `failed ${error.keyword} validation` };
+};
+
+export function validate(graph: unknown): asserts graph is PipelineGraphV1 {
+  if (validatePipelineGraph(graph)) return;
+
+  const errors = validatePipelineGraph.errors;
+  assert(errors, 'Pipeline graph validation failed without errors');
+  const issueKeys = new Set<string>();
+  const issues: PipelineGraphValidationIssue[] = [];
+  for (const error of errors) {
+    const issue = toValidationIssue(error);
+    const key = `${issue.path}\n${issue.reason}`;
+    if (issueKeys.has(key)) continue;
+    issueKeys.add(key);
+    issues.push(issue);
+  }
+  throw PipelineGraphValidationError.fromIssues(issues);
+}

package/src/wait-for.ts

@@ -0,0 +1,54 @@
+import { assert } from 'es-toolkit';
+import { PotatoApiError } from './errors';
+
+export type WaitForOptions = {
+  readonly timeoutMs?: number;
+  readonly intervalMs?: number;
+};
+
+export const pollUntilTerminal = async <T>(
+  poll: (signal: AbortSignal) => Promise<T>,
+  isTerminal: (value: T) => boolean,
+  options: WaitForOptions = {}
+): Promise<T> => {
+  const timeoutMs = options.timeoutMs ?? 60_000;
+  const intervalMs = options.intervalMs ?? 1_000;
+  assert(Number.isFinite(timeoutMs) && timeoutMs >= 0, 'The wait timeout must be a nonnegative finite number');
+  assert(Number.isFinite(intervalMs) && intervalMs > 0, 'The polling interval must be a positive finite number');
+
+  const deadline = Date.now() + timeoutMs;
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    while (true) {
+      if (controller.signal.aborted) {
+        throw PotatoApiError.waitTimeout(timeoutMs);
+      }
+
+      const value = await poll(controller.signal);
+
+      if (isTerminal(value)) {
+        return value;
+      }
+
+      const remainingMs = deadline - Date.now();
+
+      if (remainingMs <= 0) {
+        throw PotatoApiError.waitTimeout(timeoutMs);
+      }
+
+      const { promise, resolve } = Promise.withResolvers<void>();
+      setTimeout(resolve, Math.min(intervalMs, remainingMs));
+      await promise;
+    }
+  } catch (error) {
+    if (controller.signal.aborted) {
+      throw PotatoApiError.waitTimeout(timeoutMs);
+    }
+
+    throw error;
+  } finally {
+    clearTimeout(timeout);
+  }
+};