@sanoma-ai/workflows 0.0.0-stage → 0.2.0

package/dist/drift.d.ts

@@ -0,0 +1,127 @@
+import { z } from "zod";
+import { type WorkflowDefinition } from "./define.ts";
+import type { Op } from "./op.ts";
+import { type DriftField, type Resource } from "./resource.ts";
+import type { DeclaredResource, ResourceProblem } from "./resources.ts";
+import { type sourceOps } from "./source.ts";
+export type { DriftField } from "./resource.ts";
+export { DRIFT_WORKFLOW } from "./shared.ts";
+/**
+ * How a declared resource compares: `clean` when every declared field of its bound object holds
+ * its declared value, `drifted` when one does not, `gone` when the vendor no longer has its bound
+ * object, `absent` when it is bound to none (whether or not its identity finds one: `found`), and
+ * `error` when it could not be read (the vendor's error, a policy denial, or no driver for its type).
+ */
+export type DriftStatus = "clean" | "drifted" | "gone" | "absent" | "error";
+/** One declared resource in a drift report. */
+export interface DriftResult {
+    /** The resource's id, `<file>#<export>`: `resources/identity/github.ts#website`. */
+    id: string;
+    /** Its type within the vendor, such as `repository`. */
+    type: string;
+    vendor: string;
+    /** What people call it: its identity, else its export's name. */
+    name: string;
+    status: DriftStatus;
+    /** The vendor's id of the object the lockfile binds it to; absent when unbound. */
+    binding?: string;
+    /** For `absent`: the binding id of the object its identity found, which apply may bind it to. */
+    found?: string;
+    /** The declared fields that differ; empty unless `drifted`. */
+    fields: DriftField[];
+    /** Why it could not be read, for `error`. */
+    error?: string;
+}
+/** The drift workflow's output. */
+export interface DriftReport {
+    /** Epoch milliseconds, by `ctx.now()`. */
+    startedAt: number;
+    /** Epoch milliseconds, by `ctx.now()`. */
+    finishedAt: number;
+    /** What was wrong in the data files when the run read them: their resources are not in `resources`. */
+    problems: ResourceProblem[];
+    /** Each resource the data files declared when the run read them, in their order. */
+    resources: DriftResult[];
+}
+/**
+ * The drift workflow's input: nothing. The run reads the data files itself, so a run says what
+ * they declared when it ran, and no caller can hand it other resources to check.
+ */
+export declare const DriftInput: z.ZodObject<{}, z.core.$strict>;
+/**
+ * What a drift run records of the data files, as its first step: each resource without its
+ * write-only values, and the problems.
+ */
+export interface DriftDeclared {
+    resources: Pick<DeclaredResource, "id" | "vendor" | "type" | "name" | "identity" | "binding" | "desired" | "refs">[];
+    problems: ResourceProblem[];
+}
+type State = Record<string, unknown>;
+type ImportOp = Op<string, string, "import", {
+    id: string;
+}, {
+    id: string;
+    gone: boolean;
+    state?: State;
+}>;
+export type ResolveOp = typeof sourceOps.source.resolve;
+/** What one import found: the object's state, that it is gone, or why it could not be read. */
+export type Found = {
+    state: State;
+} | {
+    gone: true;
+} | {
+    error: string;
+};
+/** What a host's ref names now, or why it could not be resolved. */
+export type Revision = {
+    revision: string;
+} | {
+    error: string;
+};
+/** The `import` ops of the types among `ops` with a driver, by type, sorted: what observing them uses. */
+export declare function importsOf(types: ReadonlyMap<string, Resource>, ops: ReadonlyMap<string, Op>, drivers: ReadonlyMap<string, unknown>): ImportOp[];
+/**
+ * What a declared resource is observed by: the import id (`by`, default its binding, else its
+ * identity), or without one what it is found to be: `gone` for none, `error` when its type is
+ * not the connectors' or has no import among `imports`.
+ */
+export declare function observeBy({ vendor, type, binding, identity }: Pick<DeclaredResource, "vendor" | "type" | "binding" | "identity">, types: ReadonlyMap<string, Resource>, imports: readonly Pick<Op, "id">[], by?: string | undefined): {
+    id: string;
+} | Found;
+/** What an import's answer found. */
+export declare const observed: (out: {
+    gone: boolean;
+    state?: State;
+}) => Found;
+/**
+ * Each declared resource against what its import `found`: `error`, `absent` (unbound, with the
+ * binding id of what its identity found as `found`), `gone`, else the state and the declared
+ * fields compared by `diffDeclared`, a reference against the state of the resource it names
+ * (so GitHub's node id for a repository counts as its name). A host with a `revisions` entry
+ * also compares its revision against the commit its ref names now (or is that entry's `error`).
+ */
+export declare function compare(types: ReadonlyMap<string, Resource>, resources: DriftDeclared["resources"], found: ReadonlyMap<string, Found>, revisions?: ReadonlyMap<string, Revision>): DriftResult[];
+/**
+ * The drift workflow for a config: it `uses` the `import` of every resource type the connectors
+ * declare (`types`) that has a driver, so its version changes with them, not with the data
+ * files. `resolveConfig` adds it to a config whose connectors declare resource types, with
+ * `declared`, the step that reads the data files.
+ *
+ * A run reads the data files and the lockfile (`declared`, recorded as a step, so a replay checks
+ * the same list), then imports each resource by its binding, else by its identity, in the files'
+ * order: one vendor call each, none for a resource with neither. A bound resource whose import
+ * says gone is `gone`; an unbound one is `absent`, with the binding id of what its identity found
+ * as `found`. Else the state and the declared fields are compared by `diffDeclared`, a reference
+ * against the state of the resource it names, read in the same run (so GitHub's node id for a
+ * repository counts as its name). A failed call is that resource's
+ * `error`, and the run goes on to the next; a failure that ends the run (`isRunControlError`)
+ * ends it.
+ */
+export declare function driftWorkflow(types: ReadonlyMap<string, Resource>, ops: ReadonlyMap<string, Op>, drivers: ReadonlyMap<string, unknown>, declared: () => Promise<DriftDeclared>): WorkflowDefinition<readonly (ImportOp | ResolveOp)[], typeof DriftInput>;
+/**
+ * A host's source: the clone URL its data file gives, or, when it names a declared repository
+ * (`target`), the first of the reference's `by` fields that holds one in that repository's state,
+ * read in this run.
+ */
+export declare function sourceUrl(desired: State, target: string | undefined, { host, fields }: Resource, found: ReadonlyMap<string, Found>): string | undefined;

