sdk comments

sdk/base/lib/interfaces/setupInterfaces.ts

@@ -1,20 +1,84 @@
+/**
+ * @module setupInterfaces
+ *
+ * This module provides utilities for setting up network interfaces (service endpoints)
+ * that are exposed to users through the StartOS UI.
+ *
+ * Service interfaces are the clickable links users see to access your service's
+ * web UI, API endpoints, or peer-to-peer connections.
+ *
+ * @example
+ * ```typescript
+ * export const setInterfaces = sdk.setupInterfaces(async ({ effects }) => {
+ *   const webHost = sdk.MultiHost.of(effects, 'webui')
+ *   const webOrigin = await webHost.bindPort(8080, { protocol: 'http' })
+ *
+ *   await webOrigin.export([
+ *     sdk.ServiceInterfaceBuilder.of({
+ *       effects,
+ *       name: 'Web Interface',
+ *       id: 'webui',
+ *       description: 'Access the web dashboard',
+ *       type: 'ui',
+ *     })
+ *   ])
+ *
+ *   return [webOrigin]
+ * })
+ * ```
+ */
+
 import * as T from "../types"
 import { once } from "../util"
 import { AddressReceipt } from "./AddressReceipt"
 
+/** @internal Type brand for interface update receipt */
 declare const UpdateServiceInterfacesProof: unique symbol
+
+/**
+ * Receipt type proving that service interfaces have been updated.
+ * @internal
+ */
 export type UpdateServiceInterfacesReceipt = {
   [UpdateServiceInterfacesProof]: never
 }
 
+/** Array of address info arrays with receipts, representing all exported interfaces */
 export type ServiceInterfacesReceipt = Array<T.AddressInfo[] & AddressReceipt>
+
+/**
+ * Function type for setting up service interfaces.
+ * @typeParam Output - The specific receipt type returned
+ */
 export type SetServiceInterfaces<Output extends ServiceInterfacesReceipt> =
   (opts: { effects: T.Effects }) => Promise<Output>
+
+/** Function type for the init-compatible interface updater */
 export type UpdateServiceInterfaces = (effects: T.Effects) => Promise<null>
+
+/** Function type for the setupServiceInterfaces helper */
 export type SetupServiceInterfaces = <Output extends ServiceInterfacesReceipt>(
   fn: SetServiceInterfaces<Output>,
 ) => UpdateServiceInterfaces
+
+/**
+ * Constant indicating no interface changes are needed.
+ * Use this as a return value when interfaces don't need to be updated.
+ */
 export const NO_INTERFACE_CHANGES = {} as UpdateServiceInterfacesReceipt
+
+/**
+ * Creates an interface setup function for use in the initialization pipeline.
+ *
+ * **Note:** This is exposed via `sdk.setupInterfaces`. See the SDK documentation
+ * for full usage examples and parameter descriptions.
+ *
+ * Internally, this wrapper:
+ * - Tracks all bindings and interfaces created during setup
+ * - Automatically cleans up stale bindings/interfaces that weren't recreated
+ *
+ * @see sdk.setupInterfaces for usage documentation
+ */
 export const setupServiceInterfaces: SetupServiceInterfaces = <
   Output extends ServiceInterfacesReceipt,
 >(