fauna-api 0.0.0-stage → 1.0.676

package/dist/src/magpie/room.d.ts

@@ -0,0 +1,61 @@
+import { Credentials, ApiKey } from "../authentification.js";
+import { Group } from "../groups.js";
+import { Authorization, Presence, Room, Hooks as ServerHooks } from "../shared/server.js";
+import { ChatRoom, RoomHooks } from "../parrot/room.js";
+import type { Asset } from "./portfolio.js";
+import type { Explorer } from "./explorer.js";
+export type PortfolioEntry = Record<string, any> & {
+    id: string;
+};
+export declare class PortfolioRoom extends Room {
+    portfolioId: string;
+    name: string;
+    profile: Map<string, PortfolioEntry>;
+    constructor(endpoint: string, ws: WebSocket, authorization: Authorization, id: string);
+    hydrate(state: any): void;
+    handleEvent(packet: any): void;
+    getChat(hooks?: RoomHooks): Promise<{
+        room: ChatRoom;
+        self: Presence;
+        chatId: string;
+    }>;
+    static connect(authorization: Credentials | ApiKey, target: {
+        id: string;
+    }, opts?: {
+        group?: Group;
+        hooks?: ServerHooks;
+        server?: string;
+    }): Promise<{
+        room: PortfolioRoom;
+        self: Presence;
+    }>;
+    static join(authorization: Credentials | ApiKey, target: {
+        accessCode: string;
+    }, hooks?: ServerHooks): Promise<{
+        room: PortfolioRoom;
+        self: Presence;
+    }>;
+}
+export declare class ExplorerRoom extends Room {
+    host: string;
+    entries: Map<string, Explorer>;
+    constructor(endpoint: string, ws: WebSocket, authorization: Authorization, id: string);
+    hydrate(state: any): void;
+    handleEvent(packet: any): void;
+    setTicker(asset: Asset, ticker: string): void;
+    commitDrawing(explorer: Explorer): void;
+    clearDrawings(asset: Asset, ticker: string): void;
+    static connect(authorization: Credentials | ApiKey, opts?: {
+        hooks?: ServerHooks;
+        server?: string;
+    }): Promise<{
+        room: ExplorerRoom;
+        self: Presence;
+    }>;
+    static join(authorization: Credentials | ApiKey, target: {
+        accessCode: string;
+    }, hooks?: ServerHooks): Promise<{
+        room: ExplorerRoom;
+        self: Presence;
+    }>;
+}

package/dist/src/magpie/room.js

