fauna-api 0.0.0-stage → 1.0.676

package/dist/src/authentification.d.ts

@@ -0,0 +1,45 @@
+import { Fauna } from "../index.js";
+import { Platform } from "./integrations.js";
+import type { Group } from "./groups.js";
+export interface Credentials {
+    token: Token;
+    emailVerified: boolean;
+    phoneVerified: boolean;
+    permissions: string[];
+    integrations: Platform[];
+    email: string;
+    phone: string;
+    displayName?: string;
+    icon?: string;
+    apiKeys: ApiKey[];
+    balance: number;
+}
+export type ApiKey = {
+    id: string;
+    balance: number;
+    services: string[];
+    name?: string;
+};
+export type Token = string;
+export type Profile = {
+    email: string;
+    displayName?: string;
+    icon?: string;
+};
+export declare const Profile: {
+    fromJSON(json: unknown): Profile | undefined;
+};
+export declare function authorize(email: string, password: string): Promise<Token>;
+export declare function authorizeToken(token: Token): Promise<Credentials>;
+export declare function authorizeApiKey(apiKey: string): Promise<ApiKey>;
+export declare function create(email: string, password: string, phone: string, displayName?: string): Promise<boolean>;
+/** email and phone are only accepted while that one isn't verified yet; a change sends a new link and code. */
+export declare function edit(credentials: Credentials, update: Partial<Pick<Credentials, 'displayName' | 'icon' | 'email' | 'phone'>>): Promise<boolean>;
+export declare function verify(channel: 'EMAIL' | 'PHONE', target: string, code: string): Promise<boolean>;
+export declare function sendVerification(credentials: Credentials, channel: 'EMAIL' | 'PHONE'): Promise<boolean>;
+export declare function allocateBalance(credentials: Credentials, target: ApiKey | Group, delta: number): Promise<true>;
+export declare function generateApiKey(credentials: Credentials): Promise<ApiKey>;
+export declare function removeApiKey(credentials: Credentials, apiKey: ApiKey): Promise<boolean>;
+export declare function profile(credentials: Credentials, email: string): Promise<Profile>;
+export declare function query(credentials: Credentials, profile: Partial<Profile>): Promise<Profile[]>;
+export declare function editApiKey(credentials: Credentials, apiKey: ApiKey, update: Partial<ApiKey>): Promise<boolean>;

package/dist/src/authentification.js

