arga-sdk 0.1.0

package/README.md

@@ -0,0 +1,96 @@
+# Arga TypeScript SDK
+
+TypeScript client for the [Arga](https://argalabs.com) API. Zero runtime dependencies -- uses native `fetch` (Node 18+).
+
+## Installation
+
+```bash
+npm install arga-sdk
+```
+
+## Quick Start
+
+```typescript
+import { Arga } from 'arga-sdk';
+
+const client = new Arga({ apiKey: 'arga_...' });
+
+// Create a URL run
+const run = await client.runs.createUrlRun({
+  url: 'https://staging.myapp.com',
+  twins: ['stripe', 'slack'],
+});
+console.log(run.runId, run.status);
+
+// Poll until the run completes
+const detail = await client.runs.wait(run.runId);
+console.log(detail.status, detail.resultsJson);
+
+// Stream results via SSE
+for await (const event of client.runs.streamResults(run.runId)) {
+  console.log(event);
+}
+```
+
+## Configuration
+
+```typescript
+const client = new Arga({
+  apiKey: 'arga_...', // required
+  baseUrl: 'https://app.argalabs.com', // optional, this is the default
+});
+```
+
+## Available Methods
+
+### Runs
+
+| Method | Description |
+|--------|-------------|
+| `client.runs.createUrlRun(params)` | Create a URL validation run |
+| `client.runs.createPrRun(params)` | Create a PR validation run |
+| `client.runs.createAgentRun(params)` | Create an autonomous agent run |
+| `client.runs.get(runId)` | Get full run details |
+| `client.runs.streamResults(runId)` | Stream run results as SSE events |
+| `client.runs.cancel(runId)` | Cancel a running run |
+| `client.runs.wait(runId, opts?)` | Poll until terminal status |
+
+### Twins
+
+| Method | Description |
+|--------|-------------|
+| `client.twins.list()` | List all available twins |
+| `client.twins.provision(params)` | Provision twins for a run |
+| `client.twins.getStatus(runId)` | Get twin provisioning status |
+| `client.twins.extend(runId, params?)` | Extend twin TTL |
+
+### Scenarios
+
+| Method | Description |
+|--------|-------------|
+| `client.scenarios.create(params)` | Create a new scenario |
+| `client.scenarios.list(params?)` | List scenarios (filter by twin or tag) |
+| `client.scenarios.get(scenarioId)` | Get a scenario by ID |
+
+## Error Handling
+
+```typescript
+import { ArgaAPIError } from 'arga-sdk';
+
+try {
+  await client.runs.get('nonexistent');
+} catch (err) {
+  if (err instanceof ArgaAPIError) {
+    console.error(err.statusCode); // e.g. 404
+    console.error(err.message);    // error detail from API
+  }
+}
+```
+
+## Documentation
+
+Full API documentation is available at [docs.argalabs.com](https://docs.argalabs.com).
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,369 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Arga: () => Arga,
+  ArgaAPIError: () => ArgaAPIError,
+  ArgaError: () => ArgaError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var ArgaError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ArgaError";
+  }
+};
+var ArgaAPIError = class extends ArgaError {
+  /** HTTP status code returned by the API. */
+  statusCode;
+  /** Raw Response object from fetch. */
+  response;
+  /** Parsed response body, if available. */
+  body;
+  constructor(message, statusCode, response, body) {
+    super(message);
+    this.name = "ArgaAPIError";
+    this.statusCode = statusCode;
+    this.response = response;
+    this.body = body;
+  }
+};
+
+// src/http.ts
+function toSnakeCase(str) {
+  return str.replace(/[A-Z]/g, (ch) => `_${ch.toLowerCase()}`);
+}
+function toCamelCase(str) {
+  return str.replace(/_([a-z])/g, (_, ch) => ch.toUpperCase());
+}
+function convertKeys(obj, mapper) {
+  if (Array.isArray(obj)) {
+    return obj.map((item) => convertKeys(item, mapper));
+  }
+  if (obj !== null && typeof obj === "object" && !(obj instanceof Date)) {
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+      result[mapper(key)] = convertKeys(value, mapper);
+    }
+    return result;
+  }
+  return obj;
+}
+function toSnakeCaseKeys(obj) {
+  return convertKeys(obj, toSnakeCase);
+}
+function toCamelCaseKeys(obj) {
+  return convertKeys(obj, toCamelCase);
+}
+var HttpClient = class {
+  baseUrl;
+  apiKey;
+  _fetch;
+  constructor(opts) {
+    this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+    this.apiKey = opts.apiKey;
+    this._fetch = opts.fetch;
+  }
+  // ---- public helpers -----------------------------------------------------
+  async get(path, query) {
+    const url = this.buildUrl(path, query);
+    const res = await this._fetch(url, {
+      method: "GET",
+      headers: this.headers()
+    });
+    return this.handleResponse(res);
+  }
+  async post(path, body) {
+    const url = this.buildUrl(path);
+    const res = await this._fetch(url, {
+      method: "POST",
+      headers: this.headers(),
+      body: body !== void 0 ? JSON.stringify(toSnakeCaseKeys(body)) : void 0
+    });
+    return this.handleResponse(res);
+  }
+  /**
+   * Perform a GET request and return the raw Response, for SSE streaming.
+   */
+  async getRaw(path) {
+    const url = this.buildUrl(path);
+    const res = await this._fetch(url, {
+      method: "GET",
+      headers: {
+        ...this.headers(),
+        Accept: "text/event-stream"
+      }
+    });
+    if (!res.ok) {
+      await this.throwApiError(res);
+    }
+    return res;
+  }
+  // ---- internals ----------------------------------------------------------
+  buildUrl(path, query) {
+    const url = new URL(`${this.baseUrl}${path}`);
+    if (query) {
+      for (const [k, v] of Object.entries(query)) {
+        if (v !== void 0 && v !== "") {
+          url.searchParams.set(k, v);
+        }
+      }
+    }
+    return url.toString();
+  }
+  headers() {
+    return {
+      Authorization: `Bearer ${this.apiKey}`,
+      "Content-Type": "application/json"
+    };
+  }
+  async handleResponse(res) {
+    if (!res.ok) {
+      await this.throwApiError(res);
+    }
+    const json = await res.json();
+    return toCamelCaseKeys(json);
+  }
+  async throwApiError(res) {
+    let body;
+    try {
+      body = await res.json();
+    } catch {
+      body = await res.text().catch(() => null);
+    }
+    const detail = body && typeof body === "object" && "detail" in body ? String(body.detail) : `HTTP ${res.status}`;
+    throw new ArgaAPIError(detail, res.status, res, body);
+  }
+};
+async function* parseSSE(response) {
+  const body = response.body;
+  if (!body) {
+    throw new ArgaError("Response body is null \u2014 cannot stream SSE");
+  }
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let currentEvent;
+  let currentData = [];
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+      for (const line of lines) {
+        if (line === "") {
+          if (currentData.length > 0) {
+            yield {
+              event: currentEvent,
+              data: currentData.join("\n")
+            };
+          }
+          currentEvent = void 0;
+          currentData = [];
+        } else if (line.startsWith("event:")) {
+          currentEvent = line.slice(6).trim();
+        } else if (line.startsWith("data:")) {
+          currentData.push(line.slice(5).trim());
+        }
+      }
+    }
+    if (currentData.length > 0) {
+      yield {
+        event: currentEvent,
+        data: currentData.join("\n")
+      };
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+// src/resources/runs.ts
+var TERMINAL_STATUSES = /* @__PURE__ */ new Set([
+  "completed",
+  "failed",
+  "cancelled",
+  "canceled",
+  "error",
+  "timed_out"
+]);
+var RunsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** Create a URL run. */
+  async createUrlRun(params) {
+    return this.http.post("/validate/url-run", params);
+  }
+  /** Create a PR run. */
+  async createPrRun(params) {
+    return this.http.post("/validate/pr-run", params);
+  }
+  /** Create an agent (sandbox) run. */
+  async createAgentRun(params) {
+    return this.http.post("/validate/agent-run", params);
+  }
+  /** Get full details of a run by ID. */
+  async get(runId) {
+    return this.http.get(`/runs/${encodeURIComponent(runId)}`);
+  }
+  /**
+   * Stream run results as Server-Sent Events.
+   *
+   * Returns an `AsyncIterable<RunEvent>`. Each yielded event contains an
+   * optional `event` field and a parsed `data` payload.
+   */
+  async *streamResults(runId) {
+    const response = await this.http.getRaw(
+      `/validate/${encodeURIComponent(runId)}/results`
+    );
+    for await (const sse of parseSSE(response)) {
+      let data;
+      try {
+        data = toCamelCaseKeys(JSON.parse(sse.data));
+      } catch {
+        data = sse.data;
+      }
+      yield { event: sse.event, data };
+    }
+  }
+  /** Cancel a run. */
+  async cancel(runId) {
+    return this.http.post(
+      `/validate/${encodeURIComponent(runId)}/cancel`
+    );
+  }
+  /**
+   * Poll a run until it reaches a terminal status.
+   *
+   * @param runId  - The run ID to poll.
+   * @param opts   - Optional polling configuration.
+   * @returns The final `RunDetail` once the run has completed (or failed/cancelled).
+   * @throws ArgaError if the timeout is exceeded.
+   */
+  async wait(runId, opts) {
+    const pollInterval = opts?.pollInterval ?? 2500;
+    const timeout = opts?.timeout ?? 6e5;
+    const deadline = Date.now() + timeout;
+    while (true) {
+      const detail = await this.get(runId);
+      if (TERMINAL_STATUSES.has(detail.status)) {
+        return detail;
+      }
+      if (Date.now() + pollInterval > deadline) {
+        throw new ArgaError(
+          `Timed out waiting for run ${runId} after ${timeout}ms (last status: ${detail.status})`
+        );
+      }
+      await new Promise((resolve) => setTimeout(resolve, pollInterval));
+    }
+  }
+};
+
+// src/resources/twins.ts
+var TwinsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** List all available twins. */
+  async list() {
+    return this.http.get("/validate/twins");
+  }
+  /** Provision a set of twins. */
+  async provision(params) {
+    return this.http.post(
+      "/validate/twins/provision",
+      params
+    );
+  }
+  /** Get the provisioning status of twins for a given run. */
+  async getStatus(runId) {
+    return this.http.get(
+      `/validate/twins/provision/${encodeURIComponent(runId)}/status`
+    );
+  }
+  /** Extend the TTL of provisioned twins. */
+  async extend(runId, params) {
+    return this.http.post(
+      `/validate/twins/provision/${encodeURIComponent(runId)}/extend`,
+      params
+    );
+  }
+};
+
+// src/resources/scenarios.ts
+var ScenariosResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** Create a new scenario. */
+  async create(params) {
+    return this.http.post("/scenarios", params);
+  }
+  /** List scenarios, optionally filtered by twin or tag. */
+  async list(params) {
+    const query = {};
+    if (params?.twin) query.twin = params.twin;
+    if (params?.tag) query.tag = params.tag;
+    return this.http.get("/scenarios", query);
+  }
+  /** Get a scenario by ID. */
+  async get(scenarioId) {
+    return this.http.get(
+      `/scenarios/${encodeURIComponent(scenarioId)}`
+    );
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://app.argalabs.com";
+var Arga = class {
+  /** Run management: create, get, stream, cancel, and wait for runs. */
+  runs;
+  /** Twin management: list, provision, check status, and extend twins. */
+  twins;
+  /** Scenario management: create, list, and get scenarios. */
+  scenarios;
+  constructor(options) {
+    const http = new HttpClient({
+      baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
+      apiKey: options.apiKey,
+      fetch: options.fetch ?? globalThis.fetch.bind(globalThis)
+    });
+    this.runs = new RunsResource(http);
+    this.twins = new TwinsResource(http);
+    this.scenarios = new ScenariosResource(http);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Arga,
+  ArgaAPIError,
+  ArgaError
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/errors.ts","../src/http.ts","../src/resources/runs.ts","../src/resources/twins.ts","../src/resources/scenarios.ts","../src/client.ts"],"sourcesContent":["export { Arga } from \"./client.js\";\n\nexport { ArgaError, ArgaAPIError } from \"./errors.js\";\n\nexport type {\n  ArgaClientOptions,\n  CreateUrlRunParams,\n  CreatePrRunParams,\n  CreateAgentRunParams,\n  Run,\n  RunDetail,\n  RunEvent,\n  StepSummary,\n  CancelRunResponse,\n  WaitOptions,\n  Twin,\n  ProvisionTwinsParams,\n  ProvisionTwinsResponse,\n  TwinInstance,\n  TwinProvisionStatus,\n  ExtendTwinsParams,\n  ExtendTwinsResponse,\n  CreateScenarioParams,\n  ListScenariosParams,\n  Scenario,\n} from \"./types.js\";\n","/**\n * Base error class for all Arga SDK errors.\n */\nexport class ArgaError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"ArgaError\";\n  }\n}\n\n/**\n * Thrown when the Arga API returns a non-2xx response.\n */\nexport class ArgaAPIError extends ArgaError {\n  /** HTTP status code returned by the API. */\n  readonly statusCode: number;\n  /** Raw Response object from fetch. */\n  readonly response: Response;\n  /** Parsed response body, if available. */\n  readonly body: unknown;\n\n  constructor(\n    message: string,\n    statusCode: number,\n    response: Response,\n    body?: unknown,\n  ) {\n    super(message);\n    this.name = \"ArgaAPIError\";\n    this.statusCode = statusCode;\n    this.response = response;\n    this.body = body;\n  }\n}\n","import { ArgaAPIError, ArgaError } from \"./errors.js\";\n\n// ---------------------------------------------------------------------------\n// Case conversion helpers\n// ---------------------------------------------------------------------------\n\n/** Convert a camelCase string to snake_case. */\nfunction toSnakeCase(str: string): string {\n  return str.replace(/[A-Z]/g, (ch) => `_${ch.toLowerCase()}`);\n}\n\n/** Convert a snake_case string to camelCase. */\nfunction toCamelCase(str: string): string {\n  return str.replace(/_([a-z])/g, (_, ch: string) => ch.toUpperCase());\n}\n\n/** Recursively convert all object keys using the supplied key mapper. */\nfunction convertKeys(\n  obj: unknown,\n  mapper: (key: string) => string,\n): unknown {\n  if (Array.isArray(obj)) {\n    return obj.map((item) => convertKeys(item, mapper));\n  }\n  if (obj !== null && typeof obj === \"object\" && !(obj instanceof Date)) {\n    const result: Record<string, unknown> = {};\n    for (const [key, value] of Object.entries(obj as Record<string, unknown>)) {\n      result[mapper(key)] = convertKeys(value, mapper);\n    }\n    return result;\n  }\n  return obj;\n}\n\n/** Convert all keys in an object tree from camelCase to snake_case. */\nexport function toSnakeCaseKeys(obj: unknown): unknown {\n  return convertKeys(obj, toSnakeCase);\n}\n\n/** Convert all keys in an object tree from snake_case to camelCase. */\nexport function toCamelCaseKeys(obj: unknown): unknown {\n  return convertKeys(obj, toCamelCase);\n}\n\n// ---------------------------------------------------------------------------\n// HTTP client\n// ---------------------------------------------------------------------------\n\nexport interface HttpClientOptions {\n  baseUrl: string;\n  apiKey: string;\n  fetch: typeof globalThis.fetch;\n}\n\nexport class HttpClient {\n  private readonly baseUrl: string;\n  private readonly apiKey: string;\n  private readonly _fetch: typeof globalThis.fetch;\n\n  constructor(opts: HttpClientOptions) {\n    // Strip trailing slash from base URL\n    this.baseUrl = opts.baseUrl.replace(/\\/+$/, \"\");\n    this.apiKey = opts.apiKey;\n    this._fetch = opts.fetch;\n  }\n\n  // ---- public helpers -----------------------------------------------------\n\n  async get<T>(path: string, query?: Record<string, string>): Promise<T> {\n    const url = this.buildUrl(path, query);\n    const res = await this._fetch(url, {\n      method: \"GET\",\n      headers: this.headers(),\n    });\n    return this.handleResponse<T>(res);\n  }\n\n  async post<T>(path: string, body?: unknown): Promise<T> {\n    const url = this.buildUrl(path);\n    const res = await this._fetch(url, {\n      method: \"POST\",\n      headers: this.headers(),\n      body: body !== undefined ? JSON.stringify(toSnakeCaseKeys(body)) : undefined,\n    });\n    return this.handleResponse<T>(res);\n  }\n\n  /**\n   * Perform a GET request and return the raw Response, for SSE streaming.\n   */\n  async getRaw(path: string): Promise<Response> {\n    const url = this.buildUrl(path);\n    const res = await this._fetch(url, {\n      method: \"GET\",\n      headers: {\n        ...this.headers(),\n        Accept: \"text/event-stream\",\n      },\n    });\n    if (!res.ok) {\n      await this.throwApiError(res);\n    }\n    return res;\n  }\n\n  // ---- internals ----------------------------------------------------------\n\n  private buildUrl(path: string, query?: Record<string, string>): string {\n    const url = new URL(`${this.baseUrl}${path}`);\n    if (query) {\n      for (const [k, v] of Object.entries(query)) {\n        if (v !== undefined && v !== \"\") {\n          url.searchParams.set(k, v);\n        }\n      }\n    }\n    return url.toString();\n  }\n\n  private headers(): Record<string, string> {\n    return {\n      Authorization: `Bearer ${this.apiKey}`,\n      \"Content-Type\": \"application/json\",\n    };\n  }\n\n  private async handleResponse<T>(res: Response): Promise<T> {\n    if (!res.ok) {\n      await this.throwApiError(res);\n    }\n    const json = await res.json();\n    return toCamelCaseKeys(json) as T;\n  }\n\n  private async throwApiError(res: Response): Promise<never> {\n    let body: unknown;\n    try {\n      body = await res.json();\n    } catch {\n      body = await res.text().catch(() => null);\n    }\n\n    const detail =\n      body && typeof body === \"object\" && \"detail\" in (body as Record<string, unknown>)\n        ? String((body as Record<string, unknown>).detail)\n        : `HTTP ${res.status}`;\n\n    throw new ArgaAPIError(detail, res.status, res, body);\n  }\n}\n\n// ---------------------------------------------------------------------------\n// SSE parser\n// ---------------------------------------------------------------------------\n\nexport interface SSEEvent {\n  event?: string;\n  data: string;\n}\n\n/**\n * Parse a fetch Response body as a Server-Sent Events stream.\n * Yields individual SSE events as they arrive.\n */\nexport async function* parseSSE(response: Response): AsyncIterable<SSEEvent> {\n  const body = response.body;\n  if (!body) {\n    throw new ArgaError(\"Response body is null — cannot stream SSE\");\n  }\n\n  const reader = body.getReader();\n  const decoder = new TextDecoder();\n  let buffer = \"\";\n  let currentEvent: string | undefined;\n  let currentData: string[] = [];\n\n  try {\n    while (true) {\n      const { done, value } = await reader.read();\n      if (done) break;\n\n      buffer += decoder.decode(value, { stream: true });\n      const lines = buffer.split(\"\\n\");\n      // Keep the last (possibly incomplete) line in the buffer\n      buffer = lines.pop() ?? \"\";\n\n      for (const line of lines) {\n        if (line === \"\") {\n          // Empty line = end of event\n          if (currentData.length > 0) {\n            yield {\n              event: currentEvent,\n              data: currentData.join(\"\\n\"),\n            };\n          }\n          currentEvent = undefined;\n          currentData = [];\n        } else if (line.startsWith(\"event:\")) {\n          currentEvent = line.slice(6).trim();\n        } else if (line.startsWith(\"data:\")) {\n          currentData.push(line.slice(5).trim());\n        }\n        // Ignore comments (lines starting with ':') and unknown fields\n      }\n    }\n\n    // Flush any remaining event\n    if (currentData.length > 0) {\n      yield {\n        event: currentEvent,\n        data: currentData.join(\"\\n\"),\n      };\n    }\n  } finally {\n    reader.releaseLock();\n  }\n}\n","import type { HttpClient } from \"../http.js\";\nimport { parseSSE, toCamelCaseKeys } from \"../http.js\";\nimport { ArgaError } from \"../errors.js\";\nimport type {\n  CancelRunResponse,\n  CreateAgentRunParams,\n  CreatePrRunParams,\n  CreateUrlRunParams,\n  Run,\n  RunDetail,\n  RunEvent,\n  WaitOptions,\n} from \"../types.js\";\n\nconst TERMINAL_STATUSES = new Set([\n  \"completed\",\n  \"failed\",\n  \"cancelled\",\n  \"canceled\",\n  \"error\",\n  \"timed_out\",\n]);\n\nexport class RunsResource {\n  constructor(private readonly http: HttpClient) {}\n\n  /** Create a URL run. */\n  async createUrlRun(params: CreateUrlRunParams): Promise<Run> {\n    return this.http.post<Run>(\"/validate/url-run\", params);\n  }\n\n  /** Create a PR run. */\n  async createPrRun(params: CreatePrRunParams): Promise<Run> {\n    return this.http.post<Run>(\"/validate/pr-run\", params);\n  }\n\n  /** Create an agent (sandbox) run. */\n  async createAgentRun(params: CreateAgentRunParams): Promise<Run> {\n    return this.http.post<Run>(\"/validate/agent-run\", params);\n  }\n\n  /** Get full details of a run by ID. */\n  async get(runId: string): Promise<RunDetail> {\n    return this.http.get<RunDetail>(`/runs/${encodeURIComponent(runId)}`);\n  }\n\n  /**\n   * Stream run results as Server-Sent Events.\n   *\n   * Returns an `AsyncIterable<RunEvent>`. Each yielded event contains an\n   * optional `event` field and a parsed `data` payload.\n   */\n  async *streamResults(runId: string): AsyncIterable<RunEvent> {\n    const response = await this.http.getRaw(\n      `/validate/${encodeURIComponent(runId)}/results`,\n    );\n\n    for await (const sse of parseSSE(response)) {\n      let data: unknown;\n      try {\n        data = toCamelCaseKeys(JSON.parse(sse.data));\n      } catch {\n        data = sse.data;\n      }\n      yield { event: sse.event, data };\n    }\n  }\n\n  /** Cancel a run. */\n  async cancel(runId: string): Promise<CancelRunResponse> {\n    return this.http.post<CancelRunResponse>(\n      `/validate/${encodeURIComponent(runId)}/cancel`,\n    );\n  }\n\n  /**\n   * Poll a run until it reaches a terminal status.\n   *\n   * @param runId  - The run ID to poll.\n   * @param opts   - Optional polling configuration.\n   * @returns The final `RunDetail` once the run has completed (or failed/cancelled).\n   * @throws ArgaError if the timeout is exceeded.\n   */\n  async wait(runId: string, opts?: WaitOptions): Promise<RunDetail> {\n    const pollInterval = opts?.pollInterval ?? 2500;\n    const timeout = opts?.timeout ?? 600_000;\n    const deadline = Date.now() + timeout;\n\n    while (true) {\n      const detail = await this.get(runId);\n      if (TERMINAL_STATUSES.has(detail.status)) {\n        return detail;\n      }\n      if (Date.now() + pollInterval > deadline) {\n        throw new ArgaError(\n          `Timed out waiting for run ${runId} after ${timeout}ms (last status: ${detail.status})`,\n        );\n      }\n      await new Promise((resolve) => setTimeout(resolve, pollInterval));\n    }\n  }\n}\n","import type { HttpClient } from \"../http.js\";\nimport type {\n  ExtendTwinsParams,\n  ExtendTwinsResponse,\n  ProvisionTwinsParams,\n  ProvisionTwinsResponse,\n  Twin,\n  TwinProvisionStatus,\n} from \"../types.js\";\n\nexport class TwinsResource {\n  constructor(private readonly http: HttpClient) {}\n\n  /** List all available twins. */\n  async list(): Promise<Twin[]> {\n    return this.http.get<Twin[]>(\"/validate/twins\");\n  }\n\n  /** Provision a set of twins. */\n  async provision(params: ProvisionTwinsParams): Promise<ProvisionTwinsResponse> {\n    return this.http.post<ProvisionTwinsResponse>(\n      \"/validate/twins/provision\",\n      params,\n    );\n  }\n\n  /** Get the provisioning status of twins for a given run. */\n  async getStatus(runId: string): Promise<TwinProvisionStatus> {\n    return this.http.get<TwinProvisionStatus>(\n      `/validate/twins/provision/${encodeURIComponent(runId)}/status`,\n    );\n  }\n\n  /** Extend the TTL of provisioned twins. */\n  async extend(\n    runId: string,\n    params?: ExtendTwinsParams,\n  ): Promise<ExtendTwinsResponse> {\n    return this.http.post<ExtendTwinsResponse>(\n      `/validate/twins/provision/${encodeURIComponent(runId)}/extend`,\n      params,\n    );\n  }\n}\n","import type { HttpClient } from \"../http.js\";\nimport type {\n  CreateScenarioParams,\n  ListScenariosParams,\n  Scenario,\n} from \"../types.js\";\n\nexport class ScenariosResource {\n  constructor(private readonly http: HttpClient) {}\n\n  /** Create a new scenario. */\n  async create(params: CreateScenarioParams): Promise<Scenario> {\n    return this.http.post<Scenario>(\"/scenarios\", params);\n  }\n\n  /** List scenarios, optionally filtered by twin or tag. */\n  async list(params?: ListScenariosParams): Promise<Scenario[]> {\n    const query: Record<string, string> = {};\n    if (params?.twin) query.twin = params.twin;\n    if (params?.tag) query.tag = params.tag;\n    return this.http.get<Scenario[]>(\"/scenarios\", query);\n  }\n\n  /** Get a scenario by ID. */\n  async get(scenarioId: string): Promise<Scenario> {\n    return this.http.get<Scenario>(\n      `/scenarios/${encodeURIComponent(scenarioId)}`,\n    );\n  }\n}\n","import { HttpClient } from \"./http.js\";\nimport { RunsResource } from \"./resources/runs.js\";\nimport { TwinsResource } from \"./resources/twins.js\";\nimport { ScenariosResource } from \"./resources/scenarios.js\";\nimport type { ArgaClientOptions } from \"./types.js\";\n\nconst DEFAULT_BASE_URL = \"https://app.argalabs.com\";\n\n/**\n * Main client for the Arga API.\n *\n * ```ts\n * import { Arga } from 'arga-sdk';\n *\n * const client = new Arga({ apiKey: 'arga_...' });\n * const run = await client.runs.createUrlRun({ url: 'https://staging.myapp.com' });\n * ```\n */\nexport class Arga {\n  /** Run management: create, get, stream, cancel, and wait for runs. */\n  readonly runs: RunsResource;\n  /** Twin management: list, provision, check status, and extend twins. */\n  readonly twins: TwinsResource;\n  /** Scenario management: create, list, and get scenarios. */\n  readonly scenarios: ScenariosResource;\n\n  constructor(options: ArgaClientOptions) {\n    const http = new HttpClient({\n      baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,\n      apiKey: options.apiKey,\n      fetch: options.fetch ?? globalThis.fetch.bind(globalThis),\n    });\n\n    this.runs = new RunsResource(http);\n    this.twins = new TwinsResource(http);\n    this.scenarios = new ScenariosResource(http);\n  }\n}\n"],"mappings":"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","names":[]}