@start9labs/start-sdk 0.4.0-beta.50 → 0.4.0-beta.52

package/package/lib/StartSdk.d.ts

@@ -12,7 +12,7 @@ import { SetupBackupsParams } from './backup/setupBackups';
 import { changeOnFirstSuccess, cooldownTrigger } from './trigger';
 import { MultiHost, Scheme } from '../../base/lib/interfaces/Host';
 import { ServiceInterfaceBuilder } from '../../base/lib/interfaces/ServiceInterfaceBuilder';
-import { GetSystemSmtp } from './util';
+import { GetOutboundGateway, GetSystemSmtp } from './util';
 import { nullIfEmpty } from './util';
 import { getServiceInterface, getServiceInterfaces } from './util';
 import { CommandOptions, SubContainer } from './util/SubContainer';
@@ -29,34 +29,91 @@ import { DropGenerator } from '../../base/lib/util/Drop';
 import { getOwnServiceInterface } from '../../base/lib/util/getServiceInterface';
 import { getOwnServiceInterfaces } from '../../base/lib/util/getServiceInterfaces';
 import { Volumes } from './util/Volume';
+/** The minimum StartOS version required by this SDK release */
 export declare const OSVersion: "0.4.0-alpha.20";
 type AnyNeverCond<T extends any[], Then, Else> = T extends [] ? Else : T extends [never, ...Array<any>] ? Then : T extends [any, ...infer U] ? AnyNeverCond<U, Then, Else> : never;
