fauna-api 0.0.0-stage → 1.0.676

package/dist/src/drive.js

@@ -0,0 +1,472 @@
+import { Fauna } from "../index.js";
+import { mimeFromFileName } from "./marmot/media.js";
+export { FaunaFile as File };
+function sendWithProgress(url, headers, body, onProgress) {
+    return new Promise((resolve, reject) => {
+        const xhr = new XMLHttpRequest();
+        xhr.open("POST", url);
+        for (const [name, value] of Object.entries(headers))
+            xhr.setRequestHeader(name, value);
+        xhr.upload.onprogress = (event) => {
+            if (event.lengthComputable && event.total > 0 && onProgress)
+                onProgress(event.loaded / event.total);
+        };
+        xhr.onload = () => resolve(xhr.status);
+        xhr.onerror = () => reject(new Error('Failed to upload file.'));
+        xhr.send(body);
+    });
+}
+class FaunaFile {
+    get name() {
+        return this._name;
+    }
+    get online() {
+        return this._online;
+    }
+    constructor(authorization, name, online, contentType, contentLength, accessDate, createDate, data = undefined) {
+        Object.defineProperty(this, "authorization", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "contentType", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "contentLength", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "accessDate", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "createDate", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_online", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "data", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "previewData", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.authorization = authorization;
+        this._name = name;
+        this._online = online;
+        this.contentType = contentType;
+        this.contentLength = contentLength;
+        this.accessDate = accessDate;
+        this.createDate = createDate;
+        this.data = data;
+    }
+    static fromJSON(json, authorization) {
+        return new FaunaFile(authorization, json.name ?? "", true, json.contentType ?? "application/octet-stream", Number(json.contentLength ?? 0), new Date(json.accessDate ?? Date.now()), new Date(json.createDate ?? Date.now()));
+    }
+    async download(revalidate = false, onProgress) {
+        if (this.data && !revalidate) {
+            return this.data;
+        }
+        const auth = this.authorization;
+        const response = 'repository' in auth
+            ? await fetch(`${Fauna.Termite.getURL()}/termite/repositories/${auth.repository}/files${auth.path.split('/').filter(Boolean).map((s) => '/' + encodeURIComponent(s)).join('')}?download=1`, {
+                method: "GET",
+                headers: {
+                    "Authorization": 'email' in auth.authorization ? `Token ${auth.authorization.token}` : `ApiKey ${auth.authorization.id}`,
+                    ...(auth.group ? { "Group": auth.group } : {}),
+                }
+            })
+            : await fetch(`${Fauna.getURL()}/file/download`, {
+                method: "GET",
+                headers: {
+                    "Authorization": 'email' in auth.authorization ? `Token ${auth.authorization.token}` : `ApiKey ${auth.authorization.id}`,
+                    ...('path' in auth ? {
+                        "Path": this.contentType === 'application/x-directory' ? auth.path + '/' : auth.path,
+                        ...(auth.group ? { "Group": auth.group } : {})
+                    } : {
+                        "Access-Code": auth.accessCode
+                    })
+                }
+            });
+        if (!response.ok) {
+            if (response.status === 401) {
+                throw new Error(`${response.status}: Unauthorized request.`);
+            }
+            else if (response.status === 403) {
+                throw new Error(`${response.status}: Forbidden request.`);
+            }
+            throw new Error(`${response.status}: Bad request.`);
+        }
+        const buffer = await parseStream(response, onProgress ? (loaded) => {
+            if (this.contentLength > 0) {
+                onProgress(Math.min(Math.max(loaded / this.contentLength, 0), 1));
+            }
+        } : undefined);
+        if (onProgress) {
+            onProgress(1);
+        }
+        const data = Array.isArray(buffer) ? buffer[0] : buffer;
+        this.data = data;
+        return data;
+    }
+    // Fetch a server-generated preview image (image/webp) for this file, or
+    // undefined when the file type has no meaningful preview. Cached per file.
+    async preview(revalidate = false) {
+        if (this.previewData !== undefined && !revalidate) {
+            return this.previewData ?? undefined;
+        }
+        const auth = this.authorization;
+        const response = 'repository' in auth
+            ? await fetch(`${Fauna.Termite.getURL()}/termite/repositories/${auth.repository}/files${auth.path.split('/').filter(Boolean).map((s) => '/' + encodeURIComponent(s)).join('')}?preview=1`, {
+                method: "GET",
+                headers: {
+                    "Authorization": 'email' in auth.authorization ? `Token ${auth.authorization.token}` : `ApiKey ${auth.authorization.id}`,
+                    ...(auth.group ? { "Group": auth.group } : {}),
+                }
+            })
+            : await fetch(`${Fauna.getURL()}/file/preview`, {
+                method: "GET",
+                headers: {
+                    "Authorization": 'email' in auth.authorization ? `Token ${auth.authorization.token}` : `ApiKey ${auth.authorization.id}`,
+                    ...('path' in auth ? {
+                        "Path": this.contentType === 'application/x-directory' ? auth.path + '/' : auth.path,
+                        ...(auth.group ? { "Group": auth.group } : {})
+                    } : {
+                        "Access-Code": auth.accessCode
+                    })
+                }
+            });
+        if (response.status === 204) {
+            this.previewData = null;
+            return undefined;
+        }
+        if (!response.ok) {
+            if (response.status === 401) {
+                throw new Error(`${response.status}: Unauthorized request.`);
+            }
+            else if (response.status === 403) {
+                throw new Error(`${response.status}: Forbidden request.`);
+            }
+            // Soft-fail (incl. 429): cache miss so this File instance does not hammer.
+            this.previewData = null;
+            return undefined;
+        }
+        const buffer = await parseStream(response);
+        const data = Array.isArray(buffer) ? buffer[0] : buffer;
+        this.previewData = data;
+        return data;
+    }
+    async upload(onProgress) {
+        if ('accessCode' in this.authorization) {
+            throw new Error('401: Unauthorized request.');
+        }
+        const directory = this.contentType === 'application/x-directory';
+        if (!this.data && !directory) {
+            throw new Error('400: No data to upload.');
+        }
+        const auth = this.authorization;
+        const url = 'repository' in auth
+            ? `${Fauna.Termite.getURL()}/termite/repositories/${auth.repository}/files${auth.path.split('/').filter(Boolean).map((s) => '/' + encodeURIComponent(s)).join('')}`
+            : `${Fauna.getURL()}/file/upload`;
+        const headers = {
+            Authorization: 'email' in auth.authorization ? `Token ${auth.authorization.token}` : `ApiKey ${auth.authorization.id}`,
+            'Content-Type': this.contentType || 'application/octet-stream',
+        };
+        if (!('repository' in auth))
+            headers.Path = directory ? auth.path + '/' : auth.path;
+        if (auth.group)
+            headers.Group = auth.group;
+        const body = directory ? 'Folder' : this.data.buffer;
+        // XMLHttpRequest reports upload progress; runtimes without it (Node) use fetch.
+        const status = typeof XMLHttpRequest === 'undefined'
+            ? await fetch(url, { method: 'POST', headers, body }).then((r) => r.status, () => { throw new Error('Failed to upload file.'); })
+            : await sendWithProgress(url, headers, body, onProgress);
+        onProgress?.(1);
+        if (status === 401)
+            throw new Error(`${status}: Unauthorized request.`);
+        if (status === 403)
+            throw new Error(`${status}: Forbidden request.`);
+        if (status < 200 || status >= 300)
+            throw new Error(`${status}: Bad request.`);
+        this._online = true;
+    }
+    async copy(path) {
+        if ('accessCode' in this.authorization) {
+            throw new Error('401: Unauthorized request.');
+        }
+        if ('repository' in this.authorization) {
+            throw new Error('403: Not available for repository files.');
+        }
+        const response = await fetch(`${Fauna.getURL()}/file/copy`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "Authorization": 'email' in this.authorization.authorization ? `Token ${this.authorization.authorization.token}` : `ApiKey ${this.authorization.authorization.id}`,
+                "Path": this.contentType === 'application/x-directory' ? this.authorization.path + '/' : this.authorization.path,
+                ...(this.authorization.group ? { "Group": this.authorization.group } : {})
+            },
+            body: JSON.stringify({ copyPath: path })
+        });
+        if (!response.ok) {
+            throw new Error(await response.text());
+        }
+    }
+    async text() {
+        return new TextDecoder().decode(await this.download());
+    }
+    async json() {
+        return JSON.parse(await this.text());
+    }
+    async remove() {
+        if ('accessCode' in this.authorization) {
+            throw new Error('401: Unauthorized request.');
+        }
+        if ('repository' in this.authorization) {
+            throw new Error('403: Not available for repository files.');
+        }
+        await remove(this.authorization.authorization, this.contentType === 'application/x-directory' ? this.authorization.path + '/' : this.authorization.path, this.authorization.group);
+        this.data = undefined;
+        this._online = false;
+    }
+    async generateAccessCode(expiration) {
+        if ('accessCode' in this.authorization) {
+            throw new Error('401: Unauthorized request.');
+        }
+        if ('repository' in this.authorization) {
+            throw new Error('403: Not available for repository files.');
+        }
+        const response = await fetch(`${Fauna.getURL()}/file/access-code`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "Authorization": 'email' in this.authorization.authorization ? `Token ${this.authorization.authorization.token}` : `ApiKey ${this.authorization.authorization.id}`,
+                "Path": this.contentType === 'application/x-directory' ? this.authorization.path + '/' : this.authorization.path,
+                ...(this.authorization.group ? { "Group": this.authorization.group } : {}),
+            },
+            body: JSON.stringify({ expiration: expiration })
+        });
+        if (!response.ok) {
+            throw new Error(await response.text());
+        }
+        return (await response.text());
+    }
+    async owner() {
+        const auth = this.authorization;
+        if ('repository' in auth) {
+            throw new Error('403: Not available for repository files.');
+        }
+        const response = await fetch(`${Fauna.getURL()}/file/owner`, {
+            method: "GET",
+            headers: {
+                "Authorization": 'email' in auth.authorization ? `Token ${auth.authorization.token}` : `ApiKey ${auth.authorization.id}`,
+                ...('path' in auth
+                    ? { "Path": auth.path, ...(auth.group ? { "Group": auth.group } : {}) }
+                    : { "Access-Code": auth.accessCode }),
+            }
+        });
+        if (!response.ok) {
+            throw new Error(await response.text());
+        }
+        return await response.json();
+    }
+}
+export async function list(authorization, path, group) {
+    const response = await fetch(`${Fauna.getURL()}/file/list`, {
+        method: "GET",
+        headers: {
+            "Authorization": 'email' in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+            "Path": path,
+            ...(group ? { "Group": group } : {})
+        }
+    });
+    if (!response.ok) {
+        throw new Error(await response.text());
+    }
+    return await response.json();
+}
+export async function wrap(authorization, file, options = {}) {
+    const now = new Date();
+    // Browsers often leave File.type empty for HEIC; infer from the extension.
+    const contentType = file.type || mimeFromFileName(file.name) || "application/octet-stream";
+    return new FaunaFile(authorization, file.name, false, contentType, file.size, options.accessDate || now, options.createDate || now, new Uint8Array(await file.arrayBuffer()));
+}
+/**
+ * Build an in-memory FaunaFile from raw bytes (not yet uploaded). `path` is
+ * the Drive destination (e.g. `tmp/${uuid}-${name}`); the display name is the
+ * last path segment. `authorization` is the caller's credentials/api key; the
+ * file is `online: false` until an explicit `upload()`.
+ */
+export function fromBytes(authorization, path, contentType, data, options = {}) {
+    const now = new Date();
+    const name = path.split('/').pop() || path;
+    return new FaunaFile({ authorization, path }, name, false, contentType, data.length, options.accessDate || now, options.createDate || now, data);
+}
+/**
+ * Build a streaming FaunaFile addressed by a per-file access code. Bytes are
+ * pulled on demand via `download()` (the `Access-Code` path). Used to hydrate
+ * chat message FILE parts returned by the server (each carries its own code),
+ * so members stream file bytes uniformly without a host-drive path.
+ */
+export function fromAccessCode(authorization, accessCode, meta) {
+    return FaunaFile.fromJSON(meta, { authorization, accessCode });
+}
+export async function folder(authorization, options = {}) {
+    if ('accessCode' in authorization) {
+        throw new Error('401: Unauthorized request.');
+    }
+    const normalized = authorization.path.replace(/\\/g, '/').replace(/\/+$/, '');
+    const parts = normalized.split('/');
+    const name = parts[parts.length - 1] || '';
+    const now = new Date();
+    return new FaunaFile(authorization, name, false, 'application/x-directory', 0, options.accessDate || now, options.createDate || now);
+}
+export async function pull(authorization) {
+    const response = 'repository' in authorization
+        ? await fetch(`${Fauna.Termite.getURL()}/termite/repositories/${authorization.repository}/files${authorization.path.split('/').filter(Boolean).map((s) => '/' + encodeURIComponent(s)).join('')}`, {
+            method: "GET",
+            headers: {
+                "Authorization": 'email' in authorization.authorization ? `Token ${authorization.authorization.token}` : `ApiKey ${authorization.authorization.id}`,
+                ...(authorization.group ? { "Group": authorization.group } : {}),
+            }
+        })
+        : await fetch(`${Fauna.getURL()}/file/pull`, {
+            method: "GET",
+            headers: {
+                "Authorization": 'email' in authorization.authorization ? `Token ${authorization.authorization.token}` : `ApiKey ${authorization.authorization.id}`,
+                ...('path' in authorization
+                    ? { "Path": authorization.path, ...(authorization.group ? { "Group": authorization.group } : {}) }
+                    : { "Access-Code": authorization.accessCode }),
+            }
+        });
+    if (!response.ok) {
+        throw new Error(await response.text());
+    }
+    return FaunaFile.fromJSON(await response.json(), authorization);
+}
+export async function remove(authorization, path, group) {
+    const response = await fetch(`${Fauna.getURL()}/file`, {
+        method: "DELETE",
+        headers: {
+            "Authorization": 'email' in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+            "Path": path,
+            ...(group ? { "Group": group } : {})
+        }
+    });
+    if (!response.ok) {
+        throw new Error(await response.text());
+    }
+    return response.ok;
+}
+/** Split a Drive style response into its parts. With `Encoding-Size` above 1 the
+ *  body is a `--BOUNDARY` separated multipart and this returns every part. */
+export async function parseStream(response, onLoaded) {
+    const encodingSize = response.headers.get('Encoding-Size');
+    if (encodingSize && parseInt(encodingSize) > 1) {
+        const reader = response.body.getReader();
+        let buffer = new Uint8Array(0);
+        let loaded = 0;
+        const boundaryBytes = new TextEncoder().encode('--BOUNDARY');
+        const parts = [];
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (value) {
+                const tmp = new Uint8Array(buffer.length + value.length);
+                tmp.set(buffer, 0);
+                tmp.set(value, buffer.length);
+                buffer = tmp;
+                loaded += value.length;
+                if (onLoaded) {
+                    onLoaded(loaded);
+                }
+            }
+        }
+        function indexOfBoundary(buf, startPos = 0) {
+            for (let i = startPos; i <= buf.length - boundaryBytes.length; i++) {
+                let match = true;
+                for (let j = 0; j < boundaryBytes.length; j++) {
+                    if (buf[i + j] !== boundaryBytes[j]) {
+                        match = false;
+                        break;
+                    }
+                }
+                if (match) {
+                    return i;
+                }
+            }
+            return -1;
+        }
+        let currentPos = 0;
+        let boundaryCount = 0;
+        while (true) {
+            const idx = indexOfBoundary(buffer, currentPos);
+            if (idx === -1) {
+                if (currentPos < buffer.length) {
+                    const part = buffer.slice(currentPos);
+                    if (part.length > 0) {
+                        parts.push(part);
+                    }
+                }
+                break;
+            }
+            else {
+                boundaryCount++;
+                const part = buffer.slice(currentPos, idx);
+                if (part.length > 0) {
+                    parts.push(part);
+                }
+                currentPos = idx + boundaryBytes.length;
+            }
+        }
+        return parts;
+    }
+    else {
+        const reader = response.body.getReader();
+        let buffer = new Uint8Array(0);
+        let loaded = 0;
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (value) {
+                const tmp = new Uint8Array(buffer.length + value.length);
+                tmp.set(buffer, 0);
+                tmp.set(value, buffer.length);
+                buffer = tmp;
+                loaded += value.length;
+                if (onLoaded) {
+                    onLoaded(loaded);
+                }
+            }
+        }
+        return buffer;
+    }
+}

