@camstack/types 1.2.310 → 1.2.312

package/dist/capabilities/hub-address.d.ts

@@ -8,44 +8,48 @@
  * and knows its tunnel and mesh names — every input the automatic answer
  * needs. A variable that restated it could only drift from it.
  *
- * ## Roles
+ * ## Roles (D734)
  *
  * An address — a DETECTED endpoint or an operator-entered CUSTOM address —
  * carries role flags, the same way for both:
  *
- * - `viewer` (many) — what the apps race and connect to. Automatic: every
- *   LAN IPv4 address plus the public tunnel.
- * - `notifications` (one) — where notification taps and links point.
- *   Automatic: the CamStack app link (D709).
- * - `agents` (one) — what agents and LAN devices pull from (addon bundles,
- *   models, a camera relay's broker host). Automatic: a LAN IPv4 literal,
- *   then any plausible LAN address, then the mesh. Never a public tunnel: it
- *   is a detour off the LAN for traffic that never left it.
- * - `signIn` (one) — sign-in links, OIDC callbacks, the passkey relying
- *   party, OAuth2's hub URL. Automatic: the public tunnel, then the mesh, then
- *   the LAN.
+ * - `appConnections` (many) — what the CamStack apps try when connecting.
+ *   Automatic: every LAN IPv4 address plus the public tunnel.
+ * - `notificationTaps` (one) — ONLY where tapping a notification opens.
+ *   Automatic: the CamStack app link (D709); a hub address may be flagged.
+ * - `publicEndpoint` (one) — every URL that must work from OUTSIDE the home
+ *   network: sign-in links, OIDC / OAuth2 callbacks, the passkey relying
+ *   party, account linking, and the notification centre's action buttons,
+ *   attachment / media links and admin links. Automatic: the public tunnel,
+ *   then the mesh, then the LAN. Never the app link.
+ * - `internal` (one) — what agents and LAN devices download from (addon
+ *   bundles, models, a camera relay's broker host, Home Assistant media).
+ *   Automatic: a LAN IPv4 literal, then any plausible LAN address, then the
+ *   mesh. Never a public tunnel: it is a detour off the LAN for traffic that
+ *   never left it.
  *
  * A single-valued role is stored as ONE URL, so "at most one address carries
  * it" holds by construction, not by a check. A flag wins outright; no flag is
  * automatic. Automatic picks only among DETECTED endpoints — a custom address
  * serves exactly the roles it is flagged with. Loopback and the app link are
- * never an agents or sign-in answer: loopback names whoever dials it, and the
- * app link is not a hub address. `null` means nothing qualifies — the caller
- * must say so rather than substitute `127.0.0.1`.
+ * never an internal or public-endpoint answer: loopback names whoever dials
+ * it, and the app link is not a hub address. `null` means nothing qualifies —
+ * the caller must say so rather than substitute `127.0.0.1`.
  */
-import type { ConnectionEndpoint } from './local-network.cap.js';
-export declare const HUB_ADDRESS_ROLES: readonly ["viewer", "notifications", "agents", "signIn"];
-export type HubAddressRole = (typeof HUB_ADDRESS_ROLES)[number];
+import type { z } from 'zod';
+import type { ConnectionEndpoint, HubAddressRoleSchema } from './local-network.cap.js';
+export declare const HUB_ADDRESS_ROLES: readonly ["appConnections", "notificationTaps", "internal", "publicEndpoint"];
+export type HubAddressRole = z.infer<typeof HubAddressRoleSchema>;
 /** The roles at most one address carries. */
-export type SingleHubAddressRole = Exclude<HubAddressRole, 'viewer'>;
+export type SingleHubAddressRole = Exclude<HubAddressRole, 'appConnections'>;
 export declare const SINGLE_HUB_ADDRESS_ROLES: readonly SingleHubAddressRole[];
 export declare function isSingleHubAddressRole(role: HubAddressRole): role is SingleHubAddressRole;
 /** The operator's role flags, as stored. `null` / `[]` = automatic. */
 export interface HubAddressFlags {
-    readonly viewer: readonly string[];
-    readonly notifications: string | null;
-    readonly agents: string | null;
-    readonly signIn: string | null;
+    readonly appConnections: readonly string[];
+    readonly notificationTaps: string | null;
+    readonly internal: string | null;
+    readonly publicEndpoint: string | null;
 }
 export declare const AUTOMATIC_HUB_ADDRESS_FLAGS: HubAddressFlags;
 export type HubAddressCheck = {
@@ -61,14 +65,14 @@ export type HubAddressCheck = {
  * Answers the normalised origin (`scheme://host[:port]`).
  */
 export declare function validateCustomAddress(raw: string): HubAddressCheck;
-/** The reason a plain-http sign-in address is refused unless accepted. */
-export declare const SIGN_IN_HTTP_REASON = "Sign-in needs an https:// address: passkeys and most identity providers refuse a plain-http origin. Accept http only for a sign-in that never leaves your own network.";
+/** The reason a plain-http public endpoint is refused unless accepted. */
+export declare const PUBLIC_ENDPOINT_HTTP_REASON = "The public endpoint needs an https:// address: passkeys and most identity providers refuse a plain-http origin. Accept http only when sign-in and notification links never leave your own network.";
 /**
  * May `baseUrl` carry `role`? The address check above, plus two role rules:
- * the app link carries `notifications` only (it is not a hub address), and a
- * plain-http address carries `signIn` only when the operator explicitly
- * accepted it (`acceptInsecureHttp`) — a LAN-only password or magic-link
- * sign-in works over http, a passkey or an OIDC callback does not.
+ * the app link carries `notificationTaps` only (it is not a hub address), and
+ * a plain-http address carries `publicEndpoint` only when the operator
+ * explicitly accepted it (`acceptInsecureHttp`) — a LAN-only password or
+ * magic-link sign-in works over http, a passkey or an OIDC callback does not.
  */
 export declare function checkRoleAddress(role: HubAddressRole, baseUrl: string, options?: {
     readonly acceptInsecureHttp?: boolean;
@@ -82,42 +86,47 @@ export interface HubAddressRoleResolution {
     readonly resolved: string | null;
     readonly source: HubAddressSource;
 }
-export interface HubViewerResolution {
-    /** The addresses flagged `viewer`, or empty for automatic. */
+export interface HubAppConnectionsResolution {
+    /** The addresses flagged `appConnections`, or empty for automatic. */
     readonly flagged: readonly string[];
     /** What the apps race right now (may be empty when nothing is up). */
     readonly resolved: readonly string[];
     readonly source: HubAddressSource;
 }
-/** `agents`: what agents and LAN devices pull from. */
-export declare function resolveAgentsAddress(endpoints: readonly ConnectionEndpoint[], flags: HubAddressFlags): HubAddressRoleResolution;
-/** `signIn`: sign-in links, OIDC callbacks, the relying party, OAuth2. */
-export declare function resolveSignInAddress(endpoints: readonly ConnectionEndpoint[], flags: HubAddressFlags): HubAddressRoleResolution;
-/** `notifications`: the flagged address, else the CamStack app link (D709). */
-export declare function resolveNotificationsAddress(flags: HubAddressFlags): HubAddressRoleResolution;
-/** AUTO viewer race: LAN IPv4 + the public tunnel. Never IPv6, mesh, loopback or custom. */
-export declare function isDefaultViewerEndpoint(endpoint: ConnectionEndpoint): boolean;
+/** `internal`: what agents and LAN devices download from. */
+export declare function resolveInternalAddress(endpoints: readonly ConnectionEndpoint[], flags: HubAddressFlags): HubAddressRoleResolution;
+/**
+ * `publicEndpoint`: every URL that must work off the LAN — sign-in links, OIDC
+ * / OAuth2 callbacks, the relying party, and notification buttons,
+ * attachments, media and admin links.
+ */
+export declare function resolvePublicEndpoint(endpoints: readonly ConnectionEndpoint[], flags: HubAddressFlags): HubAddressRoleResolution;
+/** `notificationTaps`: the flagged address, else the CamStack app link (D709). */
+export declare function resolveNotificationTapAddress(flags: HubAddressFlags): HubAddressRoleResolution;
+/** AUTO app connections: LAN IPv4 + the public tunnel. Never IPv6, mesh, loopback or custom. */
+export declare function isDefaultAppConnectionEndpoint(endpoint: ConnectionEndpoint): boolean;
 /**
  * The endpoints the apps race: the flagged ones that are in `endpoints`
- * (which carries the custom addresses flagged `viewer`), else AUTO. A flagged
+ * (which carries the custom addresses flagged `appConnections`), else AUTO. A flagged
  * set none of which is currently up falls back to AUTO rather than racing
  * nothing.
  */
-export declare function selectViewerEndpoints(endpoints: readonly ConnectionEndpoint[], flags: HubAddressFlags): ConnectionEndpoint[];
-/** `viewer`: what the apps race and connect to. */
-export declare function resolveViewerAddresses(endpoints: readonly ConnectionEndpoint[], flags: HubAddressFlags): HubViewerResolution;
+export declare function selectAppConnectionEndpoints(endpoints: readonly ConnectionEndpoint[], flags: HubAddressFlags): ConnectionEndpoint[];
+/** `appConnections`: what the apps try when connecting. */
+export declare function resolveAppConnections(endpoints: readonly ConnectionEndpoint[], flags: HubAddressFlags): HubAppConnectionsResolution;
 /** Every role's answer. */
 export interface HubAddressRoles {
-    readonly viewer: HubViewerResolution;
-    readonly notifications: HubAddressRoleResolution;
-    readonly agents: HubAddressRoleResolution;
-    readonly signIn: HubAddressRoleResolution;
+    readonly appConnections: HubAppConnectionsResolution;
+    readonly notificationTaps: HubAddressRoleResolution;
+    readonly internal: HubAddressRoleResolution;
+    readonly publicEndpoint: HubAddressRoleResolution;
 }
 /**
- * Every role at once, each through its own resolver. `viewerPalette` is what
- * the apps race (it carries the custom addresses flagged `viewer`);
- * `hubPalette` is the detected HTTPS palette agents and sign-in resolve over.
+ * Every role at once, each through its own resolver. `appPalette` is what
+ * the apps race (it carries the custom addresses flagged `appConnections`);
+ * `hubPalette` is the detected HTTPS palette `internal` and `publicEndpoint`
+ * resolve over.
  */
-export declare function resolveHubAddressRoles(viewerPalette: readonly ConnectionEndpoint[], hubPalette: readonly ConnectionEndpoint[], flags: HubAddressFlags): HubAddressRoles;
+export declare function resolveHubAddressRoles(appPalette: readonly ConnectionEndpoint[], hubPalette: readonly ConnectionEndpoint[], flags: HubAddressFlags): HubAddressRoles;
 /** The bare hostname of a base URL, or `null` when it does not parse. */
 export declare function hubAddressHostname(baseUrl: string | null): string | null;

package/dist/capabilities/index.d.ts

@@ -64,7 +64,7 @@ export { EMBEDDING_MODEL_FAILED, EMBEDDING_REQUIREMENTS_FAILED, EMBEDDING_REQUIR
 export type { FailureContribution, IFailureContributionProvider, } from './failure-contribution.cap.js';
 export { FailureContributionSchema, FailureReasonCountSchema, failureContributionCapability, } from './failure-contribution.cap.js';
 export { filesystemBrowseCapability, type IFilesystemBrowseProvider, } from './filesystem-browse.cap.js';
-export { AUTOMATIC_HUB_ADDRESS_FLAGS, checkRoleAddress, HUB_ADDRESS_ROLES, type HubAddressCheck, type HubAddressFlags, type HubAddressRole, type HubAddressRoleResolution, type HubAddressRoles, type HubAddressSource, type HubViewerResolution, hubAddressHostname, isDefaultViewerEndpoint, isSingleHubAddressRole, resolveAgentsAddress, resolveHubAddressRoles, resolveNotificationsAddress, resolveSignInAddress, resolveViewerAddresses, SIGN_IN_HTTP_REASON, SINGLE_HUB_ADDRESS_ROLES, type SingleHubAddressRole, selectViewerEndpoints, validateCustomAddress, } from './hub-address.js';
+export { AUTOMATIC_HUB_ADDRESS_FLAGS, checkRoleAddress, HUB_ADDRESS_ROLES, type HubAddressCheck, type HubAddressFlags, type HubAddressRole, type HubAddressRoleResolution, type HubAddressRoles, type HubAddressSource, type HubAppConnectionsResolution, hubAddressHostname, isDefaultAppConnectionEndpoint, isSingleHubAddressRole, PUBLIC_ENDPOINT_HTTP_REASON, resolveAppConnections, resolveHubAddressRoles, resolveInternalAddress, resolveNotificationTapAddress, resolvePublicEndpoint, SINGLE_HUB_ADDRESS_ROLES, type SingleHubAddressRole, selectAppConnectionEndpoints, validateCustomAddress, } from './hub-address.js';
 export { type HfModelResolution, HfModelResolutionSchema, type ILlmProvider, type LlmDefault, LlmDefaultSchema, type LlmDefaultSelector, LlmDefaultSelectorSchema, type LlmProfile, type LlmProfileKind, type LlmProfileKindDescriptor, LlmProfileKindDescriptorSchema, LlmProfileKindSchema, LlmProfileSchema, type LlmRuntimeNode, LlmRuntimeNodeSchema, type LlmUsageRollup, LlmUsageRollupSchema, llmCapability, type ManagedModelCatalogEntry, ManagedModelCatalogEntrySchema, } from './llm.cap.js';
 export { type AppleFmAvailability, AppleFmAvailabilitySchema, type AppleFmUnavailableReason, AppleFmUnavailableReasonSchema, type ILlmRuntimeProvider, type LlmDownloadProgress, LlmDownloadProgressSchema, type LlmNodeModel, LlmNodeModelSchema, type LlmRuntimeAppleCompleteInput, LlmRuntimeAppleCompleteInputSchema, type LlmRuntimeCancelInput, LlmRuntimeCancelInputSchema, type LlmRuntimeCompleteInput, LlmRuntimeCompleteInputSchema, type LlmRuntimeDiskUsage, LlmRuntimeDiskUsageSchema, type LlmRuntimeStatus, LlmRuntimeStatusSchema, llmRuntimeCapability, type ManagedModelExtraFile, ManagedModelExtraFileSchema, type ManagedModelRef, ManagedModelRefSchema, type ManagedRuntimeConfig, ManagedRuntimeConfigSchema, } from './llm-runtime.cap.js';
 export { type LlmErrorCode, LlmErrorCodeSchema, type LlmGenerateBaseInput, LlmGenerateBaseInputSchema, type LlmGenerateErr, LlmGenerateErrSchema, type LlmGenerateOk, LlmGenerateOkSchema, type LlmGenerateResult, LlmGenerateResultSchema, type LlmImage, LlmImageSchema, type LlmRefusalSource, LlmRefusalSourceSchema, type LlmRetryPolicy, LlmRetryPolicySchema, LlmTimeoutDefaults, type LlmUsage, LlmUsageSchema, } from './llm-shared.js';