@foir/sdk 0.11.0 → 0.13.0

package/dist/app/dispatch.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The bodies the platform sends an app's operation endpoint.
+ *
+ * `readDispatch` (`@foir/sdk/server`) reads the body an operation run is
+ * queued with. An app's endpoint is reached two more ways, each with a body of
+ * its own, and all three arrive at the same route:
+ *
+ *   a queued run        `{ executionId, operationKey, trigger, input, context,
+ *                         callback?, continuation?, ... }`: every ASYNC run,
+ *                         and every run a hook, a schedule or `execute<Op>`
+ *                         starts.
+ *   a direct call       `{ project, app, operation, triggered_by,
+ *                         execution_id, input? }`: an operator running a SYNC
+ *                         operation from the console, discovery during setup,
+ *                         and the uninstall teardown. Nothing is queued, so
+ *                         `execution_id` is the id of the token the call
+ *                         carried and no execution holds it.
+ *   the credential probe `{ project, app, operation, values }`: the reserved
+ *                         `__validate_credentials` operation, sent the
+ *                         credential an operator is about to save.
+ *
+ * `readAppDispatch` reads the first two as one shape. `readCredentialProbe`
+ * reads the third.
+ */
+import type { OperationCallback, OperationContinuationBlock } from '../server/operation-types';
+/** An app operation's dispatch, whichever way it arrived. */
+export interface AppDispatch {
+    /** The run's id on a queued run. On a direct call, the id of the token it carried. Absent when the body named neither. */
+    executionId?: string;
+    /** The operation's key as the platform stores it, `<app>/<key>` for an app's own. For logging: route on your URL. */
+    operationKey?: string;
+    /** How the run was started: a trigger type on a queued run (`api`, `lifecycle`...), or what the caller named (`manual`, `uninstall`). */
+    triggeredBy?: string;
+    /** What the caller passed. `null` when it passed nothing. */
+    input: unknown;
+    /** Where to report an ASYNC run's outcome. Present only on a queued ASYNC run. */
+    callback?: OperationCallback;
+    /** Where this slice of a run resumes. See `continueRun`. */
+    continuation?: OperationContinuationBlock;
+    /** The body as it was sent, for a block this reader has no name for. */
+    raw: Record<string, unknown>;
+}
+/**
+ * Read an app operation's dispatch body, already parsed from JSON.
+ *
+ * It does not refuse a body it cannot place: a direct call may carry no input
+ * and no id, and an endpoint that answered 4xx to one would fail an operator's
+ * action over a field it does not need. What is absent is absent on the
+ * answer.
+ */
+export declare function readAppDispatch(body: unknown): AppDispatch;
+/**
+ * Read the credential probe's body: the values an operator submitted, by the
+ * manifest's credential field names. Every value the credential store accepts
+ * is a string, so anything else is left out rather than handed on as a
+ * surprise.
+ *
+ * The probe carries no `X-Foir-Context`, and whatever answers it with a
+ * non-2xx blocks the operator's save. So answer 400 only for a value they can
+ * retype, and 200 for everything else, including a check you could not run.
+ */
+export declare function readCredentialProbe(body: unknown): {
+    values: Record<string, string>;
+};

package/dist/app/errors.d.ts

@@ -0,0 +1,50 @@
+/**
+ * What the platform said when it refused an app's call.
+ *
+ * Every call an app client makes fails with the package's one error,
+ * `FoirRequestError`, carrying the platform's own answer. Nothing is checked
+ * before the call: the token's capabilities are the platform's to hold it to,
+ * and its refusal names the reason. The readers here pick out the refusals an
+ * app acts on rather than reports, as data and never by the wording of a
+ * message.
+ */
+/** A write refused because another record holds its key on one of the model's lookups. */
+export interface AppLookupConflict {
+    model: string;
+    lookup: string;
+    /** The fields the lookup is keyed by, as the model declares them. */
+    keyBy: string[];
+}
+/**
+ * The lookup a refused write collided on, or null for any other failure.
+ *
+ * The usual cause is a vendor that lets its users change the value a record is
+ * keyed on: written under the new key, the object is refused because its own
+ * id already belongs to a record. That record is the object under its old key,
+ * and `records.rename` moves it.
+ */
+export declare function appLookupConflictOf(error: unknown): AppLookupConflict | null;
+/**
+ * A save to a customer's record refused because no customer holds the
+ * identity at the install's level and no email came to make one, or null for
+ * any other failure. Nothing is wrong with the row: the customer is known once
+ * they sign in with the sign-in the install pairs with the source.
+ */
+export declare function appCustomerUnlinkedOf(error: unknown): {
+    model: string;
+    identityProvider: string;
+} | null;
+/**
+ * Whether a read failed because the token is not served the field it asked
+ * for: the field is not on the schema this token's capabilities reach. That is
+ * the platform's refusal of a read, as data: the selection it stripped.
+ *
+ * `field` narrows it to one root field. The platform names a stripped
+ * selection by its path from the operation, which leads with the operation's
+ * name (`query` when it has none), so a root field is the path's second and
+ * last step.
+ *
+ * A refused WRITE is not answered here: the platform refuses a mutation
+ * outright, with its reason in the error.
+ */
+export declare function isAppFieldWithheld(error: unknown, field?: string): boolean;