@@ -0,0 +1,194 @@
+import { Fauna } from "../index.js";
+export const Profile = {
+    fromJSON(json) {
+        if (!json || typeof json !== "object")
+            return undefined;
+        const row = json;
+        if (typeof row.email !== "string" || !row.email)
+            return undefined;
+        return {
+            email: row.email,
+            displayName: typeof row.displayName === "string" ? row.displayName : undefined,
+            icon: typeof row.icon === "string" ? row.icon : undefined,
+        };
+    },
+};
+// Authorization
+export async function authorize(email, password) {
+    const response = await fetch(`${Fauna.getURL()}/authentification/authorize`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json"
+        },
+        body: JSON.stringify({ email: email, password: password })
+    });
+    if (!response.ok) {
+        throw new Error(await response.text());
+    }
+    return await response.text();
+}
+export async function authorizeToken(token) {
+    const response = await fetch(`${Fauna.getURL()}/authentification/authorize`, {
+        method: "POST",
+        headers: {
+            "Authorization": `Token ${token}`
+        }
+    });
+    if (!response.ok) {
+        throw new Error(await response.text());
+    }
+    const credentials = await response.json();
+    return { ...credentials, token: String(token) };
+}
+export async function authorizeApiKey(apiKey) {
+    const response = await fetch(`${Fauna.getURL()}/authentification/authorize`, {
+        method: "POST",
+        headers: {
+            "Authorization": `ApiKey ${apiKey}`
+        }
+    });
+    if (!response.ok) {
+        throw new Error(await response.text());
+    }
+    return await response.json();
+}
+// Credentials Management
+export async function create(email, password, phone, displayName) {
+    const response = await fetch(`${Fauna.getURL()}/authentification/create`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json"
+        },
+        body: JSON.stringify({ email, password, phone, displayName })
+    });
+    if (!response.ok) {
+        throw new Error(await response.text());
+    }
+    return response.ok;
+}
+/** email and phone are only accepted while that one isn't verified yet; a change sends a new link and code. */
+export async function edit(credentials, update) {
+    const response = await fetch(`${Fauna.getURL()}/authentification`, {
+        method: "PATCH",
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": `Token ${credentials.token}`
+        },
+        body: JSON.stringify(update)
+    });
+    if (!response.ok) {
+        throw new Error(await response.text());
+    }
+    return response.ok;
+}
+export async function verify(channel, target, code) {
+    const response = await fetch(`${Fauna.getURL()}/authentification/verify`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json"
+        },
+        body: JSON.stringify({ channel, target, code })
+    });
+    if (!response.ok) {
+        throw new Error(await response.text());
+    }
+    return response.ok;
+}
+export async function sendVerification(credentials, channel) {
+    const response = await fetch(`${Fauna.getURL()}/authentification/send-verification`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": `Token ${credentials.token}`
+        },
+        body: JSON.stringify({ channel })
+    });
+    if (!response.ok) {
+        throw new Error(await response.text());
+    }
+    return response.ok;
+}
+export async function allocateBalance(credentials, target, delta) {
+    const deltaMicros = Math.round(delta * 1000000);
+    if (!Number.isSafeInteger(deltaMicros))
+        throw new Error('Invalid balance delta.');
+    const headers = {
+        "Content-Type": "application/json",
+        "Authorization": `Token ${credentials.token}`
+    };
+    headers['services' in target ? "Api-Key" : "Group"] = target.id;
+    const response = await fetch(`${Fauna.getURL()}/authentification/allocate-balance`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ deltaMicros })
+    });
+    if (!response.ok) {
+        throw new Error(await response.text());
+    }
+    return response.ok;
+}
+export async function generateApiKey(credentials) {
+    const response = await fetch(`${Fauna.getURL()}/authentification/api-keys`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": `Token ${credentials.token}`
+        }
+    });
+    if (!response.ok) {
+        throw new Error(await response.text());
+    }
+    return await response.json();
+}
+export async function removeApiKey(credentials, apiKey) {
+    const response = await fetch(`${Fauna.getURL()}/authentification/api-keys/${encodeURIComponent(apiKey.id)}`, {
+        method: "DELETE",
+        headers: {
+            "Authorization": `Token ${credentials.token}`
+        }
+    });
+    if (!response.ok) {
+        throw new Error(await response.text());
+    }
+    return response.ok;
+}
+export async function profile(credentials, email) {
+    const response = await fetch(`${Fauna.getURL()}/authentification/profile/${encodeURIComponent(email)}`, {
+        method: "GET",
+        headers: {
+            "Authorization": `Token ${credentials.token}`
+        }
+    });
+    if (!response.ok) {
+        throw new Error(await response.text());
+    }
+    return await response.json();
+}
+export async function query(credentials, profile) {
+    const response = await fetch(`${Fauna.getURL()}/authentification/query`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": `Token ${credentials.token}`
+        },
+        body: JSON.stringify({ email: profile.email, displayName: profile.displayName })
+    });
+    if (!response.ok) {
+        throw new Error(await response.text());
+    }
+    return await response.json();
+}
+export async function editApiKey(credentials, apiKey, update) {
+    const response = await fetch(`${Fauna.getURL()}/authentification/api-keys/${encodeURIComponent(apiKey.id)}`, {
+        method: "PATCH",
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": `Token ${credentials.token}`
+        },
+        body: JSON.stringify({ name: update.name })
+    });
+    if (!response.ok) {
+        throw new Error(await response.text());
+    }
+    return response.ok;
+}

package/dist/src/billing.d.ts

