@mdbase-dev/connect 0.1.0-beta.100

package/dist/query-pagination.js

@@ -0,0 +1,119 @@
+import { connectProblem } from "./errors.js";
+import { connectFailure, connectSuccess } from "./outcomes.js";
+export async function* coordinatedQueryPages(query, releaseQueryCursor, input = {}, options = {}) {
+    const { offset: requestedOffset, limit: requestedLimit, cursor: requestedCursor, pagination: requestedPagination, snapshot: requestedSnapshot, ...criteria } = input;
+    let offset = nonNegativeInteger(requestedOffset, 0);
+    const firstPageSize = positiveInteger(options.firstPageSize ?? options.pageSize ?? requestedLimit, 200);
+    const pageSize = positiveInteger(options.pageSize ?? requestedLimit, 1_000);
+    let cursor = requestedCursor;
+    let cursorMode = requestedCursor !== undefined;
+    let cursorToRelease = requestedCursor;
+    let snapshot = requestedSnapshot;
+    let loaded = 0;
+    let pageNumber = 0;
+    try {
+        while (!options.signal?.aborted) {
+            const pageCursor = cursor;
+            const pageRequestOptions = {
+                signal: options.signal,
+                timeoutMs: options.pageTimeoutMs,
+                coordination: { ...options.coordination, coalesce: false }
+            };
+            const automaticCursorProbe = pageNumber === 0
+                && requestedCursor === undefined
+                && requestedPagination === undefined
+                && requestedSnapshot === undefined;
+            let queried = await query({
+                ...criteria,
+                // Continuations use the page size pinned when the cursor was opened.
+                ...(!cursorMode ? { limit: pageNumber === 0 ? firstPageSize : pageSize } : {}),
+                ...(cursorMode
+                    ? (pageCursor ? { cursor: pageCursor } : { pagination: "cursor" })
+                    : {
+                        offset,
+                        ...(snapshot ? { snapshot } : {}),
+                        ...(!snapshot && requestedPagination === "cursor"
+                            ? { pagination: "cursor" }
+                            : {})
+                    }),
+                ...(!cursorMode && !snapshot && automaticCursorProbe
+                    ? { pagination: "cursor" }
+                    : {})
+            }, pageRequestOptions);
+            // Cursor pagination is a read-only capability probe for authorities
+            // predating generation cursors. Retry the first page without that
+            // optional field only when the authority rejected the operation
+            // schema; explicit cursor requests remain strict.
+            if (automaticCursorProbe
+                && !queried.ok
+                && queried.problem.code === "operation_invalid") {
+                queried = await query({
+                    ...criteria,
+                    limit: firstPageSize,
+                    offset
+                }, pageRequestOptions);
+            }
+            if (!queried.ok) {
+                yield queried;
+                return;
+            }
+            const result = queried.value;
+            const returnedCursor = result.meta?.cursor;
+            if (returnedCursor) {
+                cursorMode = true;
+                cursor = returnedCursor;
+                cursorToRelease = returnedCursor;
+            }
+            else if (cursorMode) {
+                cursor = undefined;
+                cursorToRelease = pageCursor;
+            }
+            if (cursorMode && result.meta?.hasMore && !returnedCursor) {
+                yield connectFailure(connectProblem("invalid_operation_response", "The collection authority omitted the cursor required for the next query page."));
+                return;
+            }
+            const returnedSnapshot = result.meta?.snapshot;
+            if (!cursorMode && snapshot && returnedSnapshot && snapshot !== returnedSnapshot) {
+                yield connectFailure(connectProblem("query_snapshot_changed", "The collection query snapshot changed while paging. Refresh the query before continuing."));
+                return;
+            }
+            if (!cursorMode && !snapshot && returnedSnapshot)
+                snapshot = returnedSnapshot;
+            loaded += result.results.length;
+            const complete = !result.meta?.hasMore || result.results.length === 0;
+            const page = {
+                results: result.results,
+                ...(result.meta ? { meta: result.meta } : {}),
+                page: pageNumber,
+                offset,
+                loaded,
+                complete,
+                ...(returnedCursor ? { cursor: returnedCursor } : {}),
+                ...(!cursorMode && snapshot ? { snapshot } : {})
+            };
+            options.onProgress?.(page);
+            yield connectSuccess(page, queried.diagnostics);
+            if (complete)
+                return;
+            offset += result.results.length;
+            pageNumber += 1;
+        }
+    }
+    finally {
+        if (cursorMode && cursorToRelease) {
+            // Cleanup has its own bounded request. It must not delay delivery of
+            // completed pages or consume the caller's data deadline.
+            void releaseQueryCursor(cursorToRelease).catch(() => undefined);
+        }
+    }
+}
+function nonNegativeInteger(value, fallback) {
+    return typeof value === "number" && Number.isFinite(value)
+        ? Math.max(0, Math.floor(value))
+        : fallback;
+}
+function positiveInteger(value, fallback) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0
+        ? Math.floor(value)
+        : fallback;
+}

