@mdbase-dev/connect 0.1.0-beta.100

package/dist/outcomes.d.ts

@@ -0,0 +1,51 @@
+import type { ConnectProblem, ConnectProblemCode, MdbaseDiagnostic } from "@mdbase-dev/connect-protocol";
+export type ConnectSuccess<Value> = {
+    ok: true;
+    value: Value;
+    diagnostics: MdbaseDiagnostic[];
+};
+export type ConnectFailure<Code extends ConnectProblemCode = ConnectProblemCode> = {
+    ok: false;
+    problem: ConnectProblem<Code>;
+};
+/**
+ * Every expected failure from the public SDK is data. Exceptions are reserved
+ * for programming errors and broken SDK invariants.
+ */
+export type ConnectOutcome<Value, Code extends ConnectProblemCode = ConnectProblemCode> = ConnectSuccess<Value> | ConnectFailure<Code>;
+export type CommonOperationProblemCode = "access_denied" | "access_paused" | "application_declaration_mismatch" | "authorization_binding_incompatible" | "authorization_expired" | "capability_contract_incompatible" | "collection_access_denied" | "connector_identity_changed" | "connector_offline" | "connector_upgrade_required" | "direct_operation_rejected" | "durable_mutation_unsupported" | "operation_outcome_unknown" | "encryption_required" | "encrypted_relay_rejected" | "hosted_provider_unavailable" | "insufficient_access" | "invalid_encrypted_response" | "invalid_operation_response" | "invalid_request" | "missing_grant_key" | "mutation_recovery_expired" | "mutation_request_conflict" | "not_authorized" | "operation_cancelled" | "operation_failed" | "rate_limited" | "relay_authorization_expired" | "relay_unavailable" | "temporarily_unavailable" | "timeout" | "transport_protocol_incompatible" | "unsupported_operation";
+export declare const COMMON_OPERATION_PROBLEM_CODES: readonly ["access_denied", "access_paused", "application_declaration_mismatch", "authorization_binding_incompatible", "authorization_expired", "capability_contract_incompatible", "collection_access_denied", "connector_identity_changed", "connector_offline", "connector_upgrade_required", "direct_operation_rejected", "durable_mutation_unsupported", "operation_outcome_unknown", "encryption_required", "encrypted_relay_rejected", "hosted_provider_unavailable", "insufficient_access", "invalid_encrypted_response", "invalid_operation_response", "invalid_request", "missing_grant_key", "mutation_recovery_expired", "mutation_request_conflict", "not_authorized", "operation_cancelled", "operation_failed", "rate_limited", "relay_authorization_expired", "relay_unavailable", "temporarily_unavailable", "timeout", "transport_protocol_incompatible", "unsupported_operation"];
+export declare const ALL_CONNECT_PROBLEM_CODES: ConnectProblemCode[];
+export type RegistrationProblemCode = "discovery_failed" | "invalid_operation_response" | "invalid_application_manifest" | "invalid_request" | "manifest_load_failed" | "rate_limited" | "temporarily_unavailable" | "timeout";
+export declare const REGISTRATION_PROBLEM_CODES: readonly ["discovery_failed", "invalid_operation_response", "invalid_application_manifest", "invalid_request", "manifest_load_failed", "rate_limited", "temporarily_unavailable", "timeout"];
+export type AuthorizationProblemCode = RegistrationProblemCode | "access_denied" | "application_declaration_mismatch" | "application_identity_unavailable" | "approval_window_blocked" | "authorization_binding_incompatible" | "authorization_cancelled" | "authorization_replayed" | "browser_required" | "capability_contract_incompatible" | "collection_access_denied" | "collection_configuration_invalid" | "collection_contracts_missing" | "collection_incompatible" | "collection_invalid" | "collection_kind_unsupported" | "collection_mismatch" | "collection_not_found" | "collection_type_registry_invalid" | "collection_version_unsupported" | "connector_identity_changed" | "connector_offline" | "connector_upgrade_required" | "device_authorization_failed" | "durable_mutation_unsupported" | "encryption_required" | "expired_token" | "invalid_application_authorization" | "invalid_callback" | "invalid_device_authorization_response" | "invalid_token_response" | "legacy_scope_reauthorization_required" | "scope_denied" | "reconnect_required" | "token_exchange_failed" | "transport_protocol_incompatible";
+export declare const AUTHORIZATION_PROBLEM_CODES: readonly ["discovery_failed", "invalid_operation_response", "invalid_application_manifest", "invalid_request", "manifest_load_failed", "rate_limited", "temporarily_unavailable", "timeout", "access_denied", "application_declaration_mismatch", "application_identity_unavailable", "approval_window_blocked", "authorization_binding_incompatible", "authorization_cancelled", "authorization_replayed", "browser_required", "capability_contract_incompatible", "collection_access_denied", "collection_configuration_invalid", "collection_contracts_missing", "collection_incompatible", "collection_invalid", "collection_kind_unsupported", "collection_mismatch", "collection_not_found", "collection_type_registry_invalid", "collection_version_unsupported", "connector_identity_changed", "connector_offline", "connector_upgrade_required", "device_authorization_failed", "durable_mutation_unsupported", "encryption_required", "expired_token", "invalid_application_authorization", "invalid_callback", "invalid_device_authorization_response", "invalid_token_response", "legacy_scope_reauthorization_required", "scope_denied", "reconnect_required", "token_exchange_failed", "transport_protocol_incompatible"];
+export type NotificationProblemCode = RegistrationProblemCode | "authorization_expired" | "invalid_operation_response" | "invalid_push_subscription" | "managed_fcm_not_declared" | "not_authorized" | "notification_criterion_not_declared" | "notification_reauthorization_required" | "notification_registration_failed" | "notification_unregistration_failed" | "notifications_not_declared" | "notifications_unavailable";
+export declare const NOTIFICATION_PROBLEM_CODES: readonly ["discovery_failed", "invalid_operation_response", "invalid_application_manifest", "invalid_request", "manifest_load_failed", "rate_limited", "temporarily_unavailable", "timeout", "authorization_expired", "invalid_operation_response", "invalid_push_subscription", "managed_fcm_not_declared", "not_authorized", "notification_criterion_not_declared", "notification_reauthorization_required", "notification_registration_failed", "notification_unregistration_failed", "notifications_not_declared", "notifications_unavailable"];
+export type DirectAccessProblemCode = "connector_offline" | "connector_upgrade_required" | "invalid_operation_response" | "not_authorized" | "operation_failed" | "temporarily_unavailable" | "timeout";
+export declare const DIRECT_ACCESS_PROBLEM_CODES: readonly ["connector_offline", "connector_upgrade_required", "invalid_operation_response", "not_authorized", "operation_failed", "temporarily_unavailable", "timeout"];
+export type SessionProblemCode = AuthorizationProblemCode | "collection_not_ready" | "collection_not_selected" | "operation_cancelled" | "session_destroyed" | "session_not_started" | "session_starting" | "unknown_collection";
+export declare const SESSION_PROBLEM_CODES: readonly ["discovery_failed", "invalid_operation_response", "invalid_application_manifest", "invalid_request", "manifest_load_failed", "rate_limited", "temporarily_unavailable", "timeout", "access_denied", "application_declaration_mismatch", "application_identity_unavailable", "approval_window_blocked", "authorization_binding_incompatible", "authorization_cancelled", "authorization_replayed", "browser_required", "capability_contract_incompatible", "collection_access_denied", "collection_configuration_invalid", "collection_contracts_missing", "collection_incompatible", "collection_invalid", "collection_kind_unsupported", "collection_mismatch", "collection_not_found", "collection_type_registry_invalid", "collection_version_unsupported", "connector_identity_changed", "connector_offline", "connector_upgrade_required", "device_authorization_failed", "durable_mutation_unsupported", "encryption_required", "expired_token", "invalid_application_authorization", "invalid_callback", "invalid_device_authorization_response", "invalid_token_response", "legacy_scope_reauthorization_required", "scope_denied", "reconnect_required", "token_exchange_failed", "transport_protocol_incompatible", "collection_not_ready", "collection_not_selected", "operation_cancelled", "session_destroyed", "session_not_started", "session_starting", "unknown_collection"];
+export type CollectionSetupProblemCode = "collection_configuration_invalid" | "collection_invalid" | "collection_type_registry_invalid" | "collection_version_unsupported";
+export type CollectionDescriptionProblemCode = CommonOperationProblemCode | CollectionSetupProblemCode;
+export type CollectionReadProblemCode = CollectionDescriptionProblemCode | "invalid_path" | "operation_invalid";
+export type CollectionQueryProblemCode = CollectionReadProblemCode | "cursor_capacity_exhausted" | "generation_expired" | "invalid_read_cursor" | "query_snapshot_changed" | "sandbox_unsupported";
+export type CollectionMutationProblemCode = CollectionReadProblemCode | "concurrent_modification" | "invalid_preflight" | "pending_mutation_unresolved";
+export type CollectionChangesProblemCode = CollectionDescriptionProblemCode | "change_cursor_reset";
+export type CollectionTypeProblemCode = CollectionMutationProblemCode | "type_pack_provision_failed";
+export declare const COLLECTION_SETUP_PROBLEM_CODES: readonly ["collection_configuration_invalid", "collection_invalid", "collection_type_registry_invalid", "collection_version_unsupported"];
+export declare const COLLECTION_DESCRIPTION_PROBLEM_CODES: readonly ["access_denied", "access_paused", "application_declaration_mismatch", "authorization_binding_incompatible", "authorization_expired", "capability_contract_incompatible", "collection_access_denied", "connector_identity_changed", "connector_offline", "connector_upgrade_required", "direct_operation_rejected", "durable_mutation_unsupported", "operation_outcome_unknown", "encryption_required", "encrypted_relay_rejected", "hosted_provider_unavailable", "insufficient_access", "invalid_encrypted_response", "invalid_operation_response", "invalid_request", "missing_grant_key", "mutation_recovery_expired", "mutation_request_conflict", "not_authorized", "operation_cancelled", "operation_failed", "rate_limited", "relay_authorization_expired", "relay_unavailable", "temporarily_unavailable", "timeout", "transport_protocol_incompatible", "unsupported_operation", "collection_configuration_invalid", "collection_invalid", "collection_type_registry_invalid", "collection_version_unsupported"];
+export declare const COLLECTION_READ_PROBLEM_CODES: readonly ["access_denied", "access_paused", "application_declaration_mismatch", "authorization_binding_incompatible", "authorization_expired", "capability_contract_incompatible", "collection_access_denied", "connector_identity_changed", "connector_offline", "connector_upgrade_required", "direct_operation_rejected", "durable_mutation_unsupported", "operation_outcome_unknown", "encryption_required", "encrypted_relay_rejected", "hosted_provider_unavailable", "insufficient_access", "invalid_encrypted_response", "invalid_operation_response", "invalid_request", "missing_grant_key", "mutation_recovery_expired", "mutation_request_conflict", "not_authorized", "operation_cancelled", "operation_failed", "rate_limited", "relay_authorization_expired", "relay_unavailable", "temporarily_unavailable", "timeout", "transport_protocol_incompatible", "unsupported_operation", "collection_configuration_invalid", "collection_invalid", "collection_type_registry_invalid", "collection_version_unsupported", "invalid_path", "operation_invalid"];
+export declare const COLLECTION_QUERY_PROBLEM_CODES: readonly ["access_denied", "access_paused", "application_declaration_mismatch", "authorization_binding_incompatible", "authorization_expired", "capability_contract_incompatible", "collection_access_denied", "connector_identity_changed", "connector_offline", "connector_upgrade_required", "direct_operation_rejected", "durable_mutation_unsupported", "operation_outcome_unknown", "encryption_required", "encrypted_relay_rejected", "hosted_provider_unavailable", "insufficient_access", "invalid_encrypted_response", "invalid_operation_response", "invalid_request", "missing_grant_key", "mutation_recovery_expired", "mutation_request_conflict", "not_authorized", "operation_cancelled", "operation_failed", "rate_limited", "relay_authorization_expired", "relay_unavailable", "temporarily_unavailable", "timeout", "transport_protocol_incompatible", "unsupported_operation", "collection_configuration_invalid", "collection_invalid", "collection_type_registry_invalid", "collection_version_unsupported", "invalid_path", "operation_invalid", "cursor_capacity_exhausted", "generation_expired", "invalid_read_cursor", "query_snapshot_changed", "sandbox_unsupported"];
+export declare const COLLECTION_MUTATION_PROBLEM_CODES: readonly ["access_denied", "access_paused", "application_declaration_mismatch", "authorization_binding_incompatible", "authorization_expired", "capability_contract_incompatible", "collection_access_denied", "connector_identity_changed", "connector_offline", "connector_upgrade_required", "direct_operation_rejected", "durable_mutation_unsupported", "operation_outcome_unknown", "encryption_required", "encrypted_relay_rejected", "hosted_provider_unavailable", "insufficient_access", "invalid_encrypted_response", "invalid_operation_response", "invalid_request", "missing_grant_key", "mutation_recovery_expired", "mutation_request_conflict", "not_authorized", "operation_cancelled", "operation_failed", "rate_limited", "relay_authorization_expired", "relay_unavailable", "temporarily_unavailable", "timeout", "transport_protocol_incompatible", "unsupported_operation", "collection_configuration_invalid", "collection_invalid", "collection_type_registry_invalid", "collection_version_unsupported", "invalid_path", "operation_invalid", "concurrent_modification", "invalid_preflight", "pending_mutation_unresolved"];
+export declare const COLLECTION_CHANGES_PROBLEM_CODES: readonly ["access_denied", "access_paused", "application_declaration_mismatch", "authorization_binding_incompatible", "authorization_expired", "capability_contract_incompatible", "collection_access_denied", "connector_identity_changed", "connector_offline", "connector_upgrade_required", "direct_operation_rejected", "durable_mutation_unsupported", "operation_outcome_unknown", "encryption_required", "encrypted_relay_rejected", "hosted_provider_unavailable", "insufficient_access", "invalid_encrypted_response", "invalid_operation_response", "invalid_request", "missing_grant_key", "mutation_recovery_expired", "mutation_request_conflict", "not_authorized", "operation_cancelled", "operation_failed", "rate_limited", "relay_authorization_expired", "relay_unavailable", "temporarily_unavailable", "timeout", "transport_protocol_incompatible", "unsupported_operation", "collection_configuration_invalid", "collection_invalid", "collection_type_registry_invalid", "collection_version_unsupported", "change_cursor_reset"];
+export declare const COLLECTION_TYPE_PROBLEM_CODES: readonly ["access_denied", "access_paused", "application_declaration_mismatch", "authorization_binding_incompatible", "authorization_expired", "capability_contract_incompatible", "collection_access_denied", "connector_identity_changed", "connector_offline", "connector_upgrade_required", "direct_operation_rejected", "durable_mutation_unsupported", "operation_outcome_unknown", "encryption_required", "encrypted_relay_rejected", "hosted_provider_unavailable", "insufficient_access", "invalid_encrypted_response", "invalid_operation_response", "invalid_request", "missing_grant_key", "mutation_recovery_expired", "mutation_request_conflict", "not_authorized", "operation_cancelled", "operation_failed", "rate_limited", "relay_authorization_expired", "relay_unavailable", "temporarily_unavailable", "timeout", "transport_protocol_incompatible", "unsupported_operation", "collection_configuration_invalid", "collection_invalid", "collection_type_registry_invalid", "collection_version_unsupported", "invalid_path", "operation_invalid", "concurrent_modification", "invalid_preflight", "pending_mutation_unresolved", "type_pack_provision_failed"];
+export declare function connectSuccess<Value>(value: Value, diagnostics?: MdbaseDiagnostic[]): ConnectSuccess<Value>;
+export declare function connectFailure<Code extends ConnectProblemCode>(problem: ConnectProblem<Code>): ConnectFailure<Code>;
+export declare function captureConnectOutcome<Value, Code extends ConnectProblemCode>(operation: () => Promise<Value>, allowedCodes: readonly Code[]): Promise<ConnectOutcome<Value, Code>>;
+export declare class ConnectOutcomeError extends Error {
+    readonly problem: ConnectProblem;
+    constructor(problem: ConnectProblem);
+}
+/** Explicitly opt back into exception flow for scripts and narrow adapters. */
+export declare function unwrapConnectOutcome<Value>(outcome: ConnectOutcome<Value>): Value;

