me2lon 0.0.0-stage → 0.1.0

package/src/api.ts

@@ -0,0 +1,426 @@
+import { createHash, randomUUID } from "node:crypto";
+
+import { Me2lonApiError, Me2lonClientError } from "./errors.js";
+import { SOURCE_SCHEMA_VERSION, type JsonValue, type WorkspaceSource, type WorkspaceSnapshot } from "./types.js";
+
+const API_PREFIX = "/api/agent/v1";
+const MAX_RESPONSE_BYTES = 4 * 1024 * 1024;
+
+function transportError(error: unknown, signal: AbortSignal): Me2lonClientError {
+  if (signal.aborted || (error instanceof Error && error.name === "TimeoutError")) {
+    return new Me2lonClientError(
+      "ME2LON_API_TIMEOUT",
+      "The Me2lon API did not finish responding within 30 seconds.",
+      { cause: error },
+    );
+  }
+  const cause = error instanceof Error ? error.cause : undefined;
+  const code = cause && typeof cause === "object" && "code" in cause ? cause.code : undefined;
+  const detail = code === "ECONNREFUSED" ? " The connection was refused."
+    : code === "ENOTFOUND" || code === "EAI_AGAIN" ? " The server hostname could not be resolved."
+    : "";
+  return new Me2lonClientError(
+    "ME2LON_API_UNREACHABLE",
+    `The connection to the Me2lon API failed.${detail}`,
+    { cause: error },
+  );
+}
+
+function encodeSegment(value: string): string {
+  if (!value) {
+    throw new Me2lonClientError(
+      "ME2LON_API_INPUT_INVALID",
+      "A Me2lon API resource id cannot be empty.",
+    );
+  }
+  return encodeURIComponent(value);
+}
+
+export function idempotencyKey(kind: string, value: unknown): string {
+  const digest = createHash("sha256")
+    .update(JSON.stringify(value))
+    .digest("hex");
+  return `me2lon-${kind}-${digest}`;
+}
+
+/** One logical mutation attempt; reuse it for every retry within that attempt. */
+export function mutationAttemptId(): string {
+  return randomUUID();
+}
+
+function mutationIdempotencyKey(
+  kind: string,
+  attemptId: string,
+  value: unknown,
+): string {
+  return idempotencyKey(kind, { attemptId, request: value });
+}
+
+function assertIdempotencyKey(value: string): void {
+  if (value.length > 255 || !/^[A-Za-z0-9._:-]+$/u.test(value)) {
+    throw new Me2lonClientError(
+      "ME2LON_IDEMPOTENCY_KEY_INVALID",
+      "The generated Me2lon idempotency key has an invalid shape.",
+    );
+  }
+}
+
+function asJsonObject(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Me2lonClientError(
+      "ME2LON_API_RESPONSE_INVALID",
+      "The Me2lon API returned an invalid JSON response.",
+    );
+  }
+  return value as Record<string, unknown>;
+}
+
+export type ApiRequestOptions = Readonly<{
+  method?: "GET" | "POST";
+  body?: JsonValue | Record<string, unknown>;
+  idempotencyKey?: string;
+  sourceSchema?: boolean | string;
+}>;
+
+export class Me2lonAgentApi {
+  readonly #baseUrl: URL;
+  readonly #token: string;
+  readonly #repositoryId: string | undefined;
+  readonly #fetch: typeof fetch;
+
+  constructor(
+    baseUrl: URL,
+    token: string,
+    repositoryId?: string,
+    fetchImplementation: typeof fetch = fetch,
+  ) {
+    this.#baseUrl = baseUrl;
+    this.#token = token;
+    this.#repositoryId = repositoryId;
+    this.#fetch = fetchImplementation;
+  }
+
+  async request(
+    path: string,
+    options: ApiRequestOptions = {},
+  ): Promise<Record<string, unknown>> {
+    // Retry only transport failures, and only when replay cannot create new
+    // work. Reuse the exact options (including the mutation's idempotency key).
+    const canRetry = (options.method ?? "GET") === "GET" || Boolean(options.idempotencyKey);
+    for (let attempt = 0; ; attempt += 1) {
+      try {
+        return await this.#requestOnce(path, options);
+      } catch (error) {
+        if (!(error instanceof Me2lonClientError) ||
+          !["ME2LON_API_TIMEOUT", "ME2LON_API_UNREACHABLE"].includes(error.code)) throw error;
+        if (canRetry && attempt === 0) continue;
+        const submissionHint = options.method === "POST" && options.idempotencyKey
+          ? " The submission may already have been accepted. Check the project dashboard before starting another job."
+          : "";
+        throw new Me2lonClientError(error.code, error.message + submissionHint, { cause: error });
+      }
+    }
+  }
+
+  async #requestOnce(
+    path: string,
+    options: ApiRequestOptions,
+  ): Promise<Record<string, unknown>> {
+    const method = options.method ?? "GET";
+    const headers = new Headers({
+      Accept: "application/json",
+      "User-Agent": "me2lon-agent/0.1.0",
+    });
+    if (this.#token) headers.set("Authorization", `Bearer ${this.#token}`);
+    if (this.#repositoryId) {
+      headers.set("X-Me2lon-Repository-Id", this.#repositoryId);
+    }
+    let body: string | undefined;
+    if (options.body !== undefined) {
+      headers.set("Content-Type", "application/json");
+      body = JSON.stringify(options.body);
+    }
+    if (options.idempotencyKey) {
+      assertIdempotencyKey(options.idempotencyKey);
+      headers.set("Idempotency-Key", options.idempotencyKey);
+    }
+    if (options.sourceSchema) {
+      headers.set("X-Me2lon-Source-Schema", typeof options.sourceSchema === "string" ? options.sourceSchema : SOURCE_SCHEMA_VERSION);
+    }
+
+    const signal = AbortSignal.timeout(30_000);
+    let response: Response;
+    try {
+      response = await this.#fetch(new URL(`${API_PREFIX}${path}`, this.#baseUrl), {
+        method,
+        headers,
+        ...(body === undefined ? {} : { body }),
+        redirect: "error",
+        signal,
+      });
+    } catch (error) {
+      throw transportError(error, signal);
+    }
+    const requestId = response.headers.get("x-request-id") ?? undefined;
+    if (!response.ok) {
+      await response.body?.cancel().catch(() => undefined);
+      throw new Me2lonApiError(response.status, requestId);
+    }
+    if (response.status === 204) {
+      return {};
+    }
+    const declaredLength = Number(response.headers.get("content-length"));
+    if (Number.isFinite(declaredLength) && declaredLength > MAX_RESPONSE_BYTES) {
+      await response.body?.cancel().catch(() => undefined);
+      throw new Me2lonClientError(
+        "ME2LON_API_RESPONSE_LIMIT",
+        "The Me2lon API response exceeded the client safety limit.",
+      );
+    }
+    let bytes: Uint8Array;
+    try {
+      bytes = new Uint8Array(await response.arrayBuffer());
+    } catch (error) {
+      throw transportError(error, signal);
+    }
+    if (bytes.byteLength > MAX_RESPONSE_BYTES) {
+      throw new Me2lonClientError(
+        "ME2LON_API_RESPONSE_LIMIT",
+        "The Me2lon API response exceeded the client safety limit.",
+      );
+    }
+    try {
+      return asJsonObject(JSON.parse(new TextDecoder().decode(bytes)));
+    } catch (error) {
+      if (error instanceof Me2lonClientError) {
+        throw error;
+      }
+      throw new Me2lonClientError(
+        "ME2LON_API_RESPONSE_INVALID",
+        "The Me2lon API returned invalid JSON.",
+        { cause: error },
+      );
+    }
+  }
+
+  capabilities(): Promise<Record<string, unknown>> {
+    return this.request("/capabilities");
+  }
+
+  repositories(): Promise<Record<string, unknown>> {
+    return this.request("/repositories");
+  }
+
+  createWorkspace(
+    repositoryId: string,
+    attemptId = mutationAttemptId(),
+  ): Promise<Record<string, unknown>> {
+    const body = { repositoryId };
+    return this.request("/workspaces", {
+      method: "POST",
+      body,
+      idempotencyKey: mutationIdempotencyKey("workspace", attemptId, body),
+    });
+  }
+
+  createRevision(
+    workspaceId: string,
+    source: WorkspaceSource,
+    attemptId = mutationAttemptId(),
+  ): Promise<Record<string, unknown>> {
+    const body = {
+      baseCommitSha: source.baseCommitSha,
+      changes: source.changes,
+    };
+    return this.request(`/workspaces/${encodeSegment(workspaceId)}/revisions`, {
+      method: "POST",
+      body,
+      idempotencyKey: mutationIdempotencyKey("revision", attemptId, {
+        workspaceId,
+        digest: source.digest,
+      }),
+      sourceSchema: true,
+    });
+  }
+
+  createCheckJob(
+    workspaceRevisionId: string,
+    attemptId = mutationAttemptId(),
+  ): Promise<Record<string, unknown>> {
+    const body = { workspaceRevisionId };
+    return this.request("/check-jobs", {
+      method: "POST",
+      body,
+      idempotencyKey: mutationIdempotencyKey("check", attemptId, body),
+    });
+  }
+
+  createAnalysisJob(workspaceRevisionId: string, projectRoot?: string, attemptId = mutationAttemptId()): Promise<Record<string, unknown>> {
+    const body = { workspaceRevisionId, ...(projectRoot === undefined ? {} : { projectRoot }) };
+    return this.request('/analysis-jobs', { method: 'POST', body,
+      idempotencyKey: mutationIdempotencyKey('analysis', attemptId, body) });
+  }
+
+  createSnapshot(workspaceId: string, source: WorkspaceSnapshot, previousRevisionId: string | undefined, attemptId: string): Promise<Record<string, unknown>> {
+    const body = {
+      schemaVersion: source.schemaVersion, baseCommitSha: source.baseCommitSha,
+      branchLabel: source.branchLabel, files: source.files,
+      ...(previousRevisionId ? { previousRevisionId } : {}),
+    };
+    return this.request(`/workspaces/${encodeSegment(workspaceId)}/revisions`, {
+      method: "POST", body, sourceSchema: source.schemaVersion,
+      idempotencyKey: mutationIdempotencyKey("snapshot", attemptId, { workspaceId, ...body }),
+    });
+  }
+
+  job(jobId: string): Promise<Record<string, unknown>> {
+    return this.request(`/jobs/${encodeSegment(jobId)}`);
+  }
+
+  jobDiagnostics(
+    jobId: string,
+    cursor = 0,
+    limit = 500,
+  ): Promise<Record<string, unknown>> {
+    if (
+      !Number.isSafeInteger(cursor) ||
+      cursor < 0 ||
+      !Number.isSafeInteger(limit) ||
+      limit < 1 ||
+      limit > 500
+    ) {
+      throw new Me2lonClientError(
+        "ME2LON_API_INPUT_INVALID",
+        "Me2lon diagnostic pagination is outside the supported range.",
+      );
+    }
+    return this.request(
+      `/jobs/${encodeSegment(jobId)}/diagnostics?cursor=${cursor}&limit=${limit}`,
+    );
+  }
+
+  createTranslationJob(
+    checkJobId: string,
+    projectId: string,
+    attemptId = mutationAttemptId(),
+  ): Promise<Record<string, unknown>> {
+    const body = { checkJobId, projectId };
+    return this.request("/translation-jobs", {
+      method: "POST",
+      body,
+      idempotencyKey: mutationIdempotencyKey("translation", attemptId, body),
+    });
+  }
+
+  createVerificationJob(
+    translationJobId: string,
+    expectedPolicySetDigest: string,
+    attemptId = mutationAttemptId(),
+  ): Promise<Record<string, unknown>> {
+    const body = { translationJobId, expectedPolicySetDigest };
+    return this.request("/verification-jobs", {
+      method: "POST",
+      body,
+      idempotencyKey: mutationIdempotencyKey("verification", attemptId, body),
+    });
+  }
+
+  policyUnits(repositoryId: string): Promise<Record<string, unknown>> {
+    return this.request(
+      `/repositories/${encodeSegment(repositoryId)}/policy-units`,
+    );
+  }
+
+  policyUnit(policyUnitId: string): Promise<Record<string, unknown>> {
+    return this.request(`/policy-units/${encodeSegment(policyUnitId)}`);
+  }
+
+  createPolicyDraft(
+    policyUnitId: string,
+    expectedPolicySetDigest: string,
+    attemptId = mutationAttemptId(),
+  ): Promise<Record<string, unknown>> {
+    const body = { expectedPolicySetDigest };
+    return this.request(`/policy-units/${encodeSegment(policyUnitId)}/drafts`, {
+      method: "POST",
+      body,
+      idempotencyKey: mutationIdempotencyKey(
+        "policy-draft",
+        attemptId,
+        { policyUnitId, ...body },
+      ),
+    });
+  }
+
+  createPolicyRevision(
+    draftId: string,
+    expectedPolicySetDigest: string,
+    policy: JsonValue,
+    rationale?: string,
+    attemptId = mutationAttemptId(),
+  ): Promise<Record<string, unknown>> {
+    const body = {
+      expectedPolicySetDigest,
+      policy,
+      ...(rationale ? { rationale } : {}),
+    };
+    return this.request(`/policy-drafts/${encodeSegment(draftId)}/revisions`, {
+      method: "POST",
+      body,
+      idempotencyKey: mutationIdempotencyKey(
+        "policy-revision",
+        attemptId,
+        { draftId, ...body },
+      ),
+    });
+  }
+
+  validatePolicyRevision(
+    revisionId: string,
+    attemptId = mutationAttemptId(),
+  ): Promise<Record<string, unknown>> {
+    return this.request(
+      `/policy-revisions/${encodeSegment(revisionId)}/validate`,
+      {
+        method: "POST",
+        body: {},
+        idempotencyKey: mutationIdempotencyKey(
+          "policy-validation",
+          attemptId,
+          { revisionId },
+        ),
+      },
+    );
+  }
+
+  policyRevisionDiff(revisionId: string): Promise<Record<string, unknown>> {
+    return this.request(`/policy-revisions/${encodeSegment(revisionId)}/diff`);
+  }
+
+  submitPolicyRevision(
+    revisionId: string,
+    expectedPolicySetDigest: string,
+    attemptId = mutationAttemptId(),
+  ): Promise<Record<string, unknown>> {
+    const body = { expectedPolicySetDigest };
+    return this.request(
+      `/policy-revisions/${encodeSegment(revisionId)}/submit-for-review`,
+      {
+        method: "POST",
+        body,
+        idempotencyKey: mutationIdempotencyKey("policy-submit", attemptId, {
+          revisionId,
+          ...body,
+        }),
+      },
+    );
+  }
+
+  cancelJob(jobId: string): Promise<Record<string, unknown>> {
+    return this.request(`/jobs/${encodeSegment(jobId)}/cancel`, {
+      method: "POST",
+      body: {},
+      idempotencyKey: idempotencyKey("job-cancel", { jobId }),
+    });
+  }
+}