package/dist/app/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @foir/sdk/app: what an app installed from the marketplace is built with.
+ *
+ * An app is a server Foir calls: it serves a manifest, and the platform
+ * dispatches its operations, its webhooks and its credential probe to it, each
+ * carrying a token for one install. This subpath is the app's half of that
+ * conversation, beside `@foir/sdk/server`, which holds the half every
+ * operation endpoint shares (verifying the token, the callback, continuing a
+ * run).
+ *
+ *   createAppClient        call Foir as the install, with the token a dispatch
+ *                          carried: its configuration, credential and status,
+ *                          records of the models it maps, customers and
+ *                          notifications.
+ *   readAppDispatch        the body of a dispatch, whichever way it arrived,
+ *   readCredentialProbe    and of the credential probe.
+ *   redeemExchangeTicket   the token an OAuth callback writes a credential with.
+ *   validateAppManifest    ask the platform whether it would accept a manifest.
+ *   APP_CAPABILITIES…      the capabilities and hook events the contract lists.
+ *
+ * The manifest's own messages are on `@foir/sdk/app/contract`.
+ */
+export { createAppClient } from './client';
+export type { AppBinding, AppClient, AppClientConfig, AppConsentChange, AppCustomerEraseResult, AppCustomerSaveResult, AppFieldMapping, AppInstallConfig, AppNotification, AppOperationStart, AppRecord, AppRecordList, AppStartedOperation, AppStatusReport, AppSyncDirection, AppUpsertResult, AppWhoami, } from './client';
+export { appCustomerUnlinkedOf, appLookupConflictOf, isAppFieldWithheld } from './errors';
+export type { AppLookupConflict } from './errors';
+export { appModelFieldName, appModelTypeName, appSelectorEnumValue } from './naming';
+export { RECORD_KEY_RULE, recordKeyRefusal } from './record-key';
+export { readAppDispatch, readCredentialProbe } from './dispatch';
+export type { AppDispatch } from './dispatch';
+export { redeemExchangeTicket } from './ticket';
+export type { RedeemedExchangeTicket } from './ticket';
+export { validateAppManifest, MAX_APP_MANIFEST_BYTES } from './manifest';
+export type { AppManifestIssue, AppManifestValidation, ValidateAppManifestOptions } from './manifest';
+export { APP_CAPABILITIES, APP_HOOK_EVENTS, APP_RECORD_CAPABILITY_PREFIXES } from './vocabulary.generated';
+export type { AppCapability, AppHookEvent, AppRecordCapabilityPrefix } from './vocabulary.generated';
+export type { FoirDispatchCredential } from '../data/transport';
+export { FoirRequestError } from '../transport/foir-http';
+export type { FoirErrorCode, FoirErrorExtensions, FoirGraphQLErrorItem, FoirPrunedSelection } from '../transport/foir-http';
+export type { FoirRetryPolicy } from '../transport/retry';