package/dist/request-budget.d.ts

@@ -0,0 +1,34 @@
+import type { ConnectRequestOptions } from "./operation-types.js";
+import type { MdbaseConnectTimeouts } from "./connect-options.js";
+export declare const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
+export declare const DEFAULT_STARTUP_TIMEOUT_MS = 10000;
+export declare const DEFAULT_FILE_INDEX_TIMEOUT_MS: number;
+export declare const DEFAULT_UPLOAD_TIMEOUT_MS = 120000;
+export declare const DEFAULT_SYNC_TIMEOUT_MS = 60000;
+export interface ResolvedConnectTimeouts {
+    requestMs: number | null;
+    watchStartMs: number | null;
+    fileIndexMs: number | null;
+    uploadMs: number | null;
+    syncMs: number | null;
+}
+export declare function resolveConnectTimeouts(timeouts?: MdbaseConnectTimeouts): ResolvedConnectTimeouts;
+export interface RequestBudget {
+    readonly signal: AbortSignal;
+    readonly deadline: number | null;
+    remainingMs(): number | null;
+    dispose(): void;
+}
+export type OperationRequestOptions = ConnectRequestOptions & {
+    /** Absolute budget shared with the connector; never supplied directly by callers. */
+    deadlineUnixMs?: number;
+};
+export declare function requestOptionsWithinBudget(options: ConnectRequestOptions, budget: RequestBudget): OperationRequestOptions;
+export declare function createRequestBudget(options?: ConnectRequestOptions, defaultTimeoutMs?: number | null, now?: () => number): RequestBudget;
+export declare function withRequestBudget<Result>(options: ConnectRequestOptions | undefined, defaultTimeoutMs: number | null, operation: (budget: RequestBudget) => Promise<Result>): Promise<Result>;
+/**
+ * Budget an operation whose transport cooperates with AbortSignal and must run
+ * its own bounded cleanup/recovery before the public promise settles.
+ */
+export declare function withCooperativeRequestBudget<Result>(options: ConnectRequestOptions | undefined, defaultTimeoutMs: number | null, operation: (budget: RequestBudget) => Promise<Result>): Promise<Result>;
+export declare function requestAbortReason(signal: AbortSignal): unknown;

package/dist/request-budget.js

