@baukit/integrations-client 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Koss
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+# `@baukit/integrations-client`
+
+`@baukit/integrations-client` provides provider-neutral client behavior for integration settings:
+
+- a connection reducer with fixed states and actions;
+- an OAuth coordinator with persisted state checks and strict return URL validation; and
+- a typed provider registry built from product data.
+
+The package has no runtime dependencies. Its root entry does not import React, Expo, or browser
+globals.
+
+## Connection state
+
+Map the server's connection health before applying client events:
+
+```ts
+import { connectionStateFromServer, reduceConnectionState } from '@baukit/integrations-client';
+
+const state = connectionStateFromServer({
+  state: 'needs_reconnect',
+  diagnosticCode: 'authorization_revoked',
+  providerDiagnostic: upstreamError,
+});
+const connecting = reduceConnectionState(state, { type: 'connect_requested' });
+```
+
+`providerDiagnostic` is untrusted input and is always dropped. `diagnostic.code` accepts only a
+bounded snake_case code. Products map `status` and `availableActions` to their own localized copy.
+They must not render the diagnostic code.
+
+## OAuth sessions
+
+Create one coordinator with product-owned ports for storage, timers, nonce creation, and the web or
+native authorization runner. The coordinator saves the nonce before it opens the authorization URL.
+It returns `success`, `cancelled`, `timed_out`, `invalid_return`, or `storage_mismatch`.
+
+```ts
+import { OAuthSessionCoordinator, createReturnUrlValidator } from '@baukit/integrations-client';
+
+const coordinator = new OAuthSessionCoordinator({
+  storage,
+  clock,
+  timeoutMs: 15_000,
+  createStateNonce,
+  validateReturnUrl: createReturnUrlValidator({
+    origin: 'https://app.example',
+    paths: ['/settings/integrations/callback'],
+  }),
+  browser,
+  native,
+  redirect,
+});
+
+const outcome = await coordinator.authorize({
+  platform: 'web',
+  returnUrl: 'https://app.example/settings/integrations/callback',
+  createAuthorizationUrl: startConnection,
+});
+```
+
+On web, `browser.openPlaceholder` runs before any asynchronous work so a click can reserve the
+popup. If it returns `null`, the coordinator uses the injected redirect handler. After a full-page
+return, call `handleRedirect` with the current URL. Native products supply `native.run` and
+`native.cancel` using their auth-session library.
+
+The validator requires the exact configured origin and one exact allowlisted path. Callback checks
+reject lookalike origins, path prefixes, credentials in URLs, malformed URLs, and duplicate
+parameters.
+
+## Provider registry
+
+The product owns provider IDs, translation keys, and capabilities:
+
+```ts
+import { createProviderRegistry } from '@baukit/integrations-client';
+
+const providers = createProviderRegistry([
+  {
+    id: 'calendar',
+    labelKey: 'integrations.calendar',
+    capabilities: ['read_events'],
+    connection: state,
+  },
+] as const);
+```
+
+The registry copies caller-owned arrays, rejects duplicate IDs, and exposes each provider's current
+state and available actions. Persistence, provider OAuth parameters, identity, copy, and policy stay
+in the product.

package/dist/connection-health.d.ts

@@ -0,0 +1,44 @@
+export type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'needs_reconnect' | 'disconnecting' | 'revocation_pending' | 'error';
+export type ConnectionAction = 'connect' | 'reconnect' | 'disconnect' | 'retry';
+export type ConnectionOperation = 'connect' | 'reconnect' | 'disconnect';
+export type ServerConnectionState = 'disconnected' | 'active' | 'connected' | 'healthy' | 'degraded' | 'needs_reconnect' | 'failed' | 'revoked' | 'pending_revocation';
+export interface ConnectionDiagnostic {
+    readonly code: string;
+    readonly source: 'client' | 'server';
+}
+export interface ConnectionState {
+    readonly status: ConnectionStatus;
+    readonly availableActions: readonly ConnectionAction[];
+    readonly diagnostic?: ConnectionDiagnostic;
+    readonly operation?: ConnectionOperation;
+}
+export interface ServerConnectionSnapshot {
+    readonly state: ServerConnectionState;
+    readonly diagnosticCode?: string | null;
+    readonly providerDiagnostic?: unknown;
+}
+export type ConnectionEvent = {
+    readonly type: 'server_state';
+    readonly snapshot: ServerConnectionSnapshot;
+} | {
+    readonly type: 'connect_requested';
+} | {
+    readonly type: 'auth_started';
+} | {
+    readonly type: 'auth_returned';
+} | {
+    readonly type: 'auth_cancelled';
+} | {
+    readonly type: 'auth_timed_out';
+    readonly diagnosticCode?: string;
+} | {
+    readonly type: 'disconnect_requested';
+} | {
+    readonly type: 'revocation_pending';
+    readonly diagnosticCode?: string;
+} | {
+    readonly type: 'retry';
+};
+export declare function connectionStateFromServer(snapshot: ServerConnectionSnapshot): ConnectionState;
+export declare function reduceConnectionState(state: ConnectionState, event: ConnectionEvent): ConnectionState;
+//# sourceMappingURL=connection-health.d.ts.map

