@digitornai/sdk 0.1.0

package/dist/workspace.d.ts

@@ -0,0 +1,81 @@
+/** One pending change reported by a `workspace_changes` event. */
+export interface FileChange {
+    /** Workdir-relative path. */
+    path: string;
+    status: "added" | "modified" | "deleted" | (string & {});
+}
+/** One directory entry from `readDir`. */
+export interface DirEntry {
+    name: string;
+    /** Workdir-relative path. */
+    path: string;
+    type: "file" | "dir" | (string & {});
+}
+/**
+ * What to react to in `useWatch`:
+ *  - `"*"` (or `""`)      every change
+ *  - `"scene.json"`        one exact path
+ *  - `"pages/"`            trailing slash = prefix (a whole folder)
+ *  - `"pages/*.md"`        glob (`*` matches any chars except `/`)
+ *  - `(path) => boolean`   custom predicate
+ */
+export type WatchMatch = "*" | (string & {}) | ((path: string) => boolean);
+export interface WorkspaceApi {
+    /** Raw text of a file, or `undefined` when missing/unreadable. */
+    readFile: (path: string) => Promise<string | undefined>;
+    /** Overwrite a file (creates it if absent). Text only - use `writeBinary` for PNG/etc. */
+    writeFile: (path: string, content: string) => Promise<void>;
+    /**
+     * Overwrite a file with raw bytes (PNG, JPEG, …). Uses `content_b64` on the
+     * daemon so binary survives JSON transport - required for agent vision reads.
+     */
+    writeBinary: (path: string, data: Uint8Array | ArrayBuffer) => Promise<void>;
+    /** List a directory (non-recursive). */
+    readDir: (path: string) => Promise<DirEntry[]>;
+}
+/** Session-scoped file endpoint. Shared by every file hook so the URL/auth
+ *  logic lives in exactly one place.
+ *
+ *  Two auth modes, transparent to callers:
+ *   - Embedded preview (`?t=` present): the public `preview/files` routes,
+ *     authenticated by the per-session preview token in the query. No JWT,
+ *     no cookie - this is the only mode the sandboxed iframe can use.
+ *   - Host app (JWT present): the `workspace/files` routes with a Bearer token.
+ */
+export declare function useWorkspaceEndpoint(): {
+    root: string;
+    headers: Record<string, string>;
+    preview: boolean;
+    /** Build a read/write URL for a workdir file in the active auth mode. */
+    fileUrl: (path: string) => string;
+    /** Build a directory-listing URL for the active auth mode. */
+    treeUrl: (path: string) => string;
+};
+/**
+ * Imperative access to the session workdir over the (stable) daemon file
+ * routes. The app owns its own state shape - one JSON, a folder of files,
+ * many files - and reads/writes whatever it needs.
+ */
+export declare function useWorkspace(): WorkspaceApi;
+/**
+ * Fire `handler` whenever the agent (or anyone) changes workdir files matching
+ * `match`. The single, unopinionated primitive: it tells you WHAT changed; you
+ * re-read your own state and update the UI however your app wants.
+ *
+ * ```tsx
+ * // a whole folder
+ * useWatch("pages/", async () => setPages(await readDir("pages")));
+ * // one file
+ * useWatch("scene.json", () => reloadScene());
+ * // everything
+ * useWatch("*", (changes) => console.log(changes));
+ * ```
+ *
+ * The handler identity need not be stable (it's read via a ref).
+ */
+export declare function useWatch(match: WatchMatch, handler: (changes: FileChange[]) => void): void;
+/** A file's text, re-read automatically whenever the agent edits it. */
+export declare function useFile(path: string): string | undefined;
+/** A file parsed as JSON, re-parsed on every agent edit. `undefined` when the
+ *  file is missing or not valid JSON. */
+export declare function useFileJson<T = unknown>(path: string): T | undefined;

package/dist/workspace.js