package/dist/outcomes.js

@@ -0,0 +1,194 @@
+import { CONNECT_PROBLEM_CATALOG } from "@mdbase-dev/connect-protocol";
+import { MdbaseConnectError, unknownConnectProblem } from "./errors.js";
+export const COMMON_OPERATION_PROBLEM_CODES = [
+    "access_denied",
+    "access_paused",
+    "application_declaration_mismatch",
+    "authorization_binding_incompatible",
+    "authorization_expired",
+    "capability_contract_incompatible",
+    "collection_access_denied",
+    "connector_identity_changed",
+    "connector_offline",
+    "connector_upgrade_required",
+    "direct_operation_rejected",
+    "durable_mutation_unsupported",
+    "operation_outcome_unknown",
+    "encryption_required",
+    "encrypted_relay_rejected",
+    "hosted_provider_unavailable",
+    "insufficient_access",
+    "invalid_encrypted_response",
+    "invalid_operation_response",
+    "invalid_request",
+    "missing_grant_key",
+    "mutation_recovery_expired",
+    "mutation_request_conflict",
+    "not_authorized",
+    "operation_cancelled",
+    "operation_failed",
+    "rate_limited",
+    "relay_authorization_expired",
+    "relay_unavailable",
+    "temporarily_unavailable",
+    "timeout",
+    "transport_protocol_incompatible",
+    "unsupported_operation"
+];
+export const ALL_CONNECT_PROBLEM_CODES = Object.keys(CONNECT_PROBLEM_CATALOG);
+export const REGISTRATION_PROBLEM_CODES = [
+    "discovery_failed",
+    "invalid_operation_response",
+    "invalid_application_manifest",
+    "invalid_request",
+    "manifest_load_failed",
+    "rate_limited",
+    "temporarily_unavailable",
+    "timeout"
+];
+export const AUTHORIZATION_PROBLEM_CODES = [
+    ...REGISTRATION_PROBLEM_CODES,
+    "access_denied",
+    "application_declaration_mismatch",
+    "application_identity_unavailable",
+    "approval_window_blocked",
+    "authorization_binding_incompatible",
+    "authorization_cancelled",
+    "authorization_replayed",
+    "browser_required",
+    "capability_contract_incompatible",
+    "collection_access_denied",
+    "collection_configuration_invalid",
+    "collection_contracts_missing",
+    "collection_incompatible",
+    "collection_invalid",
+    "collection_kind_unsupported",
+    "collection_mismatch",
+    "collection_not_found",
+    "collection_type_registry_invalid",
+    "collection_version_unsupported",
+    "connector_identity_changed",
+    "connector_offline",
+    "connector_upgrade_required",
+    "device_authorization_failed",
+    "durable_mutation_unsupported",
+    "encryption_required",
+    "expired_token",
+    "invalid_application_authorization",
+    "invalid_callback",
+    "invalid_device_authorization_response",
+    "invalid_token_response",
+    "legacy_scope_reauthorization_required",
+    "scope_denied",
+    "reconnect_required",
+    "token_exchange_failed",
+    "transport_protocol_incompatible"
+];
+export const NOTIFICATION_PROBLEM_CODES = [
+    ...REGISTRATION_PROBLEM_CODES,
+    "authorization_expired",
+    "invalid_operation_response",
+    "invalid_push_subscription",
+    "managed_fcm_not_declared",
+    "not_authorized",
+    "notification_criterion_not_declared",
+    "notification_reauthorization_required",
+    "notification_registration_failed",
+    "notification_unregistration_failed",
+    "notifications_not_declared",
+    "notifications_unavailable"
+];
+export const DIRECT_ACCESS_PROBLEM_CODES = [
+    "connector_offline",
+    "connector_upgrade_required",
+    "invalid_operation_response",
+    "not_authorized",
+    "operation_failed",
+    "temporarily_unavailable",
+    "timeout"
+];
+export const SESSION_PROBLEM_CODES = [
+    ...AUTHORIZATION_PROBLEM_CODES,
+    "collection_not_ready",
+    "collection_not_selected",
+    "operation_cancelled",
+    "session_destroyed",
+    "session_not_started",
+    "session_starting",
+    "unknown_collection"
+];
+export const COLLECTION_SETUP_PROBLEM_CODES = [
+    "collection_configuration_invalid",
+    "collection_invalid",
+    "collection_type_registry_invalid",
+    "collection_version_unsupported"
+];
+export const COLLECTION_DESCRIPTION_PROBLEM_CODES = [
+    ...COMMON_OPERATION_PROBLEM_CODES,
+    ...COLLECTION_SETUP_PROBLEM_CODES
+];
+export const COLLECTION_READ_PROBLEM_CODES = [
+    ...COLLECTION_DESCRIPTION_PROBLEM_CODES,
+    "invalid_path",
+    "operation_invalid"
+];
+export const COLLECTION_QUERY_PROBLEM_CODES = [
+    ...COLLECTION_READ_PROBLEM_CODES,
+    "cursor_capacity_exhausted",
+    "generation_expired",
+    "invalid_read_cursor",
+    "query_snapshot_changed",
+    "sandbox_unsupported"
+];
+export const COLLECTION_MUTATION_PROBLEM_CODES = [
+    ...COLLECTION_READ_PROBLEM_CODES,
+    "concurrent_modification",
+    "invalid_preflight",
+    "pending_mutation_unresolved"
+];
+export const COLLECTION_CHANGES_PROBLEM_CODES = [
+    ...COLLECTION_DESCRIPTION_PROBLEM_CODES,
+    "change_cursor_reset"
+];
+export const COLLECTION_TYPE_PROBLEM_CODES = [
+    ...COLLECTION_MUTATION_PROBLEM_CODES,
+    "type_pack_provision_failed"
+];
+export function connectSuccess(value, diagnostics = []) {
+    return { ok: true, value, diagnostics };
+}
+export function connectFailure(problem) {
+    return { ok: false, problem };
+}
+export async function captureConnectOutcome(operation, allowedCodes) {
+    try {
+        return connectSuccess(await operation());
+    }
+    catch (error) {
+        if (!(error instanceof MdbaseConnectError))
+            throw error;
+        const problem = error.problem;
+        if (problem.code === "unknown" || allowedCodes.includes(problem.code)) {
+            return connectFailure(problem);
+        }
+        return connectFailure(unknownConnectProblem(problem.code, problem.message, {
+            details: problem.details,
+            operationOutcome: problem.operation_outcome,
+            traceId: problem.trace_id
+        }));
+    }
+}
+export class ConnectOutcomeError extends Error {
+    problem;
+    constructor(problem) {
+        super(problem.message);
+        this.problem = problem;
+        this.name = "ConnectOutcomeError";
+    }
+}
+/** Explicitly opt back into exception flow for scripts and narrow adapters. */
+export function unwrapConnectOutcome(outcome) {
+    if (!outcome.ok)
+        throw new ConnectOutcomeError(outcome.problem);
+    return outcome.value;
+}

