@cybernetyx1/atlasflow-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,18 @@
+PROPRIETARY SOFTWARE LICENSE
+
+Copyright (c) 2026 Cybernetyx. All rights reserved.
+
+This software and its source code are the proprietary and confidential property
+of the copyright holder. The software is original work authored independently.
+
+No part of this software may be copied, reproduced, modified, published,
+distributed, sublicensed, or sold in any form or by any means without the prior
+written permission of the copyright holder, except as expressly permitted by a
+separate written agreement.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE COPYRIGHT
+HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,45 @@
+# @cybernetyx1/atlasflow-sdk
+
+Typed HTTP client SDK for AtlasFlow agent servers — prompt agents, dispatch durable runs, stream events, and work with public streams.
+
+## Install
+
+```sh
+pnpm add @cybernetyx1/atlasflow-sdk
+```
+
+Part of the AtlasFlow monorepo. Proprietary.
+
+## Usage
+
+`createAtlasFlowClient(options)` builds a client grouped into `agents`, `runs`, `workflows`, and `streams`.
+
+```ts
+import { createAtlasFlowClient } from "@cybernetyx1/atlasflow-sdk";
+
+const client = createAtlasFlowClient({
+  baseUrl: "https://agent.example",
+  apiKey: process.env.ATLASFLOW_API_KEY, // server-side only
+});
+
+// Interactive prompt.
+const reply = await client.agents.prompt("hello", "user-123", { message: "hi" });
+console.log(reply.text);
+
+// Durable run, then wait for completion.
+const admission = await client.runs.dispatch("hello", { message: "do work" });
+const record = await client.runs.wait(admission.runId);
+```
+
+```ts
+// Stream run events as they happen.
+for await (const event of client.agents.stream("hello", "user-123", { message: "hi" })) {
+  console.log(event.type);
+}
+```
+
+Browser code must not use `ATLASFLOW_API_KEY`; mint a short-lived scoped token on your server and pass it as `apiKey`. Also exported: the `AtlasFlowError` class, the `AtlasFlowClient` type, and the request/response types (`AgentResult`, `RunRecord`, `RunWatchOptions`, stream option types, etc.).
+
+## License
+
+Proprietary. © 2026 Cybernetyx. See LICENSE.

package/dist/index.d.ts

