arga-sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,259 @@
+interface HttpClientOptions {
+    baseUrl: string;
+    apiKey: string;
+    fetch: typeof globalThis.fetch;
+}
+declare class HttpClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly _fetch;
+    constructor(opts: HttpClientOptions);
+    get<T>(path: string, query?: Record<string, string>): Promise<T>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+    /**
+     * Perform a GET request and return the raw Response, for SSE streaming.
+     */
+    getRaw(path: string): Promise<Response>;
+    private buildUrl;
+    private headers;
+    private handleResponse;
+    private throwApiError;
+}
+
+interface ArgaClientOptions {
+    /** Arga API key (starts with `arga_`). */
+    apiKey: string;
+    /** Base URL for the Arga API. Default: `https://app.argalabs.com` */
+    baseUrl?: string;
+    /** Custom fetch implementation. Default: global `fetch`. */
+    fetch?: typeof globalThis.fetch;
+}
+interface CreateUrlRunParams {
+    url: string;
+    prompt?: string;
+    twins?: string[];
+    credentials?: {
+        email?: string;
+        password?: string;
+    };
+    runnerMode?: string;
+    sessionId?: string;
+}
+interface CreatePrRunParams {
+    repo: string;
+    branch?: string;
+    prUrl?: string;
+    contextNotes?: string;
+    scenarioPrompt?: string;
+    twins?: string[];
+    frontendUrl?: string;
+    sessionId?: string;
+}
+interface CreateAgentRunParams {
+    url?: string;
+    repo?: string;
+    branch?: string;
+    credentials?: Record<string, unknown>[];
+    focus?: string;
+    actionBudget?: number;
+    runnerMode?: string;
+}
+interface Run {
+    runId: string;
+    status: string;
+    sessionId?: string;
+}
+interface StepSummary {
+    step: string;
+    status: string;
+    detail?: string;
+}
+interface RunDetail {
+    id: string;
+    status: string;
+    runType?: string;
+    mode?: string;
+    environmentUrl?: string;
+    surfaceUrls?: string[];
+    twins?: string[];
+    resultsJson?: unknown;
+    eventLogJson?: unknown;
+    storyJson?: unknown;
+    attackPlanJson?: unknown;
+    redteamReportJson?: unknown;
+    stepSummaries?: StepSummary[];
+    failureCategory?: string;
+    failureDetail?: string;
+    createdAt?: string;
+    [key: string]: unknown;
+}
+interface RunEvent {
+    event?: string;
+    data: unknown;
+}
+interface CancelRunResponse {
+    status: string;
+}
+interface WaitOptions {
+    /** Polling interval in milliseconds. Default: 2500. */
+    pollInterval?: number;
+    /** Maximum wait time in milliseconds. Default: 600000 (10 min). */
+    timeout?: number;
+}
+interface Twin {
+    name: string;
+    label: string;
+    kind: string;
+    showInUi: boolean;
+}
+interface ProvisionTwinsParams {
+    twins: string[];
+    ttlMinutes?: number;
+    scenarioId?: string;
+}
+interface ProvisionTwinsResponse {
+    runId: string;
+}
+interface TwinInstance {
+    name: string;
+    label: string;
+    baseUrl: string;
+    adminUrl: string;
+    envVars: Record<string, string>;
+    showInUi: boolean;
+}
+interface TwinProvisionStatus {
+    runId: string;
+    status: string;
+    twins: Record<string, TwinInstance>;
+    dashboardUrl?: string;
+    expiresAt?: string;
+    proxyToken?: string;
+    error?: string;
+}
+interface ExtendTwinsParams {
+    ttlMinutes?: number;
+}
+interface ExtendTwinsResponse {
+    status: string;
+    ttlMinutes: number;
+}
+interface CreateScenarioParams {
+    name: string;
+    prompt?: string;
+    seedConfig?: Record<string, unknown>;
+    twins?: string[];
+    description?: string;
+    tags?: string[];
+}
+interface ListScenariosParams {
+    twin?: string;
+    tag?: string;
+}
+interface Scenario {
+    id: string;
+    name: string;
+    description?: string;
+    prompt?: string;
+    twins?: string[];
+    seedConfig?: Record<string, unknown>;
+    tags?: string[];
+    createdAt?: string;
+    updatedAt?: string;
+}
+
+declare class RunsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Create a URL run. */
+    createUrlRun(params: CreateUrlRunParams): Promise<Run>;
+    /** Create a PR run. */
+    createPrRun(params: CreatePrRunParams): Promise<Run>;
+    /** Create an agent (sandbox) run. */
+    createAgentRun(params: CreateAgentRunParams): Promise<Run>;
+    /** Get full details of a run by ID. */
+    get(runId: string): Promise<RunDetail>;
+    /**
+     * Stream run results as Server-Sent Events.
+     *
+     * Returns an `AsyncIterable<RunEvent>`. Each yielded event contains an
+     * optional `event` field and a parsed `data` payload.
+     */
+    streamResults(runId: string): AsyncIterable<RunEvent>;
+    /** Cancel a run. */
+    cancel(runId: string): Promise<CancelRunResponse>;
+    /**
+     * 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.
+     */
+    wait(runId: string, opts?: WaitOptions): Promise<RunDetail>;
+}
+
+declare class TwinsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** List all available twins. */
+    list(): Promise<Twin[]>;
+    /** Provision a set of twins. */
+    provision(params: ProvisionTwinsParams): Promise<ProvisionTwinsResponse>;
+    /** Get the provisioning status of twins for a given run. */
+    getStatus(runId: string): Promise<TwinProvisionStatus>;
+    /** Extend the TTL of provisioned twins. */
+    extend(runId: string, params?: ExtendTwinsParams): Promise<ExtendTwinsResponse>;
+}
+
+declare class ScenariosResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Create a new scenario. */
+    create(params: CreateScenarioParams): Promise<Scenario>;
+    /** List scenarios, optionally filtered by twin or tag. */
+    list(params?: ListScenariosParams): Promise<Scenario[]>;
+    /** Get a scenario by ID. */
+    get(scenarioId: string): Promise<Scenario>;
+}
+
+/**
+ * Main client for the Arga API.
+ *
+ * ```ts
+ * import { Arga } from 'arga-sdk';
+ *
+ * const client = new Arga({ apiKey: 'arga_...' });
+ * const run = await client.runs.createUrlRun({ url: 'https://staging.myapp.com' });
+ * ```
+ */
+declare class Arga {
+    /** Run management: create, get, stream, cancel, and wait for runs. */
+    readonly runs: RunsResource;
+    /** Twin management: list, provision, check status, and extend twins. */
+    readonly twins: TwinsResource;
+    /** Scenario management: create, list, and get scenarios. */
+    readonly scenarios: ScenariosResource;
+    constructor(options: ArgaClientOptions);
+}
+
+/**
+ * Base error class for all Arga SDK errors.
+ */
+declare class ArgaError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when the Arga API returns a non-2xx response.
+ */
+declare class ArgaAPIError extends ArgaError {
+    /** HTTP status code returned by the API. */
+    readonly statusCode: number;
+    /** Raw Response object from fetch. */
+    readonly response: Response;
+    /** Parsed response body, if available. */
+    readonly body: unknown;
+    constructor(message: string, statusCode: number, response: Response, body?: unknown);
+}
+
+export { Arga, ArgaAPIError, type ArgaClientOptions, ArgaError, type CancelRunResponse, type CreateAgentRunParams, type CreatePrRunParams, type CreateScenarioParams, type CreateUrlRunParams, type ExtendTwinsParams, type ExtendTwinsResponse, type ListScenariosParams, type ProvisionTwinsParams, type ProvisionTwinsResponse, type Run, type RunDetail, type RunEvent, type Scenario, type StepSummary, type Twin, type TwinInstance, type TwinProvisionStatus, type WaitOptions };