+/**
+ * The top-level SDK facade for building StartOS service packages.
+ *
+ * Use `StartSdk.of()` to create an uninitialized instance, then call `.withManifest()`
+ * to bind it to a manifest, and finally `.build()` to obtain the full toolkit of helpers
+ * for actions, daemons, backups, interfaces, health checks, and more.
+ *
+ * @typeParam Manifest - The service manifest type; starts as `never` until `.withManifest()` is called.
+ */
 export declare class StartSdk<Manifest extends T.SDKManifest> {
     readonly manifest: Manifest;
     private constructor();
+    /**
+     * Create an uninitialized StartSdk instance. Call `.withManifest()` next.
+     * @returns A new StartSdk with no manifest bound.
+     */
     static of(): StartSdk<never>;
+    /**
+     * Bind a manifest to the SDK, producing a typed SDK instance.
+     * @param manifest - The service manifest definition
+     * @returns A new StartSdk instance parameterized by the given manifest type
+     */
     withManifest<Manifest extends T.SDKManifest = never>(manifest: Manifest): StartSdk<Manifest>;
     private ifPluginEnabled;
+    /**
+     * Finalize the SDK and return the full set of helpers for building a StartOS service.
+     *
+     * This method is only callable after `.withManifest()` has been called (enforced at the type level).
+     *
+     * @param isReady - Type-level gate; resolves to `true` only when a manifest is bound.
+     * @returns An object containing all SDK utilities: actions, daemons, backups, interfaces, health checks, volumes, triggers, and more.
+     */
     build(isReady: AnyNeverCond<[Manifest], 'Build not ready', true>): {
+        /** Persist the current data version to the StartOS effect system */
         setDataVersion: typeof setDataVersion;
+        /** Retrieve the current data version from the StartOS effect system */
         getDataVersion: typeof getDataVersion;
         action: {
+            /** Execute an action by its ID, optionally providing input */
             run: <Input extends Record<string, unknown>>(options: {
                 effects: T.Effects;
                 actionId: T.ActionId;
                 input?: actions.RunActionInput<Input>;
             }) => Promise<T.ActionResult | null>;
+            /** Create a task notification for a specific package's action */
             createTask: <T extends ActionInfo<T.ActionId, any>>(effects: T.Effects, packageId: T.PackageId, action: T, severity: T.TaskSeverity, options?: actions.TaskOptions<T>) => Promise<null>;
+            /** Create a task notification for this service's own action (uses manifest.id automatically) */
             createOwnTask: <T extends ActionInfo<T.ActionId, any>>(effects: T.Effects, action: T, severity: T.TaskSeverity, options?: actions.TaskOptions<T>) => Promise<null>;
+            /**
+             * Clear one or more task notifications by their replay IDs
+             * @param effects - The effects context
+             * @param replayIds - One or more replay IDs of the tasks to clear
+             */
             clearTask: (effects: T.Effects, ...replayIds: string[]) => Promise<null>;
         };
+        /**
+         * Check whether the specified (or all) dependencies are satisfied.
+         * @param effects - The effects context
+         * @param packageIds - Optional subset of dependency IDs to check; defaults to all
+         * @returns An object describing which dependencies are satisfied and which are not
+         */
         checkDependencies: <DependencyId extends keyof Manifest["dependencies"] & T.PackageId = keyof Manifest["dependencies"] & T.PackageId>(effects: Effects, packageIds?: DependencyId[]) => Promise<CheckDependencies<DependencyId>>;
         serviceInterface: {
+            /** Retrieve a single service interface belonging to this package by its ID */
             getOwn: typeof getOwnServiceInterface;
+            /** Retrieve a single service interface from any package */
             get: typeof getServiceInterface;
+            /** Retrieve all service interfaces belonging to this package */
             getAllOwn: typeof getOwnServiceInterfaces;
+            /** Retrieve all service interfaces, optionally filtering by package */
             getAll: typeof getServiceInterfaces;
         };
+        /**
+         * Get the container IP address with reactive subscription support.
+         *
+         * Returns an object with multiple read strategies: `const()` for a value
+         * that retries on change, `once()` for a single read, `watch()` for an async
+         * generator, `onChange()` for a callback, and `waitFor()` to block until a predicate is met.
+         *
+         * @param effects - The effects context
+         * @param options - Optional filtering options (e.g. `containerId`)
+         */
         getContainerIp: (effects: T.Effects, options?: Omit<Parameters<T.Effects["getContainerIp"]>[0], "callback">) => {
             const: () => Promise<string>;
             once: () => Promise<string>;
@@ -69,9 +126,22 @@ export declare class StartSdk<Manifest extends T.SDKManifest> {
             waitFor: (pred: (value: string | null) => boolean) => Promise<string | null>;
         };
         MultiHost: {
+            /**
+             * Create a new MultiHost instance for binding ports and exporting interfaces.
+             * @param effects - The effects context
+             * @param id - A unique identifier for this multi-host group
+             */
             of: (effects: Effects, id: string) => MultiHost;
         };
+        /**
+         * Return `null` if the given string is empty, otherwise return the string unchanged.
+         * Useful for converting empty user input into explicit null values.
+         */
         nullIfEmpty: typeof nullIfEmpty;
+        /**
+         * Indicate that a daemon should use the container image's configured entrypoint.
+         * @param overrideCmd - Optional command arguments to append after the entrypoint
+         */
         useEntrypoint: (overrideCmd?: string[]) => T.UseEntrypoint;
         /**
          * @description Use this class to create an Action. By convention, each Action should receive its own file.
@@ -197,7 +267,61 @@ export declare class StartSdk<Manifest extends T.SDKManifest> {
                 };
                 custom: {
                     name: string;
-                    spec: InputSpec<T.SmtpValue, T.SmtpValue>;
+                    spec: InputSpec<{
+                        provider: import("../../base/lib/actions/input/builder/variants").UnionRes<{
+                            gmail: {
+                                name: string;
+                                spec: InputSpec<T.SmtpValue, T.SmtpValue>;
+                            };
+                            ses: {
+                                name: string;
+                                spec: InputSpec<T.SmtpValue, T.SmtpValue>;
+                            };
+                            sendgrid: {
+                                name: string;
+                                spec: InputSpec<T.SmtpValue, T.SmtpValue>;
+                            };
+                            mailgun: {
+                                name: string;
+                                spec: InputSpec<T.SmtpValue, T.SmtpValue>;
+                            };
+                            protonmail: {
+                                name: string;
+                                spec: InputSpec<T.SmtpValue, T.SmtpValue>;
+                            };
+                            other: {
+                                name: string;
+                                spec: InputSpec<T.SmtpValue, T.SmtpValue>;
+                            };
+                        }, "other" | "gmail" | "ses" | "sendgrid" | "mailgun" | "protonmail">;
+                    }, {
+                        provider: import("../../base/lib/actions/input/builder/variants").UnionResStaticValidatedAs<{
+                            gmail: {
+                                name: string;
+                                spec: InputSpec<T.SmtpValue, T.SmtpValue>;
+                            };
+                            ses: {
+                                name: string;
+                                spec: InputSpec<T.SmtpValue, T.SmtpValue>;
+                            };
+                            sendgrid: {
+                                name: string;
+                                spec: InputSpec<T.SmtpValue, T.SmtpValue>;
+                            };
+                            mailgun: {
+                                name: string;
+                                spec: InputSpec<T.SmtpValue, T.SmtpValue>;
+                            };
+                            protonmail: {
+                                name: string;
+                                spec: InputSpec<T.SmtpValue, T.SmtpValue>;
+                            };
+                            other: {
+                                name: string;
+                                spec: InputSpec<T.SmtpValue, T.SmtpValue>;
+                            };
+                        }, "other" | "gmail" | "ses" | "sendgrid" | "mailgun" | "protonmail">;
+                    }>;
                 };
             }>, import("../../base/lib/actions/input/builder/variants").UnionResStaticValidatedAs<{
                 disabled: {
@@ -214,9 +338,145 @@ export declare class StartSdk<Manifest extends T.SDKManifest> {
                 };
                 custom: {
                     name: string;
-                    spec: InputSpec<T.SmtpValue, T.SmtpValue>;
+                    spec: InputSpec<{
+                        provider: import("../../base/lib/actions/input/builder/variants").UnionRes<{
+                            gmail: {
+                                name: string;
+                                spec: InputSpec<T.SmtpValue, T.SmtpValue>;
+                            };
+                            ses: {
+                                name: string;
+                                spec: InputSpec<T.SmtpValue, T.SmtpValue>;
+                            };
+                            sendgrid: {
+                                name: string;
+                                spec: InputSpec<T.SmtpValue, T.SmtpValue>;
+                            };
+                            mailgun: {
+                                name: string;
+                                spec: InputSpec<T.SmtpValue, T.SmtpValue>;
+                            };
+                            protonmail: {
+                                name: string;
+                                spec: InputSpec<T.SmtpValue, T.SmtpValue>;
+                            };
+                            other: {
+                                name: string;
+                                spec: InputSpec<T.SmtpValue, T.SmtpValue>;
+                            };
+                        }, "other" | "gmail" | "ses" | "sendgrid" | "mailgun" | "protonmail">;
+                    }, {
+                        provider: import("../../base/lib/actions/input/builder/variants").UnionResStaticValidatedAs<{
+                            gmail: {
+                                name: string;
+                                spec: InputSpec<T.SmtpValue, T.SmtpValue>;
+                            };
+                            ses: {
+                                name: string;
+                                spec: InputSpec<T.SmtpValue, T.SmtpValue>;
+                            };
+                            sendgrid: {
+                                name: string;
+                                spec: InputSpec<T.SmtpValue, T.SmtpValue>;
+                            };
+                            mailgun: {
+                                name: string;
+                                spec: InputSpec<T.SmtpValue, T.SmtpValue>;
+                            };
+                            protonmail: {
+                                name: string;
+                                spec: InputSpec<T.SmtpValue, T.SmtpValue>;
+                            };
+                            other: {
+                                name: string;
+                                spec: InputSpec<T.SmtpValue, T.SmtpValue>;
+                            };
+                        }, "other" | "gmail" | "ses" | "sendgrid" | "mailgun" | "protonmail">;
+                    }>;
                 };
             }>, unknown>;
+            systemSmtpSpec: InputSpec<{
+                provider: import("../../base/lib/actions/input/builder/variants").UnionRes<{
+                    gmail: {
+                        name: string;
+                        spec: InputSpec<T.SmtpValue, T.SmtpValue>;
+                    };
+                    ses: {
+                        name: string;
+                        spec: InputSpec<T.SmtpValue, T.SmtpValue>;
+                    };
+                    sendgrid: {
+                        name: string;
+                        spec: InputSpec<T.SmtpValue, T.SmtpValue>;
+                    };
+                    mailgun: {
+                        name: string;
+                        spec: InputSpec<T.SmtpValue, T.SmtpValue>;
+                    };
+                    protonmail: {
+                        name: string;
+                        spec: InputSpec<T.SmtpValue, T.SmtpValue>;
+                    };
+                    other: {
+                        name: string;
+                        spec: InputSpec<T.SmtpValue, T.SmtpValue>;
+                    };
+                }, "other" | "gmail" | "ses" | "sendgrid" | "mailgun" | "protonmail">;
+            }, {
+                provider: import("../../base/lib/actions/input/builder/variants").UnionResStaticValidatedAs<{
+                    gmail: {
+                        name: string;
+                        spec: InputSpec<T.SmtpValue, T.SmtpValue>;
+                    };
+                    ses: {
+                        name: string;
+                        spec: InputSpec<T.SmtpValue, T.SmtpValue>;
+                    };
+                    sendgrid: {
+                        name: string;
+                        spec: InputSpec<T.SmtpValue, T.SmtpValue>;
+                    };
+                    mailgun: {
+                        name: string;
+                        spec: InputSpec<T.SmtpValue, T.SmtpValue>;
+                    };
+                    protonmail: {
+                        name: string;
+                        spec: InputSpec<T.SmtpValue, T.SmtpValue>;
+                    };
+                    other: {
+                        name: string;
+                        spec: InputSpec<T.SmtpValue, T.SmtpValue>;
+                    };
+                }, "other" | "gmail" | "ses" | "sendgrid" | "mailgun" | "protonmail">;
+            }>;
+            customSmtp: InputSpec<T.SmtpValue, T.SmtpValue>;
+            smtpProviderVariants: Variants<{
+                gmail: {
+                    name: string;
+                    spec: InputSpec<T.SmtpValue, T.SmtpValue>;
+                };
+                ses: {
+                    name: string;
+                    spec: InputSpec<T.SmtpValue, T.SmtpValue>;
+                };
+                sendgrid: {
+                    name: string;
+                    spec: InputSpec<T.SmtpValue, T.SmtpValue>;
+                };
+                mailgun: {
+                    name: string;
+                    spec: InputSpec<T.SmtpValue, T.SmtpValue>;
+                };
+                protonmail: {
+                    name: string;
+                    spec: InputSpec<T.SmtpValue, T.SmtpValue>;
+                };
+                other: {
+                    name: string;
+                    spec: InputSpec<T.SmtpValue, T.SmtpValue>;
+                };
+            }, unknown>;
         };
         /**
          * @description Use this function to create a service interface.
@@ -265,8 +525,24 @@ export declare class StartSdk<Manifest extends T.SDKManifest> {
             /** mask the url (recommended if it contains credentials such as an API key or password) */
             masked: boolean;
         }) => ServiceInterfaceBuilder;
+        /**
+         * Get the system SMTP configuration with reactive subscription support.
+         * @param effects - The effects context
+         */
         getSystemSmtp: <E extends Effects>(effects: E) => GetSystemSmtp;
+        /**
+         * Get the outbound network gateway address with reactive subscription support.
+         * @param effects - The effects context
+         */
+        getOutboundGateway: <E extends Effects>(effects: E) => GetOutboundGateway;
+        /**
+         * Get an SSL certificate for the given hostnames with reactive subscription support.
+         * @param effects - The effects context
+         * @param hostnames - The hostnames to obtain a certificate for
+         * @param algorithm - Optional algorithm preference (e.g. Ed25519)
+         */
         getSslCertificate: <E extends Effects>(effects: E, hostnames: string[], algorithm?: T.Algorithm) => GetSslCertificate;
+        /** Retrieve the manifest of any installed service package by its ID */
         getServiceManifest: typeof getServiceManifest;
         healthCheck: {
             checkPortListening: typeof checkPortListening;
@@ -281,6 +557,7 @@ export declare class StartSdk<Manifest extends T.SDKManifest> {
                 message?: ((res: string) => string) | undefined;
             }) => Promise<import("./health/checkFns").HealthCheckResult>;
         };