package/dist/connection-health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-health.d.ts","sourceRoot":"","sources":["../src/connection-health.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GACxB,cAAc,GACd,YAAY,GACZ,WAAW,GACX,iBAAiB,GACjB,eAAe,GACf,oBAAoB,GACpB,OAAO,CAAC;AAEZ,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,WAAW,GAAG,YAAY,GAAG,OAAO,CAAC;AAEhF,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,WAAW,GAAG,YAAY,CAAC;AAEzE,MAAM,MAAM,qBAAqB,GAC7B,cAAc,GACd,QAAQ,GACR,WAAW,GACX,SAAS,GACT,UAAU,GACV,iBAAiB,GACjB,QAAQ,GACR,SAAS,GACT,oBAAoB,CAAC;AAEzB,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,CAAC;CACtC;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,gBAAgB,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACvD,QAAQ,CAAC,UAAU,CAAC,EAAE,oBAAoB,CAAC;IAC3C,QAAQ,CAAC,SAAS,CAAC,EAAE,mBAAmB,CAAC;CAC1C;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,KAAK,EAAE,qBAAqB,CAAC;IACtC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;CACvC;AAED,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,wBAAwB,CAAA;CAAE,GAC9E;IAAE,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAA;CAAE,GACtC;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;CAAE,GACjC;IAAE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;CAAE,GAClC;IAAE,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAA;CAAE,GACnC;IAAE,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,GACrE;IAAE,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAA;CAAE,GACzC;IAAE,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,GACzE;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAe/B,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,wBAAwB,GAAG,eAAe,CAkB7F;AAED,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,eAAe,EACtB,KAAK,EAAE,eAAe,GACrB,eAAe,CA2CjB"}

package/dist/connection-health.js