@@ -0,0 +1,304 @@
+/**
+ * @cybernetyx1/atlasflow-sdk — typed HTTP client for invoking deployed AtlasFlow agents.
+ *
+ * Dependency-free: uses the global `fetch`. Construct once with a base URL,
+ * then call agents / workflows / runs / admin.
+ */
+interface Usage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    totalTokens: number;
+    costTotal: number;
+}
+interface AgentResult {
+    ok: boolean;
+    runId: string;
+    /** The agent's final text reply. */
+    data: string;
+    /** Structured result, when the agent declared a result schema. */
+    result?: unknown;
+    usage: Usage;
+}
+interface AgentImageInput {
+    /** Base64 image bytes, or a data:image/...;base64,... URL. */
+    data: string;
+    /** Required unless `data` is a data URL that contains the MIME type. */
+    mimeType?: string;
+}
+interface AgentPromptInput {
+    message: string;
+    payload?: unknown;
+    images?: AgentImageInput[];
+    /** Abort an in-flight streaming request, useful for browser UI stop buttons. */
+    signal?: AbortSignal;
+}
+interface AgentDispatchInput {
+    message?: string;
+    payload?: unknown;
+    images?: AgentImageInput[];
+}
+interface RunAdmission {
+    runId: string;
+    status: string;
+    /** Public event-stream URL owned by the server. */
+    streamUrl?: string;
+    /** Opaque offset to use for the first event read. */
+    offset?: string;
+}
+interface RunRecord {
+    runId: string;
+    agent: string;
+    instanceId: string;
+    status: "queued" | "running" | "waiting_approval" | "success" | "failed" | "interrupted";
+    result?: unknown;
+    error?: {
+        code: string;
+        message: string;
+    };
+    startedAt: number;
+    endedAt?: number;
+}
+interface AtlasEventLike {
+    type: string;
+    /** Opaque resume offset from the public event stream. */
+    offset?: string;
+    [key: string]: unknown;
+}
+interface RunEventsOptions {
+    /** Legacy numeric cursor; returns events with index greater than this value. */
+    after?: number;
+    /** Opaque cursor returned as event.offset / response.nextOffset. Use "-1", "now", or a prior offset. */
+    offset?: string;
+    /** Limit the number of events returned in one catch-up read. */
+    limit?: number;
+    /** On offset "-1", return only the most recent N events. */
+    tail?: number;
+    follow?: boolean;
+    signal?: AbortSignal;
+}
+interface RunWatchOptions extends Omit<RunEventsOptions, "follow"> {
+    /**
+     * Reconnect the live SSE leg after transient stream failures. Catch-up JSON
+     * reads still run before every live follow attempt, so delivered offsets are
+     * reconciled against durable history.
+     */
+    reconnect?: boolean | {
+        attempts?: number;
+        delayMs?: number;
+    };
+}
+interface RunEventsResult {
+    items: AtlasEventLike[];
+    nextOffset: string;
+    upToDate: boolean;
+    closed: boolean;
+}
+interface StreamMeta {
+    exists: boolean;
+    contentType?: string;
+    offset?: string;
+    cursor?: string;
+    streamClosed?: boolean;
+    ttlSeconds?: number;
+    expiresAt?: string;
+    etag?: string;
+}
+interface StreamWriteOptions {
+    contentType?: string;
+    body?: string | Uint8Array;
+    closed?: boolean;
+    ttlSeconds?: number;
+    expiresAt?: string;
+    /** Source stream path or /streams/* URL for Durable Streams fork creation. */
+    forkedFrom?: string;
+    /** Optional Durable Streams fork offset. Defaults to the source tail. */
+    forkOffset?: string;
+}
+interface StreamAppendOptions {
+    contentType?: string;
+    close?: boolean;
+    /** Optional Durable Streams writer coordination sequence, sent as Stream-Seq. */
+    seq?: string;
+}
+interface StreamReadOptions {
+    offset?: string;
+    cursor?: string;
+    live?: false | "long-poll";
+    timeoutMs?: number;
+}
+interface StreamJsonResult<T = unknown> {
+    items: T[];
+    nextOffset: string;
+    cursor?: string;
+    upToDate: boolean;
+    closed: boolean;
+}
+interface StreamSubscriptionCreateOptions {
+    type?: "pull-wake" | "webhook";
+    streams?: string[];
+    pattern?: string;
+    wakeStream?: string;
+    leaseTtlMs?: number;
+    webhookUrl?: string;
+    url?: string;
+    headers?: Record<string, string>;
+    description?: string;
+}
+interface StreamSubscriptionLink {
+    path: string;
+    linkType: "explicit" | "glob";
+    ackedOffset: string;
+}
+interface StreamSubscriptionInfo {
+    id: string;
+    subscriptionId: string;
+    type: "pull-wake" | "webhook";
+    pattern?: string;
+    streams: StreamSubscriptionLink[];
+    wakeStream?: string;
+    leaseTtlMs?: number;
+    webhookUrl?: string;
+    webhookLastSuccessAt?: string;
+    webhookLastError?: string;
+    createdAt: string;
+    status: string;
+    description?: string;
+}
+interface StreamSubscriptionStreamInfo extends StreamSubscriptionLink {
+    tailOffset: string;
+    hasPending: boolean;
+}
+interface StreamSubscriptionClaim {
+    wakeId: string;
+    generation: number;
+    token: string;
+    streams: StreamSubscriptionStreamInfo[];
+    leaseTtlMs: number;
+}
+interface StreamSubscriptionAckOptions {
+    wakeId: string;
+    generation: number;
+    acks?: Array<{
+        stream?: string;
+        path?: string;
+        offset: string;
+    }>;
+    done?: boolean;
+}
+interface ClientOptions {
+    baseUrl: string;
+    /**
+     * Bearer token for servers protected by requireApiKey().
+     * Server-side code may use ATLASFLOW_API_KEY. Browser code must use a
+     * short-lived scoped token minted by trusted server code with mintScopedToken().
+     */
+    apiKey?: string;
+    headers?: Record<string, string>;
+    fetch?: typeof fetch;
+}
+declare class AtlasFlowError extends Error {
+    status: number;
+    code: string;
+    constructor(status: number, code: string, message: string);
+}
+declare function createAtlasFlowClient(options: ClientOptions): {
+    agents: {
+        /** Invoke an agent instance and await the full result. */
+        prompt(name: string, id: string, input: AgentPromptInput): Promise<AgentResult>;
+        /** Alias for prompt(), matching the send-style naming used by streaming agent clients. */
+        send(name: string, id: string, input: AgentPromptInput): Promise<AgentResult>;
+        /** Fire-and-forget: dispatch the agent in the background, get a runId now. */
+        dispatch(name: string, id: string, input?: AgentDispatchInput): Promise<RunAdmission>;
+        /** Stream events live as the agent works (Server-Sent Events). */
+        stream(name: string, id: string, input: AgentPromptInput): AsyncGenerator<AtlasEventLike>;
+    };
+    /** @deprecated Use `runs.dispatch` / `runs.dispatchAndWait` (same endpoints). */
+    workflows: {
+        /** Dispatch a durable workflow run; returns immediately with a runId. */
+        invoke(name: string, input?: {
+            payload?: unknown;
+            message?: string;
+        }): Promise<RunAdmission>;
+        /** Dispatch and block until the run finishes, returning its result. */
+        invokeAndWait(name: string, input?: {
+            payload?: unknown;
+            message?: string;
+        }): Promise<AgentResult>;
+    };
+    runs: {
+        /** Dispatch a durable run — an agent or an authored workflow — by name. */
+        dispatch(name: string, input?: AgentDispatchInput): Promise<RunAdmission & {
+            gate?: {
+                id: string;
+                title: string;
+            };
+        }>;
+        /** Dispatch an agent run and block until it finishes. */
+        dispatchAndWait(name: string, input?: AgentDispatchInput): Promise<AgentResult>;
+        /** Decide the gate a workflow run is parked at (approve resumes it). */
+        approve(runId: string, decision: {
+            approved: boolean;
+            gate?: string;
+            note?: string;
+        }): Promise<{
+            runId: string;
+            status: string;
+            gate?: {
+                id: string;
+                title: string;
+            };
+            data?: string;
+        }>;
+        get(runId: string): Promise<RunRecord>;
+        /** Poll until the run reaches a terminal status (success/failed/interrupted). */
+        wait(runId: string, opts?: {
+            intervalMs?: number;
+            timeoutMs?: number;
+        }): Promise<RunRecord>;
+        events(runId: string, opts?: Omit<RunEventsOptions, "follow" | "signal">): Promise<AtlasEventLike[]>;
+        eventPage(runId: string, opts?: Omit<RunEventsOptions, "follow" | "signal">): Promise<RunEventsResult>;
+        /** Stream persisted run events by run id. Reconnect with opts.after = last seen event index. */
+        stream(runId: string, opts?: RunEventsOptions): AsyncGenerator<AtlasEventLike>;
+        /**
+         * Reconciled durable event stream. Starts from a run id or dispatch
+         * admission, reads persisted pages until caught up, follows live SSE, then
+         * re-checks persisted history when the live stream closes or reconnects.
+         */
+        watch(target: string | RunAdmission, opts?: RunWatchOptions): AsyncGenerator<AtlasEventLike>;
+        list(opts?: {
+            limit?: number;
+        }): Promise<RunRecord[]>;
+    };
+    streams: {
+        url(path: string): string;
+        head(path: string): Promise<StreamMeta>;
+        create(path: string, opts?: StreamWriteOptions): Promise<StreamMeta>;
+        append(path: string, body: string | Uint8Array, opts?: StreamAppendOptions): Promise<StreamMeta>;
+        close(path: string): Promise<StreamMeta>;
+        delete(path: string): Promise<void>;
+        readJson<T = unknown>(path: string, opts?: StreamReadOptions): Promise<StreamJsonResult<T>>;
+        subscriptions: {
+            create(id: string, opts: StreamSubscriptionCreateOptions): Promise<StreamSubscriptionInfo>;
+            get(id: string): Promise<StreamSubscriptionInfo>;
+            delete(id: string): Promise<void>;
+            addStreams(id: string, streams: string[]): Promise<void>;
+            removeStream(id: string, path: string): Promise<void>;
+            claim(id: string, worker: string): Promise<StreamSubscriptionClaim>;
+            ack(id: string, token: string, opts: StreamSubscriptionAckOptions): Promise<{
+                ok: true;
+                nextWake: boolean;
+            }>;
+            release(id: string, token: string, opts: Pick<StreamSubscriptionAckOptions, "wakeId" | "generation">): Promise<void>;
+        };
+    };
+    admin: {
+        agents(): Promise<{
+            name: string;
+        }[]>;
+    };
+};
+type AtlasFlowClient = ReturnType<typeof createAtlasFlowClient>;
+
+export { type AgentDispatchInput, type AgentImageInput, type AgentPromptInput, type AgentResult, type AtlasEventLike, type AtlasFlowClient, AtlasFlowError, type ClientOptions, type RunAdmission, type RunEventsOptions, type RunEventsResult, type RunRecord, type RunWatchOptions, type StreamAppendOptions, type StreamJsonResult, type StreamMeta, type StreamReadOptions, type StreamSubscriptionAckOptions, type StreamSubscriptionClaim, type StreamSubscriptionCreateOptions, type StreamSubscriptionInfo, type StreamSubscriptionLink, type StreamSubscriptionStreamInfo, type StreamWriteOptions, type Usage, createAtlasFlowClient };

