@start9labs/start-sdk 0.4.0-beta.6 → 0.4.0-beta.61

package/base/lib/actions/input/inputSpecConstants.js

@@ -1,76 +1,174 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.smtpInputSpec = exports.customSmtp = void 0;
+exports.smtpInputSpec = exports.systemSmtpSpec = exports.smtpProviderVariants = exports.customSmtp = void 0;
 const util_1 = require("../../util");
 const inputSpec_1 = require("./builder/inputSpec");
 const value_1 = require("./builder/value");
 const variants_1 = require("./builder/variants");
+const securityVariants = variants_1.Variants.of({
+    tls: {
+        name: 'TLS',
+        spec: inputSpec_1.InputSpec.of({
+            port: value_1.Value.dynamicText(async () => ({
+                name: 'Port',
+                required: true,
+                default: '465',
+                disabled: 'Fixed for TLS',
+            })),
+        }),
+    },
+    starttls: {
+        name: 'STARTTLS',
+        spec: inputSpec_1.InputSpec.of({
+            port: value_1.Value.select({
+                name: 'Port',
+                default: '587',
+                values: { '25': '25', '587': '587', '2525': '2525' },
+            }),
+        }),
+    },
+});
 /**
- * Base SMTP settings, to be used by StartOS for system wide SMTP
+ * Creates an SMTP field spec with provider-specific defaults pre-filled.
  */