@@ -0,0 +1,100 @@
+const MAX_DIAGNOSTIC_CODE_LENGTH = 128;
+const DIAGNOSTIC_CODE_PATTERN = /^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$/;
+const ACTIONS = {
+    disconnected: ['connect'],
+    connecting: [],
+    connected: ['disconnect'],
+    needs_reconnect: ['reconnect'],
+    disconnecting: [],
+    revocation_pending: ['retry'],
+    error: ['retry'],
+};
+export function connectionStateFromServer(snapshot) {
+    const diagnostic = serverDiagnostic(snapshot.diagnosticCode);
+    switch (snapshot.state) {
+        case 'active':
+        case 'connected':
+        case 'healthy':
+            return makeConnectionState('connected');
+        case 'needs_reconnect':
+        case 'revoked':
+            return makeConnectionState('needs_reconnect', { diagnostic, operation: 'reconnect' });
+        case 'degraded':
+        case 'failed':
+            return makeConnectionState('error', { diagnostic, operation: 'reconnect' });
+        case 'pending_revocation':
+            return makeConnectionState('revocation_pending', { diagnostic, operation: 'disconnect' });
+        case 'disconnected':
+            return makeConnectionState('disconnected');
+    }
+}
+export function reduceConnectionState(state, event) {
+    switch (event.type) {
+        case 'server_state':
+            return connectionStateFromServer(event.snapshot);
+        case 'connect_requested': {
+            const action = state.status === 'needs_reconnect' ? 'reconnect' : 'connect';
+            if (!state.availableActions.includes(action))
+                return state;
+            return makeConnectionState('connecting', { operation: action });
+        }
+        case 'auth_started':
+            return state.status === 'connecting'
+                ? state
+                : makeConnectionState('connecting', {
+                    operation: state.status === 'needs_reconnect' ? 'reconnect' : 'connect',
+                });
+        case 'auth_returned':
+            return makeConnectionState('connected');
+        case 'auth_cancelled':
+            return state.operation === 'reconnect'
+                ? makeConnectionState('needs_reconnect', { operation: 'reconnect' })
+                : makeConnectionState('disconnected');
+        case 'auth_timed_out':
+            return makeConnectionState('error', {
+                diagnostic: clientDiagnostic(event.diagnosticCode ?? 'oauth_timed_out'),
+                operation: state.operation === 'reconnect' ? 'reconnect' : 'connect',
+            });
+        case 'disconnect_requested':
+            return state.availableActions.includes('disconnect')
+                ? makeConnectionState('disconnecting', { operation: 'disconnect' })
+                : state;
+        case 'revocation_pending':
+            return makeConnectionState('revocation_pending', {
+                diagnostic: clientDiagnostic(event.diagnosticCode ?? 'revocation_pending'),
+                operation: 'disconnect',
+            });
+        case 'retry':
+            if (!state.availableActions.includes('retry'))
+                return state;
+            return state.operation === 'disconnect'
+                ? makeConnectionState('disconnecting', { operation: 'disconnect' })
+                : makeConnectionState('connecting', {
+                    operation: state.operation === 'reconnect' ? 'reconnect' : 'connect',
+                });
+    }
+}
+function makeConnectionState(status, options = {}) {
+    return {
+        status,
+        availableActions: ACTIONS[status],
+        ...(options.diagnostic === undefined ? {} : { diagnostic: options.diagnostic }),
+        ...(options.operation === undefined ? {} : { operation: options.operation }),
+    };
+}
+function serverDiagnostic(code) {
+    return diagnostic(code, 'server');
+}
+function clientDiagnostic(code) {
+    return diagnostic(code, 'client');
+}
+function diagnostic(code, source) {
+    if (code === null ||
+        code === undefined ||
+        code.length > MAX_DIAGNOSTIC_CODE_LENGTH ||
+        !DIAGNOSTIC_CODE_PATTERN.test(code)) {
+        return undefined;
+    }
+    return { code, source };
+}
+//# sourceMappingURL=connection-health.js.map

package/dist/connection-health.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './connection-health.js';
+export * from './oauth-session.js';
+export * from './provider-registry.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from './connection-health.js';
+export * from './oauth-session.js';
+export * from './provider-registry.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC"}

package/dist/oauth-session.d.ts

