fauna-api 1.0.692 → 1.0.694

package/dist/src/authentification.d.ts

@@ -67,9 +67,9 @@ export declare function revokeSession(credentials: Credentials, session: Session
 export declare function signOut(credentials: Credentials): Promise<boolean>;
 /** Ends every one of your sessions, this one too. */
 export declare function signOutEverywhere(credentials: Credentials): Promise<boolean>;
-/** A single use code that passes this session to another page or app for a minute, so the token never rides in a URL. */
+/** A single use code, good for a minute, that gives another page or app a new session of the same person, so no token rides in a URL. */
 export declare function handoff(credentials: Credentials): Promise<string>;
-/** Uses up a handoff code for the session token it passes. */
+/** Uses up a handoff code for the new session token it carries. */
 export declare function redeemHandoff(code: string): Promise<Token>;
 export declare function allocateBalance(credentials: Credentials, target: ApiKey | Group, delta: number): Promise<true>;
 export declare function generateApiKey(credentials: Credentials): Promise<ApiKey>;

package/dist/src/authentification.js

@@ -216,7 +216,7 @@ export async function signOutEverywhere(credentials) {
     }
     return response.ok;
 }
-/** A single use code that passes this session to another page or app for a minute, so the token never rides in a URL. */
+/** A single use code, good for a minute, that gives another page or app a new session of the same person, so no token rides in a URL. */
 export async function handoff(credentials) {
     const response = await fetch(`${Fauna.getURL()}/authentification/handoff`, {
         method: "POST",
@@ -229,7 +229,7 @@ export async function handoff(credentials) {
     }
     return String((await response.json()).code);
 }
-/** Uses up a handoff code for the session token it passes. */
+/** Uses up a handoff code for the new session token it carries. */
 export async function redeemHandoff(code) {
     const response = await fetch(`${Fauna.getURL()}/authentification/handoff/redeem`, {
         method: "POST",

package/dist/src/cicada/inboxes.d.ts

@@ -1,7 +1,7 @@
 import { Cicada } from "./index.js";
 import { Platform } from "../integrations.js";
 import { Credentials, ApiKey } from "../authentification.js";
-import type { Text } from "../parrot/generative.js";
+import type { Text, Voice } from "../parrot/generative.js";
 export type InboxGroup = {
     id: string;
     name: string;
@@ -30,8 +30,12 @@ export declare function assign(authorization: Credentials | ApiKey, inboxId: str
 }): Promise<void>;
 export declare function listAccounts(authorization: Credentials | ApiKey, inboxId: string): Promise<InboxAccount[]>;
 /** `dailyLimit` and `spentToday` are dollars per UTC day; at the limit the agent pauses until midnight UTC. */
+/** `reasoning` is one of the text model's catalog tiers, empty for its default; `voiceModel`
+ *  is the realtime voice the agent talks with on calls, empty for the catalog's first. */
 export type AgentSettings = {
     model: Text;
+    reasoning: string;
+    voiceModel: Voice | '';
     instructions: string;
     dailyLimit: number;
     spentToday: number;
@@ -44,6 +48,8 @@ export declare function getAgent(authorization: Credentials | ApiKey, inbox: str
 /** Turns the agent on (it answers messages sent from now on) or updates it. */
 export declare function setAgent(authorization: Credentials | ApiKey, inbox: string, settings: {
     model: Text;
+    reasoning?: string;
+    voiceModel?: Voice;
     instructions: string;
     dailyLimit: number;
 }): Promise<AgentSettings>;

package/dist/src/cicada/inboxes.js

@@ -61,6 +61,8 @@ export const AgentSettings = {
     fromJSON(json) {
         return {
             model: json.model,
+            reasoning: String(json.reasoning ?? ''),
+            voiceModel: String(json.voiceModel ?? ''),
             instructions: String(json.instructions ?? ''),
             dailyLimit: Number(json.dailyLimit ?? 0),
             spentToday: Number(json.spentToday ?? 0),

package/dist/src/cicada/phone.d.ts

@@ -1,3 +1,4 @@
+import { Cicada } from "./index.js";
 import { Credentials, ApiKey } from "../authentification.js";
 import WebSocket from "isomorphic-ws";
 export type CallEnd = {
@@ -46,3 +47,47 @@ export declare function listen(authorization: Credentials | ApiKey, inbox: strin
 }>;
 /** Calls `to` from one of the inbox's phone lines: `from`, or its first line. */
 export declare function call(authorization: Credentials | ApiKey, inbox: string, to: string, from?: string): Promise<PhoneCall>;
+/** Where in a recording something was said, in milliseconds from its start. */
+export type CallSpan = {
+    startMs: number;
+    endMs: number;
+};
+/** One side speaking in a recorded call, each word timed. `You` is the inbox's side on a
+ *  call a person took or placed; `Agent` is the inbox's agent. */
+export type CallSegment = CallSpan & {
+    speaker: 'Them' | 'You' | 'Agent';
+    text: string;
+    words: CallSpan[];
+};
+/** A call on one of the inbox's lines, with its recording's timed transcript. */
+export type CallRecord = {
+    id: string;
+    direction: 'IN' | 'OUT';
+    /** The other party, E.164. */
+    peer: string;
+    /** The inbox's line, E.164. */
+    line: string;
+    status: string;
+    startedAt: Date;
+    /** Seconds it was connected. */
+    duration: number;
+    /** The inbox's agent took or placed it. */
+    agent: boolean;
+    /** A message left on the line, or a call that reached their voicemail. */
+    voicemail: boolean;
+    /** Its audio can be fetched with recording(). */
+    recorded: boolean;
+    segments: CallSegment[];
+};
+export declare const CallRecord: {
+    fromJSON(json: any): CallRecord;
+};
+/** The inbox's calls, newest first. `voicemails` keeps only voicemails; `query` matches what was said, the number, or the contact's name. */
+export declare function history(authorization: Credentials | ApiKey, inbox: string, opts?: {
+    voicemails?: boolean;
+    query?: string;
+    cursor?: number;
+    max?: number;
+}): Promise<CallRecord[]>;
+/** A recorded call's audio, MP3. */
+export declare function recording(authorization: Credentials | ApiKey, call: string): Promise<Blob>;

package/dist/src/cicada/phone.js

@@ -304,3 +304,49 @@ export async function listen(authorization, inbox, onIncoming) {
 export async function call(authorization, inbox, to, from) {
     return openCall(authorization, { event: 'dial', inbox, to, ...(from ? { from } : {}) });
 }
+export const CallRecord = {
+    fromJSON(json) {
+        return {
+            id: String(json.id),
+            direction: json.direction === 'in' ? 'IN' : 'OUT',
+            peer: String(json.peer ?? ''),
+            line: String(json.line ?? ''),
+            status: String(json.status ?? ''),
+            startedAt: new Date(json.startedAt),
+            duration: Number(json.duration ?? 0),
+            agent: Boolean(json.agent),
+            voicemail: Boolean(json.voicemail),
+            recorded: Boolean(json.recorded),
+            segments: Array.isArray(json.segments) ? json.segments : [],
+        };
+    },
+};
+/** The inbox's calls, newest first. `voicemails` keeps only voicemails; `query` matches what was said, the number, or the contact's name. */
+export async function history(authorization, inbox, opts = {}) {
+    const response = await fetch(`${Cicada.getURL()}/cicada/phone/history`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: 'email' in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+        },
+        body: JSON.stringify({ inbox, ...opts }),
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    const json = await response.json();
+    return (Array.isArray(json) ? json : []).map(CallRecord.fromJSON);
+}
+/** A recorded call's audio, MP3. */
+export async function recording(authorization, call) {
+    const response = await fetch(`${Cicada.getURL()}/cicada/phone/recording`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: 'email' in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+        },
+        body: JSON.stringify({ call }),
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    return await response.blob();
+}

package/dist/src/groups.d.ts

@@ -114,7 +114,19 @@ export type NestOffer = {
 export declare const NestOffer: {
     fromJSON(json: any): NestOffer;
 };
-/** Start a group. You are its first admin. Needs a subscription. */
+/** An email invite waiting to be accepted, as the group's admins see it. */
+export type EmailInvite = {
+    token: string;
+    email: string;
+    /** Email of the admin who sent it. */
+    by?: string;
+    expires: Date;
+};
+export declare const EmailInvite: {
+    fromJSON(json: any): EmailInvite;
+};
+/** Start a group. You are its first admin. Needs a subscription, and room under
+ *  `fauna/groups:N`, the most groups you may administer. */
 export declare function create(credentials: Credentials, name: string): Promise<Group>;
 /** Every group you are in, directly or through a nested group, oldest first.
  *  Each says how you are in it (`through`). */
@@ -147,11 +159,20 @@ export declare function acceptInvite(credentials: Credentials, token: string): P
     group: Group;
     alreadyMember: boolean;
 }>;
-/** 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. */
+/** The group's email invites waiting to be accepted, newest first. Admins only. */
+export declare function invites(credentials: Credentials, id: string, query: {
+    cursor: number;
+    max: number;
+}): Promise<EmailInvite[]>;
+/** An email invite stops working, by its token. An admin of its group, or whoever sent it. */
+export declare function revokeInvite(credentials: Credentials, token: string): Promise<void>;
+/** A join code. 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. It expires at `expires`,
+ *  in the future and at most a year out, or in seven days without it. */
 export declare function generateLink(credentials: Credentials, id: string, options?: {
     maxUses?: number;
+    expires?: Date;
 }): Promise<string>;
 /** The group's join links that still work, newest first. Admins only. */
 export declare function links(credentials: Credentials, id: string): Promise<JoinLink[]>;
@@ -171,7 +192,8 @@ export declare function leave(credentials: Credentials, id: string): Promise<voi
 /** Remove a person who is directly in the group. Admins only. */
 export declare function kick(credentials: Credentials, id: string, email: string): Promise<void>;
 /** 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. */
+ *  it only through a nested group is invited directly first. They need room under
+ *  their own `fauna/groups:N`, the most groups they may administer. */
 export declare function promote(credentials: Credentials, id: string, email: string): Promise<Group>;
 /** Make an admin a member again. Admins only; a group keeps at least one admin. */
 export declare function demote(credentials: Credentials, id: string, email: string): Promise<Group>;

package/dist/src/groups.js

@@ -89,7 +89,18 @@ export const NestOffer = {
         return json.nested === true ? { nested: true } : { nested: false, token: String(json.token) };
     },
 };
-/** Start a group. You are its first admin. Needs a subscription. */
+export const EmailInvite = {
+    fromJSON(json) {
+        return {
+            token: String(json.token),
+            email: String(json.email),
+            ...(json.by ? { by: String(json.by) } : {}),
+            expires: new Date(json.expires),
+        };
+    },
+};
+/** Start a group. You are its first admin. Needs a subscription, and room under
+ *  `fauna/groups:N`, the most groups you may administer. */
 export async function create(credentials, name) {
     const response = await fetch(`${Fauna.getURL()}/groups`, {
         method: "POST",
@@ -228,9 +239,36 @@ export async function acceptInvite(credentials, token) {
     const raw = await response.json();
     return { group: Group.fromJSON(raw.group), alreadyMember: raw.alreadyMember === true };
 }
-/** 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. */
+/** The group's email invites waiting to be accepted, newest first. Admins only. */
+export async function invites(credentials, id, query) {
+    const params = new URLSearchParams({ cursor: String(query.cursor), max: String(query.max) });
+    const response = await fetch(`${Fauna.getURL()}/groups/${encodeURIComponent(id)}/invites?${params}`, {
+        method: "GET",
+        headers: {
+            "Authorization": `Token ${credentials.token}`
+        }
+    });
+    if (!response.ok) {
+        throw new Error(await response.text());
+    }
+    return (await response.json()).map(EmailInvite.fromJSON);
+}
+/** An email invite stops working, by its token. An admin of its group, or whoever sent it. */
+export async function revokeInvite(credentials, token) {
+    const response = await fetch(`${Fauna.getURL()}/groups/invites/${encodeURIComponent(token)}`, {
+        method: "DELETE",
+        headers: {
+            "Authorization": `Token ${credentials.token}`
+        }
+    });
+    if (!response.ok) {
+        throw new Error(await response.text());
+    }
+}
+/** A join code. 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. It expires at `expires`,
+ *  in the future and at most a year out, or in seven days without it. */
 export async function generateLink(credentials, id, options = {}) {
     const response = await fetch(`${Fauna.getURL()}/groups/${encodeURIComponent(id)}/link`, {
         method: "POST",
@@ -238,7 +276,7 @@ export async function generateLink(credentials, id, options = {}) {
             "Content-Type": "application/json",
             "Authorization": `Token ${credentials.token}`
         },
-        body: JSON.stringify({ maxUses: options.maxUses })
+        body: JSON.stringify({ maxUses: options.maxUses, expires: options.expires?.toISOString() })
     });
     if (!response.ok) {
         throw new Error(await response.text());
@@ -316,7 +354,8 @@ export async function kick(credentials, id, email) {
     }
 }
 /** 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. */
+ *  it only through a nested group is invited directly first. They need room under
+ *  their own `fauna/groups:N`, the most groups they may administer. */
 export async function promote(credentials, id, email) {
     const response = await fetch(`${Fauna.getURL()}/groups/${encodeURIComponent(id)}/admins/${encodeURIComponent(email)}`, {
         method: "POST",

package/dist/src/webhooks.d.ts

@@ -1,6 +1,8 @@
 import { ApiKey, Credentials, Profile } from "./authentification.js";
-/** Event types a webhook can listen for: `chat.message` for groups and chats, payment events for API keys. */
-export type EventType = 'chat.message' | 'payment.succeeded' | 'payment.expired' | 'payment.refunded' | 'payment.disputed';
+import { GroupRef } from "./groups.js";
+/** Event types a webhook can listen for: `chat.message` for groups and chats,
+ *  `group.joined` and `group.left` for groups, payment events for API keys. */
+export type EventType = 'chat.message' | 'group.joined' | 'group.left' | 'payment.succeeded' | 'payment.expired' | 'payment.refunded' | 'payment.disputed';
 /** Who a webhook belongs to: a group, one chat, or the API key making the call. */
 export type WebhookOwner = {
     group: string;
@@ -51,6 +53,23 @@ export type ChatMessage = {
     /** Milliseconds since the epoch. */
     created: number;
 };
+/** Who came into a group or went out of it: a person, or a group nested directly inside it. */
+export type GroupChangeMember = {
+    email: string;
+} | {
+    group: GroupRef;
+};
+/** Why: `joined` for `group.joined`; for `group.left`, the person `left` or was
+ *  `removed` by an admin, or the nested group was `unnested` or `deleted`. */
+export type GroupChangeReason = 'joined' | 'left' | 'removed' | 'unnested' | 'deleted';
+/** `data` of `group.joined` and `group.left`: a person or a nested group came
+ *  directly into `group` or went directly out of it. Changes further down (someone
+ *  leaving a nested group) are told only to that group's own webhooks. */
+export type GroupChange = {
+    group: GroupRef;
+    member: GroupChangeMember;
+    reason: GroupChangeReason;
+};
 /**
  * Register a webhook for a group or a chat you can read, or, signed in with an
  * API key, for that key. In production `url` must be https on a public address.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fauna-api",
-  "version": "1.0.692",
+  "version": "1.0.694",
   "description": "The Fauna SDK: accounts, Drive, groups, calendar, chats, payments and every Fauna app (Parrot, Marmot, Magpie, Cicada, Ant, Termite), plus React UI.",
   "homepage": "https://docs.faunakit.com",
   "repository": {