@@ -0,0 +1,135 @@
+import { Fauna } from "../index.js";
+import { Token } from "./authentification.js";
+export type PaymentMethod = {
+    brand: string;
+    last4: string;
+    expMonth: number;
+    expYear: number;
+};
+export type AutoReload = {
+    enabled: boolean;
+    threshold: number;
+    target: number;
+    monthlyCap: number;
+    monthlySpent: number;
+    status: string;
+    available: boolean;
+};
+export type AutoReloadUpdate = {
+    enabled: boolean;
+    threshold: number;
+    target: number;
+    monthlyCap: number;
+};
+export type Transaction = {
+    id: string;
+    kind: 'manual' | 'automatic' | 'subscription' | 'grant';
+    amount: number;
+    status: string;
+    failureMessage?: string;
+    createdAt: string;
+    completedAt?: string;
+};
+export type Plan = 'free' | 'premium' | 'enterprise';
+export type Subscription = {
+    plan: Plan;
+    status: string;
+    periodEnd?: string;
+    cancelAtPeriodEnd: boolean;
+    /** Ids of the add-ons you hold. */
+    addons: string[];
+};
+/** Something an app sells on top of Premium, on the same subscription. Prices are in dollars per `interval`. */
+export type Addon = {
+    id: string;
+    name: string;
+    price: number;
+    /** What it costs without Premium yet, since buying it adds Premium too. */
+    withPremium: number;
+    currency: string;
+    interval: string;
+};
+export type Summary = {
+    balance: number;
+    currency: 'usd';
+    paymentMethod?: PaymentMethod;
+    autoReload: AutoReload;
+    subscription: Subscription;
+    recentTransactions: Transaction[];
+};
+type WireAutoReload = {
+    enabled: boolean;
+    thresholdMicros: number;
+    targetMicros: number;
+    monthlyCapCents: number;
+    monthlySpentCents: number;
+    status: string;
+    available: boolean;
+};
+type WireTransaction = Omit<Transaction, 'amount'> & {
+    amountCents: number;
+    creditMicros: number;
+};
+export declare const AutoReload: {
+    fromJSON(json: WireAutoReload): AutoReload;
+};
+export declare const Transaction: {
+    fromJSON(json: WireTransaction): Transaction;
+};
+export declare function get(token: Token): Promise<Summary>;
+/** Start a Stripe Checkout top-up for the caller's personal wallet. Stripe
+ *  returns to `returnUrl` when it is a trusted app origin, else the Fauna app. */
+export declare function checkout(token: Token, amount: number, options?: {
+    returnUrl?: string;
+}): Promise<{
+    url: string;
+}>;
+export declare function setupPaymentMethod(token: Token, options?: {
+    returnUrl?: string;
+}): Promise<{
+    url: string;
+}>;
+export declare function updateAutoReload(token: Token, update: AutoReloadUpdate): Promise<AutoReload>;
+export declare function openPortal(token: Token, options?: {
+    returnUrl?: string;
+}): Promise<{
+    url: string;
+}>;
+/**
+ * Subscribe to Premium, or with `addon`, buy an add-on. With a subscription
+ * already, the add-on joins it at once (the URL then returns to `returnUrl`, or
+ * opens the invoice when the card needs confirming); otherwise Checkout sells
+ * Premium and the add-on together. Open the returned URL.
+ */
+export declare function subscribe(token: Token, options?: {
+    returnUrl?: string;
+    addon?: string;
+}): Promise<{
+    url: string;
+}>;
+/** End Premium at the period's end (add-ons end with it), or with `addon`, stop that add-on now with a prorated credit. */
+export declare function cancelSubscription(token: Token, options?: {
+    addon?: string;
+}): Promise<Subscription>;
+/** The add-ons for sale. */
+export declare function addons(token: Token): Promise<Addon[]>;
+export declare function transactions(token: Token, query: {
+    cursor: number;
+    max: number;
+}): Promise<Transaction[]>;
+export type UsagePoint = {
+    day: string;
+    service: string;
+    base: number;
+    spread: number;
+};
+export type Usage = {
+    principalKind: 'user' | 'group';
+    since: string;
+    usage: UsagePoint[];
+};
+/** Daily base/spread usage for the caller's wallet, or a group's (member-only).
+ *  `days` bounds the window server-side (default 30, max 180). */
+export declare function usage(token: Token, groupId?: string, days?: number): Promise<Usage>;
+export declare function format(amount: number): string;
+export {};

package/dist/src/billing.js