package/dist/index.js

@@ -0,0 +1,549 @@
+// src/index.ts
+var AtlasFlowError = class extends Error {
+  constructor(status, code, message) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.name = "AtlasFlowError";
+  }
+  status;
+  code;
+};
+function createAtlasFlowClient(options) {
+  const base = options.baseUrl.replace(/\/$/, "");
+  const doFetch = options.fetch ?? fetch;
+  const headers = {
+    "content-type": "application/json",
+    ...options.apiKey ? { authorization: `Bearer ${options.apiKey}` } : {},
+    ...options.headers
+  };
+  async function post(path, body) {
+    const res = await doFetch(`${base}${path}`, { method: "POST", headers, body: JSON.stringify(body) });
+    const json = await res.json();
+    if (!res.ok || json.error) {
+      throw new AtlasFlowError(res.status, json.error?.code ?? "request_failed", json.error?.message ?? res.statusText);
+    }
+    return json;
+  }
+  async function get(path) {
+    const res = await doFetch(`${base}${path}`, { headers });
+    if (!res.ok) throw new AtlasFlowError(res.status, "request_failed", res.statusText);
+    return await res.json();
+  }
+  async function getEventPageUrl(url, opts = {}) {
+    const res = await doFetch(withEventQuery(url, opts), { headers });
+    if (!res.ok) throw await atlasErrorFromResponse(res);
+    return await res.json();
+  }
+  async function* streamEventUrl(url, opts = {}) {
+    const res = await doFetch(withEventQuery(url, opts), {
+      headers: { ...headers, accept: "text/event-stream" },
+      signal: opts.signal
+    });
+    if (!res.ok) throw await atlasErrorFromResponse(res);
+    if (!res.body) throw new AtlasFlowError(res.status, "no_stream", "response has no body");
+    yield* parseSSE(res.body);
+  }
+  return {
+    agents: {
+      /** Invoke an agent instance and await the full result. */
+      prompt(name, id, input) {
+        return post(`/agents/${encodeURIComponent(name)}/${encodeURIComponent(id)}`, agentRequestBody(input));
+      },
+      /** Alias for prompt(), matching the send-style naming used by streaming agent clients. */
+      send(name, id, input) {
+        return post(`/agents/${encodeURIComponent(name)}/${encodeURIComponent(id)}`, agentRequestBody(input));
+      },
+      /** Fire-and-forget: dispatch the agent in the background, get a runId now. */
+      async dispatch(name, id, input = {}) {
+        const res = await doFetch(`${base}/agents/${encodeURIComponent(name)}/${encodeURIComponent(id)}`, {
+          method: "POST",
+          headers: { ...headers, "x-webhook": "true" },
+          body: JSON.stringify(agentRequestBody(input))
+        });
+        const json = await res.json();
+        if (!res.ok || json.error) throw new AtlasFlowError(res.status, json.error?.code ?? "request_failed", json.error?.message ?? res.statusText);
+        return json;
+      },
+      /** Stream events live as the agent works (Server-Sent Events). */
+      async *stream(name, id, input) {
+        const res = await doFetch(`${base}/agents/${encodeURIComponent(name)}/${encodeURIComponent(id)}`, {
+          method: "POST",
+          headers: { ...headers, accept: "text/event-stream" },
+          body: JSON.stringify(agentRequestBody(input)),
+          signal: input.signal
+        });
+        if (!res.ok) {
+          let error;
+          try {
+            error = (await res.json()).error;
+          } catch {
+          }
+          throw new AtlasFlowError(res.status, error?.code ?? "request_failed", error?.message ?? res.statusText);
+        }
+        if (!res.body) throw new AtlasFlowError(res.status, "no_stream", "response has no body");
+        yield* parseSSE(res.body);
+      }
+    },
+    /** @deprecated Use `runs.dispatch` / `runs.dispatchAndWait` (same endpoints). */
+    workflows: {
+      /** Dispatch a durable workflow run; returns immediately with a runId. */
+      invoke(name, input = {}) {
+        return post(`/workflows/${encodeURIComponent(name)}`, input);
+      },
+      /** Dispatch and block until the run finishes, returning its result. */
+      invokeAndWait(name, input = {}) {
+        return post(`/workflows/${encodeURIComponent(name)}`, { ...input, wait: true });
+      }
+    },
+    runs: {
+      /** Dispatch a durable run — an agent or an authored workflow — by name. */
+      dispatch(name, input = {}) {
+        return post(`/runs/${encodeURIComponent(name)}`, agentRequestBody(input));
+      },
+      /** Dispatch an agent run and block until it finishes. */
+      dispatchAndWait(name, input = {}) {
+        return post(`/runs/${encodeURIComponent(name)}`, { ...agentRequestBody(input), wait: true });
+      },
+      /** Decide the gate a workflow run is parked at (approve resumes it). */
+      approve(runId, decision) {
+        return post(`/runs/${encodeURIComponent(runId)}/approve`, decision);
+      },
+      get(runId) {
+        return get(`/runs/${encodeURIComponent(runId)}?meta`);
+      },
+      /** Poll until the run reaches a terminal status (success/failed/interrupted). */
+      async wait(runId, opts = {}) {
+        const interval = opts.intervalMs ?? 250;
+        const deadline = Date.now() + (opts.timeoutMs ?? 12e4);
+        for (; ; ) {
+          const run = await get(`/runs/${encodeURIComponent(runId)}?meta`);
+          if (run.status !== "queued" && run.status !== "running") return run;
+          if (Date.now() > deadline) throw new AtlasFlowError(408, "timeout", `run ${runId} did not finish in time`);
+          await new Promise((r) => setTimeout(r, interval));
+        }
+      },
+      async events(runId, opts = {}) {
+        return (await get(`/runs/${encodeURIComponent(runId)}/events${eventQuery(opts)}`)).items;
+      },
+      async eventPage(runId, opts = {}) {
+        return get(`/runs/${encodeURIComponent(runId)}/events${eventQuery(opts)}`);
+      },
+      /** Stream persisted run events by run id. Reconnect with opts.after = last seen event index. */
+      async *stream(runId, opts = {}) {
+        yield* streamEventUrl(runEventUrl(base, runId), opts);
+      },
+      /**
+       * Reconciled durable event stream. Starts from a run id or dispatch
+       * admission, reads persisted pages until caught up, follows live SSE, then
+       * re-checks persisted history when the live stream closes or reconnects.
+       */
+      async *watch(target, opts = {}) {
+        const source = runWatchSource(base, target);
+        let offset = opts.offset ?? (opts.after !== void 0 ? String(opts.after) : source.offset);
+        const limit = opts.limit ?? 1e3;
+        const reconnect = normalizeReconnect(opts.reconnect);
+        let failures = 0;
+        for (; ; ) {
+          for (; ; ) {
+            const page = await getEventPageUrl(source.streamUrl, { offset, limit, tail: opts.tail });
+            for (const event of page.items) {
+              offset = eventResumeOffset(event, page.nextOffset);
+              yield event;
+            }
+            if (page.closed && page.upToDate) return;
+            if (page.upToDate) break;
+            offset = page.nextOffset;
+          }
+          try {
+            for await (const event of streamEventUrl(source.streamUrl, { offset, follow: true, signal: opts.signal })) {
+              offset = eventResumeOffset(event, offset);
+              failures = 0;
+              yield event;
+            }
+          } catch (err) {
+            if (opts.signal?.aborted) throw err;
+            failures++;
+            if (!reconnect || failures > reconnect.attempts) throw err;
+            await sleep(reconnect.delayMs);
+          }
+        }
+      },
+      async list(opts = {}) {
+        const q = opts.limit ? `?limit=${opts.limit}` : "";
+        return (await get(`/admin/runs${q}`)).items;
+      }
+    },
+    streams: {
+      url(path) {
+        return `${base}${streamPath(path)}`;
+      },
+      async head(path) {
+        const res = await doFetch(`${base}${streamPath(path)}`, { method: "HEAD", headers });
+        if (res.status === 404) return { exists: false };
+        if (!res.ok) throw await atlasErrorFromResponse(res);
+        return streamMeta(res);
+      },
+      async create(path, opts = {}) {
+        const res = await doFetch(`${base}${streamPath(path)}`, {
+          method: "PUT",
+          headers: streamRequestHeaders(headers, opts.contentType, {
+            ...opts.closed ? { "Stream-Closed": "true" } : {},
+            ...opts.ttlSeconds !== void 0 ? { "Stream-TTL": String(opts.ttlSeconds) } : {},
+            ...opts.expiresAt !== void 0 ? { "Stream-Expires-At": opts.expiresAt } : {},
+            ...opts.forkedFrom !== void 0 ? { "Stream-Forked-From": opts.forkedFrom } : {},
+            ...opts.forkOffset !== void 0 ? { "Stream-Fork-Offset": opts.forkOffset } : {}
+          }),
+          body: opts.body
+        });
+        if (!res.ok) throw await atlasErrorFromResponse(res);
+        return streamMeta(res);
+      },
+      async append(path, body, opts = {}) {
+        const res = await doFetch(`${base}${streamPath(path)}`, {
+          method: "POST",
+          headers: streamRequestHeaders(headers, opts.contentType, {
+            ...opts.close ? { "Stream-Closed": "true" } : {},
+            ...opts.seq !== void 0 ? { "Stream-Seq": opts.seq } : {}
+          }),
+          body
+        });
+        if (!res.ok) throw await atlasErrorFromResponse(res);
+        return streamMeta(res);
+      },
+      async close(path) {
+        const res = await doFetch(`${base}${streamPath(path)}`, {
+          method: "POST",
+          headers: streamRequestHeaders(headers, void 0, { "Stream-Closed": "true" })
+        });
+        if (!res.ok) throw await atlasErrorFromResponse(res);
+        return streamMeta(res);
+      },
+      async delete(path) {
+        const res = await doFetch(`${base}${streamPath(path)}`, { method: "DELETE", headers });
+        if (!res.ok) throw await atlasErrorFromResponse(res);
+      },
+      async readJson(path, opts = {}) {
+        const res = await doFetch(`${base}${streamPath(path)}${streamReadQuery(opts)}`, { headers });
+        if (!res.ok) throw await atlasErrorFromResponse(res);
+        const text = await res.text();
+        const items = text ? JSON.parse(text) : [];
+        return {
+          items,
+          nextOffset: res.headers.get("Stream-Next-Offset") ?? opts.offset ?? "-1",
+          cursor: res.headers.get("Stream-Cursor") ?? void 0,
+          upToDate: res.headers.get("Stream-Up-To-Date")?.toLowerCase() === "true",
+          closed: res.headers.get("Stream-Closed")?.toLowerCase() === "true"
+        };
+      },
+      subscriptions: {
+        async create(id, opts) {
+          const type = opts.type ?? "pull-wake";
+          const res = await doFetch(`${base}${subscriptionPath(id)}`, {
+            method: "PUT",
+            headers,
+            body: JSON.stringify({
+              type,
+              streams: opts.streams ?? [],
+              ...opts.pattern ? { pattern: opts.pattern } : {},
+              ...opts.wakeStream ? { wake_stream: opts.wakeStream } : {},
+              ...opts.leaseTtlMs !== void 0 ? { lease_ttl_ms: opts.leaseTtlMs } : {},
+              ...opts.webhookUrl ?? opts.url ? { webhook_url: opts.webhookUrl ?? opts.url } : {},
+              ...opts.headers ? { headers: opts.headers } : {},
+              ...opts.description ? { description: opts.description } : {}
+            })
+          });
+          if (!res.ok) throw await atlasErrorFromResponse(res);
+          return subscriptionInfo(await res.json());
+        },
+        async get(id) {
+          const res = await doFetch(`${base}${subscriptionPath(id)}`, { headers });
+          if (!res.ok) throw await atlasErrorFromResponse(res);
+          return subscriptionInfo(await res.json());
+        },
+        async delete(id) {
+          const res = await doFetch(`${base}${subscriptionPath(id)}`, { method: "DELETE", headers });
+          if (!res.ok) throw await atlasErrorFromResponse(res);
+        },
+        async addStreams(id, streams) {
+          const res = await doFetch(`${base}${subscriptionPath(id)}/streams`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({ streams })
+          });
+          if (!res.ok) throw await atlasErrorFromResponse(res);
+        },
+        async removeStream(id, path) {
+          const res = await doFetch(`${base}${subscriptionPath(id)}/streams/${path.split("/").map(encodeURIComponent).join("/")}`, {
+            method: "DELETE",
+            headers
+          });
+          if (!res.ok) throw await atlasErrorFromResponse(res);
+        },
+        async claim(id, worker) {
+          const res = await doFetch(`${base}${subscriptionPath(id)}/claim`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({ worker })
+          });
+          if (!res.ok) throw await atlasErrorFromResponse(res);
+          return subscriptionClaim(await res.json());
+        },
+        async ack(id, token, opts) {
+          const res = await doFetch(`${base}${subscriptionPath(id)}/ack`, {
+            method: "POST",
+            headers: headersWithoutContentType(headers, { "Subscription-Token": `Bearer ${token}`, "content-type": "application/json" }),
+            body: JSON.stringify(subscriptionAckBody(opts))
+          });
+          if (!res.ok) throw await atlasErrorFromResponse(res);
+          const json = await res.json();
+          return { ok: true, nextWake: json.next_wake };
+        },
+        async release(id, token, opts) {
+          const res = await doFetch(`${base}${subscriptionPath(id)}/release`, {
+            method: "POST",
+            headers: headersWithoutContentType(headers, { "Subscription-Token": `Bearer ${token}`, "content-type": "application/json" }),
+            body: JSON.stringify(subscriptionAckBody(opts))
+          });
+          if (!res.ok) throw await atlasErrorFromResponse(res);
+        }
+      }
+    },
+    admin: {
+      async agents() {
+        return (await get(`/admin/agents`)).items;
+      }
+    }
+  };
+}
+function eventQuery(opts) {
+  const params = new URLSearchParams();
+  params.set("format", "atlas");
+  if (opts.offset !== void 0) params.set("offset", opts.offset);
+  else if (opts.after !== void 0) params.set("after", String(opts.after));
+  if (opts.follow !== void 0) params.set("follow", String(opts.follow));
+  if (opts.limit !== void 0) params.set("limit", String(opts.limit));
+  if (opts.tail !== void 0) params.set("tail", String(opts.tail));
+  const query = params.toString();
+  return query ? `?${query}` : "";
+}
+function withEventQuery(url, opts) {
+  const query = eventQuery(opts);
+  if (!query) return url;
+  return `${url}${url.includes("?") ? "&" : "?"}${query.slice(1)}`;
+}
+function runEventUrl(base, runId) {
+  return `${base}/runs/${encodeURIComponent(runId)}/events`;
+}
+function streamPath(path) {
+  return `/streams/${path.split("/").map(encodeURIComponent).join("/")}`;
+}
+function subscriptionPath(id) {
+  return `/streams/__ds/subscriptions/${encodeURIComponent(id)}`;
+}
+function streamReadQuery(opts) {
+  const params = new URLSearchParams();
+  params.set("offset", opts.offset ?? "-1");
+  if (opts.cursor) params.set("cursor", opts.cursor);
+  if (opts.live) params.set("live", opts.live);
+  if (opts.timeoutMs !== void 0) params.set("timeout", String(opts.timeoutMs));
+  return `?${params.toString()}`;
+}
+function streamRequestHeaders(baseHeaders, contentType, extra) {
+  return {
+    ...headersWithoutContentType(baseHeaders, extra),
+    ...contentType ? { "content-type": contentType } : {}
+  };
+}
+function headersWithoutContentType(baseHeaders, extra) {
+  const out = {};
+  for (const [key, value] of Object.entries(baseHeaders)) {
+    if (key.toLowerCase() !== "content-type") out[key] = value;
+  }
+  return { ...out, ...extra ?? {} };
+}
+function streamMeta(res) {
+  const ttl = res.headers.get("Stream-TTL");
+  return {
+    exists: true,
+    contentType: res.headers.get("content-type") ?? void 0,
+    offset: res.headers.get("Stream-Next-Offset") ?? void 0,
+    cursor: res.headers.get("Stream-Cursor") ?? void 0,
+    streamClosed: res.headers.get("Stream-Closed")?.toLowerCase() === "true",
+    ttlSeconds: ttl == null ? void 0 : Number(ttl),
+    expiresAt: res.headers.get("Stream-Expires-At") ?? void 0,
+    etag: res.headers.get("etag") ?? void 0
+  };
+}
+function subscriptionInfo(value) {
+  const raw = value;
+  return {
+    id: raw.id,
+    subscriptionId: raw.subscription_id,
+    type: raw.type,
+    pattern: raw.pattern,
+    streams: (raw.streams ?? []).map((stream) => ({
+      path: stream.path,
+      linkType: stream.link_type,
+      ackedOffset: stream.acked_offset
+    })),
+    wakeStream: raw.wake_stream,
+    leaseTtlMs: raw.lease_ttl_ms,
+    webhookUrl: raw.webhook_url,
+    webhookLastSuccessAt: raw.webhook_last_success_at,
+    webhookLastError: raw.webhook_last_error,
+    createdAt: raw.created_at,
+    status: raw.status,
+    description: raw.description
+  };
+}
+function subscriptionClaim(value) {
+  const raw = value;
+  return {
+    wakeId: raw.wake_id,
+    generation: raw.generation,
+    token: raw.token,
+    streams: (raw.streams ?? []).map((stream) => ({
+      path: stream.path,
+      linkType: stream.link_type,
+      ackedOffset: stream.acked_offset,
+      tailOffset: stream.tail_offset,
+      hasPending: stream.has_pending
+    })),
+    leaseTtlMs: raw.lease_ttl_ms
+  };
+}
+function subscriptionAckBody(opts) {
+  return {
+    wake_id: opts.wakeId,
+    generation: opts.generation,
+    ...opts.acks ? { acks: opts.acks } : {},
+    ...opts.done !== void 0 ? { done: opts.done } : {}
+  };
+}
+function runWatchSource(base, target) {
+  if (typeof target === "string") return { streamUrl: runEventUrl(base, target), offset: "-1" };
+  return {
+    streamUrl: target.streamUrl ?? runEventUrl(base, target.runId),
+    offset: target.offset ?? "-1"
+  };
+}
+function agentRequestBody(input) {
+  const { images, signal: _signal, ...rest } = input;
+  const body = { ...rest };
+  if (images !== void 0) body.images = images.map(agentImageBody);
+  return body;
+}
+function agentImageBody(image) {
+  const parsed = parseDataImage(image.data);
+  const mimeType = image.mimeType ?? parsed.mimeType;
+  return {
+    data: parsed.data,
+    ...mimeType ? { mime_type: mimeType } : {}
+  };
+}
+function parseDataImage(value) {
+  const trimmed = value.trim();
+  const match = /^data:([^;,]+)(?:;[^,]*)?;base64,(.*)$/is.exec(trimmed);
+  if (match) return { mimeType: match[1], data: match[2].replace(/\s/g, "") };
+  return { data: trimmed.replace(/\s/g, "") };
+}
+function eventResumeOffset(event, fallback) {
+  if (typeof event.offset === "string") return event.offset;
+  if (typeof event.index === "number") return String(event.index);
+  return fallback;
+}
+function normalizeReconnect(reconnect) {
+  if (!reconnect) return void 0;
+  if (reconnect === true) return { attempts: 3, delayMs: 250 };
+  return { attempts: reconnect.attempts ?? 3, delayMs: reconnect.delayMs ?? 250 };
+}
+async function atlasErrorFromResponse(res) {
+  let error;
+  try {
+    error = (await res.json()).error;
+  } catch {
+  }
+  return new AtlasFlowError(res.status, error?.code ?? "request_failed", error?.message ?? res.statusText);
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function* parseSSE(body) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  const frame = { data: [] };
+  for (; ; ) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    buffer += decoder.decode(value, { stream: true });
+    for (; ; ) {
+      const eol = findLineEnd(buffer, false);
+      if (!eol) break;
+      const line = buffer.slice(0, eol.index);
+      buffer = buffer.slice(eol.next);
+      const event2 = readSseLine(frame, line);
+      if (event2) yield event2;
+    }
+  }
+  buffer += decoder.decode();
+  for (; ; ) {
+    const eol = findLineEnd(buffer, true);
+    if (!eol) break;
+    const line = buffer.slice(0, eol.index);
+    buffer = buffer.slice(eol.next);
+    const event2 = readSseLine(frame, line);
+    if (event2) yield event2;
+  }
+  if (buffer) {
+    const event2 = readSseLine(frame, buffer);
+    if (event2) yield event2;
+  }
+  const event = finishSseFrame(frame);
+  if (event) yield event;
+}
+function findLineEnd(buffer, eof) {
+  for (let i = 0; i < buffer.length; i++) {
+    const ch = buffer[i];
+    if (ch === "\n") return { index: i, next: i + 1 };
+    if (ch === "\r") {
+      if (i === buffer.length - 1 && !eof) return void 0;
+      return { index: i, next: buffer[i + 1] === "\n" ? i + 2 : i + 1 };
+    }
+  }
+  return void 0;
+}
+function readSseLine(frame, rawLine) {
+  const line = rawLine.endsWith("\r") ? rawLine.slice(0, -1) : rawLine;
+  if (line === "") return finishSseFrame(frame);
+  if (line.startsWith(":")) return void 0;
+  const colon = line.indexOf(":");
+  const field = colon === -1 ? line : line.slice(0, colon);
+  let value = colon === -1 ? "" : line.slice(colon + 1);
+  if (value.startsWith(" ")) value = value.slice(1);
+  if (field === "data") frame.data.push(value);
+  else if (field === "id") frame.id = value;
+  return void 0;
+}
+function finishSseFrame(frame) {
+  if (!frame.data.length) {
+    frame.id = void 0;
+    return void 0;
+  }
+  const data = frame.data.join("\n");
+  const id = frame.id;
+  frame.data = [];
+  frame.id = void 0;
+  try {
+    const parsed = JSON.parse(data);
+    if (id && parsed.offset === void 0) parsed.offset = id;
+    return parsed;
+  } catch {
+    return void 0;
+  }
+}
+export {
+  AtlasFlowError,
+  createAtlasFlowClient
+};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@cybernetyx1/atlasflow-sdk",
+  "version": "0.1.0",
+  "description": "Typed HTTP client for invoking AtlasFlow agents, streams, runs, and events.",
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "Cybernetyx",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Cybernetyx/atlasflow.git",
+    "directory": "packages/sdk"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test test/*.test.ts"
+  }
+}