package/dist/drift.js

@@ -0,0 +1,167 @@
+import { z } from "zod";
+import { defineWorkflow } from "./define.js";
+import { isRunControlError } from "./errors.js";
+import { diffDeclared, fieldPathOf, valueAt } from "./resource.js";
+import { errorMessage } from "./shared.js";
+import { SOURCE_RESOLVE } from "./source.js";
+export { DRIFT_WORKFLOW } from "./shared.js";
+/**
+ * The drift workflow's input: nothing. The run reads the data files itself, so a run says what
+ * they declared when it ran, and no caller can hand it other resources to check.
+ */
+export const DriftInput = z.object({}).strict();
+/** A clone URL (a scheme's, or scp-like `user@host:path`): what a `by` field of a host's source holds, told from an id. */
+const CLONE_URL = /^((https?|ssh|git|file):\/\/|[\w.-]+@[\w.-]+:)/;
+// What drift and apply share. Observing a resource is one `ctx` call, which a workflow makes in
+// its own `run` (the outline draws only those): `observeBy` says what each import is called with,
+// `observed` reads its answer, and `compare` turns what every import found into drift's results.
+/** The `import` ops of the types among `ops` with a driver, by type, sorted: what observing them uses. */
+export function importsOf(types, ops, drivers) {
+    return [...types.keys()].toSorted().flatMap((type) => {
+        const op = ops.get(`${type}.import`);
+        return op && drivers.has(op.id) ? [op] : [];
+    });
+}
+/**
+ * What a declared resource is observed by: the import id (`by`, default its binding, else its
+ * identity), or without one what it is found to be: `gone` for none, `error` when its type is
+ * not the connectors' or has no import among `imports`.
+ */
+export function observeBy({ vendor, type, binding, identity }, types, imports, by = binding ?? identity) {
+    const key = `${vendor}.${type}`;
+    if (!types.has(key))
+        return { error: `the config's connectors declare no resource type ${key}` };
+    if (!imports.some((op) => op.id === `${key}.import`))
+        return { error: `no driver for ${key}.import` };
+    return by === undefined ? { gone: true } : { id: by };
+}
+/** What an import's answer found. */
+export const observed = (out) => out.gone || !out.state ? { gone: true } : { state: out.state };
+/**
+ * Each declared resource against what its import `found`: `error`, `absent` (unbound, with the
+ * binding id of what its identity found as `found`), `gone`, else the state and the declared
+ * fields compared by `diffDeclared`, a reference against the state of the resource it names
+ * (so GitHub's node id for a repository counts as its name). A host with a `revisions` entry
+ * also compares its revision against the commit its ref names now (or is that entry's `error`).
+ */
+export function compare(types, resources, found, revisions = new Map()) {
+    return resources.map(({ id, vendor, type, name, binding, desired, refs }) => {
+        const row = { id, type, vendor, name, ...(binding !== undefined && { binding }) };
+        const now = found.get(id);
+        if ("error" in now)
+            return { ...row, status: "error", fields: [], error: now.error };
+        const resource = types.get(`${vendor}.${type}`);
+        if (binding === undefined) {
+            return {
+                ...row,
+                status: "absent",
+                fields: [],
+                ...("state" in now && { found: resource.bindingId(now.state) }),
+            };
+        }
+        if ("gone" in now)
+            return { ...row, status: "gone", fields: [] };
+        // Each reference, by where it is: the values the vendor may hold there for its resource.
+        const accept = {};
+        for (const [at, target] of Object.entries(refs)) {
+            const by = resource.fields.references?.[fieldPathOf(at)]?.by ?? [];
+            const named = found.get(target);
+            if (named && "state" in named)
+                accept[at] = by.map((field) => named.state[field]).filter((v) => v != null);
+        }
+        const fields = diffDeclared(resource, now.state, desired, accept);
+        const resolved = revisions.get(id);
+        if (resolved && "error" in resolved)
+            return { ...row, status: "error", fields: [], error: resolved.error };
+        // A host whose state does not say which commit it runs is not compared.
+        const actual = resource.host?.outputs(now.state).revision;
+        if (resolved && actual !== undefined && actual !== resolved.revision) {
+            fields.push({ path: resource.host.revision, desired: resolved.revision, actual });
+        }
+        return { ...row, status: fields.length ? "drifted" : "clean", fields };
+    });
+}
+/**
+ * The drift workflow for a config: it `uses` the `import` of every resource type the connectors
+ * declare (`types`) that has a driver, so its version changes with them, not with the data
+ * files. `resolveConfig` adds it to a config whose connectors declare resource types, with
+ * `declared`, the step that reads the data files.
+ *
+ * A run reads the data files and the lockfile (`declared`, recorded as a step, so a replay checks
+ * the same list), then imports each resource by its binding, else by its identity, in the files'
+ * order: one vendor call each, none for a resource with neither. A bound resource whose import
+ * says gone is `gone`; an unbound one is `absent`, with the binding id of what its identity found
+ * as `found`. Else the state and the declared fields are compared by `diffDeclared`, a reference
+ * against the state of the resource it names, read in the same run (so GitHub's node id for a
+ * repository counts as its name). A failed call is that resource's
+ * `error`, and the run goes on to the next; a failure that ends the run (`isRunControlError`)
+ * ends it.
+ */
+export function driftWorkflow(types, ops, drivers, declared) {
+    const imports = importsOf(types, ops, drivers);
+    const resolve = ops.get(SOURCE_RESOLVE);
+    const uses = [...imports, ...(resolve ? [resolve] : [])];
+    return defineWorkflow({
+        // The literal, held to the one name: the outline finds a workflow by a string, or a const of its own file.
+        name: "drift",
+        title: "Check resources for drift",
+        trigger: "manual",
+        input: DriftInput,
+        uses,
+        run: async (ctx) => {
+            const startedAt = await ctx.now();
+            const { resources, problems } = await declared();
+            // Every import first, so a reference compares against what its resource holds now.
+            const found = new Map();
+            for (const resource of resources) {
+                const by = observeBy(resource, types, imports);
+                // An if/else, not a `continue`: the outline draws the import as the way past the error.
+                if (!("id" in by))
+                    found.set(resource.id, by);
+                else {
+                    try {
+                        found.set(resource.id, observed(await ctx[resource.vendor][resource.type].import({ id: by.id })));
+                    }
+                    catch (err) {
+                        if (isRunControlError(err))
+                            throw err;
+                        found.set(resource.id, { error: errorMessage(err) });
+                    }
+                }
+            }
+            // A host's revision against the commit its ref names now: a merge is drift on the host.
+            const revisions = new Map();
+            for (const { id, vendor, type, desired, refs } of resources) {
+                const resource = types.get(`${vendor}.${type}`);
+                const host = resource?.host;
+                const source = host && sourceUrl(desired, refs[host.inputs.source], resource, found);
+                const ref = host && valueAt(desired, host.inputs.ref);
+                if (host && "state" in found.get(id) && source !== undefined && typeof ref === "string" && ref) {
+                    try {
+                        revisions.set(id, await ctx.sanoma.source.resolve({ url: source, ref }));
+                    }
+                    catch (err) {
+                        if (isRunControlError(err))
+                            throw err;
+                        revisions.set(id, { error: errorMessage(err) });
+                    }
+                }
+            }
+            const results = compare(types, resources, found, revisions);
+            return { startedAt, finishedAt: await ctx.now(), problems, resources: results };
+        },
+    });
+}
+/**
+ * A host's source: the clone URL its data file gives, or, when it names a declared repository
+ * (`target`), the first of the reference's `by` fields that holds one in that repository's state,
+ * read in this run.
+ */
+export function sourceUrl(desired, target, { host, fields }, found) {
+    const path = host.inputs.source;
+    const named = target === undefined ? undefined : found.get(target);
+    const by = fields.references?.[path]?.by ?? [];
+    const values = target === undefined ? [valueAt(desired, path)] : named && "state" in named ? by.map((f) => named.state[f]) : [];
+    return values.find((v) => typeof v === "string" && CLONE_URL.test(v));
+}
+//# sourceMappingURL=drift.js.map