-exports.customSmtp = inputSpec_1.InputSpec.of({
-    server: value_1.Value.text({
-        name: "SMTP Server",
-        required: true,
-        default: null,
-    }),
-    port: value_1.Value.number({
-        name: "Port",
-        required: true,
-        default: 587,
-        min: 1,
-        max: 65535,
-        integer: true,
-    }),
-    from: value_1.Value.text({
-        name: "From Address",
+function smtpFields(defaults = {}) {
+    const hostSpec = value_1.Value.text({
+        name: 'Host',
         required: true,
-        default: null,
-        placeholder: "Example Name <test@example.com>",
-        inputmode: "email",
-        patterns: [util_1.Patterns.emailWithName],
-    }),
-    login: value_1.Value.text({
-        name: "Login",
-        required: true,
-        default: null,
-    }),
-    password: value_1.Value.text({
-        name: "Password",
-        required: false,
-        default: null,
-        masked: true,
-    }),
+        default: defaults.host ?? null,
+        placeholder: 'smtp.example.com',
+    });
+    return inputSpec_1.InputSpec.of({
+        host: defaults.hostDisabled
+            ? hostSpec.withDisabled('Fixed for this provider')
+            : hostSpec,
+        security: value_1.Value.union({
+            name: 'Connection Security',
+            default: defaults.security ?? 'tls',
+            variants: securityVariants,
+        }),
+        from: value_1.Value.text({
+            name: 'From Address',
+            required: true,
+            default: null,
+            placeholder: 'Example Name <test@example.com>',
+            patterns: [util_1.Patterns.emailWithName],
+        }),
+        username: value_1.Value.text({
+            name: 'Username',
+            required: true,
+            default: null,
+        }),
+        password: value_1.Value.text({
+            name: 'Password',
+            required: false,
+            default: null,
+            masked: true,
+        }),
+    });
+}
+/**
+ * Base SMTP settings with no provider-specific defaults.
+ */
+exports.customSmtp = smtpFields();
+/**
+ * Provider presets for SMTP configuration.
+ * Each variant has SMTP fields pre-filled with the provider's recommended settings.
+ */
+exports.smtpProviderVariants = variants_1.Variants.of({
+    gmail: {
+        name: 'Gmail',
+        spec: smtpFields({
+            host: 'smtp.gmail.com',
+            security: 'tls',
+            hostDisabled: true,
+        }),
+    },
+    ses: {
+        name: 'Amazon SES',
+        spec: smtpFields({
+            host: 'email-smtp.us-east-1.amazonaws.com',
+            security: 'tls',
+        }),
+    },
+    sendgrid: {
+        name: 'SendGrid',
+        spec: smtpFields({
+            host: 'smtp.sendgrid.net',
+            security: 'tls',
+            hostDisabled: true,
+        }),
+    },
+    mailgun: {
+        name: 'Mailgun',
+        spec: smtpFields({
+            host: 'smtp.mailgun.org',
+            security: 'tls',
+            hostDisabled: true,
+        }),
+    },
+    protonmail: {
+        name: 'Proton Mail',
+        spec: smtpFields({
+            host: 'smtp.protonmail.ch',
+            security: 'tls',
+            hostDisabled: true,
+        }),
+    },
+    other: {
+        name: 'Other',
+        spec: exports.customSmtp,
+    },
 });
 /**
- * For service inputSpec. Gives users 3 options for SMTP: (1) disabled, (2) use system SMTP settings, (3) use custom SMTP settings
+ * System SMTP settings with provider presets.
+ * Wraps smtpProviderVariants in a union for use by the system email settings page.
  */
-exports.smtpInputSpec = value_1.Value.filteredUnion(async ({ effects }) => {
-    const smtp = await new util_1.GetSystemSmtp(effects).once();
-    return smtp ? [] : ["system"];
-}, {
-    name: "SMTP",
-    description: "Optionally provide an SMTP server for sending emails",
-    default: "disabled",
-}, variants_1.Variants.of({
-    disabled: { name: "Disabled", spec: inputSpec_1.InputSpec.of({}) },
+exports.systemSmtpSpec = inputSpec_1.InputSpec.of({
+    provider: value_1.Value.union({
+        name: 'Provider',
+        default: 'gmail',
+        variants: exports.smtpProviderVariants,
+    }),
+});
+const smtpVariants = variants_1.Variants.of({
+    disabled: { name: 'Disabled', spec: inputSpec_1.InputSpec.of({}) },
     system: {
-        name: "System Credentials",
+        name: 'System Credentials',
         spec: inputSpec_1.InputSpec.of({
             customFrom: value_1.Value.text({
-                name: "Custom From Address",
-                description: "A custom from address for this service. If not provided, the system from address will be used.",
+                name: 'Custom From Address',
+                description: 'A custom from address for this service. If not provided, the system from address will be used.',
                 required: false,
                 default: null,
-                placeholder: "<name>test@example.com",
-                inputmode: "email",
-                patterns: [util_1.Patterns.email],
+                placeholder: 'Name <test@example.com>',
+                patterns: [util_1.Patterns.emailWithName],
             }),
         }),
     },
     custom: {
-        name: "Custom Credentials",
-        spec: exports.customSmtp,
+        name: 'Custom Credentials',
+        spec: inputSpec_1.InputSpec.of({
+            provider: value_1.Value.union({
+                name: 'Provider',
+                default: null,
+                variants: exports.smtpProviderVariants,
+            }),
+        }),
     },
-}));
+});
+/**
+ * For service inputSpec. Gives users 3 options for SMTP: (1) disabled, (2) use system SMTP settings, (3) use custom SMTP settings with provider presets
+ */
+exports.smtpInputSpec = value_1.Value.dynamicUnion(async ({ effects }) => {
+    const smtp = await new util_1.GetSystemSmtp(effects).once();
+    const disabled = smtp ? [] : ['system'];
+    return {
+        name: 'SMTP',
+        description: 'Optionally provide an SMTP server for sending emails',
+        default: 'disabled',
+        disabled,
+        variants: smtpVariants,
+    };
+}, smtpVariants.validator);
 //# sourceMappingURL=inputSpecConstants.js.map

package/base/lib/actions/input/inputSpecConstants.js.map

@@ -1 +1 @@
-{"version":3,"file":"inputSpecConstants.js","sourceRoot":"","sources":["../../../../../base/lib/actions/input/inputSpecConstants.ts"],"names":[],"mappings":";;;AACA,qCAAoD;AACpD,mDAA4D;AAC5D,2CAAuC;AACvC,iDAA6C;AAE7C;;GAEG;AACU,QAAA,UAAU,GAAG,qBAAS,CAAC,EAAE,CAAgC;IACpE,MAAM,EAAE,aAAK,CAAC,IAAI,CAAC;QACjB,IAAI,EAAE,aAAa;QACnB,QAAQ,EAAE,IAAI;QACd,OAAO,EAAE,IAAI;KACd,CAAC;IACF,IAAI,EAAE,aAAK,CAAC,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM;QACZ,QAAQ,EAAE,IAAI;QACd,OAAO,EAAE,GAAG;QACZ,GAAG,EAAE,CAAC;QACN,GAAG,EAAE,KAAK;QACV,OAAO,EAAE,IAAI;KACd,CAAC;IACF,IAAI,EAAE,aAAK,CAAC,IAAI,CAAC;QACf,IAAI,EAAE,cAAc;QACpB,QAAQ,EAAE,IAAI;QACd,OAAO,EAAE,IAAI;QACb,WAAW,EAAE,iCAAiC;QAC9C,SAAS,EAAE,OAAO;QAClB,QAAQ,EAAE,CAAC,eAAQ,CAAC,aAAa,CAAC;KACnC,CAAC;IACF,KAAK,EAAE,aAAK,CAAC,IAAI,CAAC;QAChB,IAAI,EAAE,OAAO;QACb,QAAQ,EAAE,IAAI;QACd,OAAO,EAAE,IAAI;KACd,CAAC;IACF,QAAQ,EAAE,aAAK,CAAC,IAAI,CAAC;QACnB,IAAI,EAAE,UAAU;QAChB,QAAQ,EAAE,KAAK;QACf,OAAO,EAAE,IAAI;QACb,MAAM,EAAE,IAAI;KACb,CAAC;CACH,CAAC,CAAA;AAEF;;GAEG;AACU,QAAA,aAAa,GAAG,aAAK,CAAC,aAAa,CAC9C,KAAK,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE;IACpB,MAAM,IAAI,GAAG,MAAM,IAAI,oBAAa,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAA;IACpD,OAAO,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAA;AAC/B,CAAC,EACD;IACE,IAAI,EAAE,MAAM;IACZ,WAAW,EAAE,sDAAsD;IACnE,OAAO,EAAE,UAAU;CACpB,EACD,mBAAQ,CAAC,EAAE,CAAC;IACV,QAAQ,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,qBAAS,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE;IACtD,MAAM,EAAE;QACN,IAAI,EAAE,oBAAoB;QAC1B,IAAI,EAAE,qBAAS,CAAC,EAAE,CAAC;YACjB,UAAU,EAAE,aAAK,CAAC,IAAI,CAAC;gBACrB,IAAI,EAAE,qBAAqB;gBAC3B,WAAW,EACT,gGAAgG;gBAClG,QAAQ,EAAE,KAAK;gBACf,OAAO,EAAE,IAAI;gBACb,WAAW,EAAE,wBAAwB;gBACrC,SAAS,EAAE,OAAO;gBAClB,QAAQ,EAAE,CAAC,eAAQ,CAAC,KAAK,CAAC;aAC3B,CAAC;SACH,CAAC;KACH;IACD,MAAM,EAAE;QACN,IAAI,EAAE,oBAAoB;QAC1B,IAAI,EAAE,kBAAU;KACjB;CACF,CAAC,CACH,CAAA"}
+{"version":3,"file":"inputSpecConstants.js","sourceRoot":"","sources":["../../../../../base/lib/actions/input/inputSpecConstants.ts"],"names":[],"mappings":"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"}

package/base/lib/actions/input/inputSpecTypes.d.ts

@@ -1,46 +1,81 @@
+/**
+ * A record mapping field keys to their {@link ValueSpec} definitions.
+ * This is the root shape of a dynamic form specification — it defines the complete set
+ * of configurable fields for a service or action.
+ */
 export type InputSpec = Record<string, ValueSpec>;
-export type ValueType = "text" | "textarea" | "number" | "color" | "datetime" | "toggle" | "select" | "multiselect" | "list" | "object" | "file" | "union" | "hidden";
+/**
+ * The discriminator for all supported form field types.
+ */
+export type ValueType = 'text' | 'textarea' | 'number' | 'color' | 'datetime' | 'toggle' | 'select' | 'multiselect' | 'list' | 'object' | 'file' | 'union' | 'hidden';
+/** Union of all concrete form field spec types. Discriminate on the `type` field. */
 export type ValueSpec = ValueSpecOf<ValueType>;
 /** core spec types. These types provide the metadata for performing validations */
 export type ValueSpecOf<T extends ValueType> = T extends "text" ? ValueSpecText : T extends "textarea" ? ValueSpecTextarea : T extends "number" ? ValueSpecNumber : T extends "color" ? ValueSpecColor : T extends "datetime" ? ValueSpecDatetime : T extends "toggle" ? ValueSpecToggle : T extends "select" ? ValueSpecSelect : T extends "multiselect" ? ValueSpecMultiselect : T extends "list" ? ValueSpecList : T extends "object" ? ValueSpecObject : T extends "file" ? ValueSpecFile : T extends "union" ? ValueSpecUnion : T extends "hidden" ? ValueSpecHidden : never;
+/** Spec for a single-line text input field. */
 export type ValueSpecText = {
+    /** Display label for the field. */
     name: string;
+    /** Optional help text displayed below the field. */
     description: string | null;
+    /** Optional warning message displayed to the user. */
     warning: string | null;
-    type: "text";
+    type: 'text';
+    /** Regex patterns used to validate the input value. */
     patterns: Pattern[];
+    /** Minimum character length, or `null` for no minimum. */
     minLength: number | null;
+    /** Maximum character length, or `null` for no maximum. */
     maxLength: number | null;
+    /** Whether the field should obscure input (e.g. for passwords). */
     masked: boolean;
-    inputmode: "text" | "email" | "tel" | "url";
+    /** HTML input mode hint for mobile keyboards. */
+    inputmode: 'text' | 'email' | 'tel' | 'url';
+    /** Placeholder text shown when the field is empty. */
     placeholder: string | null;
+    /** Whether the field must have a value. */
     required: boolean;
+    /** Default value, which may be a literal string or a {@link RandomString} generation spec. */
     default: DefaultString | null;
+    /** `false` if editable, or a string message explaining why the field is disabled. */
     disabled: false | string;
+    /** If set, provides a "generate" button that fills the field with a random string matching this spec. */
     generate: null | RandomString;
+    /** Whether the field value cannot be changed after initial configuration. */
     immutable: boolean;
 };
+/** Spec for a multi-line textarea input field. */
 export type ValueSpecTextarea = {
     name: string;
     description: string | null;
     warning: string | null;
-    type: "textarea";
+    type: 'textarea';
+    /** Regex patterns used to validate the input value. */
+    patterns: Pattern[];
     placeholder: string | null;
     minLength: number | null;
     maxLength: number | null;
+    /** Minimum number of visible rows. */
+    minRows: number;
+    /** Maximum number of visible rows before scrolling. */
+    maxRows: number;
     required: boolean;
+    default: string | null;
     disabled: false | string;
     immutable: boolean;
 };
-export type FilePath = {
-    filePath: string;
-};
+/** Spec for a numeric input field. */
 export type ValueSpecNumber = {
-    type: "number";
+    type: 'number';
+    /** Minimum allowed value, or `null` for unbounded. */
     min: number | null;
+    /** Maximum allowed value, or `null` for unbounded. */
     max: number | null;
+    /** Whether only whole numbers are accepted. */
     integer: boolean;
+    /** Step increment for the input spinner, or `null` for any precision. */
     step: number | null;
+    /** Display label for the unit (e.g. `"MB"`, `"seconds"`), shown next to the field. */
     units: string | null;
     placeholder: string | null;
     name: string;
@@ -51,135 +86,200 @@ export type ValueSpecNumber = {
     disabled: false | string;
     immutable: boolean;
 };
+/** Spec for a browser-native color picker field. */
 export type ValueSpecColor = {
     name: string;
     description: string | null;
     warning: string | null;
-    type: "color";
+    type: 'color';
     required: boolean;
+    /** Default hex color string (e.g. `"#ff0000"`), or `null`. */
     default: string | null;
     disabled: false | string;
     immutable: boolean;
 };
+/** Spec for a date, time, or datetime input field. */
 export type ValueSpecDatetime = {
     name: string;
     description: string | null;
     warning: string | null;
-    type: "datetime";
+    type: 'datetime';
     required: boolean;
-    inputmode: "date" | "time" | "datetime-local";
+    /** Controls which kind of picker is displayed. */
+    inputmode: 'date' | 'time' | 'datetime-local';
+    /** Minimum selectable date/time as an ISO string, or `null`. */
     min: string | null;
+    /** Maximum selectable date/time as an ISO string, or `null`. */
     max: string | null;
     default: string | null;
     disabled: false | string;
     immutable: boolean;
 };
+/** Spec for a single-select field displayed as radio buttons in a modal. */
 export type ValueSpecSelect = {
+    /** Map of option keys to display labels. */
     values: Record<string, string>;
     name: string;
     description: string | null;
     warning: string | null;
-    type: "select";
+    type: 'select';
     default: string | null;
+    /** `false` if all enabled, a string disabling the whole field, or an array of disabled option keys. */
     disabled: false | string | string[];
     immutable: boolean;
 };
+/** Spec for a multi-select field displayed as checkboxes in a modal. */
 export type ValueSpecMultiselect = {
+    /** Map of option keys to display labels. */
     values: Record<string, string>;
     name: string;
     description: string | null;
     warning: string | null;
-    type: "multiselect";
+    type: 'multiselect';
+    /** Minimum number of selections required, or `null`. */
     minLength: number | null;
+    /** Maximum number of selections allowed, or `null`. */
     maxLength: number | null;
+    /** `false` if all enabled, a string disabling the whole field, or an array of disabled option keys. */
     disabled: false | string | string[];
+    /** Array of option keys selected by default. */
     default: string[];
     immutable: boolean;
 };
+/** Spec for a boolean toggle (on/off switch). */
 export type ValueSpecToggle = {
     name: string;
     description: string | null;
     warning: string | null;
-    type: "toggle";
+    type: 'toggle';
     default: boolean | null;
     disabled: false | string;
     immutable: boolean;
 };
+/**
+ * Spec for a discriminated union field — displays a dropdown for variant selection,
+ * and each variant can have its own nested sub-form.
+ */
 export type ValueSpecUnion = {
     name: string;
     description: string | null;
     warning: string | null;
-    type: "union";
+    type: 'union';
+    /** Map of variant keys to their display name and nested form spec. */
     variants: Record<string, {
+        /** Display name for this variant in the dropdown. */
         name: string;
+        /** Nested form spec shown when this variant is selected. */
         spec: InputSpec;
     }>;
+    /** `false` if all enabled, a string disabling the whole field, or an array of disabled variant keys. */
     disabled: false | string | string[];
     default: string | null;
     immutable: boolean;
 };
+/** Spec for a file upload input field. */
 export type ValueSpecFile = {
     name: string;
     description: string | null;
     warning: string | null;
-    type: "file";
+    type: 'file';
+    /** Allowed file extensions (e.g. `[".pem", ".crt"]`). */
     extensions: string[];
     required: boolean;
 };
+/** Spec for a collapsible grouping of nested fields (a "sub-form"). */
 export type ValueSpecObject = {
     name: string;
     description: string | null;
     warning: string | null;
-    type: "object";
+    type: 'object';
+    /** The nested form spec containing this object's fields. */
     spec: InputSpec;
 };
+/** Spec for a hidden field — not displayed to the user but included in the form data. */
 export type ValueSpecHidden = {
-    type: "hidden";
+    type: 'hidden';
 };
-export type ListValueSpecType = "text" | "object";
+/** The two supported list item types. */
+export type ListValueSpecType = 'text' | 'object';
+/** Maps a {@link ListValueSpecType} to its concrete list item spec. */
 export type ListValueSpecOf<T extends ListValueSpecType> = T extends "text" ? ListValueSpecText : T extends "object" ? ListValueSpecObject : never;
+/** A list field spec — union of text-list and object-list variants. */
 export type ValueSpecList = ValueSpecListOf<ListValueSpecType>;
+/**
+ * Spec for a list field — an interface to add, remove, and edit items in an ordered collection.
+ * The `spec` field determines whether list items are text strings or structured objects.
+ */
 export type ValueSpecListOf<T extends ListValueSpecType> = {
     name: string;
     description: string | null;
     warning: string | null;
-    type: "list";
+    type: 'list';
+    /** The item spec — determines whether this is a list of text values or objects. */
     spec: ListValueSpecOf<T>;
+    /** Minimum number of items, or `null` for no minimum. */
     minLength: number | null;
+    /** Maximum number of items, or `null` for no maximum. */
     maxLength: number | null;
     disabled: false | string;
+    /** Default list items to populate on creation. */
     default: string[] | DefaultString[] | Record<string, unknown>[] | readonly string[] | readonly DefaultString[] | readonly Record<string, unknown>[];
 };
+/** A regex validation pattern with a human-readable description of what it enforces. */
 export type Pattern = {
+    /** The regex pattern string (without delimiters). */
     regex: string;
+    /** A user-facing explanation shown when validation fails (e.g. `"Must be a valid email"`). */
     description: string;
 };
+/** Spec for text items within a list field. */
 export type ListValueSpecText = {
-    type: "text";
+    type: 'text';
     patterns: Pattern[];
     minLength: number | null;
     maxLength: number | null;
     masked: boolean;
     generate: null | RandomString;
-    inputmode: "text" | "email" | "tel" | "url";
+    inputmode: 'text' | 'email' | 'tel' | 'url';
     placeholder: string | null;
 };
+/** Spec for object items within a list field. */
 export type ListValueSpecObject = {
-    type: "object";
+    type: 'object';
+    /** The form spec for each object item. */
     spec: InputSpec;
+    /** Defines how uniqueness is determined among list items. */
     uniqueBy: UniqueBy;
+    /** An expression used to generate the display string for each item in the list summary (e.g. a key path). */
     displayAs: string | null;
 };
+/**
+ * Describes how list items determine uniqueness.
+ * - `null`: no uniqueness constraint
+ * - `string`: unique by a specific field key
+ * - `{ any: UniqueBy[] }`: unique if any of the sub-constraints match
+ * - `{ all: UniqueBy[] }`: unique if all sub-constraints match together
+ */
 export type UniqueBy = null | string | {
     any: readonly UniqueBy[] | UniqueBy[];
 } | {
     all: readonly UniqueBy[] | UniqueBy[];
 };
+/** A default value that is either a literal string or a {@link RandomString} generation spec. */
 export type DefaultString = string | RandomString;
+/** Spec for generating a random string — used for default passwords, API keys, etc. */
 export type RandomString = {
+    /** The character set to draw from (e.g. `"a-zA-Z0-9"`). */
     charset: string;
+    /** The length of the generated string. */
     len: number;
 };
+/**
+ * Type guard that narrows a {@link ValueSpec} to a {@link ValueSpecListOf} of a specific item type.
+ *
+ * @param t - The value spec to check
+ * @param s - The list item type to narrow to (`"text"` or `"object"`)
+ */
 export declare function isValueSpecListOf<S extends ListValueSpecType>(t: ValueSpec, s: S): t is ValueSpecListOf<S> & {
     spec: ListValueSpecOf<S>;
 };

package/base/lib/actions/input/inputSpecTypes.js

@@ -1,8 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isValueSpecListOf = isValueSpecListOf;
-// sometimes the type checker needs just a little bit of help
+/**
+ * Type guard that narrows a {@link ValueSpec} to a {@link ValueSpecListOf} of a specific item type.
+ *
+ * @param t - The value spec to check
+ * @param s - The list item type to narrow to (`"text"` or `"object"`)
+ */
 function isValueSpecListOf(t, s) {
-    return "spec" in t && t.spec.type === s;
+    return 'spec' in t && t.spec.type === s;
 }
 //# sourceMappingURL=inputSpecTypes.js.map

package/base/lib/actions/input/inputSpecTypes.js.map

@@ -1 +1 @@
-{"version":3,"file":"inputSpecTypes.js","sourceRoot":"","sources":["../../../../../base/lib/actions/input/inputSpecTypes.ts"],"names":[],"mappings":";;AAmPA,8CAKC;AAND,6DAA6D;AAC7D,SAAgB,iBAAiB,CAC/B,CAAY,EACZ,CAAI;IAEJ,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,CAAA;AACzC,CAAC"}
+{"version":3,"file":"inputSpecTypes.js","sourceRoot":"","sources":["../../../../../base/lib/actions/input/inputSpecTypes.ts"],"names":[],"mappings":";;AAoVA,8CAKC;AAXD;;;;;GAKG;AACH,SAAgB,iBAAiB,CAC/B,CAAY,EACZ,CAAI;IAEJ,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,CAAA;AACzC,CAAC"}

package/base/lib/actions/setupActions.d.ts

@@ -1,47 +1,58 @@
-import { InputSpec } from "./input/builder";
-import { ExtractInputSpecType, ExtractPartialInputSpecType } from "./input/builder/inputSpec";
-import * as T from "../types";
-export type Run<A extends Record<string, any> | InputSpec<Record<string, any>, any> | InputSpec<Record<string, never>, never>> = (options: {
+import { InputSpec } from './input/builder';
+import { ExtractInputSpecType } from './input/builder/inputSpec';
+import * as T from '../types';
+import { InitScript } from '../inits';
+export type Run<A extends Record<string, any>> = (options: {
     effects: T.Effects;
-    input: ExtractInputSpecType<A>;
+    input: A;
+    spec: T.inputSpecTypes.InputSpec;
 }) => Promise<(T.ActionResult & {
-    version: "1";
+    version: '1';
 }) | null | void | undefined>;
-export type GetInput<A extends Record<string, any> | InputSpec<Record<string, any>, any> | InputSpec<Record<string, any>, never>> = (options: {
+export type GetInput<A extends Record<string, any>> = (options: {
     effects: T.Effects;
-}) => Promise<null | void | undefined | ExtractPartialInputSpecType<A>>;
-export type MaybeFn<T> = T | ((options: {
+    prefill: T.DeepPartial<A> | null;
+}) => Promise<null | void | undefined | T.DeepPartial<A>>;
+export type MaybeFn<T, Opts = {
     effects: T.Effects;
-}) => Promise<T>);
-export declare class Action<Id extends T.ActionId, Store, InputSpecType extends Record<string, any> | InputSpec<any, Store> | InputSpec<any, never>> {
+}> = T | ((options: Opts) => Promise<T>);
+export interface ActionInfo<Id extends T.ActionId, Type extends Record<string, any>> {
+    readonly id: Id;
+    readonly _INPUT: Type;
+}
+export declare class Action<Id extends T.ActionId, Type extends Record<string, any>> implements ActionInfo<Id, Type> {
     readonly id: Id;
     private readonly metadataFn;
     private readonly inputSpec;
     private readonly getInputFn;
     private readonly runFn;
+    readonly _INPUT: Type;
+    private prevInputSpec;
     private constructor();
-    static withInput<Id extends T.ActionId, Store, InputSpecType extends Record<string, any> | InputSpec<any, Store> | InputSpec<any, never>>(id: Id, metadata: MaybeFn<Omit<T.ActionMetadata, "hasInput">>, inputSpec: InputSpecType, getInput: GetInput<InputSpecType>, run: Run<InputSpecType>): Action<Id, Store, InputSpecType>;
-    static withoutInput<Id extends T.ActionId, Store>(id: Id, metadata: MaybeFn<Omit<T.ActionMetadata, "hasInput">>, run: Run<{}>): Action<Id, Store, {}>;
+    static withInput<Id extends T.ActionId, InputSpecType extends InputSpec<Record<string, any>>>(id: Id, metadata: MaybeFn<Omit<T.ActionMetadata, 'hasInput'>>, inputSpec: MaybeFn<InputSpecType, {
+        effects: T.Effects;
+        prefill: unknown | null;
+    }>, getInput: GetInput<ExtractInputSpecType<InputSpecType>>, run: Run<ExtractInputSpecType<InputSpecType>>): Action<Id, ExtractInputSpecType<InputSpecType>>;
+    static withoutInput<Id extends T.ActionId>(id: Id, metadata: MaybeFn<Omit<T.ActionMetadata, 'hasInput'>>, run: Run<{}>): Action<Id, {}>;
     exportMetadata(options: {
         effects: T.Effects;
     }): Promise<T.ActionMetadata>;
     getInput(options: {
         effects: T.Effects;
+        prefill: T.DeepPartial<Type> | null;
     }): Promise<T.ActionInput>;
     run(options: {
         effects: T.Effects;
-        input: ExtractInputSpecType<InputSpecType>;
+        input: Type;
     }): Promise<T.ActionResult | null>;
 }
-export declare class Actions<Store, AllActions extends Record<T.ActionId, Action<T.ActionId, Store, any>>> {
+export declare class Actions<AllActions extends Record<T.ActionId, Action<T.ActionId, any>>> implements InitScript {
     private readonly actions;
     private constructor();
-    static of<Store>(): Actions<Store, {}>;
-    addAction<A extends Action<T.ActionId, Store, any>>(action: A): Actions<Store, AllActions & {
-        [id in A["id"]]: A;
+    static of(): Actions<{}>;
+    addAction<A extends Action<T.ActionId, any>>(action: A): Actions<AllActions & {
+        [id in A['id']]: A;
     }>;
-    update(options: {
-        effects: T.Effects;
-    }): Promise<null>;
+    init(effects: T.Effects): Promise<void>;
     get<Id extends T.ActionId>(actionId: Id): AllActions[Id];
 }