@@ -0,0 +1,104 @@
+import { MdbaseConnectError, connectError } from "./errors.js";
+export const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+export const DEFAULT_STARTUP_TIMEOUT_MS = 10_000;
+export const DEFAULT_FILE_INDEX_TIMEOUT_MS = 10 * 60_000;
+export const DEFAULT_UPLOAD_TIMEOUT_MS = 120_000;
+export const DEFAULT_SYNC_TIMEOUT_MS = 60_000;
+export function resolveConnectTimeouts(timeouts = {}) {
+    return {
+        requestMs: configuredTimeout(timeouts.requestMs, DEFAULT_REQUEST_TIMEOUT_MS, "requestMs"),
+        watchStartMs: configuredTimeout(timeouts.watchStartMs, DEFAULT_STARTUP_TIMEOUT_MS, "watchStartMs"),
+        fileIndexMs: configuredTimeout(timeouts.fileIndexMs, DEFAULT_FILE_INDEX_TIMEOUT_MS, "fileIndexMs"),
+        uploadMs: configuredTimeout(timeouts.uploadMs, DEFAULT_UPLOAD_TIMEOUT_MS, "uploadMs"),
+        syncMs: configuredTimeout(timeouts.syncMs, DEFAULT_SYNC_TIMEOUT_MS, "syncMs")
+    };
+}
+export function requestOptionsWithinBudget(options, budget) {
+    return {
+        ...options,
+        signal: budget.signal,
+        ...(budget.deadline === null ? {} : { deadlineUnixMs: budget.deadline })
+    };
+}
+export function createRequestBudget(options = {}, defaultTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS, now = Date.now) {
+    const configured = options.timeoutMs === undefined ? defaultTimeoutMs : options.timeoutMs;
+    const timeoutMs = configured === null ? null : validTimeout(configured);
+    const controller = new AbortController();
+    const deadline = timeoutMs === null ? null : now() + timeoutMs;
+    const abortFromCaller = () => controller.abort(options.signal?.reason);
+    if (options.signal?.aborted)
+        abortFromCaller();
+    else
+        options.signal?.addEventListener("abort", abortFromCaller, { once: true });
+    const timer = timeoutMs === null
+        ? undefined
+        : setTimeout(() => controller.abort(connectError("timeout", "The operation exceeded its request deadline.", { operationOutcome: "not_sent" })), timeoutMs);
+    let disposed = false;
+    return {
+        signal: controller.signal,
+        deadline,
+        remainingMs: () => deadline === null ? null : Math.max(0, deadline - now()),
+        dispose: () => {
+            if (disposed)
+                return;
+            disposed = true;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            options.signal?.removeEventListener("abort", abortFromCaller);
+        }
+    };
+}
+export async function withRequestBudget(options, defaultTimeoutMs, operation) {
+    const budget = createRequestBudget(options, defaultTimeoutMs);
+    let rejectOnAbort;
+    const aborted = new Promise((_resolve, reject) => {
+        rejectOnAbort = reject;
+    });
+    const abort = () => rejectOnAbort?.(requestAbortReason(budget.signal));
+    budget.signal.addEventListener("abort", abort, { once: true });
+    try {
+        if (budget.signal.aborted)
+            throw requestAbortReason(budget.signal);
+        return await Promise.race([operation(budget), aborted]);
+    }
+    finally {
+        budget.signal.removeEventListener("abort", abort);
+        budget.dispose();
+    }
+}
+/**
+ * Budget an operation whose transport cooperates with AbortSignal and must run
+ * its own bounded cleanup/recovery before the public promise settles.
+ */
+export async function withCooperativeRequestBudget(options, defaultTimeoutMs, operation) {
+    const budget = createRequestBudget(options, defaultTimeoutMs);
+    try {
+        if (budget.signal.aborted)
+            throw requestAbortReason(budget.signal);
+        return await operation(budget);
+    }
+    finally {
+        budget.dispose();
+    }
+}
+export function requestAbortReason(signal) {
+    if (signal.reason instanceof MdbaseConnectError)
+        return signal.reason;
+    return connectError("operation_cancelled", "The operation was cancelled before it changed the collection.", { operationOutcome: "not_sent", cause: signal.reason });
+}
+function validTimeout(value) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new TypeError("timeoutMs must be a positive safe integer or null.");
+    }
+    return value;
+}
+function configuredTimeout(value, fallback, name) {
+    if (value === undefined)
+        return fallback;
+    if (value === null)
+        return null;
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new TypeError(`${name} must be a positive safe integer or null.`);
+    }
+    return value;
+}

package/dist/request-coordinator.d.ts