package/dist/app/manifest.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Ask the platform whether it would accept an app's manifest.
+ *
+ * A manifest is held to rules only the platform knows in full: which
+ * capabilities exist, which events a hook may name, how a feature's storage
+ * may be declared, what an install would refuse. Copying those rules into an
+ * app's build means the copy and the platform disagree the first time either
+ * changes. So the build asks instead. `validateAppManifest` sends the manifest
+ * to the platform's own validation, as a dry run: nothing is registered and
+ * nothing is stored.
+ *
+ * ```ts
+ * const { ok, issues } = await validateAppManifest({ apiUrl, apiKey, manifest });
+ * if (!ok) throw new Error(issues.map((issue) => `${issue.path}: ${issue.message}`).join('\n'));
+ * ```
+ *
+ * Any credential the data API accepts may ask, a publishable key included: the
+ * check reads only the manifest it is handed.
+ */
+import type { FoirDispatchCredential } from '../data/transport';
+/** One thing validation found, at the path in the manifest it found it. */
+export interface AppManifestIssue {
+    /** ERROR: an install refuses the manifest over it. WARNING: it does not. */
+    severity: 'ERROR' | 'WARNING';
+    /** Where in the manifest, as a dotted path of its own field names. */
+    path: string;
+    message: string;
+}
+export interface AppManifestValidation {
+    /** True when no issue is an ERROR. */
+    ok: boolean;
+    issues: AppManifestIssue[];
+}
+/** The largest manifest the platform reads, in bytes. */
+export declare const MAX_APP_MANIFEST_BYTES: number;
+export type ValidateAppManifestOptions = {
+    /** The data API's origin, e.g. `https://api.foir.dev`. */
+    apiUrl: string;
+    /** The manifest: the object, or the JSON you serve. */
+    manifest: string | Record<string, unknown>;
+    /** Defaults to the global `fetch`. */
+    fetch?: typeof globalThis.fetch;
+    requestInit?: Omit<RequestInit, 'method' | 'headers' | 'body'>;
+} & ({
+    apiKey: string;
+    dispatch?: never;
+} | {
+    dispatch: FoirDispatchCredential;
+    apiKey?: never;
+});
+/**
+ * Validate a manifest against the platform's rules. Resolves with what the
+ * platform found; throws `FoirRequestError` only when the question could not
+ * be asked or answered.
+ */
+export declare function validateAppManifest(options: ValidateAppManifestOptions): Promise<AppManifestValidation>;

package/dist/app/naming.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The data API's names for a model's own fields.
+ *
+ * A project's schema gives each model a set of typed fields, named from the
+ * model's key: the singular query, `delete<Type>`, `<Type>WhereInput` and the
+ * rest. A client generated for one project reads those names off the schema.
+ * An app installed in many projects cannot, because the model is whichever one
+ * each operator mapped, so it derives them from the key the same way the
+ * schema does.
+ *
+ * The rule: split the key on every run of characters that are not letters or
+ * digits, upper-case the first character of each part, and join. The rest of a
+ * part is left as written, so `shopifyCustomer` stays `ShopifyCustomer`.
+ */
+/** The type name of a model: `blog_post` is `BlogPost`. */
+export declare function appModelTypeName(modelKey: string): string;
+/** The name of a model's singular query: `blog_post` is `blogPost`. */
+export declare function appModelFieldName(modelKey: string): string;
+/**
+ * A field key as a value of a selector enum (an aggregate's group-by):
+ * upper-cased, each run of anything that is not a letter or digit made one
+ * underscore, and led by an underscore when it would start with a digit. So
+ * `variantId` is `VARIANTID`.
+ */
+export declare function appSelectorEnumValue(fieldKey: string): string;
+/**
+ * Whether a model field key can be selected as written. A key that is not a
+ * legal GraphQL name is not on the type at all, and asking for it refuses the
+ * whole document.
+ */
+export declare function isSelectableFieldKey(fieldKey: string): boolean;

package/dist/app/record-key.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The rule for a record's key.
+ *
+ * A record's key is its address: the console routes to it and every client
+ * builds a link from it. So a key is one URL-safe path segment (letters,
+ * digits, "-", "_", "." and "~"), and never "." or "..", which a browser
+ * resolves away before the request leaves it. Every write refuses anything
+ * else, naming the key.
+ *
+ * It is stated here for an app that BUILDS keys, from a vendor's ids and
+ * handles: it can tell which of them can be a key as written, and encode the
+ * ones that cannot, instead of finding out from a refused write.
+ */
+/** The rule in words. */
+export declare const RECORD_KEY_RULE = "a record's key is one URL-safe segment: letters, digits, \"-\", \"_\", \".\" and \"~\", and never \".\" or \"..\"";
+/** Why a key would be refused, in the platform's words, or null for a key that is fine. */
+export declare function recordKeyRefusal(key: string): string | null;