@@ -0,0 +1,98 @@
+export interface OAuthInFlightSession {
+    readonly stateNonce: string;
+    readonly returnUrl: string;
+    readonly createdAt: number;
+}
+export interface OAuthSessionStorage {
+    load(): Promise<OAuthInFlightSession | null>;
+    save(session: OAuthInFlightSession): Promise<void>;
+    clear(): Promise<void>;
+}
+export interface OAuthClock {
+    now(): number;
+    setTimeout(callback: () => void, timeoutMs: number): unknown;
+    clearTimeout(handle: unknown): void;
+}
+export type OAuthSessionResult = {
+    readonly type: 'success';
+    readonly returnUrl: string;
+} | {
+    readonly type: 'cancelled';
+};
+export interface BrowserPopupSession {
+    readonly result: Promise<OAuthSessionResult>;
+    navigate(authorizationUrl: string): void;
+    close(): void;
+}
+export interface BrowserPopupOpener {
+    openPlaceholder(input: {
+        readonly placeholderUrl: string;
+        readonly returnUrl: string;
+        readonly windowName: string;
+    }): BrowserPopupSession | null;
+}
+export interface NativeAuthSessionRunner {
+    run(input: {
+        readonly authorizationUrl: string;
+        readonly returnUrl: string;
+    }): Promise<OAuthSessionResult>;
+    cancel(): void;
+}
+export interface OAuthRedirectHandler {
+    authorize(input: {
+        readonly authorizationUrl: string;
+        readonly returnUrl: string;
+    }): Promise<OAuthSessionResult>;
+}
+export interface OAuthReturnUrlPolicy {
+    readonly origin: string;
+    readonly paths: readonly string[];
+}
+export type OAuthReturnUrlValidator = (returnUrl: string) => boolean;
+export type OAuthSessionOutcome = {
+    readonly type: 'success';
+    readonly callbackParams: Readonly<Record<string, string>>;
+} | {
+    readonly type: 'cancelled';
+} | {
+    readonly type: 'timed_out';
+} | {
+    readonly type: 'invalid_return';
+} | {
+    readonly type: 'storage_mismatch';
+};
+export interface OAuthSessionCoordinatorOptions {
+    readonly storage: OAuthSessionStorage;
+    readonly clock: OAuthClock;
+    readonly timeoutMs: number;
+    readonly createStateNonce: () => string;
+    readonly validateReturnUrl: OAuthReturnUrlValidator;
+    readonly browser?: BrowserPopupOpener;
+    readonly native?: NativeAuthSessionRunner;
+    readonly redirect?: OAuthRedirectHandler;
+    readonly placeholderUrl?: string;
+    readonly windowName?: string;
+}
+export interface OAuthAuthorizationRequest {
+    readonly platform: 'web' | 'native';
+    readonly returnUrl: string;
+    readonly createAuthorizationUrl: (input: {
+        readonly stateNonce: string;
+        readonly returnUrl: string;
+    }) => Promise<string>;
+}
+export declare class OAuthSessionCoordinator {
+    #private;
+    constructor(options: OAuthSessionCoordinatorOptions);
+    authorize(request: OAuthAuthorizationRequest): Promise<OAuthSessionOutcome>;
+    handleRedirect(returnUrl: string): Promise<OAuthSessionOutcome>;
+    discardStaleSession(): Promise<boolean>;
+    private openBrowserPopup;
+    private performAuthorization;
+    private completeReturn;
+    private isStale;
+    private clearIfCurrent;
+    private withTimeout;
+}
+export declare function createReturnUrlValidator(policy: OAuthReturnUrlPolicy): OAuthReturnUrlValidator;
+//# sourceMappingURL=oauth-session.d.ts.map

package/dist/oauth-session.d.ts.map

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

package/dist/oauth-session.js

