@krischoichoi/channel-control 0.6.0

package/lib/types.d.ts

@@ -0,0 +1,370 @@
+/**
+ * Public type surface of @krischoichoi/channel-control.
+ *
+ * These types define the stable boundary between the Channel Control Plane
+ * and every downstream consumer (channel adapters, the Web control plane in
+ * channel-web, and future provider auth helpers). Platform differences stop
+ * here: channel-control itself is adapter-agnostic and never branches on a
+ * specific channel id.
+ *
+ * Host-only types ([InternalAuthSession], [AuthProviderSession]) must never
+ * cross the browser boundary — see auth/sanitizer.ts for the public DTOs.
+ */
+import type { ChannelAccessPolicy, ChannelAdapter, ChannelHealth } from '@krischoichoi/channel-core';
+/** How a channel begins an authorization flow (doc §15). */
+export type AuthMethod = 'qr' | 'device' | 'portal-login' | 'credentials' | 'hybrid';
+/**
+ * Fine-grained progress of an auth flow (doc §15/§16). The UI switches on
+ * this value rather than parsing free-form [PublicAuthStatus.detail] text.
+ */
+export type AuthPhase = 'preparing' | 'waiting-scan' | 'scanned' | 'waiting-confirm' | 'verification-required' | 'credentials-required' | 'authorized' | 'expired' | 'failed' | 'cancelled';
+/** Coarse public auth state, kept M1-compatible (doc §15). */
+export type AuthState = 'pending' | 'authenticated' | 'expired' | 'failed';
+/**
+ * Structured QR payload (doc §17). Replaces the ambiguous bare string:
+ * a value is either opaque content to render, a ready-made data URL, or an
+ * external URL to open.
+ */
+export interface PublicQrPayload {
+    kind: 'content' | 'data-url' | 'external-url';
+    value: string;
+    expiresAt?: number;
+}
+/** Structured user-facing prompt associated with a phase (doc §16). */
+export interface PublicAuthPrompt {
+    kind: 'verification-code' | 'confirm-on-phone' | 'credentials-required' | 'open-browser';
+    message?: string;
+}
+/** Public auth status returned by polling (doc §16). */
+export interface PublicAuthStatus {
+    state: AuthState;
+    phase: AuthPhase;
+    prompt?: PublicAuthPrompt;
+    expiresAt?: number;
+    detail?: string;
+}
+/**
+ * Browser-facing session (doc §18). It NEVER contains secrets, tokens, the
+ * provider challenge or any provider payload. Build it exclusively through
+ * auth/sanitizer.ts.
+ */
+export interface PublicAuthSession {
+    id: string;
+    channelId: string;
+    state: AuthState;
+    phase: AuthPhase;
+    qr?: PublicQrPayload;
+    expiresAt?: number;
+    prompt?: PublicAuthPrompt;
+    /**
+     * Safe provider polling interval (ms) the browser may use to space its own
+     * client polls (doc §15). NOT a secret: it is the provider's declared
+     * throttle and the host already enforces the same bound server-side via
+     * `nextPollAt`. Omitted unless the provider declared one (> 0).
+     */
+    pollingIntervalMs?: number;
+}
+/**
+ * Host-only full session (doc §18). Holds the AbortController and opaque
+ * provider state. Must never be serialized to the browser.
+ */
+export interface InternalAuthSession {
+    id: string;
+    channelId: string;
+    accountId: string;
+    provider: string;
+    createdAt: number;
+    expiresAt: number;
+    pollingIntervalMs: number;
+    nextPollAt: number;
+    deviceCode?: string;
+    challenge?: unknown;
+    abortController: AbortController;
+    providerState: unknown;
+}
+/** Input that begins an auth flow (doc §14/§19). */
+export interface AuthBeginInput {
+    method: AuthMethod;
+    accountId?: string;
+}
+/**
+ * What a definition's [ChannelDefinition.beginAuth] returns (doc §14/§19).
+ * Provider-specific and host-only. [providerState] is opaque and handed back
+ * verbatim to [ChannelDefinition.pollAuth] / [ChannelDefinition.submitAuthInput].
+ */
+export interface AuthProviderSession {
+    provider: string;
+    expiresAt: number;
+    pollingIntervalMs: number;
+    qr?: PublicQrPayload;
+    prompt?: PublicAuthPrompt;
+    deviceCode?: string;
+    /** Opaque provider state; pollAuth/submitAuthInput receive this object back. */
+    providerState: unknown;
+}
+/** Auth input submitted during a flow (e.g. a verification code). */
+export interface AuthInput {
+    kind: 'verification-code';
+    value: string;
+}
+/** One selectable setup field of a channel (doc §29). */
+export interface ChannelSetupField {
+    name: string;
+    kind: 'text' | 'secret';
+    secret: boolean;
+    configured: boolean;
+    writable: boolean;
+    /**
+     * Credential reference name for secret fields (doc §31). The web layer
+     * never sees this — the control plane maps a field name to its ref and
+     * calls ctx.credentials. Non-secret fields omit it.
+     */
+    ref?: string;
+    /**
+     * Current value for NON-secret fields only (doc §29). Populated dynamically
+     * by ChannelControlService.getSetup from ConfiguredState; secret fields never
+     * carry it, and static definition.setup.fields leave it undefined.
+     */
+    value?: string;
+}
+/** Static setup descriptor advertising a channel's editable surface (doc §29). */
+export interface ChannelSetupDescriptor {
+    fields: ChannelSetupField[];
+    authMethods: AuthMethod[];
+    /** Optional official console where users obtain the required credentials. */
+    setupUrl?: string;
+}
+/** One-shot setup payload used by the Web form. Secret values stay host-side. */
+export interface ChannelSetupInput {
+    config: Record<string, unknown>;
+    credentials: Record<string, string>;
+    /**
+     * Whether a successful save immediately reconciles the channel runtime.
+     * Defaults to true. Interactive authorization can persist prerequisite
+     * credentials first, then start the provider auth flow without mounting an
+     * adapter that is not authorized yet.
+     */
+    reconcile?: boolean;
+}
+/** Result of saving setup and reconciling the channel runtime. */
+export interface ChannelSetupResult {
+    configured: boolean;
+    connection: ChannelRuntimeStatus['connection'];
+}
+/**
+ * Dynamic configured state: never returns secret values (doc §14/§29).
+ * Per-field `value` carries non-secret config values only (e.g. appId/clientId);
+ * secret fields never set it.
+ */
+export interface ConfiguredState {
+    configured: boolean;
+    fields: Record<string, {
+        configured: boolean;
+        writable: boolean;
+        source?: string;
+        value?: string;
+    }>;
+}
+/**
+ * Runtime status of one mounted (or not) channel (doc §60 / ChannelSummary).
+ */
+export interface ChannelRuntimeStatus {
+    mounted: boolean;
+    running: boolean;
+    connection: 'connected' | 'degraded' | 'disconnected' | 'unknown';
+    health?: ChannelHealth | null;
+    lastError?: string | null;
+}
+/**
+ * How a channel determines its local operator / owner identity.
+ * - `account`: the domain account is identified up front (e.g. Weixin's
+ *   scanning QR userId); owner is bootstrapped automatically.
+ * - `claim`: no upfront identity; the owner identifies themselves via the
+ *   reserved `/dsh-claim` flow.
+ * - `manual`: the owner is assigned manually by the operator.
+ * - `platform`: the platform restricts private messages to the bot creator;
+ *   no local owner claim is needed.
+ */
+export type OwnerDiscoveryMode = 'account' | 'claim' | 'manual' | 'platform';
+/**
+ * Declared access capability of a channel. Adapters publish it; the
+ * control plane and harness use it to decide what a policy may express and
+ * whether owner bootstrap applies.
+ */
+export interface ChannelAccessDescriptor {
+    directMessages: boolean;
+    groups: boolean;
+    mentions: boolean;
+    ownerDiscovery: OwnerDiscoveryMode;
+    identityLabels: {
+        user: string;
+        group?: string;
+    };
+    defaults?: {
+        requireMention?: boolean;
+    };
+    /**
+     * Conversation identity presentation metadata (generic — the Web renders
+     * from this, never from per-channel conditionals). Declared by channels
+     * whose adapters expose a discovered conversation identity list (e.g. QQ
+     * group_openid).
+     */
+    identity?: {
+        conversation?: {
+            /** Label for an optional human-facing id when the platform provides one. */
+            externalIdLabel?: string;
+            /**
+             * True when the Web must select groups from the conversation directory
+             * rather than accept a typed identity.
+             */
+            conversationDiscoverable?: boolean;
+        };
+    };
+}
+/**
+ * High-level access state of a channel, surfaced to the Web control
+ * plane so an operator can see at a glance why inbound is gated.
+ */
+export type ChannelAccessReadiness = 'ready' | 'needs-owner' | 'missing-policy' | 'invalid-policy';
+/**
+ * Full access picture for one channel+account. The `policy` carries
+ * canonical sender/group IDs — never any secret — because these are exactly what
+ * the operator edits in the ACL.
+ */
+export interface ChannelAccessState {
+    descriptor: ChannelAccessDescriptor;
+    readiness: ChannelAccessReadiness;
+    policy?: ChannelAccessPolicy;
+    owner: {
+        configured: boolean;
+        id?: string;
+        source?: 'account' | 'claim' | 'manual' | 'platform';
+    };
+}
+/**
+ * Lifecycle phase of a local owner-claim session.
+ * - `waiting-message`: a challenge is outstanding; no valid candidate yet.
+ * - `candidate`: a valid DM reply carried the exact challenge code.
+ * - `confirmed`: the local operator confirmed the candidate (owner persisted).
+ * - `expired`: TTL passed before confirmation.
+ * - `cancelled`: the local operator cancelled the session.
+ */
+export type OwnerClaimPhase = 'waiting-message' | 'candidate' | 'confirmed' | 'expired' | 'cancelled';
+/**
+ * Browser-facing owner-claim session. This is the ONLY claim DTO
+ * surfaced outside the host. `challengeCode` is a short one-time challenge the
+ * local browser shows the operator who then sends it to the bot; it is NOT a
+ * platform credential and must never be logged.
+ */
+export interface PublicOwnerClaimSession {
+    id: string;
+    channelId: string;
+    accountId: string;
+    phase: OwnerClaimPhase;
+    /** Short one-time challenge the local browser shows the operator. NOT a credential. */
+    challengeCode?: string;
+    expiresAt: number;
+    candidate?: {
+        senderId: string;
+    };
+}
+/**
+ * Sanitized conversation identity row surfaced to the Web (plan §35). This is
+ * display/mapping metadata ONLY: `canonicalId` is the authorization key the
+ * policy stores; `externalId`/`displayName` are optional human-facing metadata
+ * and must never be written into a policy or consumed by the Access Gate.
+ */
+export interface PublicConversationIdentity {
+    type: 'group';
+    canonicalId: string;
+    externalId?: string;
+    displayName?: string;
+    alias?: string;
+    /** The platform identity for this conversation changed at some point (plan §23). */
+    identityConflict?: boolean;
+    firstSeenAt: number;
+    lastSeenAt: number;
+}
+/** Row returned by [ChannelControlService.listChannels] (doc §29). */
+export interface ChannelSummary {
+    id: string;
+    configured: boolean;
+    enabled: boolean;
+    mounted: boolean;
+    runtime: 'running' | 'stopped';
+    connection: 'connected' | 'degraded' | 'disconnected' | 'unknown';
+    /** Access readiness of the channel. */
+    access: ChannelAccessReadiness;
+}
+/**
+ * One channel's setup/authorization/instantiation spec (doc §14). Platform
+ * differences stop here: channel-control drives channels purely through this
+ * interface, never through per-channel conditionals.
+ */
+export interface ChannelDefinition {
+    id: string;
+    /**
+     * Whether the channel is enabled in configuration (doc §29 ChannelSummary.enabled).
+     *
+     * Implementations MUST expose this as a live getter over their mutable
+     * config snapshot (e.g. `get enabled() { return state.enabled }`), never as
+     * a registration-time snapshot — the control plane's `setEnabled` reads it
+     * again after persisting a change.
+     */
+    readonly enabled: boolean;
+    /**
+     * Persist the enabled intent (doc §21). Implementations mutate their
+     * config snapshot and push through their durable store (settings scope /
+     * credentials seam). The control plane reacts by stopping the runtime when
+     * disabled or starting it when re-enabled (doc §22). Optional for
+     * definitions that are permanently enabled.
+     */
+    setEnabled?(enabled: boolean): Promise<void>;
+    /** Static setup descriptor (fields + authMethods). */
+    setup: ChannelSetupDescriptor;
+    /**
+     * Dynamic configured state: reads config + credential describe().
+     * NEVER returns secret values.
+     */
+    getConfiguredState(): Promise<ConfiguredState>;
+    /**
+     * Persist a non-secret config patch. Secret field names are rejected by the
+     * control plane before reaching the definition (see saveConfig rules).
+     */
+    saveConfig(patch: Record<string, unknown>): Promise<void>;
+    /**
+     * Optional opaque, non-secret fingerprint for the active provider/application
+     * scope. Conversation-directory entries are partitioned by this value so a
+     * human-facing identifier observed under one Bot/App cannot be resolved
+     * after that provider scope changes. It is control-plane bookkeeping only:
+     * never returned to the Web and never used for authorization.
+     */
+    conversationScopeFingerprint?(accountId: string): string | undefined;
+    /**
+     * Optional host-only snapshot/restore hooks for transactional setup updates.
+     * Definitions with mutable config implement both methods so a failed adapter
+     * restart can restore the exact prior runtime configuration.
+     */
+    snapshotConfig?(): unknown;
+    restoreConfig?(snapshot: unknown): Promise<void> | void;
+    /** Begin an auth session (optional: channels without provider auth omit). */
+    beginAuth?(input: AuthBeginInput): Promise<AuthProviderSession>;
+    /** Poll a provider session (optional). Receives the SAME AuthProviderSession returned by beginAuth. */
+    pollAuth?(session: AuthProviderSession): Promise<PublicAuthStatus>;
+    /** Submit auth input (verification code etc.) (optional). */
+    submitAuthInput?(session: AuthProviderSession, input: AuthInput): Promise<PublicAuthStatus> | void;
+    /** Build the adapter; resolves credentials itself via the injected credentials seam. */
+    createAdapter(): Promise<ChannelAdapter>;
+    /** Whether this channel should auto-mount when configured (headless, doc §27). Default true. */
+    autoStart?: boolean;
+    /** Required: declared access capability descriptor. */
+    access: ChannelAccessDescriptor;
+    /**
+     * Only implemented by ownerDiscovery='account' channels. Returns the canonical
+     * sender.id of the account owner (e.g. Weixin's scanning QR userId). Never
+     * exposes platform storage format to the control plane.
+     */
+    resolveOwnerIdentity?(accountId: string): Promise<string | undefined>;
+}
+export type { ChannelAdapter, ChannelHealth };
+//# sourceMappingURL=types.d.ts.map

