@start9labs/start-sdk 0.4.0-beta.9 → 0.4.0

package/package/lib/StartSdk.js

@@ -35,58 +35,85 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StartSdk = exports.OSVersion = void 0;
 exports.runCommand = runCommand;
-const value_1 = require("../../base/lib/actions/input/builder/value");
+const fs = __importStar(require("node:fs/promises"));
+const actions = __importStar(require("../../base/lib/actions"));
 const inputSpec_1 = require("../../base/lib/actions/input/builder/inputSpec");
+const list_1 = require("../../base/lib/actions/input/builder/list");
+const value_1 = require("../../base/lib/actions/input/builder/value");
 const variants_1 = require("../../base/lib/actions/input/builder/variants");
+const inputSpecConstants_1 = require("../../base/lib/actions/input/inputSpecConstants");
 const setupActions_1 = require("../../base/lib/actions/setupActions");
+const dependencies_1 = require("../../base/lib/dependencies/dependencies");
+const setupDependencies_1 = require("../../base/lib/dependencies/setupDependencies");
+const exver_1 = require("../../base/lib/exver");
+const inits_1 = require("../../base/lib/inits");
+const Host_1 = require("../../base/lib/interfaces/Host");
+const ServiceInterfaceBuilder_1 = require("../../base/lib/interfaces/ServiceInterfaceBuilder");
+const setupExportedUrls_1 = require("../../base/lib/interfaces/setupExportedUrls");
+const setupInterfaces_1 = require("../../base/lib/interfaces/setupInterfaces");
+const T = __importStar(require("../../base/lib/types"));
+const GetContainerIp_1 = require("../../base/lib/util/GetContainerIp");
+const GetStatus_1 = require("../../base/lib/util/GetStatus");
+const getServiceInterface_1 = require("../../base/lib/util/getServiceInterface");
+const getServiceInterfaces_1 = require("../../base/lib/util/getServiceInterfaces");
 const patterns = __importStar(require("../../base/lib/util/patterns"));
 const Backups_1 = require("./backup/Backups");
-const inputSpecConstants_1 = require("../../base/lib/actions/input/inputSpecConstants");
-const Daemons_1 = require("./mainFn/Daemons");
-const HealthCheck_1 = require("./health/HealthCheck");
-const checkPortListening_1 = require("./health/checkFns/checkPortListening");
-const checkFns_1 = require("./health/checkFns");
-const list_1 = require("../../base/lib/actions/input/builder/list");
-const setupInstall_1 = require("./inits/setupInstall");
 const setupBackups_1 = require("./backup/setupBackups");
-const setupUninstall_1 = require("./inits/setupUninstall");
+const checkFns_1 = require("./health/checkFns");
+const checkPortListening_1 = require("./health/checkFns/checkPortListening");
 const mainFn_1 = require("./mainFn");
-const defaultTrigger_1 = require("./trigger/defaultTrigger");
+const Daemons_1 = require("./mainFn/Daemons");
+const Mounts_1 = require("./mainFn/Mounts");
 const trigger_1 = require("./trigger");
-const setupInterfaces_1 = require("../../base/lib/interfaces/setupInterfaces");
+const defaultTrigger_1 = require("./trigger/defaultTrigger");
 const successFailure_1 = require("./trigger/successFailure");
-const Host_1 = require("../../base/lib/interfaces/Host");
-const ServiceInterfaceBuilder_1 = require("../../base/lib/interfaces/ServiceInterfaceBuilder");
 const util_1 = require("./util");
-const util_2 = require("./util");
-const util_3 = require("./util");
-const getStore_1 = require("./store/getStore");
 const SubContainer_1 = require("./util/SubContainer");