package/dist/pending-mutation-store.d.ts

@@ -0,0 +1,13 @@
+import { type MutationOperationIdentifier } from "@mdbase-dev/connect-protocol";
+import type { PendingMutation } from "./internal-types.js";
+export declare class PendingMutationStore {
+    private readonly storage;
+    private readonly baseKey;
+    constructor(storage: Storage, baseKey: string);
+    list(collectionId: string | null): PendingMutation[];
+    find(collectionId: string | null, requestId: string): PendingMutation | null;
+    identifier(pending: PendingMutation): MutationOperationIdentifier;
+    store(pending: PendingMutation): void;
+    take(requestId: string): PendingMutation | null;
+    private key;
+}

package/dist/pending-mutation-store.js

@@ -0,0 +1,64 @@
+import { isCollectionOperation, mutationOperationIdentifier } from "@mdbase-dev/connect-protocol";
+import { parseStored } from "./runtime-utils.js";
+export class PendingMutationStore {
+    storage;
+    baseKey;
+    constructor(storage, baseKey) {
+        this.storage = storage;
+        this.baseKey = baseKey;
+    }
+    list(collectionId) {
+        if (!collectionId)
+            return [];
+        const legacy = parseStored(this.storage.getItem(this.baseKey));
+        if (validPendingMutation(legacy) && legacy.collectionId === collectionId) {
+            const migratedKey = this.key(legacy.requestId);
+            if (!this.storage.getItem(migratedKey)) {
+                this.storage.setItem(migratedKey, JSON.stringify(legacy));
+            }
+            this.storage.removeItem(this.baseKey);
+        }
+        const keys = [];
+        for (let index = 0; index < this.storage.length; index += 1) {
+            const key = this.storage.key(index);
+            if (key?.startsWith(`${this.baseKey}:`))
+                keys.push(key);
+        }
+        return keys
+            .map((key) => parseStored(this.storage.getItem(key)))
+            .filter((pending) => validPendingMutation(pending) && pending.collectionId === collectionId)
+            .sort((left, right) => left.createdAt - right.createdAt
+            || left.requestId.localeCompare(right.requestId));
+    }
+    find(collectionId, requestId) {
+        return this.list(collectionId)
+            .find((pending) => pending.requestId === requestId) ?? null;
+    }
+    identifier(pending) {
+        return pending.mutation ?? mutationOperationIdentifier(pending.operation, pending.request?.input ?? (pending.operation === "sync" ? { action: "mutate" } : {})) ?? (pending.operation === "sync" ? "sync:mutate" : pending.operation);
+    }
+    store(pending) {
+        this.storage.setItem(this.key(pending.requestId), JSON.stringify(pending));
+    }
+    take(requestId) {
+        const key = this.key(requestId);
+        const pending = parseStored(this.storage.getItem(key));
+        this.storage.removeItem(key);
+        return pending;
+    }
+    key(requestId) {
+        return `${this.baseKey}:${encodeURIComponent(requestId)}`;
+    }
+}
+function validPendingMutation(pending) {
+    return Boolean(pending
+        && typeof pending.collectionId === "string"
+        && typeof pending.requestId === "string"
+        && pending.requestId.length > 0
+        && isCollectionOperation(pending.operation)
+        && typeof pending.inputFingerprint === "string"
+        && Number.isFinite(pending.createdAt)
+        && pending.createdAt > 0
+        && (pending.envelope || pending.request)
+        && (pending.operation === "sync" || mutationOperationIdentifier(pending.operation, pending.request?.input ?? {}) !== null));
+}