@@ -0,0 +1,128 @@
+import { Fauna } from "../index.js";
+async function request(token, path, init) {
+    const response = await fetch(`${Fauna.getURL()}${path}`, {
+        ...init,
+        headers: {
+            ...init?.headers,
+            "Authorization": `Token ${token}`,
+        },
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    return await response.json();
+}
+export const AutoReload = {
+    fromJSON(json) {
+        return {
+            enabled: json.enabled,
+            threshold: json.thresholdMicros / 1000000,
+            target: json.targetMicros / 1000000,
+            monthlyCap: json.monthlyCapCents / 100,
+            monthlySpent: json.monthlySpentCents / 100,
+            status: json.status,
+            available: json.available === true,
+        };
+    },
+};
+export const Transaction = {
+    fromJSON(json) {
+        const { amountCents, creditMicros: _, ...transaction } = json;
+        return { ...transaction, amount: amountCents / 100 };
+    },
+};
+export async function get(token) {
+    const value = await request(token, '/billing');
+    const { balanceMicros, autoReload, recentTransactions, ...summary } = value;
+    return {
+        ...summary,
+        balance: balanceMicros / 1000000,
+        autoReload: AutoReload.fromJSON(autoReload),
+        subscription: summary.subscription ?? { plan: 'free', status: 'none', cancelAtPeriodEnd: false, addons: [] },
+        recentTransactions: recentTransactions.map((row) => Transaction.fromJSON(row)),
+    };
+}
+/** Start a Stripe Checkout top-up for the caller's personal wallet. Stripe
+ *  returns to `returnUrl` when it is a trusted app origin, else the Fauna app. */
+export function checkout(token, amount, options = {}) {
+    const amountCents = Math.round(amount * 100);
+    if (!Number.isSafeInteger(amountCents))
+        throw new Error('Invalid top-up amount.');
+    return request(token, '/billing/checkout', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ amountCents, returnUrl: options.returnUrl }),
+    });
+}
+export function setupPaymentMethod(token, options = {}) {
+    return request(token, '/billing/payment-method/setup', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ returnUrl: options.returnUrl }),
+    });
+}
+export async function updateAutoReload(token, update) {
+    const value = await request(token, '/billing/auto-reload', {
+        method: 'PATCH',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            enabled: update.enabled,
+            thresholdCents: Math.round(update.threshold * 100),
+            targetCents: Math.round(update.target * 100),
+            monthlyCapCents: Math.round(update.monthlyCap * 100),
+        }),
+    });
+    return AutoReload.fromJSON(value);
+}
+export function openPortal(token, options = {}) {
+    return request(token, '/billing/payment-method/portal', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ returnUrl: options.returnUrl }),
+    });
+}
+/**
+ * Subscribe to Premium, or with `addon`, buy an add-on. With a subscription
+ * already, the add-on joins it at once (the URL then returns to `returnUrl`, or
+ * opens the invoice when the card needs confirming); otherwise Checkout sells
+ * Premium and the add-on together. Open the returned URL.
+ */
+export function subscribe(token, options = {}) {
+    return request(token, '/billing/subscription/checkout', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ returnUrl: options.returnUrl, addon: options.addon }),
+    });
+}
+/** End Premium at the period's end (add-ons end with it), or with `addon`, stop that add-on now with a prorated credit. */
+export function cancelSubscription(token, options = {}) {
+    return request(token, '/billing/subscription/cancel', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ addon: options.addon }),
+    });
+}
+/** The add-ons for sale. */
+export function addons(token) {
+    return request(token, '/billing/addons');
+}
+export async function transactions(token, query) {
+    const params = new URLSearchParams({ cursor: String(query.cursor), max: String(query.max) });
+    const rows = await request(token, `/billing/transactions?${params}`);
+    return rows.map((row) => Transaction.fromJSON(row));
+}
+/** Daily base/spread usage for the caller's wallet, or a group's (member-only).
+ *  `days` bounds the window server-side (default 30, max 180). */
+export async function usage(token, groupId, days = 30) {
+    const query = new URLSearchParams({ days: String(days) });
+    if (groupId)
+        query.set('groupId', groupId);
+    const value = await request(token, `/billing/usage?${query.toString()}`);
+    return {
+        principalKind: value.principalKind,
+        since: value.since,
+        usage: value.usage.map((u) => ({ day: u.day, service: u.service, base: u.baseMicros / 1000000, spread: u.spreadMicros / 1000000 })),
+    };
+}
+export function format(amount) {
+    return new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(amount);
+}