package/dist/index.d.ts

@@ -0,0 +1,259 @@
+interface HttpClientOptions {
+    baseUrl: string;
+    apiKey: string;
+    fetch: typeof globalThis.fetch;
+}
+declare class HttpClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly _fetch;
+    constructor(opts: HttpClientOptions);
+    get<T>(path: string, query?: Record<string, string>): Promise<T>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+    /**
+     * Perform a GET request and return the raw Response, for SSE streaming.
+     */
+    getRaw(path: string): Promise<Response>;
+    private buildUrl;
+    private headers;
+    private handleResponse;
+    private throwApiError;
+}
+
+interface ArgaClientOptions {
+    /** Arga API key (starts with `arga_`). */
+    apiKey: string;
+    /** Base URL for the Arga API. Default: `https://app.argalabs.com` */
+    baseUrl?: string;
+    /** Custom fetch implementation. Default: global `fetch`. */
+    fetch?: typeof globalThis.fetch;
+}
+interface CreateUrlRunParams {
+    url: string;
+    prompt?: string;
+    twins?: string[];
+    credentials?: {
+        email?: string;
+        password?: string;
+    };
+    runnerMode?: string;
+    sessionId?: string;
+}
+interface CreatePrRunParams {
+    repo: string;
+    branch?: string;
+    prUrl?: string;
+    contextNotes?: string;
+    scenarioPrompt?: string;
+    twins?: string[];
+    frontendUrl?: string;
+    sessionId?: string;
+}
+interface CreateAgentRunParams {
+    url?: string;
+    repo?: string;
+    branch?: string;
+    credentials?: Record<string, unknown>[];
+    focus?: string;
+    actionBudget?: number;
+    runnerMode?: string;
+}
+interface Run {
+    runId: string;
+    status: string;
+    sessionId?: string;
+}
+interface StepSummary {
+    step: string;
+    status: string;
+    detail?: string;
+}
+interface RunDetail {
+    id: string;
+    status: string;
+    runType?: string;
+    mode?: string;
+    environmentUrl?: string;
+    surfaceUrls?: string[];
+    twins?: string[];
+    resultsJson?: unknown;
+    eventLogJson?: unknown;
+    storyJson?: unknown;
+    attackPlanJson?: unknown;
+    redteamReportJson?: unknown;
+    stepSummaries?: StepSummary[];
+    failureCategory?: string;
+    failureDetail?: string;
+    createdAt?: string;
+    [key: string]: unknown;
+}
+interface RunEvent {
+    event?: string;
+    data: unknown;
+}
+interface CancelRunResponse {
+    status: string;
+}
+interface WaitOptions {
+    /** Polling interval in milliseconds. Default: 2500. */
+    pollInterval?: number;
+    /** Maximum wait time in milliseconds. Default: 600000 (10 min). */
+    timeout?: number;
+}
+interface Twin {
+    name: string;
+    label: string;
+    kind: string;
+    showInUi: boolean;
+}
+interface ProvisionTwinsParams {
+    twins: string[];
+    ttlMinutes?: number;
+    scenarioId?: string;
+}
+interface ProvisionTwinsResponse {
+    runId: string;
+}
+interface TwinInstance {
+    name: string;
+    label: string;
+    baseUrl: string;
+    adminUrl: string;
+    envVars: Record<string, string>;
+    showInUi: boolean;
+}
+interface TwinProvisionStatus {
+    runId: string;
+    status: string;
+    twins: Record<string, TwinInstance>;
+    dashboardUrl?: string;
+    expiresAt?: string;
+    proxyToken?: string;
+    error?: string;
+}
+interface ExtendTwinsParams {
+    ttlMinutes?: number;
+}
+interface ExtendTwinsResponse {
+    status: string;
+    ttlMinutes: number;
+}
+interface CreateScenarioParams {
+    name: string;
+    prompt?: string;
+    seedConfig?: Record<string, unknown>;
+    twins?: string[];
+    description?: string;
+    tags?: string[];
+}
+interface ListScenariosParams {
+    twin?: string;
+    tag?: string;
+}
+interface Scenario {
+    id: string;
+    name: string;
+    description?: string;
+    prompt?: string;
+    twins?: string[];
+    seedConfig?: Record<string, unknown>;
+    tags?: string[];
+    createdAt?: string;
+    updatedAt?: string;
+}
+
+declare class RunsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Create a URL run. */
+    createUrlRun(params: CreateUrlRunParams): Promise<Run>;
+    /** Create a PR run. */
+    createPrRun(params: CreatePrRunParams): Promise<Run>;
+    /** Create an agent (sandbox) run. */
+    createAgentRun(params: CreateAgentRunParams): Promise<Run>;
+    /** Get full details of a run by ID. */
+    get(runId: string): Promise<RunDetail>;
+    /**
+     * Stream run results as Server-Sent Events.
+     *
+     * Returns an `AsyncIterable<RunEvent>`. Each yielded event contains an
+     * optional `event` field and a parsed `data` payload.
+     */
+    streamResults(runId: string): AsyncIterable<RunEvent>;
+    /** Cancel a run. */
+    cancel(runId: string): Promise<CancelRunResponse>;
+    /**
+     * 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.
+     */
+    wait(runId: string, opts?: WaitOptions): Promise<RunDetail>;
+}
+
+declare class TwinsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** List all available twins. */
+    list(): Promise<Twin[]>;
+    /** Provision a set of twins. */
+    provision(params: ProvisionTwinsParams): Promise<ProvisionTwinsResponse>;
+    /** Get the provisioning status of twins for a given run. */
+    getStatus(runId: string): Promise<TwinProvisionStatus>;
+    /** Extend the TTL of provisioned twins. */
+    extend(runId: string, params?: ExtendTwinsParams): Promise<ExtendTwinsResponse>;
+}
+
+declare class ScenariosResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Create a new scenario. */
+    create(params: CreateScenarioParams): Promise<Scenario>;
+    /** List scenarios, optionally filtered by twin or tag. */
+    list(params?: ListScenariosParams): Promise<Scenario[]>;
+    /** Get a scenario by ID. */
+    get(scenarioId: string): Promise<Scenario>;
+}
+
+/**
+ * Main client for the Arga API.
+ *
+ * ```ts
+ * import { Arga } from 'arga-sdk';
+ *
+ * const client = new Arga({ apiKey: 'arga_...' });
+ * const run = await client.runs.createUrlRun({ url: 'https://staging.myapp.com' });
+ * ```
+ */
+declare class Arga {
+    /** Run management: create, get, stream, cancel, and wait for runs. */
+    readonly runs: RunsResource;
+    /** Twin management: list, provision, check status, and extend twins. */
+    readonly twins: TwinsResource;
+    /** Scenario management: create, list, and get scenarios. */
+    readonly scenarios: ScenariosResource;
+    constructor(options: ArgaClientOptions);
+}
+
+/**
+ * Base error class for all Arga SDK errors.
+ */
+declare class ArgaError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when the Arga API returns a non-2xx response.
+ */
+declare class ArgaAPIError extends ArgaError {
+    /** HTTP status code returned by the API. */
+    readonly statusCode: number;
+    /** Raw Response object from fetch. */
+    readonly response: Response;
+    /** Parsed response body, if available. */
+    readonly body: unknown;
+    constructor(message: string, statusCode: number, response: Response, body?: unknown);
+}
+
+export { Arga, ArgaAPIError, type ArgaClientOptions, ArgaError, type CancelRunResponse, type CreateAgentRunParams, type CreatePrRunParams, type CreateScenarioParams, type CreateUrlRunParams, type ExtendTwinsParams, type ExtendTwinsResponse, type ListScenariosParams, type ProvisionTwinsParams, type ProvisionTwinsResponse, type Run, type RunDetail, type RunEvent, type Scenario, type StepSummary, type Twin, type TwinInstance, type TwinProvisionStatus, type WaitOptions };