fauna-api 0.0.0-stage → 1.0.676

package/dist/src/parrot/socket.js

@@ -0,0 +1,478 @@
+// The socket transport shared by Parrot's generative and agent functions. Not
+// re-exported: Generative.* and Agent.* are the public surface.
+import { Parrot } from "./index.js";
+import { fromBytes, fromAccessCode, pull } from "../drive.js";
+import { Role } from "./generative.js";
+import WebSocket from "isomorphic-ws";
+/** A Parrot socket URL; `group` adds the Group header (shared memory, group billing). */
+export function socketUrl(path, authorization, group) {
+    const wsURL = Parrot.getURL().replace('https://', 'wss://').replace('http://', 'ws://');
+    const authParam = encodeURIComponent(JSON.stringify({
+        Authorization: 'email' in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+        ...(group ? { Group: group.id } : {}),
+    }));
+    return `${wsURL}${path}?authorization=${authParam}`;
+}
+async function ensureOnline(authorization, file, dest) {
+    if (file.online)
+        return file;
+    const bytes = await file.download();
+    const data = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+    const ready = fromBytes(authorization, dest, file.contentType, data);
+    await ready.upload();
+    return ready;
+}
+function fileRef(file) {
+    const authorization = file.authorization;
+    if ('accessCode' in authorization) {
+        return { type: 'FILE', name: file.name, contentType: file.contentType, accessCode: authorization.accessCode };
+    }
+    return {
+        type: 'FILE',
+        name: file.name,
+        contentType: file.contentType,
+        path: authorization.path,
+        ...(authorization.group ? { group: authorization.group } : {}),
+    };
+}
+/** FILE parts become path or access code refs (uploading offline files first); no binaries go up. */
+export async function prepareMessages(authorization, messages) {
+    for (const part of messages.flatMap((message) => message.parts)) {
+        if (part.type === 'FILE' && !part.file.online) {
+            part.file = await ensureOnline(authorization, part.file, `tmp/${crypto.randomUUID()}-${part.file.name}`);
+        }
+    }
+    return messages.map((message) => ({
+        parts: message.parts.map((part) => part.type === 'FILE' ? fileRef(part.file) : part),
+        role: message.role,
+        author: message.author,
+    }));
+}
+function toBytes(data) {
+    if (data instanceof Uint8Array)
+        return data;
+    if (data instanceof ArrayBuffer)
+        return new Uint8Array(data);
+    if (ArrayBuffer.isView(data))
+        return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+    return new Uint8Array();
+}
+function decodeAudioDelta(delta) {
+    if (delta instanceof Uint8Array)
+        return delta;
+    if (typeof delta === 'string') {
+        const binary = atob(delta);
+        const bytes = new Uint8Array(binary.length);
+        for (let i = 0; i < binary.length; i++)
+            bytes[i] = binary.charCodeAt(i);
+        return bytes;
+    }
+    if (Array.isArray(delta))
+        return new Uint8Array(delta);
+    return toBytes(delta);
+}
+function concatBytes(chunks) {
+    let total = 0;
+    for (const chunk of chunks)
+        total += chunk.length;
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return out;
+}
+function isFaunaFile(value) {
+    return !!value && typeof value.download === 'function';
+}
+function filePartNeedsBinary(part) {
+    return typeof part.fileIndex === 'number' && !part.path && !part.accessCode && !isFaunaFile(part.file);
+}
+async function hydrateFilePart(authorization, part, binaries, fallbackType) {
+    if (isFaunaFile(part.file))
+        return { type: 'FILE', file: part.file };
+    const name = part.name ?? 'file';
+    const contentType = part.contentType ?? fallbackType;
+    if (part.accessCode) {
+        return { type: 'FILE', file: fromAccessCode(authorization, part.accessCode, { name, contentType }) };
+    }
+    if (typeof part.fileIndex === 'number' && binaries[part.fileIndex]) {
+        return { type: 'FILE', file: fromBytes(authorization, name, contentType, binaries[part.fileIndex]) };
+    }
+    if (part.path) {
+        return { type: 'FILE', file: await pull({ authorization, path: part.path, group: part.group }) };
+    }
+    return { type: 'FILE', file: fromBytes(authorization, name, contentType, new Uint8Array()) };
+}
+async function hydrateContent(authorization, content, binaries, fallbackType) {
+    const used = new Set();
+    const parts = [];
+    for (const part of content.parts) {
+        if (part && part.type === 'FILE') {
+            const wire = part;
+            if (typeof wire.fileIndex === 'number')
+                used.add(wire.fileIndex);
+            if (isFaunaFile(wire.file)) {
+                parts.push({ type: 'FILE', file: wire.file });
+            }
+            else {
+                parts.push(await hydrateFilePart(authorization, wire, binaries, fallbackType));
+            }
+        }
+        else {
+            parts.push(part);
+        }
+    }
+    for (let i = 0; i < binaries.length; i++) {
+        if (used.has(i))
+            continue;
+        parts.push({
+            type: 'FILE',
+            file: fromBytes(authorization, `output-${i}`, fallbackType, binaries[i]),
+        });
+    }
+    return { ...content, parts, role: content.role ?? Role.MODEL, createdAt: new Date(content.createdAt) };
+}
+function responseReady(content, binaries) {
+    if (!content?.parts)
+        return false;
+    return content.parts.every((part) => part?.type !== 'FILE' || !filePartNeedsBinary(part) || binaries[part.fileIndex] !== undefined);
+}
+async function drainSocketToTextResponse(authorization, ws, fallbackType = 'application/octet-stream') {
+    const binaries = [];
+    let text = '';
+    let usage = { promptTokens: 0, completionTokens: 0 };
+    let response;
+    let error;
+    let closed = false;
+    let gotDone = false;
+    let notify;
+    ws.onmessage = (msg) => {
+        const data = msg.data;
+        if (typeof data !== 'string') {
+            binaries.push(toBytes(data));
+            notify?.();
+            return;
+        }
+        try {
+            const parsed = JSON.parse(data);
+            if (parsed.event === 'error') {
+                const err = new Error(parsed.message);
+                if (parsed.code)
+                    err.code = parsed.code;
+                error = err;
+            }
+            else if (parsed.event === 'text') {
+                text += parsed.delta ?? '';
+            }
+            else if (parsed.event === 'done') {
+                if (parsed.usage)
+                    usage = parsed.usage;
+                gotDone = true;
+            }
+            else if (parsed.content && parsed.usage) {
+                response = parsed;
+            }
+        }
+        catch { }
+        notify?.();
+    };
+    ws.onclose = () => { closed = true; notify?.(); };
+    ws.onerror = () => { closed = true; notify?.(); };
+    while (!closed && !error) {
+        if (response && responseReady(response.content, binaries))
+            break;
+        if (gotDone && text && binaries.length === 0 && !response)
+            break;
+        await new Promise((resolve) => { notify = resolve; });
+    }
+    if (error)
+        throw error;
+    if (response) {
+        return {
+            content: await hydrateContent(authorization, response.content, binaries, fallbackType),
+            usage: response.usage ?? usage,
+        };
+    }
+    const parts = [];
+    if (text)
+        parts.push({ type: 'TEXT', text });
+    for (let i = 0; i < binaries.length; i++) {
+        parts.push({
+            type: 'FILE',
+            file: fromBytes(authorization, `output-${i}`, fallbackType, binaries[i]),
+        });
+    }
+    return { content: { parts, role: Role.MODEL, createdAt: new Date() }, usage };
+}
+/** One generate frame in, one TextResponse (with any files) out. */
+export async function generateMedia(authorization, path, model, options, fallbackType) {
+    const { content, group, ...extra } = options;
+    const messages = await prepareMessages(authorization, content ?? []);
+    const ws = new WebSocket(socketUrl(path, authorization, group));
+    ws.binaryType = 'arraybuffer';
+    try {
+        await new Promise((resolve, reject) => {
+            ws.onopen = () => resolve();
+            ws.onerror = () => reject(new Error('WebSocket connection failed'));
+        });
+        const drained = drainSocketToTextResponse(authorization, ws, fallbackType);
+        ws.send(JSON.stringify({ event: 'generate', model, messages, ...extra }));
+        ws.send(JSON.stringify({ event: 'start' }));
+        return await drained;
+    }
+    finally {
+        try {
+            ws.close();
+        }
+        catch { }
+    }
+}
+function replyToolResult(ws, tools, event) {
+    if (!tools)
+        return;
+    const tool = tools.find((t) => t.function.name === event.name);
+    if (tool) {
+        tool.evaluate(event.args).then((result) => {
+            ws.send(JSON.stringify({ event: 'tool_result', id: event.id, result }));
+        }).catch((err) => {
+            ws.send(JSON.stringify({ event: 'tool_result', id: event.id, result: `Error: ${err.message}` }));
+        });
+    }
+    else {
+        ws.send(JSON.stringify({ event: 'tool_result', id: event.id, result: `Error: Tool not found for ${event.name}.` }));
+    }
+}
+/** Reads a socket's events in order until done, error, or close. */
+async function* readEvents(ws, push) {
+    const queue = [];
+    let resolveNext = undefined;
+    let done = false;
+    ws.onmessage = (msg) => {
+        push(msg, queue);
+        resolveNext?.();
+    };
+    ws.onclose = () => {
+        done = true;
+        resolveNext?.();
+    };
+    ws.onerror = () => {
+        done = true;
+        resolveNext?.();
+    };
+    while (true) {
+        if (queue.length > 0) {
+            const event = queue.shift();
+            yield event;
+            if (event.event === 'done' || event.event === 'error')
+                break;
+        }
+        else if (done) {
+            break;
+        }
+        else {
+            await new Promise((resolve) => { resolveNext = resolve; });
+        }
+    }
+}
+/** Streaming text generation on `path`. A singular Tool forces it; an array lets the model choose. */
+export async function* streamText(authorization, path, model, options = {}) {
+    const toolDefs = options.tools
+        ? (Array.isArray(options.tools) ? options.tools.map((t) => t.function) : options.tools.function)
+        : undefined;
+    const tools = options.tools
+        ? (Array.isArray(options.tools) ? options.tools : [options.tools])
+        : undefined;
+    const serializedMessages = await prepareMessages(authorization, options.content ?? []);
+    const ws = new WebSocket(socketUrl(path, authorization, options.group));
+    // Cancellation: closing the socket makes the server stop streaming and ends
+    // the read loop (onclose flips `done`). Wired before connecting so an abort
+    // during the handshake still tears the socket down.
+    const onAbort = () => { try {
+        ws.close();
+    }
+    catch { } };
+    if (options.signal) {
+        if (options.signal.aborted)
+            onAbort();
+        else
+            options.signal.addEventListener('abort', onAbort);
+    }
+    try {
+        await new Promise((resolve, reject) => {
+            ws.onopen = () => resolve();
+            ws.onerror = () => reject(new Error('WebSocket connection failed'));
+        });
+        if (options.signal?.aborted)
+            return;
+        ws.send(JSON.stringify({
+            event: 'generate',
+            model,
+            messages: serializedMessages,
+            tools: toolDefs,
+            maxTools: options.maxTools,
+            memories: options.memories,
+            reasoning: options.reasoning,
+        }));
+        ws.send(JSON.stringify({ event: 'start' }));
+        yield* readEvents(ws, (msg, queue) => {
+            try {
+                const event = JSON.parse(msg.data);
+                // Server-handled tools are forwarded only for rendering: the server
+                // already ran them and won't accept a result.
+                if (event.event === 'tool_call' && !event.server && tools) {
+                    replyToolResult(ws, tools, event);
+                }
+                queue.push(event);
+            }
+            catch { }
+        });
+    }
+    finally {
+        options.signal?.removeEventListener('abort', onAbort);
+        try {
+            ws.close();
+        }
+        catch { }
+    }
+}
+/** Buffers a text stream into a TextResponse. */
+export async function collectText(stream) {
+    let text = '';
+    let usage = { promptTokens: 0, completionTokens: 0 };
+    for await (const event of stream) {
+        if (event.event === 'text') {
+            text += event.delta;
+        }
+        else if (event.event === 'done') {
+            usage = event.usage;
+        }
+        else if (event.event === 'error') {
+            const err = new Error(event.message);
+            if (event.code)
+                err.code = event.code;
+            throw err;
+        }
+    }
+    return { content: { parts: [{ type: 'TEXT', text }], role: Role.MODEL, createdAt: new Date() }, usage };
+}
+/** Realtime voice on `path`: PCM16 16 kHz in from `audio`, PCM16 24 kHz out as audio events. */
+export async function* streamVoice(authorization, path, model, options = {}) {
+    const toolDefs = options.tools
+        ? (Array.isArray(options.tools) ? options.tools.map((t) => t.function) : options.tools.function)
+        : undefined;
+    const tools = options.tools
+        ? (Array.isArray(options.tools) ? options.tools : [options.tools])
+        : undefined;
+    const serializedMessages = await prepareMessages(authorization, options.content ?? []);
+    const ws = new WebSocket(socketUrl(path, authorization, options.group));
+    ws.binaryType = 'arraybuffer';
+    const onAbort = () => { try {
+        ws.close();
+    }
+    catch { } };
+    if (options.signal) {
+        if (options.signal.aborted)
+            onAbort();
+        else
+            options.signal.addEventListener('abort', onAbort);
+    }
+    try {
+        await new Promise((resolve, reject) => {
+            ws.onopen = () => resolve();
+            ws.onerror = () => reject(new Error('WebSocket connection failed'));
+        });
+        if (options.signal?.aborted)
+            return;
+        ws.send(JSON.stringify({
+            event: 'generate',
+            model,
+            messages: serializedMessages,
+            tools: toolDefs,
+            maxTools: options.maxTools,
+            voice: options.voice,
+            memories: options.memories,
+        }));
+        ws.send(JSON.stringify({ event: 'start' }));
+        if (options.audio) {
+            void (async () => {
+                try {
+                    for await (const chunk of options.audio) {
+                        if (ws.readyState !== WebSocket.OPEN)
+                            break;
+                        ws.send(chunk);
+                    }
+                }
+                catch { }
+            })();
+        }
+        yield* readEvents(ws, (msg, queue) => {
+            const data = msg.data;
+            if (typeof data !== 'string') {
+                queue.push({ event: 'audio', delta: toBytes(data), contentType: 'audio/pcm' });
+                return;
+            }
+            try {
+                const parsed = JSON.parse(data);
+                if (parsed.event === 'audio') {
+                    queue.push({ event: 'audio', delta: decodeAudioDelta(parsed.delta), contentType: 'audio/pcm' });
+                }
+                else {
+                    const event = parsed;
+                    if (event.event === 'tool_call' && !parsed.server && tools) {
+                        replyToolResult(ws, tools, event);
+                    }
+                    queue.push(event);
+                }
+            }
+            catch { }
+        });
+    }
+    finally {
+        options.signal?.removeEventListener('abort', onAbort);
+        try {
+            ws.close();
+        }
+        catch { }
+    }
+}
+/** Buffers a voice stream: the audio as one PCM file, then the input and output transcripts. */
+export async function collectVoice(authorization, stream) {
+    const audio = [];
+    let inputTranscript = '';
+    let outputTranscript = '';
+    let usage = { promptTokens: 0, completionTokens: 0 };
+    for await (const event of stream) {
+        if (event.event === 'audio') {
+            audio.push(event.delta);
+        }
+        else if (event.event === 'input_transcript') {
+            inputTranscript += event.delta;
+        }
+        else if (event.event === 'output_transcript') {
+            outputTranscript += event.delta;
+        }
+        else if (event.event === 'done') {
+            usage = event.usage;
+        }
+        else if (event.event === 'error') {
+            const err = new Error(event.message);
+            if (event.code)
+                err.code = event.code;
+            throw err;
+        }
+    }
+    const parts = [];
+    if (audio.length > 0) {
+        parts.push({
+            type: 'FILE',
+            file: fromBytes(authorization, 'voice.pcm', 'audio/pcm', concatBytes(audio)),
+        });
+    }
+    if (inputTranscript)
+        parts.push({ type: 'TEXT', text: inputTranscript });
+    if (outputTranscript)
+        parts.push({ type: 'TEXT', text: outputTranscript });
+    return { content: { parts, role: Role.MODEL, createdAt: new Date() }, usage };
+}