package/dist/pending-recovery-transports.d.ts

@@ -0,0 +1,5 @@
+import type { CollectionOperation, OperationTransportProtocolVersion } from "@mdbase-dev/connect-protocol";
+export declare function pendingRecoveryTransports(storage: Storage, storagePrefix: string, operations: readonly CollectionOperation[], collectionId?: string): OperationTransportProtocolVersion[];
+export declare function pendingMutationsUseKey(storage: Storage, baseKey: string, keyHandle: string): boolean;
+export declare function pendingMutationKeyHandles(storage: Storage, baseKey: string): Set<string>;
+export declare function removePendingMutations(storage: Storage, baseKey: string, removeKey: (keyHandle: string) => void): void;

package/dist/pending-recovery-transports.js

@@ -0,0 +1,52 @@
+import { isSupportedOperationTransport, OPERATION_TRANSPORT_PROTOCOL_VERSION } from "@mdbase-dev/connect-protocol";
+import { parseStored } from "./runtime-utils.js";
+export function pendingRecoveryTransports(storage, storagePrefix, operations, collectionId) {
+    const prefix = `${storagePrefix}:pending-mutation:`;
+    const versions = new Set();
+    for (let index = 0; index < storage.length; index += 1) {
+        const key = storage.key(index);
+        if (!key?.startsWith(prefix))
+            continue;
+        const pending = parseStored(storage.getItem(key));
+        if (!pending
+            || !operations.includes(pending.operation)
+            || (collectionId && pending.collectionId !== collectionId))
+            continue;
+        const version = pending.envelope?.protocol_version ?? pending.request?.protocol_version;
+        if (version !== undefined
+            && version !== OPERATION_TRANSPORT_PROTOCOL_VERSION
+            && isSupportedOperationTransport(version)) {
+            versions.add(version);
+        }
+    }
+    return [...versions].sort((left, right) => right - left);
+}
+export function pendingMutationsUseKey(storage, baseKey, keyHandle) {
+    return pendingMutationKeyHandles(storage, baseKey).has(keyHandle);
+}
+export function pendingMutationKeyHandles(storage, baseKey) {
+    const handles = new Set();
+    for (let index = 0; index < storage.length; index += 1) {
+        const key = storage.key(index);
+        if (key !== baseKey && !key?.startsWith(`${baseKey}:`))
+            continue;
+        const pending = parseStored(storage.getItem(key));
+        if (pending?.keyHandle)
+            handles.add(pending.keyHandle);
+    }
+    return handles;
+}
+export function removePendingMutations(storage, baseKey, removeKey) {
+    const keys = [baseKey];
+    for (let index = 0; index < storage.length; index += 1) {
+        const key = storage.key(index);
+        if (key?.startsWith(`${baseKey}:`))
+            keys.push(key);
+    }
+    for (const key of keys) {
+        const pending = parseStored(storage.getItem(key));
+        if (pending?.keyHandle)
+            removeKey(pending.keyHandle);
+        storage.removeItem(key);
+    }
+}