@@ -0,0 +1,238 @@
+import { Magpie } from "./index.js";
+import { Room, connect as connectServer } from "../shared/server.js";
+import { connectRoom } from "../parrot/room.js";
+function entryKey(entry) {
+    if (entry.id)
+        return entry.id;
+    if (entry.asset && entry.ticker)
+        return `${entry.asset}:${entry.ticker}`;
+    return "";
+}
+export class PortfolioRoom extends Room {
+    constructor(endpoint, ws, authorization, id) {
+        super(endpoint, ws, authorization, id);
+        Object.defineProperty(this, "portfolioId", {
+            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, "profile", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.portfolioId = id;
+        this.name = "";
+        this.profile = new Map();
+    }
+    hydrate(state) {
+        this.portfolioId = state?.id ?? this.portfolioId;
+        this.name = state?.name ?? this.name;
+        this.profile.clear();
+        for (const entry of state?.profile ?? []) {
+            const key = entryKey(entry);
+            if (key)
+                this.profile.set(key, entry);
+        }
+    }
+    handleEvent(packet) {
+        switch (packet.event) {
+            case "upsert-entry": {
+                const entry = packet.entry ?? packet.data?.entry;
+                const key = entry ? entryKey(entry) : "";
+                if (key)
+                    this.profile.set(key, entry);
+                break;
+            }
+            case "remove-entry": {
+                const id = packet.id ?? packet.data?.id;
+                if (id)
+                    this.profile.delete(id);
+                break;
+            }
+            case "update-portfolio": {
+                const portfolio = packet.portfolio ?? packet.data?.portfolio;
+                if (portfolio?.name)
+                    this.name = portfolio.name;
+                break;
+            }
+        }
+    }
+    async getChat(hooks) {
+        const auth = this.authorization;
+        const response = await fetch(`${Magpie.getURL()}/magpie/portfolio/chat/ensure`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: "email" in auth.authorization ? `Token ${auth.authorization.token}` : `ApiKey ${auth.authorization.id}`,
+                ...("accessCode" in auth
+                    ? { "Access-Code": auth.accessCode }
+                    : { Server: this.portfolioId, ...(auth.group ? { Group: auth.group } : {}) }),
+            },
+        });
+        if (!response.ok)
+            throw new Error(await response.text());
+        const { chatId, reference, code } = await response.json();
+        if (!chatId || !code)
+            throw new Error("Invalid ensure response.");
+        const guest = "accessCode" in this.authorization;
+        const target = guest
+            ? { code }
+            : { reference: reference || `parrot:chat:${chatId}` };
+        const { room, self } = await connectRoom(this.authorization.authorization, target, hooks ?? {});
+        return { room, self, chatId };
+    }
+    static async connect(authorization, target, opts) {
+        const server = opts?.server ?? target.id;
+        let room;
+        const user = opts?.hooks ?? {};
+        const self = await connectServer({ authorization, server, ...(opts?.group ? { group: opts.group.id } : {}) }, `${Magpie.getURL()}/magpie/portfolio`, {
+            ...user,
+            createRoom: (endpoint, ws, a, id, state) => {
+                room = (user.createRoom?.(endpoint, ws, a, id, state)
+                    ?? new PortfolioRoom(endpoint, ws, a, id));
+                return room;
+            },
+            onConnection: (r, state) => {
+                r.hydrate(state);
+                user.onConnection?.(r, state);
+            },
+            onEvent: (r, packet) => applyPortfolioEvent(r, packet, user),
+        });
+        return { room, self };
+    }
+    static async join(authorization, target, hooks) {
+        let room;
+        const user = hooks ?? {};
+        const self = await connectServer({ authorization, accessCode: target.accessCode }, `${Magpie.getURL()}/magpie/portfolio`, {
+            ...user,
+            createRoom: (endpoint, ws, a, id, state) => {
+                room = (user.createRoom?.(endpoint, ws, a, id, state)
+                    ?? new PortfolioRoom(endpoint, ws, a, id));
+                return room;
+            },
+            onConnection: (r, state) => {
+                r.hydrate(state);
+                user.onConnection?.(r, state);
+            },
+            onEvent: (r, packet) => applyPortfolioEvent(r, packet, user),
+        });
+        return { room, self };
+    }
+}
+function applyPortfolioEvent(room, packet, user) {
+    room.handleEvent(packet);
+    return user.onEvent?.(room, packet) ?? true;
+}
+function explorerKey(entry) {
+    if (!entry.asset || !entry.ticker)
+        return "";
+    return `${entry.asset}:${entry.ticker}`;
+}
+export class ExplorerRoom extends Room {
+    constructor(endpoint, ws, authorization, id) {
+        super(endpoint, ws, authorization, id);
+        Object.defineProperty(this, "host", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "entries", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.host = id;
+        this.entries = new Map();
+    }
+    hydrate(state) {
+        this.host = state?.host ?? this.host;
+        this.entries.clear();
+        for (const entry of state?.entries ?? []) {
+            const key = explorerKey(entry);
+            if (key)
+                this.entries.set(key, entry);
+        }
+    }
+    handleEvent(packet) {
+        switch (packet.event) {
+            case "upsert-entry": {
+                const entry = packet.entry ?? packet.data?.entry;
+                const key = entry ? explorerKey(entry) : "";
+                if (key)
+                    this.entries.set(key, entry);
+                break;
+            }
+            case "remove-entry": {
+                const ticker = packet.ticker ?? packet.data?.ticker;
+                const asset = packet.asset ?? packet.data?.asset;
+                const key = explorerKey({ ticker, asset });
+                if (key)
+                    this.entries.delete(key);
+                break;
+            }
+        }
+    }
+    setTicker(asset, ticker) {
+        this.post({ event: "set-ticker", asset, ticker });
+    }
+    commitDrawing(explorer) {
+        this.post({ event: "draw-commit", explorer });
+    }
+    clearDrawings(asset, ticker) {
+        this.post({ event: "draw-clear", asset, ticker });
+    }
+    static async connect(authorization, opts) {
+        // "me" is resolved on the edge to the caller's credentials principal.
+        // Client Credentials has no server id.
+        const server = opts?.server ?? "me";
+        let room;
+        const user = opts?.hooks ?? {};
+        const self = await connectServer({ authorization, server }, `${Magpie.getURL()}/magpie/explorer`, {
+            ...user,
+            createRoom: (endpoint, ws, a, id, state) => {
+                room = (user.createRoom?.(endpoint, ws, a, id, state)
+                    ?? new ExplorerRoom(endpoint, ws, a, id));
+                return room;
+            },
+            onConnection: (r, state) => {
+                r.hydrate(state);
+                user.onConnection?.(r, state);
+            },
+            onEvent: (r, packet) => applyExplorerEvent(r, packet, user),
+        });
+        return { room, self };
+    }
+    static async join(authorization, target, hooks) {
+        let room;
+        const user = hooks ?? {};
+        const self = await connectServer({ authorization, accessCode: target.accessCode }, `${Magpie.getURL()}/magpie/explorer`, {
+            ...user,
+            createRoom: (endpoint, ws, a, id, state) => {
+                room = (user.createRoom?.(endpoint, ws, a, id, state)
+                    ?? new ExplorerRoom(endpoint, ws, a, id));
+                return room;
+            },
+            onConnection: (r, state) => {
+                r.hydrate(state);
+                user.onConnection?.(r, state);
+            },
+            onEvent: (r, packet) => applyExplorerEvent(r, packet, user),
+        });
+        return { room, self };
+    }
+}
+function applyExplorerEvent(room, packet, user) {
+    room.handleEvent(packet);
+    return user.onEvent?.(room, packet) ?? true;
+}

package/dist/src/maps.d.ts

@@ -0,0 +1,159 @@
+import { Credentials, ApiKey } from "./authentification.js";
+import type { Group } from "./groups.js";
+export type Coordinates = {
+    latitude: number;
+    longitude: number;
+};
+/** A place to start or end at: coordinates, an address, or a place id. Set one. */
+export type Waypoint = {
+    coordinates?: Coordinates;
+    address?: string;
+    place?: string;
+};
+export type Place = {
+    id: string;
+    name: string;
+    address: string;
+    coordinates: Coordinates;
+};
+/** One autocomplete match. `place` resolves through `geocode({ place })`. */
+export type Suggestion = {
+    place: string;
+    name: string;
+    description: string;
+};
+export type TravelMode = 'drive' | 'walk' | 'transit' | 'flight';
+export type Money = {
+    amount: number;
+    currency: string;
+};
+/** One instruction along a route. Transit steps also carry the line, stops and times. */
+export type Step = {
+    mode: TravelMode;
+    instruction: string;
+    /** Meters. */
+    distance: number;
+    /** Seconds. */
+    duration: number;
+    line?: string;
+    vehicle?: string;
+    stops?: number;
+    from?: string;
+    to?: string;
+    departure?: Date;
+    arrival?: Date;
+};
+export type Route = {
+    mode: TravelMode;
+    /** Seconds. */
+    duration: number;
+    /** Meters. */
+    distance: number;
+    path: Coordinates[];
+    steps: Step[];
+    fare?: Money;
+    departure?: Date;
+    arrival?: Date;
+};
+export type Airport = {
+    code: string;
+    name: string;
+    city: string;
+    country: string;
+    coordinates: Coordinates;
+    /** Meters from the point searched. */
+    distance: number;
+    large: boolean;
+};
+export type Units = 'metric' | 'imperial';
+export type Condition = 'clear' | 'partly_cloudy' | 'cloudy' | 'fog' | 'rain' | 'showers' | 'thunderstorm' | 'snow' | 'sleet' | 'hail' | 'wind' | 'unknown';
+export type ForecastDay = {
+    /** The local date, YYYY-MM-DD. */
+    date: string;
+    high: number;
+    low: number;
+    condition: Condition;
+    summary: string;
+    /** Chance of precipitation, 0 to 100. */
+    precipitation: number;
+    wind: number;
+    sunrise?: Date;
+    sunset?: Date;
+};
+export type ForecastHour = {
+    time: Date;
+    temperature: number;
+    feelsLike: number;
+    condition: Condition;
+    summary: string;
+    precipitation: number;
+    wind: number;
+};
+/** Temperatures in °C and wind in km/h for metric, °F and mph for imperial. */
+export type Forecast = {
+    units: Units;
+    timeZone: string;
+    days: ForecastDay[];
+    hours: ForecastHour[];
+};
+export type MapTheme = 'light' | 'dark';
+/** What a map must show while its tiles are on screen. */
+export type Attribution = {
+    text: string;
+    logo: string;
+};
+/** Prepaid map tiles. The pass id is all a tile request needs, so map libraries can fetch tiles directly. */
+export type TilePass = {
+    id: string;
+    tiles: number;
+    expires: Date;
+    size: number;
+    maxZoom: number;
+    attribution: Attribution;
+};
+export type Bounds = {
+    north: number;
+    south: number;
+    east: number;
+    west: number;
+};
+/** Find places for an address, coordinates (reverse lookup) or a place id. */
+export declare function geocode(authorization: Credentials | ApiKey, query: Waypoint, group?: Group): Promise<Place[]>;
+export declare function searchPlaces(authorization: Credentials | ApiKey, text: string, options?: {
+    near?: Coordinates;
+    radius?: number;
+    max?: number;
+}, group?: Group): Promise<Place[]>;
+export declare function autocomplete(authorization: Credentials | ApiKey, text: string, options?: {
+    near?: Coordinates;
+}, group?: Group): Promise<Suggestion[]>;
+/** Drive, walk and transit routes between two waypoints, one per mode that has one. Flights come from Travel. */
+export declare function getRoutes(authorization: Credentials | ApiKey, from: Waypoint, to: Waypoint, options?: {
+    modes?: TravelMode[];
+    departure?: Date;
+    arrival?: Date;
+}, group?: Group): Promise<Route[]>;
+/** The nearest airports with scheduled flights, closest first. Free. */
+export declare function getAirports(authorization: Credentials | ApiKey, near: Coordinates, options?: {
+    max?: number;
+    large?: boolean;
+}): Promise<Airport[]>;
+/** Daily (up to 10) and hourly (up to 240) forecasts for a point. */
+export declare function getWeather(authorization: Credentials | ApiKey, at: Coordinates, options?: {
+    days?: number;
+    hours?: number;
+    units?: Units;
+}, group?: Group): Promise<Forecast>;
+/** Buy a pass for `tiles` map tiles (default 150). Tiles are billed up front, when the pass is bought. */
+export declare function createTilePass(authorization: Credentials | ApiKey, options?: {
+    theme?: MapTheme;
+    tiles?: number;
+    language?: string;
+    region?: string;
+}, group?: Group): Promise<TilePass>;
+/** A tile URL template with `{z}`, `{x}` and `{y}` left in, the way map libraries take them. */
+export declare function getTileURL(pass: TilePass): string;
+/** One map tile image, read as it streams in. */
+export declare function getTile(pass: TilePass, z: number, x: number, y: number, onLoaded?: (loadedBytes: number) => void): Promise<Uint8Array>;
+/** The attribution for what a map shows right now. Free; call it as the view moves. */
+export declare function getAttribution(pass: TilePass, zoom: number, bounds: Bounds): Promise<Attribution>;

package/dist/src/maps.js

@@ -0,0 +1,171 @@
+import { Fauna } from "../index.js";
+/** Find places for an address, coordinates (reverse lookup) or a place id. */
+export async function geocode(authorization, query, group) {
+    const response = await fetch(`${Fauna.getURL()}/maps/geocode`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": 'email' in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+            ...(group ? { "Group": group.id } : {})
+        },
+        body: JSON.stringify({ query })
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    return await response.json();
+}
+export async function searchPlaces(authorization, text, options = {}, group) {
+    const response = await fetch(`${Fauna.getURL()}/maps/places/search`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": 'email' in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+            ...(group ? { "Group": group.id } : {})
+        },
+        body: JSON.stringify({ text, near: options.near, radius: options.radius, max: options.max })
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    return await response.json();
+}
+export async function autocomplete(authorization, text, options = {}, group) {
+    const response = await fetch(`${Fauna.getURL()}/maps/places/autocomplete`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": 'email' in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+            ...(group ? { "Group": group.id } : {})
+        },
+        body: JSON.stringify({ text, near: options.near })
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    return await response.json();
+}
+/** Drive, walk and transit routes between two waypoints, one per mode that has one. Flights come from Travel. */
+export async function getRoutes(authorization, from, to, options = {}, group) {
+    const response = await fetch(`${Fauna.getURL()}/maps/routes`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": 'email' in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+            ...(group ? { "Group": group.id } : {})
+        },
+        body: JSON.stringify({ from, to, modes: options.modes, departure: options.departure, arrival: options.arrival })
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    const routes = await response.json();
+    return routes.map((route) => ({
+        ...route,
+        departure: route.departure ? new Date(route.departure) : undefined,
+        arrival: route.arrival ? new Date(route.arrival) : undefined,
+        steps: route.steps.map((step) => ({
+            ...step,
+            departure: step.departure ? new Date(step.departure) : undefined,
+            arrival: step.arrival ? new Date(step.arrival) : undefined,
+        })),
+    }));
+}
+/** The nearest airports with scheduled flights, closest first. Free. */
+export async function getAirports(authorization, near, options = {}) {
+    const response = await fetch(`${Fauna.getURL()}/maps/airports`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": 'email' in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`
+        },
+        body: JSON.stringify({ near, max: options.max, large: options.large })
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    return await response.json();
+}
+/** Daily (up to 10) and hourly (up to 240) forecasts for a point. */
+export async function getWeather(authorization, at, options = {}, group) {
+    const response = await fetch(`${Fauna.getURL()}/maps/weather`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": 'email' in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+            ...(group ? { "Group": group.id } : {})
+        },
+        body: JSON.stringify({ at, days: options.days, hours: options.hours, units: options.units })
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    const forecast = await response.json();
+    return {
+        ...forecast,
+        days: forecast.days.map((day) => ({
+            ...day,
+            sunrise: day.sunrise ? new Date(day.sunrise) : undefined,
+            sunset: day.sunset ? new Date(day.sunset) : undefined,
+        })),
+        hours: forecast.hours.map((hour) => ({ ...hour, time: new Date(hour.time) })),
+    };
+}
+/** Buy a pass for `tiles` map tiles (default 150). Tiles are billed up front, when the pass is bought. */
+export async function createTilePass(authorization, options = {}, group) {
+    const response = await fetch(`${Fauna.getURL()}/maps/tiles/pass`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": 'email' in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+            ...(group ? { "Group": group.id } : {})
+        },
+        body: JSON.stringify({ theme: options.theme, tiles: options.tiles, language: options.language, region: options.region })
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    const pass = await response.json();
+    return { ...pass, expires: new Date(pass.expires) };
+}
+/** A tile URL template with `{z}`, `{x}` and `{y}` left in, the way map libraries take them. */
+export function getTileURL(pass) {
+    return `${Fauna.getURL()}/maps/tile?pass=${encodeURIComponent(pass.id)}&z={z}&x={x}&y={y}`;
+}
+/** One map tile image, read as it streams in. */
+export async function getTile(pass, z, x, y, onLoaded) {
+    const response = await fetch(`${Fauna.getURL()}/maps/tile?pass=${encodeURIComponent(pass.id)}&z=${z}&x=${x}&y=${y}`, {
+        method: "GET"
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    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;
+}
+/** The attribution for what a map shows right now. Free; call it as the view moves. */
+export async function getAttribution(pass, zoom, bounds) {
+    const query = new URLSearchParams({
+        pass: pass.id,
+        zoom: String(zoom),
+        north: String(bounds.north),
+        south: String(bounds.south),
+        east: String(bounds.east),
+        west: String(bounds.west),
+    });
+    const response = await fetch(`${Fauna.getURL()}/maps/tiles/attribution?${query}`, {
+        method: "GET"
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    return await response.json();
+}