package/dist/src/payments.d.ts

@@ -0,0 +1,73 @@
+import { ApiKey, Credentials } from "./authentification.js";
+export type PaymentStatus = 'pending' | 'succeeded' | 'expired' | 'refunded' | 'disputed';
+/** A payment to a person through their payout account. Amounts are in dollars. */
+export type Payment = {
+    id: string;
+    status: PaymentStatus;
+    amount: number;
+    /** Fauna's fee, taken from what the payee receives. */
+    fee: number;
+    refunded: number;
+    currency: string;
+    /** The payee's email. */
+    payee: string;
+    payer?: string;
+    /** Your own label, to find the payment again. */
+    reference: string;
+    description: string;
+    created: Date;
+    /** Where the payer pays. Only returned by `create`. */
+    url?: string;
+};
+/** What `create` needs. `amount` is in dollars; usd is the only currency for now. */
+export type PaymentRequest = {
+    /** Email of the Fauna account that gets paid. */
+    payee: string;
+    amount: number;
+    payer?: string;
+    currency?: string;
+    description?: string;
+    reference?: string;
+    /** Where Checkout sends the payer back, with ?payment=paid or ?payment=cancelled. */
+    returnUrl?: string;
+    cancelUrl?: string;
+};
+/** Whether you can be paid. Payments need `chargesEnabled`. */
+export type Payouts = {
+    connected: boolean;
+    chargesEnabled: boolean;
+    payoutsEnabled: boolean;
+    detailsSubmitted: boolean;
+};
+/** What a payment of `amount` costs: Fauna's fee and what the payee receives. */
+export type Quote = {
+    amount: number;
+    fee: number;
+    payout: number;
+};
+/** Start or continue setting up payouts. Open the returned URL; Stripe sends you back with ?payouts=connected. */
+export declare function connect(credentials: Credentials, options?: {
+    returnUrl?: string;
+}): Promise<{
+    url: string;
+}>;
+export declare function payouts(credentials: Credentials): Promise<Payouts>;
+/** A link into your payouts dashboard: balance, payouts and bank details. */
+export declare function dashboard(credentials: Credentials): Promise<{
+    url: string;
+}>;
+export declare function quote(authorization: Credentials | ApiKey, amount: number): Promise<Quote>;
+/**
+ * Ask for a payment to `payee`. Send the payer to the returned `url`. With an API
+ * key, that key's webhooks hear `payment.succeeded`, `payment.expired`,
+ * `payment.refunded` and `payment.disputed`.
+ */
+export declare function create(authorization: Credentials | ApiKey, request: PaymentRequest): Promise<Payment>;
+/** A payment you made, paid or are paid by. */
+export declare function get(authorization: Credentials | ApiKey, id: string): Promise<Payment>;
+/** Payments you asked for, newest first, optionally those with one reference. */
+export declare function list(authorization: Credentials | ApiKey, query?: {
+    reference?: string;
+}): Promise<Payment[]>;
+/** Refund a completed payment in full, Fauna's fee included. Whoever made it, or its payee, can. */
+export declare function refund(authorization: Credentials | ApiKey, id: string): Promise<Payment>;