package/dist/drift.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"drift.js","sourceRoot":"","sources":["../src/drift.ts"],"names":[],"mappings":"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"}

package/dist/env.d.ts

@@ -0,0 +1,49 @@
+import type { Driver, DriverEnv } from "./op.ts";
+/** One environment variable a driver declares in `env`, and whether its value lets the driver run: never the value. */
+export interface CredentialStatus {
+    /** The variable's name, such as `GHOST_ADMIN_API_KEY`. */
+    name: string;
+    /** Its one-line manual, from its schema's `.describe()`. */
+    description?: string;
+    /** It may be unset. */
+    optional: boolean;
+    /** `missing` when unset or empty; `invalid` when its schema refuses the value. */
+    status: "set" | "missing" | "invalid";
+    /** Why it is `invalid`: the schema's first issue, never the value. */
+    problem?: string;
+    /**
+     * Where the value is from, when there is one: the process environment, which wins, or the
+     * credentials stored with `SanomaClient.setCredential`. Only `SanomaClient.credentials` says.
+     */
+    source?: "environment" | "stored";
+    /** Who set the stored value (`setCredential`'s `by`). */
+    setBy?: string;
+    /** When the stored value was set, as an ISO 8601 time. */
+    setAt?: string;
+}
+/**
+ * Each vendor's driver's `env` (a resolved config's `driversByVendor`), by vendor in the map's
+ * order (a vendor whose driver declares none has no entry), each variable in declared order and
+ * checked against the value `lookup` gives for its name: only the declared names are looked up,
+ * an empty value counts as unset, and a value is never kept. The one walk of the declarations:
+ * the worker, the client and its checks all read them through it.
+ */
+export declare function credentialsOf(drivers: ReadonlyMap<string, Driver>, lookup: (name: string) => string | undefined): Map<string, CredentialStatus[]>;
+/** One driver's `env`, each variable checked against `lookup`'s value, as `credentialsOf` checks it. */
+export declare function statusesOf(env: DriverEnv, lookup: (name: string) => string | undefined): CredentialStatus[];
+/**
+ * Why the vendor's drivers cannot run on `statuses`, as a call to one fails (`startWorker` names
+ * the vendor alone, `unconfiguredSummary`): `<vendor> is not configured: <problems>; <hint>`, a
+ * missing variable (not optional) as `NAME (description)`, an invalid one as `NAME is invalid:
+ * <why>`, never a value. The hint says
+ * where to set them: in the environment when an invalid value is there (the environment wins
+ * over a stored value, so the connector page cannot replace it), else on the connector page.
+ * Undefined when the drivers can run.
+ */
+export declare function unconfigured(vendor: string, statuses: readonly CredentialStatus[]): string | undefined;
+/**
+ * The one line `startWorker` prints for the vendors whose drivers cannot run yet (`vendors`, those
+ * `unconfigured` has a message for) among the config's `total`: their names alone, since a call
+ * to one fails with its own message, and its connector page says the same. Undefined for none.
+ */
+export declare function unconfiguredSummary(vendors: readonly string[], total: number): string | undefined;