@@ -0,0 +1,29 @@
+import { type CollectionOperation } from "@mdbase-dev/connect-protocol";
+import type { ConnectRequestOptions, MdbaseCollectionTransport } from "./operation-types.js";
+interface CoordinatorLimits {
+    foregroundCapacity?: number;
+    foregroundQueueCapacity?: number;
+    mutationQueueCapacity?: number;
+}
+/** One bounded request owner for a selected connection. */
+export declare class CollectionRequestCoordinator implements MdbaseCollectionTransport {
+    private readonly transport;
+    private readonly requestTimeoutMs;
+    private readonly foregroundCapacity;
+    private readonly foregroundQueueCapacity;
+    private readonly mutationQueueCapacity;
+    private readonly foregroundQueue;
+    private readonly mutationQueue;
+    private readonly identicalReads;
+    private readonly latestFamilies;
+    private activeForeground;
+    private mutationActive;
+    constructor(transport: MdbaseCollectionTransport, requestTimeoutMs: number | null, limits?: CoordinatorLimits);
+    operation<Result>(operation: CollectionOperation, input: unknown, options?: ConnectRequestOptions): Promise<Result>;
+    private schedule;
+    private replaceLatest;
+    private releaseLatest;
+    private pump;
+    private start;
+}
+export {};

package/dist/request-coordinator.js