@@ -0,0 +1,187 @@
+import * as React from "react";
+import { useDigitorn } from "./provider.js";
+// ── Internals ──────────────────────────────────────────────────────────
+function encodePath(p) {
+    return p.split("/").map(encodeURIComponent).join("/");
+}
+/** Encode raw bytes as standard base64 for `content_b64` writes. */
+function bytesToBase64(data) {
+    const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
+    let binary = "";
+    const chunk = 0x8000;
+    for (let i = 0; i < bytes.length; i += chunk) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + chunk));
+    }
+    return btoa(binary);
+}
+function compileMatch(match) {
+    if (typeof match === "function")
+        return match;
+    if (match === "*" || match === "")
+        return () => true;
+    if (match.includes("*")) {
+        const re = new RegExp("^" +
+            match.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*") +
+            "$");
+        return (p) => re.test(p);
+    }
+    if (match.endsWith("/"))
+        return (p) => p.startsWith(match);
+    return (p) => p === match;
+}
+/** Session-scoped file endpoint. Shared by every file hook so the URL/auth
+ *  logic lives in exactly one place.
+ *
+ *  Two auth modes, transparent to callers:
+ *   - Embedded preview (`?t=` present): the public `preview/files` routes,
+ *     authenticated by the per-session preview token in the query. No JWT,
+ *     no cookie - this is the only mode the sandboxed iframe can use.
+ *   - Host app (JWT present): the `workspace/files` routes with a Bearer token.
+ */
+export function useWorkspaceEndpoint() {
+    const { session } = useDigitorn();
+    const root = `${session.baseUrl}/api/apps/${encodeURIComponent(session.appId)}/sessions/${encodeURIComponent(session.sessionId)}`;
+    const preview = Boolean(session.previewToken);
+    const headers = React.useMemo(() => {
+        const h = {};
+        if (!preview && session.token)
+            h.Authorization = `Bearer ${session.token}`;
+        return h;
+    }, [preview, session.token]);
+    const fileUrl = React.useCallback((path) => preview
+        ? // getPreviewFile already returns raw bytes - no `?raw=1` needed.
+            `${root}/preview/files/${encodePath(path)}?t=${encodeURIComponent(session.previewToken)}`
+        : `${root}/workspace/files/${encodePath(path)}`, [preview, root, session.previewToken]);
+    const treeUrl = React.useCallback((path) => preview
+        ? `${root}/preview/tree?path=${encodeURIComponent(path)}&t=${encodeURIComponent(session.previewToken)}`
+        : `${root}/workspace/tree?path=${encodeURIComponent(path)}`, [preview, root, session.previewToken]);
+    return { root, headers, preview, fileUrl, treeUrl };
+}
+// ── useWorkspace - imperative file access ──────────────────────────────
+/**
+ * Imperative access to the session workdir over the (stable) daemon file
+ * routes. The app owns its own state shape - one JSON, a folder of files,
+ * many files - and reads/writes whatever it needs.
+ */
+export function useWorkspace() {
+    const { headers, preview, fileUrl, treeUrl } = useWorkspaceEndpoint();
+    return React.useMemo(() => ({
+        async readFile(path) {
+            try {
+                // The workspace route wraps content in JSON unless `?raw=1`; the
+                // preview route always returns raw bytes.
+                const url = preview ? fileUrl(path) : `${fileUrl(path)}?raw=1`;
+                const res = await fetch(url, { headers });
+                if (!res.ok)
+                    return undefined;
+                return await res.text();
+            }
+            catch {
+                return undefined;
+            }
+        },
+        async writeFile(path, content) {
+            await fetch(fileUrl(path), {
+                method: "PUT",
+                headers: { ...headers, "Content-Type": "application/json" },
+                body: JSON.stringify({ content }),
+            }).catch(() => { });
+        },
+        async writeBinary(path, data) {
+            await fetch(fileUrl(path), {
+                method: "PUT",
+                headers: { ...headers, "Content-Type": "application/json" },
+                body: JSON.stringify({ content_b64: bytesToBase64(data) }),
+            }).catch(() => { });
+        },
+        async readDir(path) {
+            try {
+                const res = await fetch(treeUrl(path), { headers });
+                if (!res.ok)
+                    return [];
+                const json = (await res.json());
+                return json?.entries ?? [];
+            }
+            catch {
+                return [];
+            }
+        },
+    }), [headers, preview, fileUrl, treeUrl]);
+}
+/**
+ * Fire `handler` whenever the agent (or anyone) changes workdir files matching
+ * `match`. The single, unopinionated primitive: it tells you WHAT changed; you
+ * re-read your own state and update the UI however your app wants.
+ *
+ * ```tsx
+ * // a whole folder
+ * useWatch("pages/", async () => setPages(await readDir("pages")));
+ * // one file
+ * useWatch("scene.json", () => reloadScene());
+ * // everything
+ * useWatch("*", (changes) => console.log(changes));
+ * ```
+ *
+ * The handler identity need not be stable (it's read via a ref).
+ */
+export function useWatch(match, handler) {
+    const { onEvent, state } = useDigitorn();
+    const matcher = React.useMemo(() => compileMatch(match), [match]);
+    const handlerRef = React.useRef(handler);
+    handlerRef.current = handler;
+    // Primary: the daemon PUSHES a `workspace_changes` envelope (debounced) over
+    // the same `/events` socket the host uses - for both the agent's filesystem
+    // writes and our own `preview/files` writes. Instant, zero polling.
+    React.useEffect(() => onEvent((env) => {
+        const e = env;
+        if (e.type !== "workspace_changes")
+            return;
+        const files = e.payload?.files ?? [];
+        const matched = files.filter((f) => matcher(f.path));
+        if (matched.length > 0)
+            handlerRef.current(matched);
+    }), [onEvent, matcher]);
+    // Fallback: while the socket is NOT connected (e.g. the sandboxed iframe
+    // couldn't open it), poll gently so updates still land. This never runs when
+    // the socket is up - no hammering - and stops the moment it connects.
+    React.useEffect(() => {
+        if (state.connected)
+            return;
+        const id = setInterval(() => handlerRef.current([]), 1500);
+        return () => clearInterval(id);
+    }, [state.connected]);
+}
+// ── useFile / useFileJson - reactive single-file reads ─────────────────
+/** A file's text, re-read automatically whenever the agent edits it. */
+export function useFile(path) {
+    const { readFile } = useWorkspace();
+    const [content, setContent] = React.useState(undefined);
+    const reload = React.useCallback(() => {
+        let alive = true;
+        void readFile(path).then((c) => {
+            if (alive)
+                setContent(c);
+        });
+        return () => {
+            alive = false;
+        };
+    }, [readFile, path]);
+    React.useEffect(reload, [reload]);
+    useWatch(path, () => void readFile(path).then(setContent));
+    return content;
+}
+/** A file parsed as JSON, re-parsed on every agent edit. `undefined` when the
+ *  file is missing or not valid JSON. */
+export function useFileJson(path) {
+    const content = useFile(path);
+    return React.useMemo(() => {
+        if (content === undefined)
+            return undefined;
+        try {
+            return JSON.parse(content);
+        }
+        catch {
+            return undefined;
+        }
+    }, [content]);
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@digitornai/sdk",
+  "version": "0.1.0",
+  "description": "Lean React SDK for Digitorn preview apps — one provider, a few hooks, the live agent runtime over Socket.IO.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18",
+    "socket.io-client": ">=4.7"
+  },
+  "devDependencies": {
+    "@types/react": "^19",
+    "typescript": "^6"
+  }
+}