package/dist/env.js

@@ -0,0 +1,83 @@
+import { credentialReady } from "./shared.js";
+/**
+ * Each vendor's driver's `env` (a resolved config's `driversByVendor`), by vendor in the map's
+ * order (a vendor whose driver declares none has no entry), each variable in declared order and
+ * checked against the value `lookup` gives for its name: only the declared names are looked up,
+ * an empty value counts as unset, and a value is never kept. The one walk of the declarations:
+ * the worker, the client and its checks all read them through it.
+ */
+export function credentialsOf(drivers, lookup) {
+    const map = new Map();
+    for (const [vendor, { env }] of drivers)
+        if (env)
+            map.set(vendor, statusesOf(env, lookup));
+    return map;
+}
+/** One driver's `env`, each variable checked against `lookup`'s value, as `credentialsOf` checks it. */
+export function statusesOf(env, lookup) {
+    return Object.entries(env.shape).map(([name, schema]) => credentialStatus(name, schema, lookup(name) || undefined));
+}
+/**
+ * Why the vendor's drivers cannot run on `statuses`, as a call to one fails (`startWorker` names
+ * the vendor alone, `unconfiguredSummary`): `<vendor> is not configured: <problems>; <hint>`, a
+ * missing variable (not optional) as `NAME (description)`, an invalid one as `NAME is invalid:
+ * <why>`, never a value. The hint says
+ * where to set them: in the environment when an invalid value is there (the environment wins
+ * over a stored value, so the connector page cannot replace it), else on the connector page.
+ * Undefined when the drivers can run.
+ */
+export function unconfigured(vendor, statuses) {
+    const unready = statuses.filter((c) => !credentialReady(c));
+    if (!unready.length)
+        return undefined;
+    const problems = unready.map((c) => c.status === "invalid"
+        ? `${c.name} is invalid: ${c.problem}`
+        : `${c.name}${c.description ? ` (${c.description})` : ""}`);
+    const inEnvironment = unready.some((c) => c.status === "invalid" && process.env[c.name]);
+    const hint = inEnvironment ? "set in the environment" : "set it on the connector page";
+    return `${vendor} is not configured: ${problems.join(", ")}; ${hint}`;
+}
+/**
+ * The one line `startWorker` prints for the vendors whose drivers cannot run yet (`vendors`, those
+ * `unconfigured` has a message for) among the config's `total`: their names alone, since a call
+ * to one fails with its own message, and its connector page says the same. Undefined for none.
+ */
+export function unconfiguredSummary(vendors, total) {
+    if (!vendors.length)
+        return undefined;
+    return (`${vendors.length} of ${total} connectors not configured yet: ${vendors.join(", ")}; ` +
+        "set their variables on the connector pages or in the environment");
+}
+function credentialStatus(name, schema, value) {
+    const description = descriptionOf(schema);
+    const parsed = value === undefined ? undefined : check(schema, value);
+    const problem = parsed?.problem;
+    return {
+        name,
+        ...(description !== undefined && { description }),
+        optional: check(schema, undefined).success,
+        status: !parsed ? "missing" : parsed.success ? "set" : "invalid",
+        ...(problem !== undefined && { problem }),
+    };
+}
+/**
+ * `schema.safeParse(value)`, with its first issue's message as the problem. A check that throws
+ * (zod lets a `.refine()` or `.transform()` throw) fails without its error, which may carry the value.
+ */
+function check(schema, value) {
+    try {
+        const { success, error } = schema.safeParse(value);
+        return { success, ...(error && { problem: error.issues[0].message }) };
+    }
+    catch {
+        return { success: false, problem: "its check threw" };
+    }
+}
+/** A schema's `.describe()`, also through `.optional()`, `.default()` and `.prefault()` in any order. */
+function descriptionOf(schema) {
+    let s = schema;
+    while (s && !s.description)
+        s = "unwrap" in s ? s.unwrap() : undefined;
+    return s?.description;
+}
+//# sourceMappingURL=env.js.map