@@ -0,0 +1,213 @@
+import { isMutatingOperation } from "@mdbase-dev/connect-protocol";
+import { connectError } from "./errors.js";
+import { requestAbortReason, requestOptionsWithinBudget, withCooperativeRequestBudget } from "./request-budget.js";
+const DEFAULT_FOREGROUND_CAPACITY = 4;
+const DEFAULT_QUEUE_CAPACITY = 32;
+/** One bounded request owner for a selected connection. */
+export class CollectionRequestCoordinator {
+    transport;
+    requestTimeoutMs;
+    foregroundCapacity;
+    foregroundQueueCapacity;
+    mutationQueueCapacity;
+    foregroundQueue = [];
+    mutationQueue = [];
+    identicalReads = new Map();
+    latestFamilies = new Map();
+    activeForeground = 0;
+    mutationActive = false;
+    constructor(transport, requestTimeoutMs, limits = {}) {
+        this.transport = transport;
+        this.requestTimeoutMs = requestTimeoutMs;
+        this.foregroundCapacity = positiveCapacity(limits.foregroundCapacity, DEFAULT_FOREGROUND_CAPACITY);
+        this.foregroundQueueCapacity = positiveCapacity(limits.foregroundQueueCapacity, DEFAULT_QUEUE_CAPACITY);
+        this.mutationQueueCapacity = positiveCapacity(limits.mutationQueueCapacity, DEFAULT_QUEUE_CAPACITY);
+    }
+    operation(operation, input, options = {}) {
+        const read = !isMutatingOperation(operation, input);
+        const coordination = validatedCoordination(options.coordination, read);
+        const coalesceKey = read
+            && coordination.coalesce !== false
+            && !coordination.latestWins
+            && options.signal === undefined
+            ? stableRequestKey(operation, input, options.timeoutMs)
+            : undefined;
+        if (coalesceKey) {
+            const existing = this.identicalReads.get(coalesceKey);
+            if (existing)
+                return existing;
+        }
+        const request = withCooperativeRequestBudget(options, this.requestTimeoutMs, (budget) => this.schedule(operation, input, options, coordination, read, budget));
+        if (coalesceKey) {
+            this.identicalReads.set(coalesceKey, request);
+            void request.finally(() => {
+                if (this.identicalReads.get(coalesceKey) === request) {
+                    this.identicalReads.delete(coalesceKey);
+                }
+            }).catch(() => undefined);
+        }
+        return request;
+    }
+    schedule(operation, input, options, coordination, read, budget) {
+        const replacement = coordination.latestWins
+            ? this.replaceLatest(coordination.family)
+            : undefined;
+        const combined = combineSignals(budget.signal, replacement?.signal);
+        const { coordination: _coordination, ...transportOptions } = options;
+        const withinBudget = requestOptionsWithinBudget({ ...transportOptions, timeoutMs: null }, budget);
+        const run = () => this.transport.operation(operation, input, {
+            ...withinBudget,
+            signal: combined.signal
+        });
+        const queue = read ? this.foregroundQueue : this.mutationQueue;
+        const capacity = read ? this.foregroundQueueCapacity : this.mutationQueueCapacity;
+        if (queue.length >= capacity) {
+            combined.dispose();
+            this.releaseLatest(coordination.family, replacement);
+            return Promise.reject(connectError("connector_busy", "The selected connection request queue is full.", { operationOutcome: "not_sent", status: 503 }));
+        }
+        return new Promise((resolve, reject) => {
+            const queued = {
+                budget,
+                run,
+                resolve: (result) => resolve(result),
+                reject,
+                started: false,
+                settled: false
+            };
+            const abortQueued = () => {
+                if (queued.started || queued.settled)
+                    return;
+                queued.settled = true;
+                queue.splice(queue.indexOf(queued), 1);
+                queued.reject(requestAbortReason(combined.signal));
+                combined.dispose();
+                this.releaseLatest(coordination.family, replacement);
+            };
+            combined.signal.addEventListener("abort", abortQueued, { once: true });
+            const originalRun = queued.run;
+            queued.run = async () => {
+                combined.signal.removeEventListener("abort", abortQueued);
+                try {
+                    if (combined.signal.aborted)
+                        throw requestAbortReason(combined.signal);
+                    return await originalRun();
+                }
+                finally {
+                    combined.dispose();
+                    this.releaseLatest(coordination.family, replacement);
+                }
+            };
+            queue.push(queued);
+            this.pump();
+        });
+    }
+    replaceLatest(family) {
+        const replacement = new AbortController();
+        this.latestFamilies.get(family)?.abort(connectError("operation_cancelled", "A newer request replaced this read before it changed the collection.", { operationOutcome: "not_sent" }));
+        this.latestFamilies.set(family, replacement);
+        return replacement;
+    }
+    releaseLatest(family, controller) {
+        if (family && controller && this.latestFamilies.get(family) === controller) {
+            this.latestFamilies.delete(family);
+        }
+    }
+    pump() {
+        while (this.activeForeground < this.foregroundCapacity) {
+            const request = nextLive(this.foregroundQueue);
+            if (!request)
+                break;
+            this.activeForeground += 1;
+            this.start(request, () => {
+                this.activeForeground -= 1;
+                this.pump();
+            });
+        }
+        if (!this.mutationActive) {
+            const request = nextLive(this.mutationQueue);
+            if (request) {
+                this.mutationActive = true;
+                this.start(request, () => {
+                    this.mutationActive = false;
+                    this.pump();
+                });
+            }
+        }
+    }
+    start(request, release) {
+        request.started = true;
+        void request.run().then((result) => {
+            if (!request.settled) {
+                request.settled = true;
+                request.resolve(result);
+            }
+        }, (error) => {
+            if (!request.settled) {
+                request.settled = true;
+                request.reject(error);
+            }
+        }).finally(release);
+    }
+}
+function nextLive(queue) {
+    while (queue.length > 0) {
+        const request = queue.shift();
+        if (!request.settled)
+            return request;
+    }
+    return undefined;
+}
+function validatedCoordination(coordination, read) {
+    const resolved = coordination ?? {};
+    if (resolved.latestWins && !read) {
+        throw new TypeError("latestWins coordination is available only for read operations.");
+    }
+    if (resolved.latestWins && !resolved.family?.trim()) {
+        throw new TypeError("latestWins coordination requires a non-empty family.");
+    }
+    return resolved;
+}
+function stableRequestKey(operation, input, timeoutMs) {
+    return `${operation}:${timeoutMs === undefined ? "default" : String(timeoutMs)}:${stableJson(input)}`;
+}
+function stableJson(value) {
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value) ?? String(value);
+    }
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(",")}]`;
+    return `{${Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, nested]) => `${JSON.stringify(key)}:${stableJson(nested)}`)
+        .join(",")}}`;
+}
+function combineSignals(primary, secondary) {
+    if (!secondary)
+        return { signal: primary, dispose: () => undefined };
+    const controller = new AbortController();
+    const abortPrimary = () => controller.abort(primary.reason);
+    const abortSecondary = () => controller.abort(secondary.reason);
+    if (primary.aborted)
+        abortPrimary();
+    else
+        primary.addEventListener("abort", abortPrimary, { once: true });
+    if (secondary.aborted)
+        abortSecondary();
+    else
+        secondary.addEventListener("abort", abortSecondary, { once: true });
+    return {
+        signal: controller.signal,
+        dispose: () => {
+            primary.removeEventListener("abort", abortPrimary);
+            secondary.removeEventListener("abort", abortSecondary);
+        }
+    };
+}
+function positiveCapacity(value, fallback) {
+    const resolved = value ?? fallback;
+    if (!Number.isSafeInteger(resolved) || resolved <= 0) {
+        throw new TypeError("Request coordinator capacities must be positive safe integers.");
+    }
+    return resolved;
+}

package/dist/retired-grant-keys.d.ts

@@ -0,0 +1,9 @@
+import type { StoredToken } from "./internal-types.js";
+import type { GrantKeyStore } from "./crypto.js";
+export declare function storedTokenKeyHandles(token: StoredToken | null, additional?: string): Set<string>;
+export declare function planRetiredGrantKeys(storage: Storage, pendingMutationKey: string, previous: StoredToken | null, current?: string, leased?: Iterable<string>, retainAll?: boolean): {
+    retained: string[];
+    disposable: string[];
+};
+export declare function removeRetiredGrantKeyMetadata(storage: Storage, tokenKey: string, handle: string): void;
+export declare function deleteUnusedGrantKey(storage: Storage, keyStore: GrantKeyStore, pendingMutationKey: string, tokenKey: string, handle: string): Promise<void>;

package/dist/retired-grant-keys.js

@@ -0,0 +1,56 @@
+import { pendingMutationKeyHandles, pendingMutationsUseKey } from "./pending-recovery-transports.js";
+import { parseStored } from "./runtime-utils.js";
+export function storedTokenKeyHandles(token, additional) {
+    const handles = new Set();
+    if (additional)
+        handles.add(additional);
+    if (token?.keyHandle)
+        handles.add(token.keyHandle);
+    if (Array.isArray(token?.retiredKeyHandles)) {
+        for (const handle of token.retiredKeyHandles) {
+            if (typeof handle === "string" && handle.length > 0)
+                handles.add(handle);
+        }
+    }
+    return handles;
+}
+export function planRetiredGrantKeys(storage, pendingMutationKey, previous, current, leased = [], retainAll = false) {
+    const retained = [];
+    const disposable = [];
+    const candidates = storedTokenKeyHandles(previous);
+    for (const handle of pendingMutationKeyHandles(storage, pendingMutationKey)) {
+        candidates.add(handle);
+    }
+    const leasedHandles = new Set(leased);
+    for (const handle of leasedHandles)
+        candidates.add(handle);
+    for (const handle of candidates) {
+        if (handle === current)
+            continue;
+        (retainAll || leasedHandles.has(handle) || pendingMutationsUseKey(storage, pendingMutationKey, handle)
+            ? retained
+            : disposable).push(handle);
+    }
+    return { retained, disposable };
+}
+export function removeRetiredGrantKeyMetadata(storage, tokenKey, handle) {
+    const token = parseStored(storage.getItem(tokenKey));
+    if (!token || !Array.isArray(token.retiredKeyHandles))
+        return;
+    const retiredKeyHandles = token.retiredKeyHandles.filter((candidate) => candidate !== handle);
+    if (retiredKeyHandles.length === token.retiredKeyHandles.length)
+        return;
+    if (retiredKeyHandles.length > 0)
+        token.retiredKeyHandles = retiredKeyHandles;
+    else
+        delete token.retiredKeyHandles;
+    storage.setItem(tokenKey, JSON.stringify(token));
+}
+export async function deleteUnusedGrantKey(storage, keyStore, pendingMutationKey, tokenKey, handle) {
+    const current = parseStored(storage.getItem(tokenKey));
+    if (current?.keyHandle === handle
+        || pendingMutationsUseKey(storage, pendingMutationKey, handle))
+        return;
+    await keyStore.delete(handle);
+    removeRetiredGrantKeyMetadata(storage, tokenKey, handle);
+}

package/dist/runtime-utils.d.ts

@@ -0,0 +1,52 @@
+import type { FileCapability, GrantEncryption, GrantScope } from "@mdbase-dev/connect-protocol";
+import type { MdbaseApplicationManifest as MdbaseAppManifest } from "./application-contract.js";
+import { MdbaseConnectError } from "./errors.js";
+import type { StoredToken } from "./internal-types.js";
+import type { MdbaseDeviceAuthorization } from "./authorization-types.js";
+/** Resolve bundled declarations and their stable storage identity without loading URLs. */
+export declare function resolveManifestSource(input?: MdbaseAppManifest | string | URL, redirect?: string | URL): {
+    manifest: MdbaseAppManifest | string;
+    manifestSource: string;
+    redirectUri: string;
+};
+type NetworkProblemCode = "notification_registration_failed" | "notification_unregistration_failed" | "notifications_unavailable" | "temporarily_unavailable";
+/** Normalize fetch rejection at the exact I/O boundary. */
+export declare function connectFetch(input: RequestInfo | URL, init: RequestInit | undefined, code: NetworkProblemCode, message: string): Promise<Response>;
+/** Decode JSON without allowing native syntax/body errors across the SDK boundary. */
+export declare function decodeJsonResponse(response: Response, code: string, message: string): Promise<any>;
+export declare function canonicalLoopbackUrl(value: string): string;
+export declare function createPkce(): Promise<{
+    verifier: string;
+    challenge: string;
+}>;
+export declare function apiError(body: any, fallbackCode: string, fallbackMessage: string, status?: number): MdbaseConnectError;
+export declare function oauthErrorCode(body: any): string | undefined;
+export declare function validAuthorityTokenResponse(value: unknown, collectionId: unknown): boolean;
+export declare function validStoredAuthority(authority: StoredToken["authority"], collectionId: string): boolean;
+export declare function validFileCapability(value: unknown): value is FileCapability;
+export declare function validStoredEncryption(encryption: StoredToken["encryption"], collectionId: string): encryption is GrantEncryption;
+export declare function parseDeviceAuthorization(body: any): MdbaseDeviceAuthorization;
+export declare function parseStored<T>(value: string | null): T | null;
+/** Parse both canonical and N-1 grant shapes so callers can diagnose legacy grants. */
+export declare function parseGrantScope(value: unknown): GrantScope | null;
+/** Only this scope authorizes application data access. */
+export declare function isCanonicalGrantScope(scope: GrantScope): boolean;
+export declare function stripTrailingSlash(value: string): string;
+export declare function defaultManifestSource(): string;
+export declare function defaultRedirectUri(): string;
+export declare function applicationStorageOrigin(manifest: MdbaseAppManifest | string, manifestSource: string, redirectUri: string, registeredPortable: boolean): string;
+export declare function collectionIdFromTokenKey(key: string): string;
+export declare function defaultCallbackUrl(): string;
+export declare function defaultStorage(memoryOnly: boolean): Storage;
+export declare class MemoryStorage implements Storage {
+    private readonly values;
+    get length(): number;
+    clear(): void;
+    getItem(key: string): string | null;
+    key(index: number): string | null;
+    removeItem(key: string): void;
+    setItem(key: string, value: string): void;
+}
+export declare function isOpaquePortableManifest(manifest: MdbaseAppManifest | string): boolean;
+export declare function manifestStorageFingerprint(manifest: MdbaseAppManifest): string;
+export {};