@sanoma-ai/workflows 0.1.0 → 0.4.0

package/dist/resource.d.ts

@@ -1,5 +1,7 @@
 import { z } from "zod";
+import { type HostSpec } from "./host.ts";
 import { type Connector, type OpSpec, RESOURCE } from "./op.ts";
+import { type Secret } from "./secret.ts";
 /** Which fields of a resource are flagged, by dotted path (`pages.html_url`; a list's items have no index). */
 export interface ResourceFields {
     /** Changing it replaces the object. */
@@ -20,8 +22,8 @@ export interface ResourceFields {
 }
 /** Where a field names another declared resource: see `ResourceFields.references`. */
 export interface FieldReference {
-    /** The `<vendor>.<type>` of the resource it names. */
-    readonly type: string;
+    /** The `<vendor>.<type>` of the resource it names, or the types it may name one of. */
+    readonly type: string | readonly string[];
     /**
      * The fields of that resource's state the vendor may hold here instead of its `name`, such as
      * GitHub's `node_id`: a drift check takes any of their values, read in the same run, as the
@@ -44,20 +46,68 @@ export interface ResourceSpec<S extends z.ZodObject = z.ZodObject> {
     title: string;
     /**
      * How `find` makes the import id, for people: `name`, `repository_id:pattern`. The fields it
-     * names stay declarable even when the vendor sets them (Stripe's `id`).
+     * names stay declarable even when the vendor sets them. Absent with `find`: a type the vendor
+     * names alone (Stripe's) is found only by its binding.
      */
-    identity: string;
+    identity?: string;
     /** The resource's fields as a read returns them; a data file declares them, less the vendor-owned ones. */
     schema: S;
     fields: ResourceFields;
-    /** The vendor's id for a declared resource (the import id), from its declared fields. */
-    find: (desired: z.input<S>) => string;
+    /**
+     * The import id that finds a declared resource before it is bound, from its declared fields:
+     * its identity. Absent when its fields cannot name it.
+     */
+    find?: (desired: z.input<S>) => string;
+    /**
+     * The id a binding keeps for an object, from its state: stable for the object's life (GitHub's
+     * `node_id`, not its name), and one `import` accepts. Default: `String(state.id)`.
+     */
+    bindingId?: (state: State) => string;
     /**
      * The part of a state that a drift check compares, given what was declared. The check
      * compares `normalize(actual, desired)` with `normalize(desired, desired)`. Default:
      * `compareDeclared`, which keeps the declared fields only.
      */
     normalize?: (state: State, desired: z.input<S>) => State;
+    /**
+     * True when apply may change its objects: the type then has the change operations `plan`,
+     * `create`, `update` and `delete` besides `read` and `import`. Default false.
+     */
+    writable?: boolean;
+    /** Set when the type meets the `Host` contract: it runs the company. Such a type is `writable` and `stateless`. */
+    host?: HostSpec;
+    /**
+     * True when its objects hold no data, so one gone at the vendor is created again by apply
+     * without asking (a host running the company's code); otherwise apply asks first, as a
+     * recreated database looks fine and has lost its data. Default: true for a host, else false.
+     */
+    stateless?: boolean;
+    /**
+     * True when there is no vendor object behind a declaration: the repo is all there is of it (the
+     * runtime's people, `sanoma.person`). Such a type has no operations, so no driver, and drift and
+     * apply pass its resources by. Default false.
+     */
+    vendorless?: boolean;
+    /**
+     * Operations apply calls, in order, right after it creates one of its objects and binds it: a
+     * Supabase project's health, until it is healthy, then its database URL stored.
+     */
+    afterCreate?: readonly AfterCreate[];
+}
+/** One operation apply calls after a create (`ResourceSpec.afterCreate`). */
+export interface AfterCreate {
+    /** The operation's id, among the config's: `supabase.database.storeUrl`. */
+    op: string;
+    /** Its input, from the new object's binding id and the data file's export that declares it. */
+    input: (made: {
+        id: string;
+        export: string;
+    }) => unknown;
+    /**
+     * Called again, every few seconds, until its output passes this, for up to 10 minutes; a call
+     * that fails meanwhile is one that did not pass, its output `undefined`.
+     */
+    until?: (output: any) => boolean;
 }
 /**
  * Where a declared resource keeps its brand, its type's `<vendor>.<type>`: a symbol, so a field
@@ -70,8 +120,8 @@ export interface Declared<Id extends string = string, T = State> {
     readonly [DECLARED]: Id;
     readonly vendor: string;
     readonly type: string;
-    /** The vendor's id for it: what `find` made of `desired`. */
-    readonly name: string;
+    /** Its identity, the import id that finds it unbound: what `find` made of `desired`; absent without `find`. */
+    readonly name?: string;
     /**
      * Its fields, each resource it names replaced by that resource's `name`: what its type
      * checked, and what a drift check compares.
@@ -85,14 +135,24 @@ export interface Declared<Id extends string = string, T = State> {
 }
 /**
  * What a resource type's constructor takes: its fields, where `R` (its `fields.references`)
- * names a path, a declared resource of that type instead of a value (`repository_id: site`).
+ * names a path, a declared resource of that type instead of a value (`repository_id: site`), and
+ * where a string goes, a secret (`secret("NAME")`), which the constructor allows at a write-only
+ * field only.
  */
-export type Declaring<T, R extends References = {}> = [keyof R] extends [never] ? T : DeclaringAt<T, R, "">;
+export type Declaring<T, R extends References = {}> = [keyof R] extends [never] ? WithSecrets<T> : DeclaringAt<T, R, "">;
+type WithSecrets<V> = V extends string ? V | Secret : V extends readonly (infer I)[] ? WithSecrets<I>[] : V extends object ? {
+    [K in keyof V]: WithSecrets<V[K]>;
+} : V;
 type DeclaringAt<T, R extends References, P extends string> = T extends readonly (infer I)[] ? DeclaringAt<I, R, P>[] : T extends object ? {
     [K in keyof T]: K extends string ? DeclaringField<T[K], R, P extends "" ? K : `${P}.${K}`> : T[K];
-} : T;
-type DeclaringField<V, R extends References, P extends string> = P extends keyof R ? V | DeclaredOf<R[P]["type"]> : [Extract<keyof R, `${P}.${string}`>] extends [never] ? V : DeclaringAt<V, R, P>;
-type DeclaredOf<Id> = Id extends string ? Declared<Id> : never;
+} : WithSecrets<T>;
+type DeclaringField<V, R extends References, P extends string> = P extends keyof R ? V extends readonly (infer I)[] ? (WithSecrets<I> | DeclaredOf<R[P]["type"]>)[] : WithSecrets<V> | DeclaredOf<R[P]["type"]> : [Extract<keyof R, `${P}.${string}`>] extends [never] ? WithSecrets<V> : DeclaringAt<V, R, P>;
+type DeclaredOf<Id> = Id extends string ? Declared<Id> : Id extends readonly (infer E)[] ? DeclaredOf<E> : never;
+/** What a plan of a change says will happen, as `PlanResponse.Action` names it. */
+export declare const PLAN_ACTIONS: readonly ["none", "create", "update", "replace", "delete"];
+export type PlanAction = (typeof PLAN_ACTIONS)[number];
+/** The operations of a writable type that change its objects: only the apply workflow calls them (`isChangeOp`). */
+export declare const CHANGE_OPS: readonly ["create", "update", "delete"];
 declare const opsOf: <S extends z.ZodObject>(schema: S) => {
     import: {
         input: z.ZodObject<{
@@ -118,20 +178,111 @@ declare const opsOf: <S extends z.ZodObject>(schema: S) => {
             handle: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>;
     };
+    plan: {
+        input: z.ZodObject<{
+            state: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            handle: z.ZodOptional<z.ZodString>;
+            id: z.ZodOptional<z.ZodString>;
+            desired: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$strip>;
+        output: z.ZodObject<{
+            action: z.ZodEnum<{
+                create: "create";
+                delete: "delete";
+                none: "none";
+                replace: "replace";
+                update: "update";
+            }>;
+            planned: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            unknown: z.ZodArray<z.ZodString>;
+            replace: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>;
+    };
+    create: {
+        input: z.ZodObject<{
+            desired: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, z.core.$strip>;
+        output: z.ZodObject<{
+            id: z.ZodString;
+            state: S;
+            handle: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    };
+    update: {
+        input: z.ZodObject<{
+            id: z.ZodString;
+            state: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            handle: z.ZodOptional<z.ZodString>;
+            desired: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            expect: z.ZodOptional<z.ZodObject<{
+                action: z.ZodEnum<{
+                    create: "create";
+                    delete: "delete";
+                    none: "none";
+                    replace: "replace";
+                    update: "update";
+                }>;
+                replace: z.ZodArray<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+        output: z.ZodObject<{
+            id: z.ZodString;
+            state: S;
+            handle: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    };
+    delete: {
+        input: z.ZodObject<{
+            id: z.ZodString;
+            state: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            handle: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+        output: z.ZodObject<{
+            id: z.ZodString;
+            gone: z.ZodLiteral<true>;
+        }, z.core.$strip>;
+    };
 };
 type OpsOf<S extends z.ZodObject> = ReturnType<typeof opsOf<S>>;
-/** A resource type's operation specs: `read` and `import`. */
-export type ResourceOps<S extends z.ZodObject> = {
-    [N in keyof OpsOf<S>]: OpSpec<OpsOf<S>[N]["input"], OpsOf<S>[N]["output"]>;
+type Specs<S extends z.ZodObject, N extends keyof OpsOf<S>> = {
+    [K in N]: OpSpec<OpsOf<S>[K]["input"], OpsOf<S>[K]["output"]>;
 };
+/**
+ * A resource type's operation specs: `read` and `import`, and for a writable type (`W`) the
+ * change operations `plan`, `create`, `update` and `delete`.
+ */
+export type ResourceOps<S extends z.ZodObject, W extends boolean = false> = Specs<S, "read" | "import"> & ([W] extends [true] ? Specs<S, "plan" | (typeof CHANGE_OPS)[number]> : {});
+/**
+ * True for an operation that changes a writable type's objects (`CHANGE_OPS`), which only the
+ * apply workflow may call: by its vendor, resource and name, so a copy of a connector is told too.
+ */
+export declare function isChangeOp(op: {
+    readonly vendor: string;
+    readonly resource: string;
+    readonly name: string;
+}, types: ReadonlyMap<string, Pick<Resource, "writable">>): boolean;
+/**
+ * True for an operation of a declared resource type (`read`, `import`, and a writable type's
+ * `plan` and change operations), which only drift and apply call: by its vendor and resource.
+ */
+export declare const isResourceOp: (op: {
+    readonly vendor: string;
+    readonly resource: string;
+}, types: ReadonlyMap<string, unknown>) => boolean;
 /**
  * A resource type: call it to declare a resource in a data file, and give it to
  * `defineConnector` as a group, under its `type`: `defineConnector("github", { repository })`.
  */
-export interface Resource<S extends z.ZodObject = z.ZodObject, Id extends string = string, R extends References = {}> extends Readonly<Required<ResourceSpec<S>>> {
+export interface Resource<S extends z.ZodObject = z.ZodObject, Id extends string = string, R extends References = {}, W extends boolean = boolean> extends Readonly<Required<Omit<ResourceSpec<S>, "identity" | "find" | "writable" | "host" | "stateless" | "afterCreate" | "vendorless">>>, Readonly<Pick<ResourceSpec<S>, "identity" | "find" | "host" | "afterCreate">> {
     (desired: Declaring<z.input<S>, R>): Declared<Id, z.input<S>>;
-    /** `read` and `import`, each effect `read`, idempotent, with the import id as `target`. */
-    readonly ops: ResourceOps<S>;
+    /** `read` and `import`, each effect `read`, idempotent, with the id as `target`; for a writable type, the change operations too. */
+    readonly ops: ResourceOps<S, W>;
+    /** True when apply may change its objects: it has the change operations. */
+    readonly writable: W;
+    /** True when apply may recreate or replace its objects as routine: they keep no data. */
+    readonly stateless: boolean;
+    /** True when there is no vendor object behind it (`ResourceSpec.vendorless`): it has no operations. */
+    readonly vendorless: boolean;
     readonly [RESOURCE]: true;
 }
 /** True for a plain object: not null, not a list. */
@@ -174,9 +325,20 @@ export declare function diffDeclared(resource: {
     readonly fields: ResourceFields;
     readonly normalize: (state: State, desired: any) => State;
 }, state: State, desired: State, accept?: Readonly<Record<string, readonly unknown[]>>): DriftField[];
+/** The object or list holding the value at a dotted path (a list item's by its index), and its key there. */
+export declare function holderOf(value: unknown, path: string): {
+    holder: State;
+    key: string;
+} | undefined;
+/** A field's dotted path as `fields` names it, without a list item's index: `teams.0` is `teams`. */
+export declare const fieldPathOf: (at: string) => string;
+/** The value at a dotted path, a list item's by its index. */
+export declare const valueAt: (value: unknown, path: string) => unknown;
 /**
- * `desired` without the fields the type marks write-only (a webhook's `secret`): what a run may
- * record of a declaration. A list's items lose them too.
+ * `desired` without the values at the fields the type marks write-only (a webhook's `secret`):
+ * what a run may record of a declaration. A list's items lose them too. A secret marker
+ * (`secret("NAME")`) stays, there or inside a write-only map (a host's `secrets`): it names a
+ * stored secret and holds none, and the driver resolves it.
  */
 export declare function withoutWriteOnly(fields: ResourceFields, desired: State): State;
 /**
@@ -184,13 +346,31 @@ export declare function withoutWriteOnly(fields: ResourceFields, desired: State)
  * derives its operations, `<vendor>.<type>.read` and `<vendor>.<type>.import`, both effect
  * `read` and idempotent, with the import id as the policy's `target`:
  *
- * - `import` takes `{ id }`, the import id, and returns `{ gone: false, state }`, the object's
+ * - `import` takes `{ id }`, an identity (what `find` makes) or a binding id (what `bindingId`
+ *   makes), and returns `{ gone: false, state }`, the object's
  *   state (with the driver's opaque `handle` when it keeps one), or `{ gone: true }` when the
  *   vendor has no such object.
  * - `read` takes `{ id, state?, handle? }`, a state from an earlier `import` or `read`, and
  *   returns the same: `{ gone: true }` when the object no longer exists, else its fresh
  *   `state`. A driver may import first when it is given no state.
  *
+ * A `writable` type has the change operations too, which only the apply workflow may call
+ * (`isChangeOp`): `create`, `update` and `delete` effect `write` (`delete` idempotent), and `plan`:
+ *
+ * - `plan` (`read`, idempotent) takes `{ id?, state?, handle?, desired? }`, no `desired` for a
+ *   delete and no `id` for a create, and returns `{ action, planned?, unknown, replace }`:
+ *   what apply would do, the new state without write-only fields, the paths known only after
+ *   apply, and those whose change replaces the object.
+ * - `create` (`target` `new:<vendor>.<type>`) takes `{ desired }` and returns `{ id, state,
+ *   handle? }`, `id` its binding id.
+ * - `update` takes `{ id, state?, handle?, desired, expect? }` and returns the same; given
+ *   `expect` (a plan's `action` and `replace`), it refuses a fresh plan that differs
+ *   (`DriverError`, `vendorCode` `plan_changed`).
+ * - `delete` takes `{ id, state?, handle? }` and returns `{ id, gone: true }`.
+ *
+ * `desired` may hold secret markers at write-only fields, which the driver resolves; no output
+ * holds a write-only value.
+ *
  * The ledger records a `handle` as `"<handle>"`, never its bytes (the operations' `opaque`).
  *
  * Calling the result declares one resource, for a data file: `repository({ name: "sanoma" })`
@@ -198,15 +378,17 @@ export declare function withoutWriteOnly(fields: ResourceFields, desired: State)
  * schema does not have, fields the vendor owns (unless the identity names them), values the
  * schema rejects, and an empty identity. Where `fields.references` allows it, a field may name
  * another declared resource of that type (`repository_id: site`): `desired` holds, and the
- * schema and `find` read, that resource's `name`, and `refs` says where it was named.
+ * schema and `find` read, that resource's `name`, and `refs` says where it was named. A type
+ * without `find` declares resources without a `name`, found only by their bindings.
  */
-export declare function defineResource<S extends z.ZodObject, const V extends string, const T extends string, const R extends References = {}>(spec: ResourceSpec<S> & {
+export declare function defineResource<S extends z.ZodObject, const V extends string, const T extends string, const R extends References = {}, const W extends boolean = false>(spec: ResourceSpec<S> & {
     vendor: V;
     type: T;
     fields: {
         references?: R;
     };
-}): Resource<S, `${V}.${T}`, R>;
+    writable?: W;
+}): Resource<S, `${V}.${T}`, R, W>;
 /** Every resource type the connectors declare, by `<vendor>.<type>`. */
 export declare function resourceTypesOf(connectors: readonly Connector<any, any>[]): Map<string, Resource>;
 export {};