package/dist/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,88 @@
+import type { z } from "zod";
+import type { Principal } from "./define.ts";
+declare const CODES: readonly ["policy_denied", "approval_rejected", "not_approver", "no_pending_approval", "already_decided", "run_not_found", "driver_failed", "invalid_input", "run_ended", "run_running", "call_not_in_outline"];
+/**
+ * Why something failed, as a stable string a caller can branch on. Messages are for people
+ * and may change; codes are the contract.
+ */
+export type ErrorCode = (typeof CODES)[number];
+/**
+ * An error with a `code` and plain-JSON `data`, both own enumerable properties, so they survive
+ * the trip through DBOS: a run's error is stored serialized and comes back as a new object that
+ * is not an instance of this class. Read the code with `errorCode`, never `instanceof`.
+ */
+export declare class SanomaError extends Error {
+    readonly code: ErrorCode;
+    readonly data: Record<string, unknown>;
+    constructor(code: ErrorCode, message: string, data?: Record<string, unknown>, options?: ErrorOptions);
+}
+/** The error's code, read from its own `code` property, or undefined when it has none of ours. */
+export declare function errorCode(e: unknown): ErrorCode | undefined;
+/**
+ * True when the error says trying again would only repeat it (`retryable: false`), as a
+ * `DriverError` for a vendor's final answer or a ledger store for a corrupt file does. Read as
+ * a property, never `instanceof`: the error may come from another copy of this package.
+ */
+export declare const isFinal: (err: unknown) => boolean;
+/** The error and the ones it was caused by, a few deep. */
+export declare function causes(err: unknown): Error[];
+/**
+ * True for a failure that ends the run rather than one call: anything DBOS throws (it cancelled
+ * the run, another process took it over, the worker is shutting down, the run is not
+ * deterministic) and `run_ended` (a call queued after the run's body ended). Looked for in the
+ * error and its causes. A workflow that goes on past a failed call, as `drift` does, rethrows these.
+ */
+export declare const isRunControlError: (err: unknown) => boolean;
+/** Thrown into the run when the policy denies an operation call. The run fails with it. */
+export declare class PolicyDeniedError extends SanomaError {
+    constructor(op: string, reason: string);
+}
+/** Thrown into the run when an approver rejects. The run fails with it. */
+export declare class RejectedError extends SanomaError {
+    /**
+     * @param title The approval's title.
+     * @param by Who rejected it.
+     * @param approvalId The approval's id in the run, such as "approval-2".
+     */
+    constructor(title: string, by: Principal, note: string | undefined, approvalId: string);
+}
+/**
+ * The wrapper, given the original's own `code` and `data` when it has one of our codes, so
+ * `errorCode` reads the same through it: a denied call whose ledger write failed too is still
+ * `policy_denied`.
+ */
+export declare function keepCode<E extends Error>(wrapper: E, original: unknown): E;
+/** A zod issue as the ledger and an API can carry it: no symbols in the path. */
+export interface InputIssue {
+    path: (string | number)[];
+    message: string;
+    code: string;
+}
+/** The value, parsed by the schema, or an `invalid_input` error carrying zod's issues and `data`. */
+export declare function parseOrThrow<T extends z.ZodType>(schema: T, value: unknown, what: string, data?: Record<string, unknown>): z.output<T>;
+/** An `invalid_input` error from zod issues, with the issues in `data` and a one-line message. */
+export declare function invalidInput(what: string, zodIssues: readonly {
+    path: PropertyKey[];
+    message: string;
+    code: string;
+}[], data?: Record<string, unknown>): SanomaError;
+/**
+ * What the ledger keeps of an error. `status`, `vendorCode` and `retryable` are a
+ * `DriverError`'s account of the vendor's answer; `data` is one of the runtime's errors'. Each is
+ * there only when the error has it, and `data`, `status` and `vendorCode` only from those errors.
+ */
+export interface ErrorInfo {
+    code?: ErrorCode;
+    name: string;
+    message: string;
+    /** The vendor's HTTP status, from a `DriverError`. */
+    status?: number;
+    /** The vendor's own error code, from a `DriverError`. */
+    vendorCode?: string;
+    /** Whether trying again could succeed, from a `DriverError` or a ledger store. */
+    retryable?: boolean;
+    /** A `SanomaError`'s `data`: the operation, the approval, the issues. */
+    data?: Record<string, unknown>;
+}
+export declare function errorInfo(err: unknown): ErrorInfo;
+export {};