@@ -0,0 +1,204 @@
+const DEFAULT_PLACEHOLDER_URL = 'about:blank';
+const DEFAULT_WINDOW_NAME = 'baukit-integration-oauth';
+const TIMED_OUT = Symbol('timed_out');
+export class OAuthSessionCoordinator {
+    #options;
+    constructor(options) {
+        if (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0) {
+            throw new TypeError('OAuth timeout must be a positive finite number.');
+        }
+        this.#options = options;
+    }
+    async authorize(request) {
+        if (!this.#options.validateReturnUrl(request.returnUrl))
+            return { type: 'invalid_return' };
+        const stateNonce = this.#options.createStateNonce();
+        if (stateNonce.length === 0)
+            throw new TypeError('OAuth state nonce must not be empty.');
+        const popup = request.platform === 'web' ? this.openBrowserPopup(request.returnUrl) : null;
+        const operation = this.performAuthorization(request, stateNonce, popup);
+        const result = await this.withTimeout(operation, () => {
+            popup?.close();
+            if (request.platform === 'native')
+                this.#options.native?.cancel();
+        });
+        if (result === TIMED_OUT) {
+            await this.clearIfCurrent(stateNonce);
+            return { type: 'timed_out' };
+        }
+        return result;
+    }
+    async handleRedirect(returnUrl) {
+        return this.completeReturn(returnUrl);
+    }
+    async discardStaleSession() {
+        const stored = await this.#options.storage.load();
+        if (stored === null || !this.isStale(stored))
+            return false;
+        await this.#options.storage.clear();
+        return true;
+    }
+    openBrowserPopup(returnUrl) {
+        const browser = this.#options.browser;
+        if (browser === undefined)
+            return null;
+        return browser.openPlaceholder({
+            placeholderUrl: this.#options.placeholderUrl ?? DEFAULT_PLACEHOLDER_URL,
+            returnUrl,
+            windowName: this.#options.windowName ?? DEFAULT_WINDOW_NAME,
+        });
+    }
+    async performAuthorization(request, stateNonce, popup) {
+        await this.discardStaleSession();
+        await this.#options.storage.save({
+            stateNonce,
+            returnUrl: request.returnUrl,
+            createdAt: this.#options.clock.now(),
+        });
+        const authorizationUrl = await request.createAuthorizationUrl({
+            stateNonce,
+            returnUrl: request.returnUrl,
+        });
+        let sessionResult;
+        if (request.platform === 'native') {
+            const native = this.#options.native;
+            if (native === undefined)
+                throw new TypeError('Native OAuth runner is required.');
+            sessionResult = await native.run({ authorizationUrl, returnUrl: request.returnUrl });
+        }
+        else if (popup !== null) {
+            popup.navigate(authorizationUrl);
+            sessionResult = await popup.result;
+        }
+        else {
+            const redirect = this.#options.redirect;
+            if (redirect === undefined)
+                throw new TypeError('Browser OAuth handler is required.');
+            sessionResult = await redirect.authorize({
+                authorizationUrl,
+                returnUrl: request.returnUrl,
+            });
+        }
+        if (sessionResult.type === 'cancelled') {
+            await this.clearIfCurrent(stateNonce);
+            return { type: 'cancelled' };
+        }
+        return this.completeReturn(sessionResult.returnUrl, stateNonce);
+    }
+    async completeReturn(returnUrl, expectedStateNonce) {
+        if (!this.#options.validateReturnUrl(returnUrl))
+            return { type: 'invalid_return' };
+        const callbackParams = parseCallbackParams(returnUrl);
+        if (callbackParams === null)
+            return { type: 'invalid_return' };
+        const stored = await this.#options.storage.load();
+        if (stored === null)
+            return { type: 'storage_mismatch' };
+        if (this.isStale(stored)) {
+            await this.#options.storage.clear();
+            return { type: 'timed_out' };
+        }
+        if ((expectedStateNonce !== undefined && stored.stateNonce !== expectedStateNonce) ||
+            callbackParams['state'] !== stored.stateNonce) {
+            return { type: 'storage_mismatch' };
+        }
+        if (!sameReturnEndpoint(stored.returnUrl, returnUrl))
+            return { type: 'invalid_return' };
+        await this.#options.storage.clear();
+        return { type: 'success', callbackParams };
+    }
+    isStale(session) {
+        const elapsed = this.#options.clock.now() - session.createdAt;
+        return elapsed < 0 || elapsed >= this.#options.timeoutMs;
+    }
+    async clearIfCurrent(stateNonce) {
+        const stored = await this.#options.storage.load();
+        if (stored?.stateNonce === stateNonce)
+            await this.#options.storage.clear();
+    }
+    async withTimeout(operation, onTimeout) {
+        let timer;
+        const timeout = new Promise((resolve) => {
+            timer = this.#options.clock.setTimeout(() => {
+                try {
+                    onTimeout();
+                }
+                finally {
+                    resolve(TIMED_OUT);
+                }
+            }, this.#options.timeoutMs);
+        });
+        try {
+            return await Promise.race([operation, timeout]);
+        }
+        finally {
+            this.#options.clock.clearTimeout(timer);
+        }
+    }
+}
+export function createReturnUrlValidator(policy) {
+    const origin = parseOrigin(policy.origin);
+    const paths = new Set(policy.paths.map(normalizeAllowedPath));
+    if (paths.size === 0)
+        throw new TypeError('At least one OAuth return path is required.');
+    return (returnUrl) => {
+        const parsed = parseUrl(returnUrl);
+        return (parsed !== null &&
+            parsed.username === '' &&
+            parsed.password === '' &&
+            exactOrigin(parsed) === origin &&
+            paths.has(parsed.pathname));
+    };
+}
+function parseOrigin(origin) {
+    const parsed = parseUrl(origin);
+    if (parsed?.username !== '' ||
+        parsed.password !== '' ||
+        (parsed.pathname !== '' && parsed.pathname !== '/') ||
+        parsed.search !== '' ||
+        parsed.hash !== '') {
+        throw new TypeError('OAuth return origin must contain only a scheme and authority.');
+    }
+    return exactOrigin(parsed);
+}
+function normalizeAllowedPath(path) {
+    if (!path.startsWith('/') || path.includes('?') || path.includes('#')) {
+        throw new TypeError('OAuth return paths must be absolute paths without a query or fragment.');
+    }
+    const parsed = new URL(path, 'https://baukit.invalid');
+    if (parsed.pathname !== path)
+        throw new TypeError('OAuth return paths must be normalized.');
+    return path;
+}
+function parseCallbackParams(returnUrl) {
+    const parsed = parseUrl(returnUrl);
+    if (parsed === null)
+        return null;
+    const values = {};
+    for (const [key, value] of parsed.searchParams) {
+        if (Object.hasOwn(values, key))
+            return null;
+        values[key] = value;
+    }
+    return Object.freeze(values);
+}
+function sameReturnEndpoint(expected, actual) {
+    const expectedUrl = parseUrl(expected);
+    const actualUrl = parseUrl(actual);
+    return (expectedUrl !== null &&
+        actualUrl !== null &&
+        exactOrigin(expectedUrl) === exactOrigin(actualUrl) &&
+        expectedUrl.pathname === actualUrl.pathname);
+}
+function exactOrigin(url) {
+    return url.origin === 'null' ? `${url.protocol}//${url.host}` : url.origin;
+}
+function parseUrl(value) {
+    try {
+        return new URL(value);
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=oauth-session.js.map

package/dist/oauth-session.js.map

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

package/dist/provider-registry.d.ts

@@ -0,0 +1,22 @@
+import type { ConnectionAction, ConnectionState, ConnectionStatus } from './connection-health.js';
+export interface ProviderRegistration<ProviderId extends string, LabelKey extends string, Capability extends string> {
+    readonly id: ProviderId;
+    readonly labelKey: LabelKey;
+    readonly capabilities: readonly Capability[];
+    readonly connection: ConnectionState;
+}
+export interface RegisteredProvider<ProviderId extends string, LabelKey extends string, Capability extends string> {
+    readonly id: ProviderId;
+    readonly labelKey: LabelKey;
+    readonly capabilities: readonly Capability[];
+    readonly currentState: ConnectionStatus;
+    readonly availableActions: readonly ConnectionAction[];
+}
+export declare class ProviderRegistry<ProviderId extends string, LabelKey extends string, Capability extends string> {
+    #private;
+    constructor(registrations: readonly ProviderRegistration<ProviderId, LabelKey, Capability>[]);
+    list(): readonly RegisteredProvider<ProviderId, LabelKey, Capability>[];
+    get(providerId: ProviderId): RegisteredProvider<ProviderId, LabelKey, Capability> | undefined;
+}
+export declare function createProviderRegistry<ProviderId extends string, LabelKey extends string, Capability extends string>(registrations: readonly ProviderRegistration<ProviderId, LabelKey, Capability>[]): ProviderRegistry<ProviderId, LabelKey, Capability>;
+//# sourceMappingURL=provider-registry.d.ts.map

package/dist/provider-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-registry.d.ts","sourceRoot":"","sources":["../src/provider-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAElG,MAAM,WAAW,oBAAoB,CACnC,UAAU,SAAS,MAAM,EACzB,QAAQ,SAAS,MAAM,EACvB,UAAU,SAAS,MAAM;IAEzB,QAAQ,CAAC,EAAE,EAAE,UAAU,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,SAAS,UAAU,EAAE,CAAC;IAC7C,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;CACtC;AAED,MAAM,WAAW,kBAAkB,CACjC,UAAU,SAAS,MAAM,EACzB,QAAQ,SAAS,MAAM,EACvB,UAAU,SAAS,MAAM;IAEzB,QAAQ,CAAC,EAAE,EAAE,UAAU,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,SAAS,UAAU,EAAE,CAAC;IAC7C,QAAQ,CAAC,YAAY,EAAE,gBAAgB,CAAC;IACxC,QAAQ,CAAC,gBAAgB,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACxD;AAED,qBAAa,gBAAgB,CAC3B,UAAU,SAAS,MAAM,EACzB,QAAQ,SAAS,MAAM,EACvB,UAAU,SAAS,MAAM;;gBAMvB,aAAa,EAAE,SAAS,oBAAoB,CAAC,UAAU,EAAE,QAAQ,EAAE,UAAU,CAAC,EAAE;IAiB3E,IAAI,IAAI,SAAS,kBAAkB,CAAC,UAAU,EAAE,QAAQ,EAAE,UAAU,CAAC,EAAE;IAIvE,GAAG,CACR,UAAU,EAAE,UAAU,GACrB,kBAAkB,CAAC,UAAU,EAAE,QAAQ,EAAE,UAAU,CAAC,GAAG,SAAS;CAGpE;AAED,wBAAgB,sBAAsB,CACpC,UAAU,SAAS,MAAM,EACzB,QAAQ,SAAS,MAAM,EACvB,UAAU,SAAS,MAAM,EAEzB,aAAa,EAAE,SAAS,oBAAoB,CAAC,UAAU,EAAE,QAAQ,EAAE,UAAU,CAAC,EAAE,GAC/E,gBAAgB,CAAC,UAAU,EAAE,QAAQ,EAAE,UAAU,CAAC,CAEpD"}

package/dist/provider-registry.js

@@ -0,0 +1,28 @@
+export class ProviderRegistry {
+    #providers;
+    #byId;
+    constructor(registrations) {
+        const providers = registrations.map((registration) => Object.freeze({
+            id: registration.id,
+            labelKey: registration.labelKey,
+            capabilities: Object.freeze([...registration.capabilities]),
+            currentState: registration.connection.status,
+            availableActions: Object.freeze([...registration.connection.availableActions]),
+        }));
+        const byId = new Map(providers.map((provider) => [provider.id, provider]));
+        if (byId.size !== providers.length)
+            throw new TypeError('Provider IDs must be unique.');
+        this.#providers = Object.freeze(providers);
+        this.#byId = byId;
+    }
+    list() {
+        return this.#providers;
+    }
+    get(providerId) {
+        return this.#byId.get(providerId);
+    }
+}
+export function createProviderRegistry(registrations) {
+    return new ProviderRegistry(registrations);
+}
+//# sourceMappingURL=provider-registry.js.map

package/dist/provider-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-registry.js","sourceRoot":"","sources":["../src/provider-registry.ts"],"names":[],"mappings":"AAyBA,MAAM,OAAO,gBAAgB;IAKlB,UAAU,CAAkE;IAC5E,KAAK,CAAgF;IAE9F,YACE,aAAgF;QAEhF,MAAM,SAAS,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC,YAAY,EAAE,EAAE,CACnD,MAAM,CAAC,MAAM,CAAC;YACZ,EAAE,EAAE,YAAY,CAAC,EAAE;YACnB,QAAQ,EAAE,YAAY,CAAC,QAAQ;YAC/B,YAAY,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,YAAY,CAAC,YAAY,CAAC,CAAC;YAC3D,YAAY,EAAE,YAAY,CAAC,UAAU,CAAC,MAAM;YAC5C,gBAAgB,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,YAAY,CAAC,UAAU,CAAC,gBAAgB,CAAC,CAAC;SAC/E,CAAC,CACH,CAAC;QACF,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;QAC3E,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,MAAM;YAAE,MAAM,IAAI,SAAS,CAAC,8BAA8B,CAAC,CAAC;QACxF,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAC3C,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;IAEM,IAAI;QACT,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAEM,GAAG,CACR,UAAsB;QAEtB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IACpC,CAAC;CACF;AAED,MAAM,UAAU,sBAAsB,CAKpC,aAAgF;IAEhF,OAAO,IAAI,gBAAgB,CAAC,aAAa,CAAC,CAAC;AAC7C,CAAC"}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@baukit/integrations-client",
+  "version": "0.2.0",
+  "description": "Provider-neutral connection state, OAuth session coordination, and provider registration for web and native clients.",
+  "license": "MIT",
+  "author": "Patrick Koss",
+  "homepage": "https://github.com/PatrickKoss/baukit#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PatrickKoss/baukit.git",
+    "directory": "typescript/packages/integrations-client"
+  },
+  "bugs": {
+    "url": "https://github.com/PatrickKoss/baukit/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepare": "pnpm run build",
+    "test": "vitest run --config ../../vitest.config.ts",
+    "lint": "eslint src --max-warnings=0",
+    "format:check": "prettier --check src package.json tsconfig.json"
+  },
+  "devDependencies": {
+    "typescript": "6.0.3",
+    "vitest": "4.1.10"
+  }
+}