fauna-api 1.0.686 → 1.0.693

package/dist/src/groups.js

@@ -1,5 +1,95 @@
 import { Fauna } from "../index.js";
 import { LastMessage } from "./parrot/chat.js";
+export const GroupRef = {
+    fromJSON(json) {
+        return {
+            id: String(json.id),
+            name: String(json.name),
+            ...(json.icon ? { icon: String(json.icon) } : {}),
+        };
+    },
+};
+export const GroupMember = {
+    fromJSON(json) {
+        return {
+            email: String(json.email),
+            ...(json.displayName ? { displayName: String(json.displayName) } : {}),
+            ...(json.icon ? { icon: String(json.icon) } : {}),
+            through: String(json.through),
+        };
+    },
+};
+export const Group = {
+    fromJSON(json) {
+        return {
+            id: String(json.id),
+            name: String(json.name),
+            ...(json.icon ? { icon: String(json.icon) } : {}),
+            balance: Number(json.balance),
+            createdAt: new Date(json.createdAt),
+            admins: json.admins.map(String),
+            people: json.people.map(String),
+            groups: json.groups.map(GroupRef.fromJSON),
+            members: json.members.map(GroupMember.fromJSON),
+            through: String(json.through),
+        };
+    },
+};
+export const JoinLink = {
+    fromJSON(json) {
+        return {
+            code: String(json.code),
+            uses: Number(json.uses),
+            ...(typeof json.maxUses === 'number' ? { maxUses: json.maxUses } : {}),
+            expires: new Date(json.expires),
+        };
+    },
+};
+export const GroupSummary = {
+    fromJSON(json) {
+        return {
+            id: String(json.id),
+            name: String(json.name),
+            ...(json.icon ? { icon: String(json.icon) } : {}),
+            memberCount: Number(json.memberCount),
+        };
+    },
+};
+export const MatchedGroup = {
+    fromJSON(json) {
+        return { ...GroupSummary.fromJSON(json), through: String(json.through) };
+    },
+};
+export const GroupMatch = {
+    fromJSON(json) {
+        return {
+            profile: {
+                email: String(json.profile.email),
+                ...(json.profile.displayName ? { displayName: String(json.profile.displayName) } : {}),
+                ...(json.profile.icon ? { icon: String(json.profile.icon) } : {}),
+            },
+            groups: json.groups.map(MatchedGroup.fromJSON),
+        };
+    },
+};
+export const GroupNest = {
+    fromJSON(json) {
+        return {
+            token: String(json.token),
+            parent: GroupRef.fromJSON(json.parent),
+            child: GroupRef.fromJSON(json.child),
+            from: json.from === 'child' ? 'child' : 'parent',
+            ...(json.by ? { by: String(json.by) } : {}),
+            expires: new Date(json.expires),
+        };
+    },
+};
+export const NestOffer = {
+    fromJSON(json) {
+        return json.nested === true ? { nested: true } : { nested: false, token: String(json.token) };
+    },
+};
+/** Start a group. You are its first admin. Needs a subscription. */
 export async function create(credentials, name) {
     const response = await fetch(`${Fauna.getURL()}/groups`, {
         method: "POST",
@@ -12,9 +102,10 @@ export async function create(credentials, name) {
     if (!response.ok) {
         throw new Error(await response.text());
     }
-    const raw = await response.json();
-    return { ...raw, createdAt: new Date(raw.createdAt) };
+    return Group.fromJSON(await response.json());
 }
+/** Every group you are in, directly or through a nested group, oldest first.
+ *  Each says how you are in it (`through`). */
 export async function list(authorization) {
     const response = await fetch(`${Fauna.getURL()}/groups`, {
         method: "GET",
@@ -25,11 +116,10 @@ export async function list(authorization) {
     if (!response.ok) {
         throw new Error(await response.text());
     }
-    const raw = await response.json();
-    return raw.map((group) => ({ ...group, createdAt: new Date(group.createdAt) }));
+    return (await response.json()).map(Group.fromJSON);
 }
-/** People matching a partial email or name, best first, each with their groups.
- *  Only people in at least one group come back. */
+/** People matching a partial email or name, best first, each with every group
+ *  they are in and how. Only people in at least one group come back. */
 export async function query(authorization, profile) {
     const response = await fetch(`${Fauna.getURL()}/groups/query`, {
         method: "POST",
@@ -42,7 +132,7 @@ export async function query(authorization, profile) {
     if (!response.ok) {
         throw new Error(await response.text());
     }
-    return await response.json();
+    return (await response.json()).map(GroupMatch.fromJSON);
 }
 /** Name, icon and member count of groups by id, including groups you are not in.
  *  Unknown ids are left out. */
@@ -58,8 +148,9 @@ export async function summaries(authorization, ids) {
     if (!response.ok) {
         throw new Error(await response.text());
     }
-    return await response.json();
+    return (await response.json()).map(GroupSummary.fromJSON);
 }
+/** A group you are in, directly or through a nested group. */
 export async function get(authorization, id) {
     const response = await fetch(`${Fauna.getURL()}/groups/${encodeURIComponent(id)}`, {
         method: "GET",
@@ -70,9 +161,9 @@ export async function get(authorization, id) {
     if (!response.ok) {
         throw new Error(await response.text());
     }
-    const raw = await response.json();
-    return { ...raw, createdAt: new Date(raw.createdAt) };
+    return Group.fromJSON(await response.json());
 }
+/** Change the group's name or icon. Admins only. */
 export async function edit(credentials, id, update) {
     const response = await fetch(`${Fauna.getURL()}/groups/${encodeURIComponent(id)}`, {
         method: "PATCH",
@@ -85,14 +176,27 @@ export async function edit(credentials, id, update) {
     if (!response.ok) {
         throw new Error(await response.text());
     }
-    const raw = await response.json();
-    return { ...raw, createdAt: new Date(raw.createdAt) };
+    return Group.fromJSON(await response.json());
 }
-/** Add a user to a group by email. Resolves `{ status: 'added' }` if they were
- *  added directly (they have a Fauna account), or `{ status: 'invited', token }`
- *  if a pending invite was stored instead (no Fauna account for that email yet).
- *  Fauna emails the invite unless `notify` is false, so an app can send its own
- *  email carrying the token. */
+/** Delete a group with its chats, files, calendar, rooms, webhooks and
+ *  partnerships. It leaves every group it was in; the groups inside it stay.
+ *  Its direct admins may, and so may anyone holding `fauna/groups:delete:global`. */
+export async function remove(credentials, id) {
+    const response = await fetch(`${Fauna.getURL()}/groups/${encodeURIComponent(id)}`, {
+        method: "DELETE",
+        headers: {
+            "Authorization": `Token ${credentials.token}`
+        }
+    });
+    if (!response.ok) {
+        throw new Error(await response.text());
+    }
+}
+/** Invite an email to a group. Admins only. Nobody joins until they accept the
+ *  invite with its token (`acceptInvite`), whether or not the email already has
+ *  a Fauna account, and the answer is the same either way. Fauna emails the
+ *  invite unless `notify` is false, so an app can send its own email carrying
+ *  the token. Resolves to the token. */
 export async function invite(credentials, id, email, options = {}) {
     const response = await fetch(`${Fauna.getURL()}/groups/${encodeURIComponent(id)}/invite`, {
         method: "POST",
@@ -105,9 +209,10 @@ export async function invite(credentials, id, email, options = {}) {
     if (!response.ok) {
         throw new Error(await response.text());
     }
-    return await response.json();
+    return (await response.json()).token;
 }
-/** Join the group an email invite points at, using the token from the invite. */
+/** Join the group an email invite points at, using the token from the invite.
+ *  `alreadyMember` says you were directly in it already. */
 export async function acceptInvite(credentials, token) {
     const response = await fetch(`${Fauna.getURL()}/groups/invites/accept`, {
         method: "POST",
@@ -121,17 +226,19 @@ export async function acceptInvite(credentials, token) {
         throw new Error(await response.text());
     }
     const raw = await response.json();
-    return {
-        group: { ...raw.group, createdAt: new Date(raw.group.createdAt) },
-        alreadyMember: raw.alreadyMember
-    };
+    return { group: Group.fromJSON(raw.group), alreadyMember: raw.alreadyMember === true };
 }
-export async function generateLink(credentials, id) {
+/** A join code good for seven days. Admins only. People join with it, and admins
+ *  of other groups put their group inside this one with it. `maxUses` caps how
+ *  many it lets in; without it, any number can join until it expires. */
+export async function generateLink(credentials, id, options = {}) {
     const response = await fetch(`${Fauna.getURL()}/groups/${encodeURIComponent(id)}/link`, {
         method: "POST",
         headers: {
+            "Content-Type": "application/json",
             "Authorization": `Token ${credentials.token}`
-        }
+        },
+        body: JSON.stringify({ maxUses: options.maxUses })
     });
     if (!response.ok) {
         throw new Error(await response.text());
@@ -139,24 +246,52 @@ export async function generateLink(credentials, id) {
     const json = await response.json();
     return json.code;
 }
-export async function join(credentials, code) {
+/** The group's join links that still work, newest first. Admins only. */
+export async function links(credentials, id) {
+    const response = await fetch(`${Fauna.getURL()}/groups/${encodeURIComponent(id)}/links`, {
+        method: "GET",
+        headers: {
+            "Authorization": `Token ${credentials.token}`
+        }
+    });
+    if (!response.ok) {
+        throw new Error(await response.text());
+    }
+    return (await response.json()).map(JoinLink.fromJSON);
+}
+/** A join link stops working. Admins only. */
+export async function revokeLink(credentials, id, code) {
+    const response = await fetch(`${Fauna.getURL()}/groups/${encodeURIComponent(id)}/links/${encodeURIComponent(code)}`, {
+        method: "DELETE",
+        headers: {
+            "Authorization": `Token ${credentials.token}`
+        }
+    });
+    if (!response.ok) {
+        throw new Error(await response.text());
+    }
+}
+/** Join a group with a join code. With `group`, a group you administer goes
+ *  inside it instead, and you are in it through that group. `alreadyMember` says
+ *  you (or `group`) were in it already. */
+export async function join(credentials, code, group) {
     const response = await fetch(`${Fauna.getURL()}/groups/join`, {
         method: "POST",
         headers: {
             "Content-Type": "application/json",
             "Authorization": `Token ${credentials.token}`
         },
-        body: JSON.stringify({ code })
+        body: JSON.stringify({ code, group })
     });
     if (!response.ok) {
         throw new Error(await response.text());
     }
     const raw = await response.json();
-    return {
-        group: { ...raw.group, createdAt: new Date(raw.group.createdAt) },
-        alreadyMember: raw.alreadyMember
-    };
+    return { group: Group.fromJSON(raw.group), alreadyMember: raw.alreadyMember === true };
 }
+/** Leave a group you are directly in. The last admin can't while anyone else is
+ *  in it, directly or through a nested group: make someone else an admin, or
+ *  delete the group. When nobody else is in it, leaving deletes it. */
 export async function leave(credentials, id) {
     const response = await fetch(`${Fauna.getURL()}/groups/${encodeURIComponent(id)}/membership`, {
         method: "DELETE",
@@ -168,6 +303,7 @@ export async function leave(credentials, id) {
         throw new Error(await response.text());
     }
 }
+/** Remove a person who is directly in the group. Admins only. */
 export async function kick(credentials, id, email) {
     const response = await fetch(`${Fauna.getURL()}/groups/${encodeURIComponent(id)}/members/${encodeURIComponent(email)}`, {
         method: "DELETE",
@@ -179,6 +315,126 @@ export async function kick(credentials, id, email) {
         throw new Error(await response.text());
     }
 }
+/** Make a person who is directly in the group an admin. Admins only. Someone in
+ *  it only through a nested group is invited directly first. */
+export async function promote(credentials, id, email) {
+    const response = await fetch(`${Fauna.getURL()}/groups/${encodeURIComponent(id)}/admins/${encodeURIComponent(email)}`, {
+        method: "POST",
+        headers: {
+            "Authorization": `Token ${credentials.token}`
+        }
+    });
+    if (!response.ok) {
+        throw new Error(await response.text());
+    }
+    return Group.fromJSON(await response.json());
+}
+/** Make an admin a member again. Admins only; a group keeps at least one admin. */
+export async function demote(credentials, id, email) {
+    const response = await fetch(`${Fauna.getURL()}/groups/${encodeURIComponent(id)}/admins/${encodeURIComponent(email)}`, {
+        method: "DELETE",
+        headers: {
+            "Authorization": `Token ${credentials.token}`
+        }
+    });
+    if (!response.ok) {
+        throw new Error(await response.text());
+    }
+    return Group.fromJSON(await response.json());
+}
+/** Invite group `child` inside group `id`; the child's admins accept with the
+ *  token (`acceptNest`). Admins of `id` only. Nests at once when you administer
+ *  both. Unless `notify` is false, the child's admins hear about it in their
+ *  Fauna inbox. Nesting is at most 5 groups deep and never makes a loop. */
+export async function inviteGroup(credentials, id, child, options = {}) {
+    const response = await fetch(`${Fauna.getURL()}/groups/${encodeURIComponent(id)}/groups`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": `Token ${credentials.token}`
+        },
+        body: JSON.stringify({ group: child, notify: options.notify })
+    });
+    if (!response.ok) {
+        throw new Error(await response.text());
+    }
+    return NestOffer.fromJSON(await response.json());
+}
+/** Ask to put group `id` inside group `parent`; the parent's admins approve with
+ *  the token (`acceptNest`). Admins of `id` only. Nests at once when you
+ *  administer both. Unless `notify` is false, the parent's admins hear about it
+ *  in their Fauna inbox. */
+export async function requestGroup(credentials, id, parent, options = {}) {
+    const response = await fetch(`${Fauna.getURL()}/groups/${encodeURIComponent(id)}/parents`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": `Token ${credentials.token}`
+        },
+        body: JSON.stringify({ group: parent, notify: options.notify })
+    });
+    if (!response.ok) {
+        throw new Error(await response.text());
+    }
+    return NestOffer.fromJSON(await response.json());
+}
+/** The invites and requests waiting on or from a group, newest first. Admins only. */
+export async function nests(credentials, id, query) {
+    const params = new URLSearchParams({ cursor: String(query.cursor), max: String(query.max) });
+    const response = await fetch(`${Fauna.getURL()}/groups/${encodeURIComponent(id)}/nests?${params}`, {
+        method: "GET",
+        headers: {
+            "Authorization": `Token ${credentials.token}`
+        }
+    });
+    if (!response.ok) {
+        throw new Error(await response.text());
+    }
+    return (await response.json()).map(GroupNest.fromJSON);
+}
+/** Accept an invite into a group, or approve a request to join one, by its
+ *  token. An admin of the side it waits on only. Resolves to the parent group. */
+export async function acceptNest(credentials, token) {
+    const response = await fetch(`${Fauna.getURL()}/groups/nests/accept`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": `Token ${credentials.token}`
+        },
+        body: JSON.stringify({ token })
+    });
+    if (!response.ok) {
+        throw new Error(await response.text());
+    }
+    return Group.fromJSON(await response.json());
+}
+/** Drop a waiting invite or request by its token. An admin of either group. */
+export async function revokeNest(credentials, token) {
+    const response = await fetch(`${Fauna.getURL()}/groups/nests/revoke`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": `Token ${credentials.token}`
+        },
+        body: JSON.stringify({ token })
+    });
+    if (!response.ok) {
+        throw new Error(await response.text());
+    }
+}
+/** Take group `child` out of group `id`. An admin of either group. Everyone who
+ *  was in `id` only through it loses it. */
+export async function unnest(credentials, id, child) {
+    const response = await fetch(`${Fauna.getURL()}/groups/${encodeURIComponent(id)}/groups/${encodeURIComponent(child)}`, {
+        method: "DELETE",
+        headers: {
+            "Authorization": `Token ${credentials.token}`
+        }
+    });
+    if (!response.ok) {
+        throw new Error(await response.text());
+    }
+}
 function hydratePartnership(raw) {
     return {
         ...raw,

package/dist/src/marmot/web.d.ts

@@ -162,8 +162,9 @@ export declare class DomRecorder {
     stop(): void;
 }
 /**
- * Re-render a `WebSnapshot` into a target document (typically an isolated iframe
- * or shadow root on the viewer) and apply incoming `WebMutation`s. The replayer
+ * Re-render a shared page into a frame inside `mount` and apply incoming `WebMutation`s.
+ * The page is someone else's, so the frame is sandboxed without scripts: the replayer
+ * writes into it from this page, and nothing the page carries ever runs. The replayer
  * keeps its own id->Node map mirroring the recorder's synthetic ids.
  */
 export declare class DomReplayer {
@@ -185,9 +186,15 @@ export declare class DomReplayer {
     } | null;
     private docRoot;
     /**
-     * Apply a full cleaned HTML document (or fragment). Uses an iframe when the
-     * payload looks like a full document so `<html>/<head>/<body>` structure and
-     * DFS ids match the host.
+     * A fresh frame for a replay, loaded with `srcdoc`. Same origin without scripts: this
+     * page can write into it, and the shared page can't run anything there. Null when a
+     * newer replay started while it loaded.
+     */
+    private openFrame;
+    private flushQueued;
+    /**
+     * Apply a cleaned HTML document, or a fragment, which the frame parses into one.
+     * The `<html>/<head>/<body>` structure and DFS ids match the host's.
      */
     applyHtml(html: string, viewport?: {
         width: number;
@@ -229,10 +236,11 @@ export declare class DomReplayer {
      */
     private mirrorStates;
     private ownerDoc;
+    /** `seen` keeps a subtree that names a node twice (or itself) from building forever. */
     private build;
     private buildFromList;
     /** Render a fresh snapshot, replacing whatever the mount currently holds. */
-    apply(snapshot: WebSnapshot): void;
+    apply(snapshot: WebSnapshot): Promise<void>;
     /** Apply one incremental mutation to the rendered tree. */
     mutate(mutation: WebMutation): void;
 }
@@ -249,10 +257,20 @@ export declare function pageToHtml(root?: Node): {
     clone: Element;
     cssUrls: string[];
 };
-/** Install a MutationObserver that posts WebMutations to `window[pushName]`.
+/** Install a MutationObserver that posts WebMutations to `window[pushName]` as
+ *  `{ token, mutation }`, so the host knows which recorder sent each one.
  *  Framed documents are walked, observed, and re-inlined on navigation, with
- *  their html, head, and body addressed as the divs `pageToHtml` emits. */
-export declare function pageInstallRecorder(pushName: string): void;
+ *  their html, head, and body addressed as the divs `pageToHtml` emits.
+ *  With `remoteFrames`, a frame whose document this page can't read is left to
+ *  the host, which streams it from the frame itself: its wrapper says
+ *  `data-fauna-iframe="remote"` and holds nothing. With `framed`, this document
+ *  is such a frame, recorded the way a parent would inline it, and
+ *  `__faunaRecorder.snapshot()` serializes it. */
+export declare function pageInstallRecorder(pushName: string, options: {
+    token: string;
+    framed?: boolean;
+    remoteFrames?: boolean;
+}): void;
 export declare function pageStopRecorder(): void;
 /** Runs in the page: the pointer at (x, y) with the CSS cursor of whatever is under it,
  *  looking inside frames the recorder inlines. */