package/dist/popup-authorization.d.ts

@@ -0,0 +1,31 @@
+import type { JsonObject } from "@mdbase-dev/connect-protocol";
+import type { MdbaseAuthorizeOptions, MdbaseAuthorizationOutcome, MdbaseAuthorizationResult, MdbaseConnection } from "./connection.js";
+import type { GrantKeyStore } from "./crypto.js";
+import type { Application, StoredAuthorization } from "./internal-types.js";
+export declare function prepareAuthorizationWindow(input: {
+    options: MdbaseAuthorizeOptions;
+    portableDeclared: boolean;
+    navigate?: (url: string) => void | Promise<void>;
+    register(signal: AbortSignal): Promise<Application>;
+}): Promise<{
+    application: Application;
+    popup: Window | null;
+}>;
+export declare function waitForPopupAuthorization<Frontmatter extends JsonObject>(input: {
+    storage: Storage;
+    storagePrefix: string;
+    state: string;
+    pending: StoredAuthorization;
+    popup: Window;
+    signal: AbortSignal;
+    keyStore: GrantKeyStore;
+    connection(collectionId: string): MdbaseConnection<Frontmatter> | null;
+}): Promise<MdbaseAuthorizationOutcome<Frontmatter>>;
+export declare function publishPopupAuthorizationCompletion<Frontmatter extends JsonObject>(input: {
+    storage: Storage;
+    storagePrefix: string;
+    state: string;
+    pending: StoredAuthorization | null;
+    popupAttempt: boolean;
+    completion: Promise<MdbaseAuthorizationResult<Frontmatter>>;
+}): Promise<MdbaseAuthorizationResult<Frontmatter>>;