package/dist/app/ticket.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The exchange ticket: how an app's own OAuth callback gets to write the
+ * credential it was just granted.
+ *
+ * An install that needs a vendor's consent sends the operator to the app's
+ * authorize route with a single-use ticket. When the vendor returns them, the
+ * app redeems the ticket for a short-lived token that can do one thing: write
+ * this install's credential. It cannot read the configuration, report status
+ * or read the credential back, and it cannot be renewed.
+ *
+ * ```ts
+ * const { dispatch } = await redeemExchangeTicket({ apiUrl, ticket });
+ * await createAppClient({ apiUrl, dispatch }).install.writeCredentials(values);
+ * ```
+ *
+ * Holding the ticket is the whole of the proof, so carry it only inside a
+ * state you signed and never in a URL you did not.
+ */
+import type { FoirDispatchCredential } from '../data/transport';
+export interface RedeemedExchangeTicket {
+    /** The token, as the credential for `createAppClient`. */
+    dispatch: FoirDispatchCredential;
+    /** When the token stops being accepted, as the platform stated it. */
+    expiresAt: string;
+}
+/**
+ * Redeem an exchange ticket. ONE ATTEMPT, on purpose: the ticket is single-use,
+ * so repeating a call whose answer was lost would find the ticket spent, and
+ * the operator's only way forward would be to start the install again. A
+ * failure here is the answer.
+ */
+export declare function redeemExchangeTicket(options: {
+    apiUrl: string;
+    ticket: string;
+    fetch?: typeof globalThis.fetch;
+    requestInit?: Omit<RequestInit, 'method' | 'headers' | 'body'>;
+}): Promise<RedeemedExchangeTicket>;

package/dist/app/vocabulary.generated.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Every event the platform emits, as a hook names it. Which of them a
+ * manifest's hook may subscribe to (an event of the project, that something
+ * emits) is the platform's to say: `validateAppManifest` answers it.
+ */
+export declare const APP_HOOK_EVENTS: readonly ["RECORD_CREATED", "RECORD_UPDATED", "RECORD_DELETED", "RECORD_PUBLISHED", "RECORD_UNPUBLISHED", "CUSTOMER_CREATED", "CUSTOMER_UPDATED", "CUSTOMER_DELETED", "CUSTOMER_MERGED", "SESSION_REVOKED", "OPERATION_COMPLETED", "OPERATION_FAILED", "OPERATION_CANCELLED", "OPERATION_TIMED_OUT", "ADMIN_MEMBERSHIP_GRANTED", "ADMIN_MEMBERSHIP_REVOKED", "ADMIN_ROLE_CHANGED", "TENANT_PLAN_CHANGED", "TENANT_SUBSCRIPTION_STATUS_CHANGED", "PROJECT_CREATED", "PROJECT_ARCHIVED", "INVITATION_ACCEPTED", "IMPORT_COMPLETED", "MIGRATION_APPLIED", "BULK_UPDATE_COMPLETED", "BULK_PUBLISH_COMPLETED", "CUSTOMER_PREFERENCE_CHANGED", "ORGANIZATION_CREATED", "ORGANIZATION_UPDATED", "ORGANIZATION_MOVED", "ORGANIZATION_SUSPENDED", "ORGANIZATION_RESUMED", "ORGANIZATION_DELETION_SCHEDULED", "ORGANIZATION_DELETION_CANCELLED", "ORGANIZATION_DELETED", "ORGANIZATION_MEMBER_ADDED", "ORGANIZATION_MEMBER_REMOVED", "ORGANIZATION_MEMBER_ROLE_CHANGED"];
+/** An event a hook can name. */
+export type AppHookEvent = (typeof APP_HOOK_EVENTS)[number];
+/** The capabilities an operation declares as written. */
+export declare const APP_CAPABILITIES: readonly ["config:read", "secrets:read.app", "secrets:put.app", "secrets:list.app", "secrets:delete.app", "status:write", "files:read", "files:list", "files:write", "customers:write", "notifications:write", "notifications:consent", "operations:complete"];
+/** A capability an operation declares as written. */
+export type AppCapability = (typeof APP_CAPABILITIES)[number];
+/**
+ * The capabilities an operation declares once per model. Each is a prefix: a
+ * model key follows it, or `$<name>` for the model an install maps one of the
+ * app's sources or sinks onto.
+ */
+export declare const APP_RECORD_CAPABILITY_PREFIXES: readonly ["records:read:", "records:write:", "records:delete:", "records:publish:", "records:attribute:"];
+/** A per-model capability's prefix. */
+export type AppRecordCapabilityPrefix = (typeof APP_RECORD_CAPABILITY_PREFIXES)[number];