package/lib/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/lib/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/lib/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/lib/update-check.d.ts

@@ -0,0 +1,128 @@
+import type { ChannelStorage } from '@krischoichoi/channel-core';
+/** The bundle package users install (checked on the npm registry). */
+export declare const BUNDLE_PACKAGE = "@krischoichoi/dsh-channels";
+/** Dist-tags consulted by the check (in priority order). */
+export type BundleDistTag = 'latest' | 'next';
+/** Registry fetch timeout (mirrors scripts/check-upstream.mjs). */
+export declare const FETCH_TIMEOUT_MS = 15000;
+/** Durable cache key (versioned so future format changes invalidate old rows). */
+export declare const UPDATE_CHECK_STORAGE_KEY = "update-check:v1";
+/**
+ * The installed bundle version. By release convention every runtime-family
+ * package (the bundle + its ten dependencies, see docs/release.md) moves in
+ * lockstep — each changeset lists the whole family and every package.json
+ * carries the same version — so this package's own version IS the installed
+ * `@krischoichoi/dsh-channels` version. Keep the family lockstep when bumping;
+ * `test/update-check.test.ts` asserts this package's version equals the
+ * bundle's.
+ */
+export declare const BUNDLE_VERSION: string;
+/** One upgrade command, plus the hint metadata the UI/command plane renders. */
+export interface BundleUpdateInfo {
+    /** Target version string, e.g. "0.6.0". */
+    version: string;
+    /** Which dist-tag provided the target. */
+    tag: BundleDistTag;
+    /** Target sits on a different major.minor line than the installed bundle. */
+    crossLine: boolean;
+    /** Advisory upgrade commands in execution order. Nothing is auto-installed. */
+    commands: string[];
+}
+/** Sanitized, read-only DTO served to channel-web and the /version command. */
+export interface BundleUpdateStatus {
+    /** Installed @krischoichoi/dsh-channels version (workspace lockstep version). */
+    currentVersion: string;
+    /** Present only when a strictly newer version was found per the tag rules. */
+    update?: BundleUpdateInfo;
+    /** Epoch ms of the last completed registry check; absent before the first. */
+    checkedAt?: number;
+}
+/** Narrow logger seam (satisfied by a Cordis logger; kept structural). */
+export interface UpdateCheckLogger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+}
+export interface BundleUpdateCheckerOptions {
+    /** Installed bundle version; defaults to this package's lockstep version. */
+    currentVersion?: string;
+    /** Whether the check runs at all (config `updateCheck.enabled`). */
+    enabled: boolean;
+    /** Cache TTL in hours (config `updateCheck.intervalHours`). */
+    intervalHours: number;
+    /** Lazily resolved durable storage; absent → memory-only caching. */
+    getStorage?: () => ChannelStorage | undefined;
+    /** Logger for the single info line (update found) and debug diagnostics. */
+    logger?: UpdateCheckLogger;
+    /** Injectable clock (tests). */
+    now?: () => number;
+}
+export interface ParsedSemver {
+    major: number;
+    minor: number;
+    patch: number;
+    /** Dot-separated prerelease identifiers; null for a stable release. */
+    pre: string[] | null;
+}
+/** Parse a strict semver string, or undefined when malformed. */
+export declare function parseSemver(version: string): ParsedSemver | undefined;
+/** Whether a version string is a legal strict semver (with/without suffixes). */
+export declare function isSemverString(version: string): boolean;
+/**
+ * Full semver precedence compare. Build metadata is ignored. Callers must
+ * pre-validate inputs with parseSemver; an unparseable side compares equal
+ * (never greater), so a malformed value can never fabricate an update hint.
+ */
+export declare function compareSemver(a: string, b: string): number;
+/**
+ * Evaluate the prompt from dist-tag versions against the installed version.
+ * Pure function; malformed versions are ignored (they can never prompt).
+ */
+export declare function evaluateBundleUpdate(currentVersion: string, tags: {
+    latest?: string;
+    next?: string;
+}): BundleUpdateInfo | undefined;
+/**
+ * [BundleUpdateChecker] — TTL-cached, offline-tolerant npm dist-tag check.
+ * Never throws: every failure path (disabled, offline, timeout, schema
+ * rejection, storage error) degrades to "no update known".
+ */
+export declare class BundleUpdateChecker {
+    private readonly currentVersion;
+    private readonly enabled;
+    private readonly intervalMs;
+    private readonly getStorage;
+    private readonly logger;
+    private readonly now;
+    /** In-memory snapshot so a process reads storage at most once per cache. */
+    private memory;
+    private inflight;
+    constructor(options: BundleUpdateCheckerOptions);
+    /**
+     * Fire-and-forget check (startup hook). Re-entrant: concurrent callers share
+     * one in-flight promise; a fresh cache short-circuits without fetching.
+     * Never rejects — callers may `void` it safely.
+     */
+    trigger(): Promise<void>;
+    /**
+     * Read-only status for the web control plane / /version command. Returns
+     * immediately with the cached snapshot (storage-backed when the process has
+     * not checked yet) and kicks a background refresh when the cache is stale
+     * or absent — a first request never blocks on the registry.
+     */
+    getStatus(): Promise<BundleUpdateStatus>;
+    private runCheck;
+    private isFresh;
+    private toStatus;
+    /**
+     * Fetch the `latest` and `next` single-tag manifests in parallel. The next
+     * tag is optional (404 → absent); latest is required for a successful
+     * check. Any non-404 failure, and any zod rejection, throws so the whole
+     * check is treated as offline (no partially-trusted snapshot is kept).
+     */
+    private fetchDistTags;
+    /** One tag manifest → its version. 404 → undefined (tag not published). */
+    private fetchManifestVersion;
+    private loadStored;
+    private persist;
+}
+//# sourceMappingURL=update-check.d.ts.map

package/lib/update-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-check.d.ts","sourceRoot":"","sources":["../src/update-check.ts"],"names":[],"mappings":"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"}