package/dist/src/calendar.d.ts

@@ -0,0 +1,83 @@
+import { ApiKey, Credentials } from "./authentification.js";
+import { Group } from "./groups.js";
+/** An invitee's answer. Everyone starts at `invited`. */
+export type Answer = 'invited' | 'yes' | 'no' | 'maybe';
+export type Attendee = {
+    email: string;
+    response: Answer;
+};
+/** Whose calendar an event is on. */
+export type CalendarKind = 'person' | 'group';
+export type Calendar = {
+    kind: CalendarKind;
+    id: string;
+    name: string;
+};
+/** A linked calendar an event syncs from. */
+export type Source = 'google' | 'microsoft';
+export type Event = {
+    id: string;
+    /** The calendar it's on: yours, a group's, or whoever invited you. */
+    calendar: Calendar;
+    title: string;
+    notes: string;
+    place: string;
+    /** For a recurring event in a list, this occurrence's. */
+    start: Date;
+    end: Date;
+    allDay: boolean;
+    /** An IANA time zone, like America/New_York. A recurring event repeats on its clock. */
+    timeZone: string;
+    /** An RRULE without its prefix, like FREQ=WEEKLY;BYDAY=MO. Empty for a one off. */
+    recurrence: string;
+    /** Minutes before each start to email a reminder; 0 for none. */
+    reminder: number;
+    attendees: Attendee[];
+    /** A linked Google or Outlook calendar it syncs from, or null for Fauna's own. */
+    source: Source | null;
+    /** You can change it: it's on your calendar or one of your groups'. */
+    editable: boolean;
+    /** Your answer, when you're invited. */
+    response?: Answer;
+    created: Date;
+    updated: Date;
+};
+/** A new event. Only `title`, `start` and `end` are required. */
+export type Draft = {
+    title: string;
+    start: Date;
+    end: Date;
+    allDay?: boolean;
+    /** UTC by default. */
+    timeZone?: string;
+    place?: string;
+    notes?: string;
+    recurrence?: string;
+    /** 10 minutes by default; 0 for none. */
+    reminder?: number;
+    /** Emails to invite. Each gets an invitation. */
+    attendees?: string[];
+};
+/**
+ * Events between `from` and `to` (at most 400 days apart), one per occurrence,
+ * soonest first. With `group`, that group's calendar; otherwise yours, your
+ * groups' and the events you're invited to.
+ */
+export declare function list(authorization: Credentials | ApiKey, from: Date, to: Date, group?: Group): Promise<Event[]>;
+/** One event on your calendar, a group's, or one you're invited to. */
+export declare function get(authorization: Credentials | ApiKey, id: string): Promise<Event>;
+/** Put an event on your calendar, or `group`'s, and email everyone it invites. */
+export declare function create(authorization: Credentials | ApiKey, draft: Draft, group?: Group): Promise<Event>;
+/**
+ * Change an event on your calendar or a group's. A recurring event changes as a
+ * whole. New invitees get invited; the rest hear about a new time or place.
+ */
+export declare function update(authorization: Credentials | ApiKey, id: string, update: Partial<Draft>): Promise<Event>;
+/** Remove an event from your calendar or a group's, telling everyone it invited. */
+export declare function remove(authorization: Credentials | ApiKey, id: string): Promise<void>;
+/** Answer an event you're invited to: `yes`, `no` or `maybe`. */
+export declare function respond(authorization: Credentials | ApiKey, id: string, answer: Answer): Promise<Event>;
+/** The secret .ics link for your calendar, or `group`'s, for Google, Apple or Outlook to subscribe to. */
+export declare function feed(authorization: Credentials | ApiKey, group?: Group): Promise<string>;
+/** A new .ics link for your calendar, or `group`'s. The old one stops working. */
+export declare function resetFeed(credentials: Credentials, group?: Group): Promise<string>;