@foir/sdk 0.10.0 → 0.12.0

package/dist/app/client.d.ts

@@ -0,0 +1,371 @@
+/**
+ * The client an installed app calls Foir with.
+ *
+ * An app is installed in many projects, and each install maps the app's
+ * sources onto whichever models that project's operator chose. So an app has
+ * no schema to generate a client from: it learns the model keys at request
+ * time, from the install's own configuration, and names them in each call.
+ * `createFoirClient` is the client for an endpoint that knows its project;
+ * this is the one for an endpoint that does not.
+ *
+ * ```ts
+ * const { dispatch } = await requireScopedToken(request, { verifier });
+ * const foir = createAppClient({ apiUrl, dispatch });
+ * const config = await foir.install.config();
+ * const products = config.sources.find((source) => source.key === 'product');
+ * await foir.records.upsert({ model: products.model, naturalKey: handle, data });
+ * ```
+ *
+ * The credential is the token the dispatch carried, and nothing else. Every
+ * call goes to the data API as that token, so what it may do is exactly what
+ * the operation declared. NOTHING IS CHECKED HERE FIRST: the client does not
+ * read the token, and a call the token cannot make is refused by the platform,
+ * whose answer is the error thrown (see `./errors`).
+ *
+ * A client is cheap and holds no state. Build one per dispatch and let it go
+ * with the request, so a credential revoked in Foir stops working on the next
+ * call rather than whenever a cache expires.
+ */
+import type { FoirDispatchCredential } from '../data/transport';
+import { type FoirRetryPolicy } from '../transport/retry';
+type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+type JsonObject = {
+    [key: string]: Json;
+};
+export interface AppClientConfig {
+    /** The data API's origin, e.g. `https://api.foir.dev`. */
+    apiUrl: string;
+    /**
+     * The token to call as: `dispatch` from `requireScopedToken`, the token an
+     * exchange ticket was redeemed for (`redeemExchangeTicket`), or an ASYNC
+     * run's callback token (`{ token: () => payload.callback.token }`), which
+     * keeps writing records after the dispatch token has expired.
+     */
+    dispatch: FoirDispatchCredential;
+    /** Defaults to the global `fetch`. */
+    fetch?: typeof globalThis.fetch;
+    /** Extra init for every request, e.g. an abort signal. */
+    requestInit?: Omit<RequestInit, 'method' | 'headers' | 'body'>;
+    /**
+     * How a call that got no answer, a 5xx or a 429 is tried again. Three
+     * attempts unless told otherwise; `{ attempts: 1 }` turns it off. Every call
+     * here is safe to repeat except a notification sent without an
+     * `idempotencyKey`, which a retry after a lost answer can deliver twice.
+     */
+    retry?: FoirRetryPolicy;
+}
+/** Which way one mapped field is allowed to move. */
+export type AppSyncDirection = 'SOURCE_ONLY' | 'SINK_ONLY' | 'BIDIRECTIONAL';
+export interface AppFieldMapping {
+    /** The app's own field name, from its manifest. */
+    appField: string;
+    /** The project model's field key. */
+    modelField: string;
+    /**
+     * SINK_ONLY means the operator has said Foir owns the field: a value from
+     * the app's side must not be written over it. An unrecognised direction
+     * reads as SINK_ONLY, which withholds the field rather than writing on a
+     * guess.
+     */
+    direction: AppSyncDirection;
+}
+/** One of the operator's mappings: a source or sink of the app onto a model. */
+export interface AppBinding {
+    /** The app's source or sink name. */
+    key: string;
+    /** The project model the operator mapped it onto. */
+    model: string;
+    /** The model field the app's records are keyed on. Empty when the mapping names none. */
+    naturalKey: string;
+    fields: AppFieldMapping[];
+    /** REFERENCE: Foir reads the source's fields live. SYNC: it holds a copy. A sink is a copy. */
+    mode: 'SYNC' | 'REFERENCE';
+}
+/** An install's own configuration, as the operator left it. */
+export interface AppInstallConfig {
+    name: string;
+    enabled: boolean;
+    middlewareUrl: string;
+    targetModels: string[];
+    /** The address the app's vendor is told to deliver webhooks to. Empty when the app declares none. */
+    webhookUrl: string;
+    /** The operator's answers to the manifest's settings schema. */
+    settings: JsonObject;
+    sources: AppBinding[];
+    sinks: AppBinding[];
+}
+/**
+ * The status an install reports. Leaving out `subscriptionHealth`,
+ * `authStatus`, `deletionStrategy` or `extra` keeps the stored value; leaving
+ * out any of the `lastSync*` or `lastError*` fields clears it. So send the
+ * sync fields together or not at all.
+ */
+export interface AppStatusReport {
+    lastSyncAt?: string;
+    lastSyncDurationMs?: number;
+    lastSyncRecordCount?: number;
+    /** null clears the field. */
+    lastError?: string | null;
+    lastErrorAt?: string | null;
+    subscriptionHealth?: 'healthy' | 'degraded' | 'failed';
+    authStatus?: 'authenticated' | 'unverified' | 'stale' | 'expired';
+    deletionStrategy?: string;
+    /** Replaced whole on every report that carries it. */
+    extra?: JsonObject;
+}
+/** A record as a read by model key answers it. */
+export interface AppRecord {
+    /** The platform's own id. What `records.delete` takes. */
+    id: string;
+    naturalKey: string | null;
+    /** The customer the record belongs to, or null. */
+    ownerId: string | null;
+    /** The fields that were asked for and could be read, by model field key. */
+    fields: JsonObject;
+    /** Fields that were asked for and could not be selected, so the answer says nothing about them. */
+    unreadable: string[];
+}
+export interface AppUpsertResult {
+    /** The record as the platform holds it now. */
+    record: Record<string, unknown>;
+    /** The platform's own id for it, when the answer carried one. */
+    id: string | null;
+    created: boolean;
+    /** True when nothing was written because Foir already holds a newer copy (`sourceModifiedAt`). */
+    stale: boolean;
+}
+export type AppCustomerSaveResult = (AppUpsertResult & {
+    unlinked: false;
+    customerCreated: boolean;
+}) | {
+    unlinked: true;
+};
+export interface AppCustomerEraseResult {
+    recordDeleted: boolean;
+    identityRemoved: boolean;
+    customerDeleted: boolean;
+    /** Another sign-in method, or something else they own; null when the customer went or none was found. */
+    customerKeptBecause: string | null;
+}
+export interface AppNotification {
+    customerId: string;
+    /** The in-app title, and the email's subject when `email` names none. */
+    title: string;
+    message?: string;
+    /** A notification category the project defines. */
+    category?: string;
+    actionUrl?: string;
+    imageUrl?: string;
+    /** The email, when the send should reach one. Without it, in-app and push only. */
+    email?: {
+        subject?: string;
+        body: string;
+        ctas?: ReadonlyArray<{
+            label: string;
+            url: string;
+        }>;
+    };
+    /** Makes the send safe to repeat: the same key from the same operation tells the customer once. */
+    idempotencyKey?: string;
+}
+export interface AppConsentChange {
+    customerId: string;
+    /** A notification category the project makes opt-in. */
+    category: string;
+    /** The channel the consent is for, as the project's preferences name it (for example `email`). */
+    channel: string;
+    enabled: boolean;
+    /**
+     * When the change was made at its source, as an RFC 3339 time. The platform
+     * keeps the latest it has taken and writes nothing for an older one,
+     * answering `stale`.
+     */
+    sourceModifiedAt?: string;
+}
+/** What the calling token is, and what it is served. Read from the platform, never off the token. */
+export interface AppWhoami {
+    /** The app the token acts for, when it acts for one. */
+    app: string | null;
+    /** The capabilities the token carries. */
+    capabilities: string[];
+    /** The models its record capabilities name, by verb. */
+    models: {
+        read: string[];
+        write: string[];
+        delete: string[];
+        publish: string[];
+    };
+    /** The scopes its calls are held to. */
+    effective: string[];
+    expiresAt: string | null;
+}
+export interface AppClient {
+    /**
+     * Run a hand-written document as the app and answer its whole `data`. For a
+     * field this client has no method for. A read asking for something the token
+     * is not served throws rather than answering the rest without it.
+     */
+    request<T = Record<string, unknown>>(document: string, variables?: Record<string, unknown>): Promise<T>;
+    /**
+     * What the platform says this token is and may do. For an app that has to
+     * SHOW that; a call the token cannot make needs no check first, since the
+     * platform's refusal already says why.
+     */
+    whoami(): Promise<AppWhoami>;
+    /** The install this token acts for: its configuration, its credential, its status. */
+    install: {
+        /** The operator's settings and mappings. Needs `config:read`. */
+        config(): Promise<AppInstallConfig>;
+        /**
+         * The install's credential, by the manifest's credential field names.
+         * Values are always strings. Needs `secrets:read.app`.
+         */
+        credentials(): Promise<Record<string, string>>;
+        /**
+         * Write or rotate credential fields. An empty value is skipped, not
+         * cleared, and a call naming no non-empty field is refused. Needs
+         * `secrets:put.app`.
+         */
+        writeCredentials(values: Record<string, string>): Promise<void>;
+        /** Report the install's health. Needs `status:write`. See {@link AppStatusReport}. */
+        reportStatus(status: AppStatusReport): Promise<void>;
+    };
+    /** Records of a model the install maps, named by its key. */
+    records: {
+        /**
+         * Write the record at a natural key, making it when there is none.
+         * `ownerId` names the customer it belongs to (needs
+         * `records:attribute:<model>`); `sourceModifiedAt` is when the object this
+         * mirrors last changed at its source, so an older copy arriving late is
+         * not written.
+         */
+        upsert(input: {
+            model: string;
+            naturalKey: string;
+            data: JsonObject;
+            ownerId?: string;
+            sourceModifiedAt?: string;
+        }): Promise<AppUpsertResult>;
+        /**
+         * One record by natural key or by id, or null. It reads the PUBLISHED
+         * version: on a model with publishing, a record that was never published
+         * reads as null, the same as one that does not exist. A field that cannot
+         * be selected as written is reported in `unreadable` rather than failing
+         * the read.
+         */
+        read(model: string, by: {
+            naturalKey: string;
+        } | {
+            id: string;
+        }, fields: readonly string[]): Promise<AppRecord | null>;
+        /** Delete one record by its platform id, which only a read supplies. */
+        delete(model: string, id: string): Promise<{
+            deleted: boolean;
+        }>;
+        /**
+         * Drop what the data API has cached for one record, by natural key or id,
+         * so its next read resolves it again. False when Foir holds no such
+         * record. For a source read live from its host.
+         */
+        refresh(model: string, idOrKey: string): Promise<{
+            refreshed: boolean;
+        }>;
+        /**
+         * Change the natural key of the one record a filter matches. The platform
+         * refuses a filter matching none or several, and a key already held.
+         */
+        rename(model: string, where: JsonObject, naturalKey: string): Promise<void>;
+        /**
+         * Update every record matching a filter, in one call. `where` and `data`
+         * are the model's typed filter and update, by model field key. An empty
+         * filter is refused: it would change every record.
+         */
+        updateMany(model: string, input: {
+            where: JsonObject;
+            data: JsonObject;
+            idempotencyKey?: string;
+        }): Promise<{
+            count: number;
+            ids: string[];
+        }>;
+        /**
+         * How many records match, grouped by one field, counted by the platform.
+         * It groups only by an indexed field, largest group first; `truncated`
+         * says `limit` cut the list short.
+         */
+        aggregate(model: string, query: {
+            groupBy: string;
+            where?: JsonObject;
+            limit?: number;
+        }): Promise<{
+            groups: Array<{
+                key: string | null;
+                count: number;
+            }>;
+            truncated: boolean;
+        }>;
+        /**
+         * The record of a customer the app names by identity: their id at the
+         * external system, which is also the subject of their sign-in with it. For
+         * a source that declares an identity. The platform finds the customer
+         * through the sign-in the install pairs with the source, at the install's
+         * level, and never by email.
+         */
+        customer: {
+            /**
+             * Merge `data` into the customer's record, making the record when they
+             * have none, and the customer when `email` is given and nobody holds the
+             * identity. An identity nobody holds, with no email, is `{ unlinked:
+             * true }`: nothing was written, and they are known once they sign in.
+             */
+            save(input: {
+                model: string;
+                identity: string;
+                data: JsonObject;
+                email?: string;
+                sourceModifiedAt?: string;
+            }): Promise<AppCustomerSaveResult>;
+            /** The customer's record, or null when nobody holds the identity or they hold no record. */
+            read(model: string, identity: string): Promise<AppRecord | null>;
+            /**
+             * Erase what the app holds for the customer, as a privacy request asks:
+             * their record and the identity's link, and the customer when nothing
+             * else is attached to them. Needs `customers:write` as well.
+             */
+            erase(model: string, identity: string): Promise<AppCustomerEraseResult>;
+            /**
+             * The other direction: the identities a customer the app names by id
+             * signs in with there, most recently seen first. Empty when they sign in
+             * with none. For an app acting on an event that names the Foir customer.
+             */
+            identities(model: string, customerId: string): Promise<string[]>;
+        };
+    };
+    customers: {
+        /**
+         * The customer who has this email at the install's level, made when there
+         * is none. The same customer every time for one email. Needs
+         * `customers:write`.
+         */
+        ensure(email: string): Promise<{
+            id: string;
+            email: string;
+        }>;
+    };
+    notifications: {
+        /** Tell a customer something. Needs `notifications:write`. */
+        send(notification: AppNotification): Promise<void>;
+        /**
+         * Set a named customer's consent in an opt-in category. Needs
+         * `notifications:consent`, which only an operation's token carries.
+         */
+        setConsent(change: AppConsentChange): Promise<{
+            stale: boolean;
+        }>;
+    };
+}
+/** Build the client an installed app calls Foir with. See the module doc. */
+export declare function createAppClient(config: AppClientConfig): AppClient;
+export {};

package/dist/app/contract/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The app contract, as the messages the platform itself reads and writes.
+ *
+ * A manifest is `AppConfig`, and a discovery answer is `DiscoveryResult`. They
+ * are generated from the same definitions the platform decodes them with, so a
+ * manifest built with `create(AppConfigSchema, …)` and written with `toJson`
+ * cannot carry a key the platform would refuse: it would not compile.
+ *
+ * ```ts
+ * import { create, toJson } from '@bufbuild/protobuf';
+ * import { AppConfigSchema } from '@foir/sdk/app/contract';
+ *
+ * const manifest = create(AppConfigSchema, { name: 'my-app', version: '1.0.0' });
+ * const served = toJson(AppConfigSchema, manifest, { useProtoFieldName: true });
+ * ```
+ *
+ * These are protobuf-es messages, so this subpath needs `@bufbuild/protobuf`
+ * installed beside the SDK; the rest of the SDK does not. The messages follow
+ * the platform's contract, which only ever grows: a field or a message can
+ * appear in any release, and none is removed without a breaking one.
+ */
+export * from './proto/apps/v1/apps_pb.js';
+export * from './proto/apps/v1/discovery_pb.js';