+        /** Common utility patterns (e.g. hostname regex, port validators) */
         patterns: typeof patterns;
         /**
          * @description Use this function to list every Action offered by the service. Actions will be displayed in the provided order.
@@ -467,24 +744,50 @@ export declare class StartSdk<Manifest extends T.SDKManifest> {
          * ```
          */
         setupInterfaces: import("../../base/lib/interfaces/setupInterfaces").SetupServiceInterfaces;
+        /**
+         * Define the main entrypoint for the service. The provided function should
+         * configure and return a `Daemons` instance describing all long-running processes.
+         * @param fn - Async function that receives `effects` and returns a `Daemons` instance
+         */
         setupMain: (fn: (o: {
             effects: Effects;
         }) => Promise<Daemons<Manifest, any>>) => T.ExpectedExports.main;
+        /** Built-in trigger strategies for controlling health-check polling intervals */
         trigger: {
+            /** Default trigger: polls at a fixed interval */
             defaultTrigger: import("./trigger").Trigger;
+            /** Trigger with a cooldown period between checks */
             cooldownTrigger: typeof cooldownTrigger;
+            /** Switches to a different interval after the first successful check */
             changeOnFirstSuccess: typeof changeOnFirstSuccess;
+            /** Uses different intervals based on success vs failure results */
             successFailure: (o: {
                 duringSuccess: import("./trigger").Trigger;
                 duringError: import("./trigger").Trigger;
             }) => import("./trigger").Trigger;
         };
         Mounts: {
+            /**
+             * Create an empty Mounts builder for declaring volume, asset, dependency, and backup mounts.
+             * @returns A new Mounts instance with no mounts configured
+             */
             of: () => Mounts<Manifest, never>;
         };
         Backups: {
+            /**
+             * Create a Backups configuration that backs up entire volumes by name.
+             * @param volumeNames - Volume IDs from the manifest to include in backups
+             */
             ofVolumes: (...volumeNames: Manifest["volumes"][number][]) => Backups<Manifest>;
+            /**
+             * Create a Backups configuration from explicit sync path pairs.
+             * @param syncs - Array of `{ dataPath, backupPath }` objects
+             */
             ofSyncs: (...syncs: import("./backup/Backups").BackupSync<Manifest["volumes"][number]>[]) => Backups<Manifest>;
+            /**
+             * Create a Backups configuration with custom rsync options (e.g. exclude patterns).
+             * @param options - Partial sync options to override defaults
+             */
             withOptions: (options?: Partial<T.SyncOptions>) => Backups<Manifest>;
         };
         InputSpec: {
@@ -518,9 +821,18 @@ export declare class StartSdk<Manifest extends T.SDKManifest> {
             of: <Spec extends Record<string, Value<any>>>(spec: Spec) => InputSpec<{ [K in keyof Spec]: Spec[K] extends Value<infer T extends any, any, unknown> ? T : never; }, { [K_1 in keyof Spec]: Spec[K_1] extends Value<any, infer T_1, unknown> ? T_1 : never; }>;
         };
         Daemon: {
+            /**
+             * Create a single Daemon that wraps a long-running process with automatic restart logic.
+             * Returns a curried function: call with `(effects, subcontainer, exec)`.
+             */
             readonly of: <C extends SubContainer<Manifest, Effects> | null>(effects: T.Effects, subcontainer: C, exec: import("./mainFn/Daemons").DaemonCommandType<Manifest, C>) => Daemon<Manifest, SubContainer<Manifest, Effects> | null>;
         };
         Daemons: {
+            /**
+             * Create a new Daemons builder for defining the service's daemon topology.
+             * Chain `.addDaemon()` calls to register each long-running process.
+             * @param effects - The effects context
+             */
             of(effects: Effects): Daemons<Manifest, never>;
         };
         SubContainer: {
@@ -609,10 +921,25 @@ export declare class StartSdk<Manifest extends T.SDKManifest> {
             hostnames: string[];
             algorithm?: "ecdsa" | "ed25519";
         }) => Promise<string>;
+        /** The bound service manifest */
         manifest: Manifest;
+        /** Volume path helpers derived from the manifest volume definitions */
         volumes: Volumes<Manifest>;
     };
 }
+/**
+ * Run a one-shot command inside a temporary subcontainer.
+ *
+ * Creates a subcontainer, executes the command, and destroys the subcontainer when finished.
+ * Throws an {@link ExitError} if the command exits with a non-zero code or signal.
+ *
+ * @param effects - The effects context
+ * @param image - The container image to use
+ * @param command - The command to execute (string array or UseEntrypoint)
+ * @param options - Mount and command options
+ * @param name - Optional human-readable name for debugging
+ * @returns The stdout and stderr output of the command
+ */
 export declare function runCommand<Manifest extends T.SDKManifest>(effects: Effects, image: {
     imageId: keyof Manifest['images'] & T.ImageId;
     sharedRun?: boolean;