package/dist/src/extensions/index.d.ts

@@ -0,0 +1,4 @@
+import { Web as WebAPI } from "./web/index.js";
+export declare namespace Extensions {
+    export import Web = WebAPI;
+}

package/dist/src/extensions/index.js

@@ -0,0 +1,5 @@
+import { Web as WebAPI } from "./web/index.js";
+export var Extensions;
+(function (Extensions) {
+    Extensions.Web = WebAPI;
+})(Extensions || (Extensions = {}));

package/dist/src/extensions/web/index.d.ts

@@ -0,0 +1,6 @@
+import * as SessionAPI from "./session.js";
+import * as ToolsAPI from "./tools.js";
+export declare namespace Web {
+    export import Session = SessionAPI;
+    export import Tools = ToolsAPI;
+}

package/dist/src/extensions/web/index.js

@@ -0,0 +1,7 @@
+import * as SessionAPI from "./session.js";
+import * as ToolsAPI from "./tools.js";
+export var Web;
+(function (Web) {
+    Web.Session = SessionAPI;
+    Web.Tools = ToolsAPI;
+})(Web || (Web = {}));

package/dist/src/extensions/web/session.d.ts

@@ -0,0 +1,106 @@
+import { Credentials, ApiKey } from "../../authentification.js";
+import { Presence } from "../../shared/server.js";
+import { ChatRoom, RoomHooks } from "../../parrot/room.js";
+import { WebRoom, type WebRoomHooks, DomReplayer, type WebSnapshot, type WebMutation } from "../../marmot/web.js";
+/** Public join URL for a web-room access code (chat joins via ensure, not the URL). */
+export declare function shareUrl(code: string, origin?: string): string;
+export type SessionHooks = {
+    web?: WebRoomHooks;
+    chat?: RoomHooks;
+};
+/**
+ * A paired live session: one `WebRoom` (live page DOM) + one `ChatRoom`.
+ * Share links carry only the web access code; chat uses ensure + Parrot code.
+ */
+export declare class ExtensionWebSession {
+    readonly web: WebRoom;
+    readonly chat: ChatRoom;
+    readonly webSelf: Presence;
+    readonly chatSelf: Presence;
+    /** Bare web access code used in the share URL. */
+    readonly code: string;
+    private recorder;
+    replayer: DomReplayer | null;
+    private detachTools;
+    constructor(parts: {
+        web: WebRoom;
+        chat: ChatRoom;
+        webSelf: Presence;
+        chatSelf: Presence;
+        code: string;
+    });
+    shareCode(): string;
+    /** Page tools routed through the web room (host executes). */
+    pageTools(): import("../../parrot/generative.js").Tool[];
+    /**
+     * Begin hosting: upload HTML + assets, bind ids, stream mutations.
+     * Prefer `startWebShare` from the extension for progress UX.
+     */
+    startHosting(root?: Node, onProgress?: (percent: number) => void): Promise<void>;
+    stopHosting(): void;
+    startViewing(mount: Element, onProgress?: (percent: number) => void): Promise<void>;
+    renderSnapshot(snapshot: WebSnapshot): void;
+    renderMutation(mutation: WebMutation): void;
+    private renderMutationAsync;
+    close(): void;
+}
+/**
+ * Cached chat half of a share. The content script only mints/opens the room
+ * (`openRoom`); the chat iframe owns the live `ChatRoom` socket so the host
+ * does not double-join presence.
+ */
+export type CachedChatRoom = {
+    reference: string;
+    roomId: string;
+    code: string;
+};
+/**
+ * Open (or return) a shared Parrot chat room for this tab. Lives until the host
+ * leaves the page — panel close must not destroy it. Does not connect a socket
+ * here; call `connectRoom` from the chat UI with `code`.
+ */
+export declare function ensureChatRoom(authorization: Credentials | ApiKey, cached?: CachedChatRoom | null): Promise<CachedChatRoom>;
+export type WebShareSession = {
+    web: WebRoom;
+    webSelf: Presence;
+    chatId: string;
+    webCode: string;
+    reference: string;
+    shareCode(): string;
+    close(): void;
+};
+/**
+ * Bind (host) or open the Parrot chat paired with a web room. Always returns a
+ * fresh Parrot access code for `connectRoom({ code })`.
+ */
+export declare function ensureChatFromWebAccess(authorization: Credentials | ApiKey, scope: {
+    accessCode: string;
+} | {
+    reference: string;
+}, opts?: {
+    chatId?: string;
+}): Promise<{
+    chatId: string;
+    code: string;
+}>;
+/**
+ * Start the web room only (chat room must already exist). Uploads HTML + assets
+ * with progress, publishes bootstrap meta, starts mutation streaming + tools.
+ * Persists `chatId` under the web room so guests can ensure a Parrot code later.
+ */
+export declare function startWebShare(authorization: Credentials | ApiKey, chat: {
+    roomId: string;
+}, options?: {
+    hooks?: WebRoomHooks;
+    root?: Node;
+    onProgress?: (percent: number) => void;
+}): Promise<WebShareSession>;
+export declare function openSession(authorization: Credentials | ApiKey, hooks?: SessionHooks): Promise<ExtensionWebSession>;
+export declare function joinRoom(authorization: Credentials | ApiKey, webCode: string, hooks?: SessionHooks): Promise<ExtensionWebSession>;
+export declare function invite(authorization: Credentials | ApiKey, email: string, joinUrl: string, scope: {
+    accessCode: string;
+} | {
+    reference: string;
+}): Promise<{
+    status: "added" | "invited";
+}>;