-const util_4 = require("./util");
-const Mounts_1 = require("./mainFn/Mounts");
-const setupDependencies_1 = require("../../base/lib/dependencies/setupDependencies");
-const T = __importStar(require("../../base/lib/types"));
-const exver_1 = require("../../base/lib/exver");
-const PathBuilder_1 = require("../../base/lib/util/PathBuilder");
-const dependencies_1 = require("../../base/lib/dependencies/dependencies");
-const util_5 = require("./util");
-const actions = __importStar(require("../../base/lib/actions"));
-const setupInit_1 = require("./inits/setupInit");
-const fs = __importStar(require("node:fs/promises"));
-exports.OSVersion = (0, exver_1.testTypeVersion)("0.4.0-alpha.0");
+const Volume_1 = require("./util/Volume");
+const version_1 = require("./version");
+/** The minimum StartOS version required by this SDK release */
+exports.OSVersion = (0, exver_1.testTypeVersion)('0.4.0-alpha.23');
+/**
+ * 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.
+ */
 class StartSdk {
     constructor(manifest) {
         this.manifest = manifest;
     }
+    /**
+     * Create an uninitialized StartSdk instance. Call `.withManifest()` next.
+     * @returns A new StartSdk with no manifest bound.
+     */
     static of() {
         return new StartSdk(null);
     }
+    /**
+     * 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) {
         return new StartSdk(manifest);
     }
-    withStore() {
-        return new StartSdk(this.manifest);
+    ifPluginEnabled(plugin, value) {
+        if (this.manifest.plugins?.includes(plugin))
+            return value;
+        return null;
     }
+    /**
+     * 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) {
         const startSdkEffectWrapper = {
             restart: (effects, ...args) => effects.restart(...args),
@@ -94,102 +121,106 @@ class StartSdk {
             checkDependencies: (effects, ...args) => effects.checkDependencies(...args),
             mount: (effects, ...args) => effects.mount(...args),
             getInstalledPackages: (effects, ...args) => effects.getInstalledPackages(...args),
-            exposeForDependents: (effects, ...args) => effects.exposeForDependents(...args),
             getServicePortForward: (effects, ...args) => effects.getServicePortForward(...args),
             clearBindings: (effects, ...args) => effects.clearBindings(...args),
             getOsIp: (effects, ...args) => effects.getOsIp(...args),
             getSslKey: (effects, ...args) => effects.getSslKey(...args),
-            setDataVersion: (effects, ...args) => effects.setDataVersion(...args),
-            getDataVersion: (effects, ...args) => effects.getDataVersion(...args),
             shutdown: (effects, ...args) => effects.shutdown(...args),
             getDependencies: (effects, ...args) => effects.getDependencies(...args),
-            getStatus: (effects, ...args) => effects.getStatus(...args),
+            setHealth: (effects, ...args) => effects.setHealth(...args),
         };
         return {
+            /** The bound service manifest */
             manifest: this.manifest,
+            /** Volume path helpers derived from the manifest volume definitions */
+            volumes: (0, Volume_1.createVolumes)(this.manifest),
             ...startSdkEffectWrapper,
+            /** Persist the current data version to the StartOS effect system */
+            setDataVersion: version_1.setDataVersion,
+            /** Retrieve the current data version from the StartOS effect system */
+            getDataVersion: version_1.getDataVersion,
             action: {
+                /** Execute an action by its ID, optionally providing input */
                 run: actions.runAction,
-                request: (effects, packageId, action, severity, options) => actions.requestAction({
+                /** Create a task notification for a specific package's action */
+                createTask: (effects, packageId, action, severity, options) => actions.createTask({
                     effects,
                     packageId,
                     action,
                     severity,
                     options: options,
                 }),
-                requestOwn: (effects, action, severity, options) => actions.requestAction({
+                /** Create a task notification for this service's own action (uses manifest.id automatically) */
+                createOwnTask: (effects, action, severity, options) => actions.createTask({
                     effects,
                     packageId: this.manifest.id,
                     action,
                     severity,
                     options: options,
                 }),
-                clearRequest: (effects, ...replayIds) => effects.action.clearRequests({ only: replayIds }),
+                /**
+                 * 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, ...replayIds) => effects.action.clearTasks({ only: replayIds }),
             },
+            /**
+             * 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: dependencies_1.checkDependencies,
             serviceInterface: {
-                getOwn: (effects, id) => (0, util_3.getServiceInterface)(effects, {
-                    id,
-                }),
-                get: (effects, opts) => (0, util_3.getServiceInterface)(effects, opts),
-                getAllOwn: (effects) => (0, util_3.getServiceInterfaces)(effects, {}),
-                getAll: (effects, opts) => (0, util_3.getServiceInterfaces)(effects, opts),
-            },
-            getContainerIp: (effects, options = {}) => {
-                async function* watch() {
-                    const resolveCell = { resolve: () => { } };
-                    effects.onLeaveContext(() => {
-                        resolveCell.resolve();
-                    });
-                    while (effects.isInContext) {
-                        let callback = () => { };
-                        const waitForNext = new Promise((resolve) => {
-                            callback = resolve;
-                            resolveCell.resolve = resolve;
-                        });
-                        yield await effects.getContainerIp({ ...options, callback });
-                        await waitForNext;
-                    }
-                }
-                return {
-                    const: () => effects.getContainerIp({
-                        ...options,
-                        callback: effects.constRetry &&
-                            (() => effects.constRetry && effects.constRetry()),
-                    }),
-                    once: () => effects.getContainerIp(options),
-                    watch,
-                    onChange: (callback) => {
-                        ;
-                        (async () => {
-                            for await (const value of watch()) {
-                                try {
-                                    await callback(value);
-                                }
-                                catch (e) {
-                                    console.error("callback function threw an error @ getContainerIp.onChange", e);
-                                }
-                            }
-                        })()
-                            .catch((e) => callback(null, e))
-                            .catch((e) => console.error("callback function threw an error @ getContainerIp.onChange", e));
-                    },
-                };
-            },
-            store: {
-                get: (effects, packageId, path) => (0, getStore_1.getStore)(effects, path, {
-                    packageId,
-                }),
-                getOwn: (effects, path) => (0, getStore_1.getStore)(effects, path),
-                setOwn: (effects, path, value) => effects.store.set({
-                    value,
-                    path: (0, PathBuilder_1.extractJsonPath)(path),
-                }),
+                /** Retrieve a single service interface belonging to this package by its ID */
+                getOwn: getServiceInterface_1.getOwnServiceInterface,
+                /** Retrieve a single service interface from any package */
+                get: util_1.getServiceInterface,
+                /** Retrieve all service interfaces belonging to this package */
+                getAllOwn: getServiceInterfaces_1.getOwnServiceInterfaces,
+                /** Retrieve all service interfaces, optionally filtering by package */
+                getAll: util_1.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, options = {}) => new GetContainerIp_1.GetContainerIp(effects, options),
+            /**
+             * Get the service's current status 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. `packageId`)
+             */
+            getStatus: (effects, options = {}) => new GetStatus_1.GetStatus(effects, options),
             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, id) => new Host_1.MultiHost({ id, effects }),
             },
-            nullIfEmpty: util_2.nullIfEmpty,
+            /**
+             * Return `null` if the given string is empty, otherwise return the string unchanged.
+             * Useful for converting empty user input into explicit null values.
+             */
+            nullIfEmpty: util_1.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) => new T.UseEntrypoint(overrideCmd),
             /**
              * @description Use this class to create an Action. By convention, each Action should receive its own file.
@@ -253,7 +284,7 @@ class StartSdk {
                   )
                  * ```
                 */
-                withInput: (id, metadata, inputSpec, getInput, run) => setupActions_1.Action.withInput(id, metadata, inputSpec, getInput, run),
+                withInput: setupActions_1.Action.withInput,
                 /**
                  * @description Use this function to create an action that does not accept form input
                  * @param id - a unique ID for this action
@@ -263,6 +294,7 @@ class StartSdk {
                  * In this example, we create an action that returns a secret phrase for the user to see.
                  *
                  * ```
+                  import { store } from '../file-models/store.json'
                   import { sdk } from '../sdk'
         
                   export const showSecretPhrase = sdk.Action.withoutInput(
@@ -287,9 +319,7 @@ class StartSdk {
                         'Below is your secret phrase. Use it to gain access to extraordinary places',
                       result: {
                         type: 'single',
-                        value: await sdk.store
-                          .getOwn(effects, sdk.StorePath.secretPhrase)
-                          .const(),
+                        value: (await store.read.once())?.secretPhrase,
                         copyable: true,
                         qr: true,
                         masked: true,
@@ -300,7 +330,12 @@ class StartSdk {
                 */
                 withoutInput: (id, metadata, run) => setupActions_1.Action.withoutInput(id, metadata, run),
             },
-            inputSpecConstants: { smtpInputSpec: inputSpecConstants_1.smtpInputSpec },
+            inputSpecConstants: {
+                smtpInputSpec: inputSpecConstants_1.smtpInputSpec,
+                systemSmtpSpec: inputSpecConstants_1.systemSmtpSpec,
+                customSmtp: inputSpecConstants_1.customSmtp,
+                smtpProviderVariants: inputSpecConstants_1.smtpProviderVariants,
+            },
             /**
              * @description Use this function to create a service interface.
              * @param effects
@@ -318,19 +353,36 @@ class StartSdk {
                 schemeOverride: null,
                 username: null,
                 path: '',
-                search: {},
+                query: {},
               })
              * ```
              */
             createInterface: (effects, options) => new ServiceInterfaceBuilder_1.ServiceInterfaceBuilder({ ...options, effects }),
+            /**
+             * Get the system SMTP configuration with reactive subscription support.
+             * @param effects - The effects context
+             */
             getSystemSmtp: (effects) => new util_1.GetSystemSmtp(effects),
-            getSslCerificate: (effects, hostnames, algorithm) => new util_5.GetSslCertificate(effects, hostnames, algorithm),
-            HealthCheck: HealthCheck_1.HealthCheck,
+            /**
+             * Get the outbound network gateway address with reactive subscription support.
+             * @param effects - The effects context
+             */
+            getOutboundGateway: (effects) => new util_1.GetOutboundGateway(effects),
+            /**
+             * 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: (effects, hostnames, algorithm) => new util_1.GetSslCertificate(effects, { hostnames, algorithm }),
+            /** Retrieve the manifest of any installed service package by its ID */
+            getServiceManifest: util_1.getServiceManifest,
             healthCheck: {
                 checkPortListening: checkPortListening_1.checkPortListening,
                 checkWebUrl: checkFns_1.checkWebUrl,
                 runHealthScript: checkFns_1.runHealthScript,
             },
+            /** Common utility patterns (e.g. hostname regex, port validators) */
             patterns,
             /**
              * @description Use this function to list every Action offered by the service. Actions will be displayed in the provided order.
@@ -376,11 +428,11 @@ class StartSdk {
             /**
              * @description Use this function to set dependency information.
              * @example
-             * In this example, we create a perpetual dependency on Hello World >=1.0.0:0, where Hello World must be running and passing its "primary" health check.
+             * In this example, we create a dependency on Hello World >=1.0.0:0, where Hello World must be running and passing its "primary" health check.
              *
              * ```
               export const setDependencies = sdk.setupDependencies(
-                async ({ effects, input }) => {
+                async ({ effects }) => {
                   return {
                     'hello-world': {
                       kind: 'running',
@@ -391,66 +443,57 @@ class StartSdk {
                 },
               )
              * ```
-             * @example
-             * In this example, we create a conditional dependency on Hello World based on a hypothetical "needsWorld" boolean in our Store.
-             * Using .const() ensures that if the "needsWorld" boolean changes, setupDependencies will re-run.
-             *
-             * ```
-              export const setDependencies = sdk.setupDependencies(
-                async ({ effects }) => {
-                  if (sdk.store.getOwn(sdk.StorePath.needsWorld).const()) {
-                    return {
-                      'hello-world': {
-                        kind: 'running',
-                        versionRange: '>=1.0.0',
-                        healthChecks: ['primary'],
-                      },
-                    }
-                  }
-                  return {}
-                },
-              )
-             * ```
              */
             setupDependencies: (setupDependencies_1.setupDependencies),
-            setupInit: (setupInit_1.setupInit),
             /**
-             * @description Use this function to execute arbitrary logic *once*, on initial install *before* interfaces, actions, and dependencies are updated.
+             * @description Use this function to create an InitScript that runs every time the service initializes (install, update, restore, rebuild, and server bootup)
+             */
+            setupOnInit: inits_1.setupOnInit,
+            /**
+             * @description Use this function to create an UninitScript that runs every time the service uninitializes (update, uninstall, and server shutdown)
+             */
+            setupOnUninit: inits_1.setupOnUninit,
+            /**
+             * @description Use this function to setup what happens when the service initializes.
+             *
+             *    This happens when the server boots, or a service is installed, updated, or restored
+             *
+             *    Not every init script does something on every initialization. For example, versions only does something on install or update
+             *
+             *    These scripts are run in the order they are supplied
              * @example
-             * In the this example, we initialize a config file
              *
              * ```
-              const preInstall = sdk.setupPreInstall(async ({ effects }) => {
-                await configFile.write(effects, { name: 'World' })
-              })
+              export const init = sdk.setupInit(
+                restoreInit,
+                versions,
+                setDependencies,
+                setInterfaces,
+                actions,
+                postInstall,
+              )
              * ```
              */
-            setupPreInstall: (fn) => setupInstall_1.PreInstall.of(fn),
+            setupInit: inits_1.setupInit,
             /**
-             * @description Use this function to execute arbitrary logic *once*, on initial install *after* interfaces, actions, and dependencies are updated.
+             * @description Use this function to setup what happens when the service uninitializes.
+             *
+             *    This happens when the server shuts down, or a service is uninstalled or updated
+             *
+             *    Not every uninit script does something on every uninitialization. For example, versions only does something on uninstall or update
+             *
+             *    These scripts are run in the order they are supplied
              * @example
-             * In the this example, we bootstrap our Store with a random, 16-char admin password.
              *
              * ```
-              const postInstall = sdk.setupPostInstall(async ({ effects }) => {
-                await sdk.store.setOwn(
-                  effects,
-                  sdk.StorePath.adminPassword,
-                  utils.getDefaultString({
-                    charset: 'a-z,A-Z,1-9,!,@,$,%,&,',
-                    len: 16,
-                  }),
-                )
-              })
+              export const uninit = sdk.setupUninit(
+                versions,
+              )
              * ```
              */
-            setupPostInstall: (fn) => setupInstall_1.PostInstall.of(fn),
+            setupUninit: inits_1.setupUninit,
             /**
              * @description Use this function to determine how this service will be hosted and served. The function executes on service install, service update, and inputSpec save.
-             *
-             *   "input" will be of type `Input` for inputSpec save. It will be `null` for install and update.
-             *
-             *   To learn about creating multi-hosts and interfaces, check out the {@link https://docs.start9.com/packaging-guide/learn/interfaces documentation}.
              * @param inputSpec - The inputSpec spec of this service as exported from /inputSpec/spec.
              * @param fn - an async function that returns an array of interface receipts. The function always has access to `effects`; it has access to `input` only after inputSpec save, otherwise `input` will be null.
              * @example
@@ -458,8 +501,7 @@ class StartSdk {
              *
              * ```
               export const setInterfaces = sdk.setupInterfaces(
-                inputSpecSpec,
-                async ({ effects, input }) => {
+                async ({ effects }) => {
                   // ** UI multi-host **
                   const uiMulti = sdk.MultiHost.of(effects, 'ui-multi')
                   const uiMultiOrigin = await uiMulti.bindPort(80, {
@@ -475,7 +517,7 @@ class StartSdk {
                     schemeOverride: null,
                     username: null,
                     path: '',
-                    search: {},
+                    query: {},
                   })
                   // Admin UI
                   const adminUi = sdk.createInterface(effects, {
@@ -487,7 +529,7 @@ class StartSdk {
                     schemeOverride: null,
                     username: null,
                     path: '/admin',
-                    search: {},
+                    query: {},
                   })
                   // UI receipt
                   const uiReceipt = await uiMultiOrigin.export([primaryUi, adminUi])
@@ -507,7 +549,7 @@ class StartSdk {
                     schemeOverride: null,
                     username: null,
                     path: '',
-                    search: {},
+                    query: {},
                   })
                   // API receipt
                   const apiReceipt = await apiMultiOrigin.export([api])
@@ -519,26 +561,58 @@ class StartSdk {
              * ```
              */
             setupInterfaces: setupInterfaces_1.setupServiceInterfaces,
-            setupMain: (fn) => (0, mainFn_1.setupMain)(fn),
             /**
-             * Use this function to execute arbitrary logic *once*, on uninstall only. Most services will not use this.
+             * 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
              */
-            setupUninstall: (fn) => (0, setupUninstall_1.setupUninstall)(fn),
+            setupMain: (fn) => (0, mainFn_1.setupMain)(fn),
+            /** Built-in trigger strategies for controlling health-check polling intervals */
             trigger: {
+                /** Default trigger: polls at a fixed interval */
                 defaultTrigger: defaultTrigger_1.defaultTrigger,
+                /** Trigger with a cooldown period between checks */
                 cooldownTrigger: trigger_1.cooldownTrigger,
+                /** Switches to a different interval after the first successful check */
                 changeOnFirstSuccess: trigger_1.changeOnFirstSuccess,
+                /** Uses different intervals based on success vs failure results */
                 successFailure: successFailure_1.successFailure,
             },
             Mounts: {
-                of() {
-                    return Mounts_1.Mounts.of();
-                },
+                /**
+                 * Create an empty Mounts builder for declaring volume, asset, dependency, and backup mounts.
+                 * @returns A new Mounts instance with no mounts configured
+                 */
+                of: (Mounts_1.Mounts.of),
             },
             Backups: {
-                volumes: (...volumeNames) => Backups_1.Backups.withVolumes(...volumeNames),
-                addSets: (...options) => Backups_1.Backups.withSyncs(...options),
-                withOptions: (options) => Backups_1.Backups.withOptions(options),
+                /**
+                 * Create a Backups configuration that backs up entire volumes by name.
+                 * @param volumeNames - Volume IDs from the manifest to include in backups
+                 */
+                ofVolumes: (Backups_1.Backups.ofVolumes),
+                /**
+                 * Create a Backups configuration from explicit sync path pairs.
+                 * @param syncs - Array of `{ dataPath, backupPath }` objects
+                 */
+                ofSyncs: (Backups_1.Backups.ofSyncs),
+                /**
+                 * Create a Backups configuration with custom rsync options (e.g. exclude patterns).
+                 * @param options - Partial sync options to override defaults
+                 */
+                withOptions: (Backups_1.Backups.withOptions),
+                /**
+                 * Create a Backups configuration that uses pg_dump/pg_restore instead of
+                 * rsyncing the raw PostgreSQL data directory. Chain `.addVolume()` to include
+                 * additional volumes in the backup.
+                 */
+                withPgDump: (Backups_1.Backups.withPgDump),
+                /**
+                 * Create a Backups configuration that uses mysqldump/mysql instead of
+                 * rsyncing the raw MySQL/MariaDB data directory. Chain `.addVolume()` to
+                 * include additional volumes in the backup.
+                 */
+                withMysqlDump: (Backups_1.Backups.withMysqlDump),
             },
             InputSpec: {
                 /**
@@ -570,9 +644,23 @@ class StartSdk {
                  */
                 of: (spec) => inputSpec_1.InputSpec.of(spec),
             },
+            Daemon: {
+                /**
+                 * Create a single Daemon that wraps a long-running process with automatic restart logic.
+                 * Returns a curried function: call with `(effects, subcontainer, exec)`.
+                 */
+                get of() {
+                    return Daemons_1.Daemon.of();
+                },
+            },
             Daemons: {
-                of(effects, started, healthChecks) {
-                    return Daemons_1.Daemons.of({ effects, started, healthChecks });
+                /**
+                 * 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) {
+                    return Daemons_1.Daemons.of({ effects });
                 },
             },
             SubContainer: {
@@ -584,7 +672,7 @@ class StartSdk {
                  * @param name - a name to use to refer to the subcontainer for debugging purposes
                  */
                 of(effects, image, mounts, name) {
-                    return SubContainer_1.SubContainer.of(effects, image, mounts, name);
+                    return SubContainer_1.SubContainerOwned.of(effects, image, mounts, name).then((subc) => subc.rc());
                 },
                 /**
                  * @description Run a function with a temporary SubContainer
@@ -594,359 +682,67 @@ class StartSdk {
                  * @param name - a name to use to refer to the ephemeral subcontainer for debugging purposes
                  */
                 withTemp(effects, image, mounts, name, fn) {
-                    return SubContainer_1.SubContainer.withTemp(effects, image, mounts, name, fn);
+                    return SubContainer_1.SubContainerOwned.withTemp(effects, image, mounts, name, fn);
                 },
             },
-            List: {
-                /**
-                 * @description Create a list of text inputs.
-                 * @param a - attributes of the list itself.
-                 * @param aSpec - attributes describing each member of the list.
-                 */
-                text: list_1.List.text,
-                /**
-                 * @description Create a list of objects.
-                 * @param a - attributes of the list itself.
-                 * @param aSpec - attributes describing each member of the list.
-                 */
-                obj: (a, aSpec) => list_1.List.obj(a, aSpec),
-                /**
-                 * @description Create a list of dynamic text inputs.
-                 * @param a - attributes of the list itself.
-                 * @param aSpec - attributes describing each member of the list.
-                 */
-                dynamicText: (list_1.List.dynamicText),
-            },
-            StorePath: (0, PathBuilder_1.pathBuilder)(),
-            Value: {
-                /**
-                 * @description Displays a boolean toggle to enable/disable
-                 * @example
-                 * ```
-                  toggleExample: Value.toggle({
-                    // required
-                    name: 'Toggle Example',
-                    default: true,
-                 
-                    // optional
-                    description: null,
-                    warning: null,
-                    immutable: false,
-                  }),
-                 * ```
-                 */
-                toggle: value_1.Value.toggle,
-                /**
-                 * @description Displays a text input field
-                 * @example
-                 * ```
-                  textExample: Value.text({
-                    // required
-                    name: 'Text Example',
-                    required: false,
-                    default: null,
-                 
-                    // optional
-                    description: null,
-                    placeholder: null,
-                    warning: null,
-                    generate: null,
-                    inputmode: 'text',
-                    masked: false,
-                    minLength: null,
-                    maxLength: null,
-                    patterns: [],
-                    immutable: false,
-                  }),
-                 * ```
-                 */
-                text: value_1.Value.text,
-                /**
-                 * @description Displays a large textarea field for long form entry.
-                 * @example
-                 * ```
-                  textareaExample: Value.textarea({
-                    // required
-                    name: 'Textarea Example',
-                    required: false,
-                    default: null,
-                 
-                    // optional
-                    description: null,
-                    placeholder: null,
-                    warning: null,
-                    minLength: null,
-                    maxLength: null,
-                    immutable: false,
-                  }),
-                 * ```
-                 */
-                textarea: value_1.Value.textarea,
-                /**
-                 * @description Displays a number input field
-                 * @example
-                 * ```
-                  numberExample: Value.number({
-                    // required
-                    name: 'Number Example',
-                    required: false,
-                    default: null,
-                    integer: true,
-                 
-                    // optional
-                    description: null,
-                    placeholder: null,
-                    warning: null,
-                    min: null,
-                    max: null,
-                    immutable: false,
-                    step: null,
-                    units: null,
-                  }),
-                 * ```
-                 */
-                number: value_1.Value.number,
-                /**
-                 * @description Displays a browser-native color selector.
-                 * @example
-                 * ```
-                  colorExample: Value.color({
-                    // required
-                    name: 'Color Example',
-                    required: false,
-                    default: null,
-                 
-                    // optional
-                    description: null,
-                    warning: null,
-                    immutable: false,
-                  }),
-                 * ```
-                 */
-                color: value_1.Value.color,
-                /**
-                 * @description Displays a browser-native date/time selector.
-                 * @example
-                 * ```
-                  datetimeExample: Value.datetime({
-                    // required
-                    name: 'Datetime Example',
-                    required: false,
-                    default: null,
-                 
-                    // optional
-                    description: null,
-                    warning: null,
-                    immutable: false,
-                    inputmode: 'datetime-local',
-                    min: null,
-                    max: null,
-                  }),
-                 * ```
-                 */
-                datetime: value_1.Value.datetime,
-                /**
-                 * @description Displays a select modal with radio buttons, allowing for a single selection.
-                 * @example
-                 * ```
-                  selectExample: Value.select({
-                    // required
-                    name: 'Select Example',
-                    default: 'radio1',
-                    values: {
-                      radio1: 'Radio 1',
-                      radio2: 'Radio 2',
-                    },
-                 
-                    // optional
-                    description: null,
-                    warning: null,
-                    immutable: false,
-                    disabled: false,
-                  }),
-                 * ```
-                 */
-                select: value_1.Value.select,
-                /**
-                 * @description Displays a select modal with checkboxes, allowing for multiple selections.
-                 * @example
-                 * ```
-                  multiselectExample: Value.multiselect({
-                    // required
-                    name: 'Multiselect Example',
-                    values: {
-                      option1: 'Option 1',
-                      option2: 'Option 2',
-                    },
-                    default: [],
-                 
-                    // optional
-                    description: null,
-                    warning: null,
-                    immutable: false,
-                    disabled: false,
-                    minlength: null,
-                    maxLength: null,
-                  }),
-                 * ```
-                 */
-                multiselect: value_1.Value.multiselect,
-                /**
-                 * @description Display a collapsable grouping of additional fields, a "sub form". The second value is the inputSpec spec for the sub form.
-                 * @example
-                 * ```
-                  objectExample: Value.object(
-                    {
-                      // required
-                      name: 'Object Example',
-                 
-                      // optional
-                      description: null,
-                      warning: null,
-                    },
-                    InputSpec.of({}),
-                  ),
-                 * ```
-                 */
-                object: value_1.Value.object,
-                /**
-                 * @description Displays a dropdown, allowing for a single selection. Depending on the selection, a different object ("sub form") is presented.
-                 * @example
-                 * ```
-                  unionExample: Value.union(
-                    {
-                      // required
-                      name: 'Union Example',
-                      default: 'option1',
-                 
-                      // optional
-                      description: null,
-                      warning: null,
-                      disabled: false,
-                      immutable: false,
-                    },
-                    Variants.of({
-                      option1: {
-                        name: 'Option 1',
-                        spec: InputSpec.of({}),
-                      },
-                      option2: {
-                        name: 'Option 2',
-                        spec: InputSpec.of({}),
-                      },
+            List: list_1.List,
+            Value: value_1.Value,
+            Variants: variants_1.Variants,
+            plugin: {
+                url: this.ifPluginEnabled('url-v0', {
+                    register: (effects, options) => effects.plugin.url.register({
+                        tableAction: options.tableAction.id,
                     }),
-                  ),
-                 * ```
-                 */
-                union: value_1.Value.union,
-                /**
-                 * @description Presents an interface to add/remove/edit items in a list.
-                 * @example
-                 * In this example, we create a list of text inputs.
-                 *
-                 * ```
-                  listExampleText: Value.list(
-                    List.text(
-                      {
-                        // required
-                        name: 'Text List',
-        
-                        // optional
-                        description: null,
-                        warning: null,
-                        default: [],
-                        minLength: null,
-                        maxLength: null,
-                      },
-                      {
-                        // required
-                        patterns: [],
-        
-                        // optional
-                        placeholder: null,
-                        generate: null,
-                        inputmode: 'url',
-                        masked: false,
-                        minLength: null,
-                        maxLength: null,
-                      },
-                    ),
-                  ),
-                 * ```
-                 * @example
-                 * In this example, we create a list of objects.
-                 *
-                 * ```
-                  listExampleObject: Value.list(
-                    List.obj(
-                      {
-                        // required
-                        name: 'Object List',
-        
-                        // optional
-                        description: null,
-                        warning: null,
-                        default: [],
-                        minLength: null,
-                        maxLength: null,
-                      },
-                      {
-                        // required
-                        spec: InputSpec.of({}),
-        
-                        // optional
-                        displayAs: null,
-                        uniqueBy: null,
-                      },
-                    ),
-                  ),
-                 * ```
-                 */
-                list: value_1.Value.list,
-                hidden: value_1.Value.hidden,
-                dynamicToggle: (value_1.Value.dynamicToggle),
-                dynamicText: (value_1.Value.dynamicText),
-                dynamicTextarea: (value_1.Value.dynamicTextarea),
-                dynamicNumber: (value_1.Value.dynamicNumber),
-                dynamicColor: (value_1.Value.dynamicColor),
-                dynamicDatetime: (value_1.Value.dynamicDatetime),
-                dynamicSelect: (value_1.Value.dynamicSelect),
-                dynamicMultiselect: (value_1.Value.dynamicMultiselect),
-                filteredUnion: (getDisabledFn, a, aVariants) => value_1.Value.filteredUnion(getDisabledFn, a, aVariants),
-                dynamicUnion: (getA, aVariants) => value_1.Value.dynamicUnion(getA, aVariants),
-            },
-            Variants: {
-                of: (a) => variants_1.Variants.of(a),
+                    exportUrl: (effects, options) => effects.plugin.url.exportUrl({
+                        hostnameInfo: options.hostnameInfo,
+                        removeAction: options.removeAction?.id ?? null,
+                        overflowActions: options.overflowActions.map((a) => a.id),
+                    }),
+                    setupExportedUrls: setupExportedUrls_1.setupExportedUrls, // similar to setupInterfaces
+                }),
             },
         };
     }
 }
 exports.StartSdk = StartSdk;