package/dist/popup-authorization.js

@@ -0,0 +1,100 @@
+import { abortableDelay } from "./async.js";
+import { MdbaseConnectError, connectError, serverConnectError } from "./errors.js";
+import { parseStored } from "./runtime-utils.js";
+export async function prepareAuthorizationWindow(input) {
+    if (typeof location === "undefined" && !input.navigate && !input.options.openVerification) {
+        throw connectError("browser_required", "Authorization navigation requires a browser environment.");
+    }
+    const popupRequested = input.options.presentation === "popup" || input.portableDeclared;
+    const popup = popupRequested
+        && !input.options.openVerification
+        && !input.navigate
+        && typeof window !== "undefined"
+        ? window.open("", "mdbase-connect-authorization", "popup,width=620,height=760")
+        : null;
+    try {
+        return {
+            application: await input.register(input.options.signal),
+            popup
+        };
+    }
+    catch (error) {
+        popup?.close();
+        throw error;
+    }
+}
+export async function waitForPopupAuthorization(input) {
+    const completionKey = authorizationCompletionKey(input.storagePrefix, input.state);
+    try {
+        while (true) {
+            const completion = parseStored(input.storage.getItem(completionKey));
+            if (completion?.version === 1) {
+                input.storage.removeItem(completionKey);
+                if (completion.status === "failed") {
+                    throw serverConnectError(completion.code, completion.message, {
+                        details: completion.returnTo ? { return_to: completion.returnTo } : undefined
+                    });
+                }
+                const connection = input.connection(completion.collectionId);
+                if (!connection) {
+                    throw connectError("invalid_callback", "Authorization completed without a usable saved connection.");
+                }
+                return {
+                    kind: "connected",
+                    connection,
+                    ...(completion.returnTo ? { returnTo: completion.returnTo } : {})
+                };
+            }
+            // Cross-origin opener isolation may report a live Connect window as
+            // closed. Shared callback state, abort, or the request budget owns exit.
+            await abortableDelay(200, input.signal);
+        }
+    }
+    finally {
+        input.popup.close();
+        input.storage.removeItem(completionKey);
+        const pendingKey = `${input.storagePrefix}:pending:${input.state}`;
+        const outstanding = parseStored(input.storage.getItem(pendingKey));
+        if (outstanding?.state === input.state) {
+            input.storage.removeItem(pendingKey);
+            if (input.pending.keyHandle)
+                await input.keyStore.delete(input.pending.keyHandle);
+        }
+    }
+}
+export function publishPopupAuthorizationCompletion(input) {
+    return input.completion.then((result) => {
+        if (input.popupAttempt)
+            writeCompletion(input, {
+                version: 1,
+                status: "connected",
+                collectionId: result.connection.collectionId,
+                ...(result.returnTo ? { returnTo: result.returnTo } : {})
+            });
+        if (input.popupAttempt)
+            closeCallbackWindow();
+        return result;
+    }).catch((error) => {
+        if (input.popupAttempt)
+            writeCompletion(input, {
+                version: 1,
+                status: "failed",
+                code: error instanceof MdbaseConnectError ? error.code : "invalid_callback",
+                message: error instanceof Error ? error.message : "Authorization could not be completed.",
+                ...(input.pending?.returnTo ? { returnTo: input.pending.returnTo } : {})
+            });
+        if (input.popupAttempt)
+            closeCallbackWindow();
+        throw error;
+    });
+}
+function writeCompletion(input, completion) {
+    input.storage.setItem(authorizationCompletionKey(input.storagePrefix, input.state), JSON.stringify(completion));
+}
+function authorizationCompletionKey(storagePrefix, state) {
+    return `${storagePrefix}:completion:${state}`;
+}
+function closeCallbackWindow() {
+    if (typeof window !== "undefined" && typeof window.close === "function")
+        window.close();
+}

package/dist/query-pagination.d.ts

@@ -0,0 +1,6 @@
+import type { JsonObject } from "@mdbase-dev/connect-protocol";
+import { type CollectionQueryProblemCode, type ConnectOutcome } from "./outcomes.js";
+import type { ConnectRequestOptions, QueryInput, QueryPage, QueryPagesOptions, QueryResult } from "./operation-types.js";
+type QueryOperation<Frontmatter extends JsonObject> = (input: QueryInput, options?: ConnectRequestOptions) => Promise<ConnectOutcome<QueryResult<Frontmatter>, CollectionQueryProblemCode>>;
+export declare function coordinatedQueryPages<Frontmatter extends JsonObject>(query: QueryOperation<Frontmatter>, releaseQueryCursor: (cursor: string) => Promise<void>, input?: QueryInput, options?: QueryPagesOptions<Frontmatter>): AsyncGenerator<ConnectOutcome<QueryPage<Frontmatter>, CollectionQueryProblemCode>>;
+export {};