package/dist/src/payments.js

@@ -0,0 +1,107 @@
+import { Fauna } from "../index.js";
+function hydrate(raw) {
+    return { ...raw, created: new Date(raw.created) };
+}
+/** Start or continue setting up payouts. Open the returned URL; Stripe sends you back with ?payouts=connected. */
+export async function connect(credentials, options = {}) {
+    const response = await fetch(`${Fauna.getURL()}/payments/payouts/connect`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": `Token ${credentials.token}`
+        },
+        body: JSON.stringify({ returnUrl: options.returnUrl })
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    return await response.json();
+}
+export async function payouts(credentials) {
+    const response = await fetch(`${Fauna.getURL()}/payments/payouts`, {
+        method: "GET",
+        headers: {
+            "Authorization": `Token ${credentials.token}`
+        }
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    return await response.json();
+}
+/** A link into your payouts dashboard: balance, payouts and bank details. */
+export async function dashboard(credentials) {
+    const response = await fetch(`${Fauna.getURL()}/payments/payouts/dashboard`, {
+        method: "POST",
+        headers: {
+            "Authorization": `Token ${credentials.token}`
+        }
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    return await response.json();
+}
+export async function quote(authorization, amount) {
+    const response = await fetch(`${Fauna.getURL()}/payments/quote?amount=${encodeURIComponent(String(amount))}`, {
+        method: "GET",
+        headers: {
+            "Authorization": 'email' in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`
+        }
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    return await response.json();
+}
+/**
+ * Ask for a payment to `payee`. Send the payer to the returned `url`. With an API
+ * key, that key's webhooks hear `payment.succeeded`, `payment.expired`,
+ * `payment.refunded` and `payment.disputed`.
+ */
+export async function create(authorization, request) {
+    const response = await fetch(`${Fauna.getURL()}/payments`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": 'email' in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`
+        },
+        body: JSON.stringify(request)
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    return hydrate(await response.json());
+}
+/** A payment you made, paid or are paid by. */
+export async function get(authorization, id) {
+    const response = await fetch(`${Fauna.getURL()}/payments/${encodeURIComponent(id)}`, {
+        method: "GET",
+        headers: {
+            "Authorization": 'email' in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`
+        }
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    return hydrate(await response.json());
+}
+/** Payments you asked for, newest first, optionally those with one reference. */
+export async function list(authorization, query = {}) {
+    const search = query.reference !== undefined ? `?reference=${encodeURIComponent(query.reference)}` : '';
+    const response = await fetch(`${Fauna.getURL()}/payments${search}`, {
+        method: "GET",
+        headers: {
+            "Authorization": 'email' in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`
+        }
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    return (await response.json()).map(hydrate);
+}
+/** Refund a completed payment in full, Fauna's fee included. Whoever made it, or its payee, can. */
+export async function refund(authorization, id) {
+    const response = await fetch(`${Fauna.getURL()}/payments/${encodeURIComponent(id)}/refund`, {
+        method: "POST",
+        headers: {
+            "Authorization": 'email' in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`
+        }
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    return hydrate(await response.json());
+}