fauna-api 1.0.681 → 1.0.686

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

@@ -1,31 +1,25 @@
-import { Platform } from "../integrations.js";
-import { Profile, Credentials, ApiKey } from "../authentification.js";
-export type Discord = {
-    displayName: string;
-    handle: string;
-    userId?: string;
-};
-export type Slack = {
-    displayName: string;
-    email: string;
-    headline: string;
-};
-export type Email = {
-    email: string;
+import { Credentials, ApiKey } from "../authentification.js";
+export type AddressKind = 'email' | 'phone' | 'discord';
+export type Address = {
+    kind: AddressKind;
+    /** Lowercase email, E.164 phone (+12395551234), or Discord handle without @. */
+    value: string;
 };
-export type SMS = {
-    phone: string;
-};
-export type Identity = Discord | Slack | Email | SMS;
 export type Contact = {
-    profile: Profile;
+    id: string;
+    displayName: string;
+    addresses: Address[];
+    /** One of its emails belongs to a Fauna account: the verified badge. */
     registered: boolean;
-    platforms: Identity[];
+    /** That Fauna account's picture. */
+    icon?: string;
 };
+/** Every contact, sorted by display name. */
 export declare function list(authorization: Credentials | ApiKey): Promise<Contact[]>;
-export declare function create(authorization: Credentials | ApiKey, params: {
-    email: string;
-    displayName?: string;
-    platform: Platform;
-    identity?: string;
+/** Creates a contact, or with `id` renames one and replaces its addresses. */
+export declare function save(authorization: Credentials | ApiKey, contact: {
+    id?: string;
+    displayName: string;
+    addresses: Address[];
 }): Promise<Contact>;
+export declare function remove(authorization: Credentials | ApiKey, id: string): Promise<void>;

package/dist/src/cicada/contacts.js

@@ -1,4 +1,5 @@
 import { Cicada } from "./index.js";
+/** Every contact, sorted by display name. */
 export async function list(authorization) {
     const response = await fetch(`${Cicada.getURL()}/cicada/contacts`, {
         method: "POST",
@@ -11,18 +12,29 @@ export async function list(authorization) {
         throw new Error(await response.text());
     return await response.json();
 }
-// Promote an anonymous sender into a contact. Email is mandatory; passing the
-// platform + raw identity (phone / handle / email) binds existing messages to it.
-export async function create(authorization, params) {
-    const response = await fetch(`${Cicada.getURL()}/cicada/contacts/create`, {
+/** Creates a contact, or with `id` renames one and replaces its addresses. */
+export async function save(authorization, contact) {
+    const response = await fetch(`${Cicada.getURL()}/cicada/contacts/save`, {
         method: "POST",
         headers: {
             "Content-Type": "application/json",
             "Authorization": 'email' in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`
         },
-        body: JSON.stringify(params)
+        body: JSON.stringify(contact)
     });
     if (!response.ok)
         throw new Error(await response.text());
     return await response.json();
 }
+export async function remove(authorization, id) {
+    const response = await fetch(`${Cicada.getURL()}/cicada/contacts/delete`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": 'email' in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`
+        },
+        body: JSON.stringify({ id })
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+}

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

@@ -12,6 +12,8 @@ export type Inbox = {
     name: string;
     createdAt: Date;
     group?: InboxGroup;
+    /** An agent is on for this inbox. */
+    agent?: boolean;
 };
 export type InboxAccount = {
     platform: Platform;
@@ -46,3 +48,17 @@ export declare function setAgent(authorization: Credentials | ApiKey, inbox: str
     dailyLimit: number;
 }): Promise<AgentSettings>;
 export declare function clearAgent(authorization: Credentials | ApiKey, inbox: string): Promise<void>;
+/**
+ * Has the inbox's agent phone `to` from one of the inbox's lines (`from`, or its first)
+ * and follow `directions`. Returns once the call is placed; the transcript lands on the
+ * thread with that number. Owners only; counts toward the agent's daily limit.
+ */
+export declare function agentCall(authorization: Credentials, inbox: string, call: {
+    to: string;
+    directions: string;
+    from?: string;
+}): Promise<{
+    calling: string;
+    from: string;
+    callId: string;
+}>;

package/dist/src/cicada/inboxes.js

@@ -25,6 +25,7 @@ function wrapInbox(raw) {
         name: raw.name,
         createdAt: new Date(raw.createdAt),
         ...(group ? { group } : {}),
+        ...(raw.agent ? { agent: true } : {}),
     };
 }
 export async function list(authorization) {
@@ -80,3 +81,12 @@ export async function setAgent(authorization, inbox, settings) {
 export async function clearAgent(authorization, inbox) {
     await post(authorization, '/cicada/inboxes/agent/clear', { inbox });
 }
+/**
+ * Has the inbox's agent phone `to` from one of the inbox's lines (`from`, or its first)
+ * and follow `directions`. Returns once the call is placed; the transcript lands on the
+ * thread with that number. Owners only; counts toward the agent's daily limit.
+ */
+export async function agentCall(authorization, inbox, call) {
+    const response = await post(authorization, '/cicada/inboxes/agent/call', { inbox, ...call });
+    return await response.json();
+}

package/dist/src/integrations.d.ts

@@ -48,5 +48,8 @@ export declare class WhatsApp extends Account {
     readonly phone: string;
     constructor(authorization: Credentials, raw: any);
 }
+/** Opens the provider's consent page in a popup and returns it, or `null` when the browser
+ *  blocked the popup. The popup opens before the request so the browser still counts it as
+ *  part of the click. */
 export declare function linkPlatform(credentials: Credentials, integration: Platform): Promise<WindowProxy | null>;
 export declare function getAccounts(credentials: Credentials): Promise<Account[]>;

package/dist/src/integrations.js

@@ -176,20 +176,32 @@ function wrapAccount(authorization, platform, raw) {
         case Platform.WHATSAPP: return new WhatsApp(authorization, raw);
     }
 }
+/** Opens the provider's consent page in a popup and returns it, or `null` when the browser
+ *  blocked the popup. The popup opens before the request so the browser still counts it as
+ *  part of the click. */
 export async function linkPlatform(credentials, integration) {
-    const response = await fetch(`${Fauna.getURL()}/integrations/link`, {
-        method: "POST",
-        headers: {
-            "Content-Type": "application/json",
-            "Authorization": `Token ${credentials.token}`
-        },
-        body: JSON.stringify({ integration })
-    });
-    if (!response.ok) {
-        return null;
+    const popup = window.open("", "_blank", "width=500,height=600");
+    try {
+        const response = await fetch(`${Fauna.getURL()}/integrations/link`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "Authorization": `Token ${credentials.token}`
+            },
+            body: JSON.stringify({ integration })
+        });
+        if (!response.ok) {
+            throw new Error(await response.text());
+        }
+        const { url } = await response.json();
+        if (popup)
+            popup.location.href = url;
+        return popup;
+    }
+    catch (err) {
+        popup?.close();
+        throw err;
     }
-    const { url } = await response.json();
-    return window.open(url, "_blank", "width=500,height=600");
 }
 export async function getAccounts(credentials) {
     const response = await fetch(`${Fauna.getURL()}/integrations/accounts`, {

package/dist/src/ui/integrations.js

@@ -1,4 +1,5 @@
 import { Fauna } from "fauna-api";
+import { sendInformaticToast } from "./toast.js";
 import gsap from "gsap";
 // Brand logos as inline SVG (currentColor-free, real brand marks) so the
 // connections panel reads as a polished product surface rather than generic
@@ -50,13 +51,17 @@ export function createConnections(credentials, options = {}) {
     grid.className = 'connections-grid';
     root.appendChild(grid);
     function fail(err) {
-        options.onError?.(err instanceof Error ? err : new Error(String(err)));
+        const error = err instanceof Error ? err : new Error(String(err));
+        if (options.onError)
+            options.onError(error);
+        else
+            void sendInformaticToast(error.message || 'Could not connect.', 'error');
     }
     async function connect(platform) {
         try {
             const popup = await Fauna.Integrations.linkPlatform(credentials, platform);
             if (!popup)
-                return;
+                return fail(new Error('Allow popups for this site to connect.'));
             // Refresh once the consent popup closes.
             const timer = setInterval(async () => {
                 if (popup.closed) {
@@ -70,6 +75,77 @@ export function createConnections(credentials, options = {}) {
             fail(err);
         }
     }
+    // Twilio delivers new texts only to the number's own "A message comes in" webhook,
+    // which Fauna doesn't set, so a linked number shows where to point it.
+    function buildTwilioWebhookNote() {
+        const url = `${new URL(Fauna.getURL()).origin}/integrations/twilio/webhook`;
+        const note = document.createElement('div');
+        note.className = 'connection-card-note';
+        const head = document.createElement('div');
+        head.className = 'connection-card-note-head';
+        head.innerHTML = '<span class="material-symbols-outlined connection-card-note-icon">error</span>';
+        const title = document.createElement('span');
+        title.className = 'connection-card-note-title';
+        title.textContent = 'Set the webhook in Twilio';
+        title.title = 'New texts only reach Fauna once Twilio sends them to this webhook.';
+        head.appendChild(title);
+        const open = document.createElement('a');
+        open.className = 'connection-card-note-link';
+        open.href = 'https://console.twilio.com/us1/develop/phone-numbers/manage/incoming';
+        open.target = '_blank';
+        open.rel = 'noopener';
+        open.innerHTML = 'Open<span class="material-symbols-outlined">open_in_new</span>';
+        head.appendChild(open);
+        note.appendChild(head);
+        const steps = document.createElement('ol');
+        steps.className = 'connection-card-note-steps';
+        for (const path of [
+            ['Active numbers', 'your number'],
+            ['Messaging', 'A message comes in'],
+            ['Webhook, HTTP POST, this URL'],
+        ]) {
+            const step = document.createElement('li');
+            path.forEach((part, i) => {
+                if (i) {
+                    const arrow = document.createElement('span');
+                    arrow.className = 'material-symbols-outlined connection-card-note-arrow';
+                    arrow.textContent = 'arrow_forward';
+                    step.appendChild(arrow);
+                }
+                const text = document.createElement('span');
+                text.textContent = part;
+                step.appendChild(text);
+            });
+            steps.appendChild(step);
+        }
+        note.appendChild(steps);
+        const copy = document.createElement('button');
+        copy.type = 'button';
+        copy.className = 'connection-card-note-url';
+        copy.title = `Copy ${url}`;
+        const code = document.createElement('code');
+        code.textContent = url;
+        const icon = document.createElement('span');
+        icon.className = 'material-symbols-outlined';
+        icon.textContent = 'content_copy';
+        copy.append(code, icon);
+        copy.onclick = async () => {
+            try {
+                await navigator.clipboard.writeText(url);
+                icon.textContent = 'check';
+                copy.classList.add('copied');
+                setTimeout(() => {
+                    icon.textContent = 'content_copy';
+                    copy.classList.remove('copied');
+                }, 1600);
+            }
+            catch (err) {
+                fail(err);
+            }
+        };
+        note.appendChild(copy);
+        return note;
+    }
     // One card per platform. `accounts` are the already-linked accounts for this
     // platform (possibly several); each gets a labeled row with an unlink action.
     function buildCard(platform, accounts) {
@@ -136,6 +212,9 @@ export function createConnections(credentials, options = {}) {
             }
             card.appendChild(accountsBox);
         }
+        if (platform === Fauna.Integrations.Platform.TWILIO && accounts.length) {
+            card.appendChild(buildTwilioWebhookNote());
+        }
         // Connect / add-another action.
         const connectBtn = document.createElement('button');
         connectBtn.type = 'button';

package/dist/src/ui/ui.css

@@ -2417,6 +2417,143 @@ button.chat-message-file {
     color: color-mix(in srgb, var(--text, #1a1a18) 70%, transparent);
 }
 
+.connection-card-note {
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+
+    padding: 10px 12px 12px;
+
+    border: 1px solid color-mix(in srgb, #f59e0b 34%, transparent);
+    border-radius: 10px;
+    background: color-mix(in srgb, #f59e0b 9%, transparent);
+}
+.connection-card-note-head {
+    display: flex;
+    align-items: center;
+    gap: 7px;
+}
+.connection-card-note-icon {
+    flex: 0 0 auto;
+    font-size: 18px !important;
+    color: #d97706;
+}
+.connection-card-note-title {
+    flex: 1;
+    min-width: 0;
+
+    font-size: 12.5px;
+    font-weight: 600;
+    line-height: 1.3;
+    color: var(--text, #1a1a18);
+}
+.connection-card-note-link {
+    display: inline-flex;
+    align-items: center;
+    gap: 2px;
+
+    font-size: 12px;
+    font-weight: 600;
+    white-space: nowrap;
+    text-decoration: none;
+    color: var(--connection-note-accent, #b45309);
+}
+.connection-card-note-link span {
+    font-size: 14px !important;
+}
+.connection-card-note-link:hover {
+    text-decoration: underline;
+}
+.connection-card-note-steps {
+    display: flex;
+    flex-direction: column;
+    gap: 5px;
+
+    margin: 0;
+    padding: 0 0 0 25px;
+
+    list-style: none;
+    counter-reset: connection-step;
+}
+.connection-card-note-steps li {
+    position: relative;
+
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: 2px 4px;
+
+    font-size: 12px;
+    line-height: 16px;
+    color: color-mix(in srgb, var(--text, #1a1a18) 78%, transparent);
+
+    counter-increment: connection-step;
+}
+.connection-card-note-steps li::before {
+    content: counter(connection-step);
+
+    position: absolute;
+    left: -25px;
+    top: 0;
+
+    display: flex;
+    align-items: center;
+    justify-content: center;
+
+    width: 16px;
+    height: 16px;
+
+    border-radius: 50%;
+    background: color-mix(in srgb, #f59e0b 20%, transparent);
+    color: var(--connection-note-accent, #b45309);
+
+    font-size: 10px;
+    font-weight: 700;
+}
+.connection-card-note-arrow {
+    font-size: 13px !important;
+    color: color-mix(in srgb, var(--text, #1a1a18) 38%, transparent);
+}
+.connection-card-note-url {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+
+    width: 100%;
+    padding: 6px 8px 6px 10px;
+
+    border: 1px solid color-mix(in srgb, var(--text, #1a1a18) 12%, transparent);
+    border-radius: 8px;
+    background: var(--surface, #fff);
+    color: var(--text, #1a1a18);
+
+    cursor: pointer;
+    text-align: left;
+    transition: border-color 0.15s ease;
+}
+.connection-card-note-url code {
+    flex: 1;
+    min-width: 0;
+
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+
+    font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+    font-size: 11.5px;
+}
+.connection-card-note-url span {
+    font-size: 15px !important;
+    color: color-mix(in srgb, var(--text, #1a1a18) 50%, transparent);
+    transition: color 0.15s ease;
+}
+.connection-card-note-url:hover {
+    border-color: color-mix(in srgb, var(--text, #1a1a18) 26%, transparent);
+}
+.connection-card-note-url.copied span {
+    color: #16a34a;
+}
+
 
 /* Social sign-in buttons (UI.Authentification.createOAuthButtons).
    Themed via --oauth-* custom properties so each app can recolor without

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fauna-api",
-  "version": "1.0.681",
+  "version": "1.0.686",
   "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": {