+/**
+ * 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
+ */
 async function runCommand(effects, image, command, options, name) {
     let commands;
-    if (command instanceof T.UseEntrypoint) {
+    if (T.isUseEntrypoint(command)) {
         const imageMeta = await fs
             .readFile(`/media/startos/images/${image.imageId}.json`, {
-            encoding: "utf8",
+            encoding: 'utf8',
         })
-            .catch(() => "{}")
+            .catch(() => '{}')
             .then(JSON.parse);
         commands = imageMeta.entrypoint ?? [];
         commands = commands.concat(...(command.overridCmd ?? imageMeta.cmd ?? []));
     }
     else
-        commands = (0, util_4.splitCommand)(command);
-    return SubContainer_1.SubContainer.withTemp(effects, image, options.mounts, name ||
+        commands = (0, util_1.splitCommand)(command);
+    return SubContainer_1.SubContainerOwned.withTemp(effects, image, options.mounts, name ||
         commands
             .map((c) => {
-            if (c.includes(" ")) {
+            if (c.includes(' ')) {
                 return `"${c.replace(/"/g, `\"`)}"`;
             }
             else {
                 return c;
             }
         })
-            .join(" "), async (subcontainer) => {
+            .join(' '), async (subcontainer) => {
         const res = await subcontainer.exec(commands);
         if (res.exitCode || res.exitSignal) {
             throw new SubContainer_1.ExitError(commands[0], res);