@mdbase-dev/connect 0.1.0-beta.126 → 0.1.0-beta.148

package/dist/browser/mdbase-connect.min.js.sha384

@@ -1 +1 @@
-sha384-JJDoYra3MuCFJxyktOaw/6TQwPZCx8ZC2YcJhJxOZqXF8xU67X+tyXiEm5KKZwcf
+sha384-rwS4Cs8c/aA1ZdOgYHyRuQz90zVNe1GLeCYRKxXrHsuo777O2T/z+Bu0Mjpf0tBD

package/dist/capabilities.d.ts

@@ -1,5 +1,5 @@
 import { type ApplicationCapabilityRequirements, type LegacyApplicationCapabilityRequirements } from "@mdbase-dev/connect-protocol";
-import type { MdbaseApplicationCapabilityId as ApplicationCapabilityId, MdbaseApplicationManifest as MdbaseAppManifest } from "./application-contract.js";
+import type { MdbaseApplicationCapabilityId as ApplicationCapabilityId, MdbaseApplicationManifest as MdbaseAppManifest } from "@mdbase-dev/connect-protocol";
 import type { MdbaseConnectionInfo } from "./connection-types.js";
 export type MdbaseCapabilityState = "available" | "requires_authorization" | "requires_setup" | "temporarily_unavailable" | "unsupported";
 export interface MdbaseCapabilityEvidence {

package/dist/collection-client.d.ts

@@ -1,4 +1,5 @@
 import type { CollectionOperation, CollectionTypeDocument, JsonObject } from "@mdbase-dev/connect-protocol";
+import { MdbaseQueryObserver, type ObserveOptions } from "./observe.js";
 import { type CollectionChangesProblemCode, type CollectionDescriptionProblemCode, type CollectionMutationProblemCode, type CollectionQueryProblemCode, type CollectionReadProblemCode, type CollectionTypeProblemCode, type ConnectOutcome } from "./outcomes.js";
 import type { ChangesInput, DescribeOptions, CollectionChange, CollectionChangesPage, CollectionDescription, CollectionSetupApplyResult, CollectionSetupAssessment, AssessCollectionSetupInput, AssessTypePackInput, ApplyCollectionSetupInput, ApplyTypePackInput, CreateInput, CreateTypeInput, CreateViewSourceInput, DeleteInput, DeletePreflightResult, DeleteResult, DeleteViewSourceInput, DeleteViewSourceResult, ExecuteViewInput, MdbaseCollectionTransport, MdbaseDesiredTimer, MdbaseTimer, MdbaseTimerList, MdbaseTimerReconciliation, ConnectRequestOptions, QueryAllOptions, QueryInput, QueryMetadataInput, QueryMetadataRecord, QueryMetadataResult, QueryMetadataPage, QueryPage, QueryPagesOptions, QueryResult, ReadInput, ReadManyOptions, ReadManyResult, ReadTypeInput, ReadViewSourceInput, RenameInput, RenamePreflightResult, RenameResult, RecordDocument, SavedViewExecution, SavedViewPage, SavedViewPagesOptions, SavedViewList, SavedViewSourceDocument, TypePackApplyResult, TypePackAssessment, UpdateInput, UpdateTypeInput, UpdateViewSourceInput, WatchOptions } from "./operation-types.js";
 /**
@@ -21,6 +22,7 @@ export declare class MdbaseCollectionClient<Frontmatter extends JsonObject = Jso
     changes(input?: ChangesInput, options?: ConnectRequestOptions): Promise<ConnectOutcome<CollectionChangesPage, CollectionChangesProblemCode>>;
     read(input: ReadInput, options?: ConnectRequestOptions): Promise<ConnectOutcome<RecordDocument<Frontmatter>, CollectionReadProblemCode>>;
     readMany(paths: readonly string[], options?: ReadManyOptions): Promise<ConnectOutcome<ReadManyResult<Frontmatter>, CollectionQueryProblemCode>>;
+    observe(query?: QueryInput, options?: ObserveOptions): MdbaseQueryObserver<Frontmatter>;
     query(input: QueryMetadataInput, options?: ConnectRequestOptions): Promise<ConnectOutcome<QueryMetadataResult, CollectionQueryProblemCode>>;
     query(input?: QueryInput, options?: ConnectRequestOptions): Promise<ConnectOutcome<QueryResult<Frontmatter>, CollectionQueryProblemCode>>;
     query(input: QueryInput | QueryMetadataInput, options?: ConnectRequestOptions): Promise<ConnectOutcome<QueryResult<Frontmatter> | QueryMetadataResult, CollectionQueryProblemCode>>;

package/dist/collection-client.js

@@ -1,8 +1,9 @@
-import { abortableDelay } from "./async.js";
+import { abortableDelay, pollDelay } from "./async.js";
 import { invalidatesDescription, normalizeChangesPage } from "./change-events.js";
 import { CollectionDescriptionCache } from "./description-cache.js";
 import { coordinatedQueryPages } from "./query-pagination.js";
 import { readMany as readManyRecords } from "./read-many.js";
+import { MdbaseQueryObserver } from "./observe.js";
 import { wireDataContractIdentity, wireQueryInput, wireQueryRecord, wireQueryResult } from "./query-wire.js";
 import { coordinatedSavedViewPages } from "./saved-view-pagination.js";
 import { MdbaseConnectError, connectError, connectProblem, operationProblem } from "./errors.js";
@@ -54,13 +55,16 @@ export class MdbaseCollectionClient {
     readMany(paths, options = {}) {
         return readManyRecords((input, requestOptions) => this.queryAll(input, requestOptions), (selected, includeBody, requestOptions) => this.envelopeOperation("read", { paths: selected, include_body: includeBody, include_document: false }, COLLECTION_READ_PROBLEM_CODES, requestOptions), this.supportsAuthorityFeature, paths, options, this.requestTimeoutMs);
     }
+    observe(query = {}, options = {}) {
+        return new MdbaseQueryObserver(this, query, options, this.supportsAuthorityFeature);
+    }
     async query(input = {}, options) {
         if (input.output !== undefined && input.output !== "metadata") {
             return connectFailure(connectProblem("invalid_request", "Unknown query output mode."));
         }
         if (input.output !== "metadata") {
             const outcome = await this.envelopeOperation("query", wireQueryInput(input), COLLECTION_QUERY_PROBLEM_CODES, options);
-            return mapOutcome(outcome, value => wireQueryResult(value, undefined));
+            return mapOutcome(outcome, value => wireQueryResult(value, undefined, input));
         }
         const captured = await captureConnectOutcome(() => withRequestBudget(options, this.requestTimeoutMs, async (budget) => {
             const requestOptions = requestOptionsWithinBudget({ ...options, timeoutMs: null }, budget);
@@ -72,7 +76,7 @@ export class MdbaseCollectionClient {
             if (!support?.value)
                 throw connectError("unsupported_operation", "This authority does not support metadata queries. Use an ordinary query on legacy authorities.");
             const outcome = await this.envelopeOperation("query", wireQueryInput(input), COLLECTION_QUERY_PROBLEM_CODES, requestOptions);
-            return mapOutcome(outcome, value => wireQueryResult(value, input.output));
+            return mapOutcome(outcome, value => wireQueryResult(value, input.output, input));
         }), COLLECTION_QUERY_PROBLEM_CODES);
         return captured.ok ? captured.value : captured;
     }
@@ -309,7 +313,7 @@ export class MdbaseCollectionClient {
             cursor = page.cursor;
             if (!page.hasMore) {
                 try {
-                    await abortableDelay(pollInterval, options.signal);
+                    await pollDelay(pollInterval, options.signal);
                 }
                 catch {
                     if (!options.signal?.aborted)

package/dist/connect-options.d.ts

@@ -1,4 +1,4 @@
-import type { MdbaseApplicationManifest as MdbaseAppManifest } from "./application-contract.js";
+import type { MdbaseApplicationManifest as MdbaseAppManifest } from "@mdbase-dev/connect-protocol";
 import type { JsonObject } from "@mdbase-dev/connect-protocol";
 import type { GrantKeyStore } from "./crypto.js";
 import type { ApplicationIdentityStore } from "./application-identity.js";

package/dist/connect.d.ts

@@ -1,5 +1,5 @@
 import type { JsonObject } from "@mdbase-dev/connect-protocol";
-import { type MdbaseApplicationManifest as MdbaseAppManifest } from "./application-contract.js";
+import { type MdbaseApplicationManifest as MdbaseAppManifest } from "@mdbase-dev/connect-protocol";
 import { type ApplicationIdentityStore } from "./application-identity.js";
 import { MdbaseConnection, type MdbaseAuthorizationOutcome, type MdbaseAuthorizationResult, type MdbaseAuthorizeOptions, type MdbaseConnectEnvironment } from "./connection.js";
 import type { MdbaseConnectOptions } from "./connect-options.js";

package/dist/connect.js

@@ -1,5 +1,5 @@
 import { APPLICATION_AUTHORIZATION_PROTOCOL_VERSION, authorizationContractRequirements, DEFAULT_LOOPBACK_PORT, GRANT_ENCRYPTION_PROTOCOL_VERSION, RELAY_ENCRYPTION_SUITE } from "@mdbase-dev/connect-protocol";
-import { authorizationOperations, authorizationFiles, semanticContractVersion, validateAuthorizationSelection } from "./application-contract.js";
+import { authorizationOperations, authorizationFiles, semanticContractVersion, validateAuthorizationSelection } from "@mdbase-dev/connect-protocol";
 import { abortableDelay } from "./async.js";
 import { authorizationCallbackState } from "./authorization-url.js";
 import { randomBase64Url } from "./base64.js";

package/dist/connection.d.ts

@@ -1,6 +1,6 @@
 import { MdbasePeopleClient } from "./people-client.js";
 import type { CollectionOperation, CollectionTypeDocument, FileCapability, GrantScope, JsonObject } from "@mdbase-dev/connect-protocol";
-import { type MdbaseApplicationCapabilityId as ApplicationCapabilityId } from "./application-contract.js";
+import { type MdbaseApplicationCapabilityId as ApplicationCapabilityId } from "@mdbase-dev/connect-protocol";
 import { MdbaseCollectionClient } from "./collection-client.js";
 import { type ConnectionTransportInternals } from "./connection-transport.js";
 import type { DirectAccessStatus, MdbaseAuthorizationCapabilities, MdbaseConnectionInfo, MdbaseConnectionRoute, MdbaseSyncConnection } from "./connection-types.js";
@@ -82,6 +82,7 @@ export declare class MdbaseConnection<Frontmatter extends JsonObject = JsonObjec
     readonly records: MdbaseRecords<Frontmatter>;
     readonly people: MdbasePeopleClient;
     readonly readMany: MdbaseCollectionClient<Frontmatter>["readMany"];
+    readonly observe: MdbaseCollectionClient<Frontmatter>["observe"];
     private readonly connectionListeners;
     constructor(internals: MdbaseConnectionInternals<Frontmatter>, collectionId: string);
     get displayName(): string;

package/dist/connection.js

@@ -1,6 +1,6 @@
 import { MdbasePeopleClient, requestPeople } from "./people-client.js";
 import { capabilityOperationsForContractVersion } from "@mdbase-dev/connect-protocol";
-import { retainedCapabilities, semanticContractVersion, validateAuthorizationSelection } from "./application-contract.js";
+import { retainedCapabilities, semanticContractVersion, validateAuthorizationSelection } from "@mdbase-dev/connect-protocol";
 import { MdbaseCollectionClient } from "./collection-client.js";
 import { AuthorityFeatures, authorityCapabilities } from "./authority-features.js";
 import { filePage } from "./file-metadata.js";
@@ -28,6 +28,7 @@ export class MdbaseConnection {
     records;
     people;
     readMany;
+    observe;
     connectionListeners = new Set();
     constructor(internals, collectionId) {
         this.internals = internals;
@@ -88,6 +89,7 @@ export class MdbaseConnection {
             operation: (operation, input, requestOptions) => this.transport.performOperation(operation, input, requestOptions)
         }, internals.timeouts.requestMs), internals.timeouts.requestMs, (id, options) => this.supportsAuthorityFeature(id, options));
         this.readMany = this.collectionClient.readMany.bind(this.collectionClient);
+        this.observe = this.collectionClient.observe.bind(this.collectionClient);
         this.notifications = new ConnectionNotifications({
             serverUrl: internals.serverUrl,
             storage: internals.storage,

package/dist/control-timers.d.ts

@@ -0,0 +1,43 @@
+/** Fixed control-plane timer/channel requests, never data-replica operations. */
+import type { MdbaseConnection } from "./connection.js";
+import type { ConnectRequestOptions } from "./operation-types.js";
+export interface TimerChannelRegistration {
+    channelId: string;
+    installationId: string;
+    criteria: string[];
+}
+export interface WebPushTimerOptions extends ConnectRequestOptions {
+    serviceWorker: ServiceWorkerRegistration;
+    criteria?: string[];
+    installationId?: string;
+}
+export interface FcmTimerOptions extends ConnectRequestOptions {
+    token: string;
+    criteria?: string[];
+    installationId?: string;
+}
+/** Structurally implements the NEXT SDK's AppTimersPort without an SDK dependency. */
+export interface ConnectAppTimersPort {
+    list(namespace: string, options: ConnectRequestOptions): Promise<unknown>;
+    put(namespace: string, id: string, body: {
+        criterion_id: string;
+        fire_at: string;
+    }, options: ConnectRequestOptions): Promise<unknown>;
+    cancel(namespace: string, id: string, generation: number | undefined, options: ConnectRequestOptions): Promise<unknown>;
+    reconcile(namespace: string, body: {
+        criterion_id: string;
+        timers: {
+            id: string;
+            fire_at: string;
+        }[];
+    }, options: ConnectRequestOptions): Promise<unknown>;
+    registerWebPush(options: WebPushTimerOptions): Promise<TimerChannelRegistration>;
+    unregisterWebPush(serviceWorker: ServiceWorkerRegistration | undefined, options: ConnectRequestOptions): Promise<void>;
+    registerFcm(options: FcmTimerOptions): Promise<TimerChannelRegistration & {
+        transport: "fcm";
+    }>;
+    unregisterFcm(options: ConnectRequestOptions): Promise<void>;
+    close(): void;
+}
+/** Bind one app consent; scope/mode decisions remain the control plane's authority. */
+export declare function appTimers(connection: MdbaseConnection): ConnectAppTimersPort;

package/dist/control-timers.js

@@ -0,0 +1,290 @@
+import { connectError, MdbaseConnectError } from "./errors.js";
+import { base64UrlBytes, bytesToBase64Url, randomBase64Url } from "./base64.js";
+import { requestAbortReason, withCooperativeRequestBudget } from "./request-budget.js";
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
+const NS = /^[A-Za-z0-9._-]{1,64}$/u;
+const ID = /^[A-Za-z0-9._:-]{1,128}$/u;
+const fail = () => connectError("invalid_request", "Invalid opaque timer or channel input.");
+function segment(s, pattern) {
+    if (typeof s !== "string" || !pattern.test(s))
+        throw fail();
+    return encodeURIComponent(s);
+}
+function desired(body) {
+    if (!body || typeof body.criterion_id !== "string" || !body.criterion_id.length || body.criterion_id.length > 100
+        || typeof body.fire_at !== "string" || !Number.isFinite(Date.parse(body.fire_at)))
+        throw fail();
+    return { criterion_id: body.criterion_id, fire_at: body.fire_at };
+}
+function origin(s) {
+    const u = new URL(s);
+    if (u.protocol !== "https:" || u.origin !== s.replace(/\/$/u, ""))
+        throw fail();
+    return u.origin;
+}
+async function boundedJSON(response, signal) {
+    if (response.headers.get("content-type")?.split(";")[0]?.trim().toLowerCase() !== "application/json")
+        throw fail();
+    const reader = response.body?.getReader();
+    if (!reader)
+        throw fail();
+    const chunks = [];
+    let size = 0;
+    const abort = () => { void reader.cancel().catch(() => { }); };
+    signal.addEventListener("abort", abort, { once: true });
+    try {
+        if (signal.aborted)
+            throw requestAbortReason(signal);
+        for (;;) {
+            const r = await reader.read();
+            if (signal.aborted)
+                throw requestAbortReason(signal);
+            if (r.done)
+                break;
+            size += r.value.length;
+            if (size > 1024 * 1024)
+                throw connectError("invalid_operation_response", "Control-plane metadata exceeds the bounded response budget.");
+            chunks.push(r.value);
+        }
+        const bytes = new Uint8Array(size);
+        let at = 0;
+        for (const chunk of chunks) {
+            bytes.set(chunk, at);
+            at += chunk.length;
+        }
+        return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    finally {
+        chunks.length = 0;
+        signal.removeEventListener("abort", abort);
+        await reader.cancel().catch(() => { });
+        reader.releaseLock();
+    }
+}
+/** Bind one app consent; scope/mode decisions remain the control plane's authority. */
+export function appTimers(connection) {
+    const transport = connection["transport"], internals = connection["internals"];
+    const server = origin(transport["serverUrl"]); // Before reading credentials.
+    const initial = transport.currentToken();
+    if (!initial?.grantId || !UUID.test(initial.grantId) || !UUID.test(initial.collectionId) || !initial.keyHandle) {
+        throw connectError("not_authorized", "A retained app consent is required for timers.");
+    }
+    const identity = (t) => JSON.stringify([
+        t.grantId, t.collectionId, t.clientId, t.keyHandle, t.applicationOrigin,
+        t.operations, t.scope, t.encryption, t.nextNoise,
+        t.authority && [t.authority.replicaId, t.authority.operationsUrl, t.authority.syncUrl, t.authority.filesUrl, t.authority.proofPublicKey]
+    ]);
+    const pinned = identity(initial), lifetime = new AbortController();
+    const prefix = `/v1/next/collections/${initial.collectionId}/timers`;
+    const run = async (options, write, operation) => {
+        const signal = options.signal ? AbortSignal.any([options.signal, lifetime.signal]) : lifetime.signal;
+        return withCooperativeRequestBudget({
+            ...options, signal,
+            timeoutMs: options.timeoutMs == null ? 10_000 : Math.min(options.timeoutMs, 10_000)
+        }, 10_000, async (budget) => {
+            const token = transport.currentToken();
+            if (!token || identity(token) !== pinned || !Number.isFinite(token.expiresAt) || token.expiresAt <= Date.now()) {
+                throw connectError("not_authorized", "The retained timer consent is unavailable.");
+            }
+            const snapshot = JSON.stringify(token), leases = transport["grantKeyLeases"]();
+            let dispatched = false;
+            const check = () => {
+                if (budget.signal.aborted)
+                    throw requestAbortReason(budget.signal);
+                const current = transport.currentToken();
+                if (!current || !Number.isFinite(current.expiresAt) || current.expiresAt <= Date.now()
+                    || JSON.stringify(current) !== snapshot || origin(transport["serverUrl"]) !== server) {
+                    throw connectError("authority_authorization_changed", "The retained timer consent changed.");
+                }
+            };
+            try {
+                await leases.retain(token, budget.signal);
+                check();
+                // Private fixed-route helper: never returned or accepted from the caller.
+                const request = async (path, method = "GET", data, noBody = false) => {
+                    check();
+                    const body = data === undefined ? undefined : JSON.stringify(data);
+                    if (body && new TextEncoder().encode(body).length > 2 * 1024 * 1024)
+                        throw fail();
+                    dispatched ||= write && method !== "GET";
+                    const response = await fetch(server + path, { method, signal: budget.signal, redirect: "error", credentials: "omit", cache: "no-store",
+                        headers: { authorization: `Bearer ${token.accessToken}`, ...(body === undefined ? {} : { "content-type": "application/json" }) },
+                        ...(body === undefined ? {} : { body }) });
+                    try {
+                        check();
+                        if (!response.ok)
+                            throw connectError(response.status === 401 || response.status === 403 ? "not_authorized" : "operation_failed", "Control-plane timer or channel request failed.", { status: response.status,
+                                operationOutcome: dispatched && response.status >= 500 ? "unknown" : "rejected" });
+                        const result = noBody ? undefined : await boundedJSON(response, budget.signal);
+                        check();
+                        return result;
+                    }
+                    finally {
+                        if (!response.body?.locked)
+                            await response.body?.cancel().catch(() => { });
+                    }
+                };
+                const result = await operation(request, check, budget.signal);
+                check();
+                return result;
+            }
+            catch (error) {
+                if (error instanceof MdbaseConnectError && error.problem.operation_outcome === "rejected")
+                    throw error;
+                if (dispatched)
+                    throw connectError("operation_failed", "Timer or channel write outcome is unknown.", { operationOutcome: "unknown" });
+                if (budget.signal.aborted)
+                    throw requestAbortReason(budget.signal);
+                if (error instanceof MdbaseConnectError)
+                    throw error;
+                throw connectError("operation_failed", "Control-plane timer or channel request failed.", { operationOutcome: "not_sent" });
+            }
+            finally {
+                leases.release();
+            }
+        });
+    };
+    const registration = async (options, native) => run(options, true, async (request, check, signal) => {
+        const application = await internals.register({ signal, timeoutMs: null });
+        check();
+        const declared = application.notifications?.criteria.map(c => c.id) ?? [];
+        const criteria = [...new Set(options.criteria ?? declared)];
+        if (!criteria.length || criteria.length > 100 || criteria.some(c => !declared.includes(c)))
+            throw fail();
+        if (native && application.notifications?.native_delivery?.mode !== "managed_fcm")
+            throw fail();
+        const storageKey = `${internals.notificationKey(initial.collectionId, native ? "fcm" : "web_push")}:control-timers`;
+        const previous = internals.storage.getItem(storageKey);
+        const saved = previous ? JSON.parse(previous) : null;
+        const installationId = options.installationId ?? (saved && saved.grantId === initial.grantId ? saved.installationId : undefined) ?? randomBase64Url(24);
+        if (typeof installationId !== "string" || !/^[A-Za-z0-9._:-]{1,200}$/u.test(installationId))
+            throw fail();
+        if (saved && saved.grantId === initial.grantId) {
+            if (!saved.channelId || saved.previousTarget !== undefined || saved.pending || !Array.isArray(saved.criteria)) {
+                throw connectError("operation_failed", "Channel registration requires reconciliation before replacement.", { operationOutcome: "unknown" });
+            }
+            if (saved.installationId !== installationId) {
+                throw connectError("operation_failed", "Unregister the acknowledged installation before replacing it.", { operationOutcome: "not_sent" });
+            }
+        }
+        let data;
+        if (native) {
+            const token = options.token;
+            if (typeof token !== "string" || !token.length || token.length > 4096)
+                throw fail();
+            data = { installation_id: installationId, criteria, transport: "fcm", token };
+        }
+        else {
+            const worker = options.serviceWorker;
+            const keyBody = await request("/v1/notifications/vapid-public-key");
+            if (typeof keyBody.public_key !== "string" || !/^[A-Za-z0-9_-]{87}$/u.test(keyBody.public_key))
+                throw fail();
+            const vapid = base64UrlBytes(keyBody.public_key);
+            if (vapid.length !== 65 || vapid[0] !== 4 || bytesToBase64Url(vapid) !== keyBody.public_key)
+                throw fail();
+            let subscription = await worker.pushManager.getSubscription();
+            check();
+            if (!subscription) {
+                subscription = await worker.pushManager.subscribe({ userVisibleOnly: true, applicationServerKey: vapid });
+                try {
+                    check();
+                }
+                catch (error) {
+                    await subscription.unsubscribe().catch(() => false);
+                    throw error;
+                }
+            }
+            const sub = subscription.toJSON();
+            if (!sub.endpoint || !sub.keys?.p256dh || !sub.keys.auth)
+                throw fail();
+            data = { installation_id: installationId, criteria, subscription: { endpoint: sub.endpoint, expirationTime: sub.expirationTime ?? null, keys: sub.keys } };
+        }
+        // Persist only this target. A different acknowledged installation must
+        // first be explicitly unregistered; uncertain targets cannot be replaced.
+        check();
+        if (internals.storage.getItem(storageKey) !== previous) {
+            throw connectError("authority_authorization_changed", "Channel registration context changed.", { operationOutcome: "not_sent" });
+        }
+        const operationNonce = randomBase64Url(24);
+        const pending = JSON.stringify({
+            installationId, grantId: initial.grantId, pending: true, operationNonce,
+            ...(saved && saved.grantId === initial.grantId && saved.installationId === installationId && saved.channelId ? { channelId: saved.channelId } : {})
+        });
+        internals.storage.setItem(storageKey, pending);
+        const result = await request("/v1/notifications/channels", "POST", data);
+        if (typeof result.channel_id !== "string" || !UUID.test(result.channel_id))
+            throw fail();
+        check();
+        if (internals.storage.getItem(storageKey) !== pending) {
+            throw connectError("authority_authorization_changed", "Channel registration context changed.");
+        }
+        const registration = { channelId: result.channel_id, installationId, criteria };
+        internals.storage.setItem(storageKey, JSON.stringify({ ...registration, grantId: initial.grantId, operationNonce }));
+        return registration;
+    });
+    const unregister = async (native, worker, options) => run(options, true, async (request, check) => {
+        const key = `${internals.notificationKey(initial.collectionId, native ? "fcm" : "web_push")}:control-timers`;
+        const saved = internals.storage.getItem(key);
+        if (saved) {
+            const r = JSON.parse(saved);
+            if (r.grantId !== initial.grantId)
+                throw fail();
+            if (!r.channelId || r.previousTarget !== undefined || r.pending || !Array.isArray(r.criteria)) {
+                // An uncertain registration is not proof that no remote channel exists.
+                throw connectError("operation_failed", "Channel registration requires reconciliation before removal.", { operationOutcome: "unknown" });
+            }
+            if (!UUID.test(r.channelId))
+                throw fail();
+            // Serialize mutations through a unique pending marker, including DELETE.
+            // An old channel ID is not a receipt for an uncertain same-target update.
+            const pending = JSON.stringify({ ...r, pending: true, operationNonce: randomBase64Url(24) });
+            internals.storage.setItem(key, pending);
+            await request(`/v1/notifications/channels/${r.channelId}`, "DELETE", undefined, true);
+            check();
+            if (internals.storage.getItem(key) !== pending) {
+                throw connectError("authority_authorization_changed", "Channel registration context changed.");
+            }
+            internals.storage.removeItem(key);
+        }
+        if (worker) {
+            const sub = await worker.pushManager.getSubscription();
+            check();
+            if (internals.storage.getItem(key) !== null) {
+                throw connectError("authority_authorization_changed", "Channel registration context changed.");
+            }
+            if (sub) {
+                await sub.unsubscribe();
+                check();
+                if (internals.storage.getItem(key) !== null) {
+                    throw connectError("authority_authorization_changed", "Channel registration context changed.");
+                }
+            }
+        }
+    });
+    return Object.freeze({
+        list: (ns, o) => run(o, false, request => request(`${prefix}/${segment(ns, NS)}`)),
+        put: (ns, id, body, o) => {
+            const path = `${prefix}/${segment(ns, NS)}/${segment(id, ID)}`, input = desired(body);
+            return run(o, true, request => request(path, "PUT", input));
+        },
+        cancel: (ns, id, generation, o) => run(o, true, request => {
+            if (generation !== undefined && (!Number.isSafeInteger(generation) || generation < 1))
+                throw fail();
+            return request(`${prefix}/${segment(ns, NS)}/${segment(id, ID)}${generation === undefined ? "" : `?generation=${generation}`}`, "DELETE");
+        }),
+        reconcile: (ns, body, o) => {
+            const path = `${prefix}/${segment(ns, NS)}/reconcile`, c = body.criterion_id;
+            if (typeof c !== "string" || !c.length || c.length > 100 || !Array.isArray(body.timers) || body.timers.length > 10_000)
+                throw fail();
+            const timers = body.timers.map(t => { segment(t.id, ID); return { id: t.id, fire_at: desired({ criterion_id: c, fire_at: t.fire_at }).fire_at }; });
+            if (new Set(timers.map(t => t.id)).size !== timers.length)
+                throw fail();
+            return run(o, true, request => request(path, "POST", { criterion_id: c, timers }));
+        },
+        registerWebPush: o => registration({ ...o, criteria: o.criteria ? [...o.criteria] : undefined }, false),
+        unregisterWebPush: (worker, o) => unregister(false, worker, o),
+        registerFcm: async (o) => ({ ...await registration({ ...o, criteria: o.criteria ? [...o.criteria] : undefined }, true), transport: "fcm" }),
+        unregisterFcm: o => unregister(true, undefined, o),
+        close: () => lifetime.abort(),
+    });
+}

package/dist/errors.d.ts

@@ -1,39 +1,14 @@
-import { type ConnectOperationOutcome, type ConnectProblem, type ConnectProblemCode, type ConnectProblemDetailsByCode, type KnownConnectProblem, type MdbaseOperationEnvelope } from "@mdbase-dev/connect-protocol";
+import { MdbaseConnectError, type ConnectOperationOutcome, type ConnectProblem, type KnownConnectProblem, type MdbaseOperationEnvelope } from "@mdbase-dev/connect-protocol";
 interface ProblemOptions {
     operationOutcome?: ConnectOperationOutcome;
     traceId?: string;
     status?: number;
     cause?: unknown;
 }
-type ProblemOptionsFor<Code extends ConnectProblemCode> = ConnectProblemDetailsByCode[Code] extends undefined ? ProblemOptions & {
-    details?: never;
-} : {} extends ConnectProblemDetailsByCode[Code] ? ProblemOptions & {
-    details?: ConnectProblemDetailsByCode[Code];
-} : ProblemOptions & {
-    details: ConnectProblemDetailsByCode[Code];
-};
-type ProblemArguments<Code extends ConnectProblemCode> = ConnectProblemDetailsByCode[Code] extends undefined ? [options?: ProblemOptionsFor<Code>] : {} extends ConnectProblemDetailsByCode[Code] ? [options?: ProblemOptionsFor<Code>] : [options: ProblemOptionsFor<Code>];
-export interface ConnectErrorContext {
-    status?: number;
-    cause?: unknown;
-}
-/** Internal carrier used while adapting throwing transports into public outcomes. */
-export declare class MdbaseConnectError extends Error {
-    readonly problem: ConnectProblem;
-    readonly code: ConnectProblem["code"];
-    readonly status?: number;
-    constructor(problem: ConnectProblem, context?: ConnectErrorContext);
-    get retryable(): boolean;
-    get requiresAuthorization(): boolean;
-    get outcomeUnknown(): boolean;
-    get recovery(): "choose_collection" | "contact_support" | "fix_request" | "none" | "reauthorize" | "refresh" | "repair_collection" | "resolve_conflict" | "resolve_outcome" | "resume_connector_access" | "retry" | "upgrade_application" | "upgrade_collection" | "upgrade_connector";
-    get details(): unknown;
-}
-export declare function connectProblem<Code extends ConnectProblemCode>(code: Code, message: string, ...[options]: ProblemArguments<Code>): KnownConnectProblem<Code>;
+export { MdbaseConnectError, connectError, connectProblem, type ConnectErrorContext } from "@mdbase-dev/connect-protocol";
 export declare function unknownConnectProblem(serverCode: string, message: string, options?: ProblemOptions & {
     details?: unknown;
 }): ConnectProblem;
-export declare function connectError<Code extends ConnectProblemCode>(code: Code, message: string, ...args: ProblemArguments<Code>): MdbaseConnectError;
 export declare function serverConnectError(serverCode: string, message: string, options?: ProblemOptions & {
     details?: unknown;
     status?: number;
@@ -42,4 +17,3 @@ export declare function serverConnectError(serverCode: string, message: string,
 export declare function operationProblem<Result>(envelope: MdbaseOperationEnvelope<Result>): KnownConnectProblem<"collection_configuration_invalid" | "collection_invalid" | "collection_type_registry_invalid" | "collection_version_unsupported" | "concurrent_modification" | "file_not_found" | "invalid_path" | "operation_invalid">;
 /** True only when repeating an operation is safe without asking the user. */
 export declare function isRetryableConnectError(error: unknown): boolean;
-export {};

package/dist/errors.js

@@ -1,48 +1,5 @@
-import { CONNECT_PROBLEM_CATALOG, CONNECT_PROBLEM_VERSION, normalizeConnectProblem } from "@mdbase-dev/connect-protocol";
-/** Internal carrier used while adapting throwing transports into public outcomes. */
-export class MdbaseConnectError extends Error {
-    problem;
-    code;
-    status;
-    constructor(problem, context = {}) {
-        super(problem.message, context.cause === undefined ? undefined : { cause: context.cause });
-        this.problem = problem;
-        this.name = "MdbaseConnectError";
-        this.code = problem.code;
-        this.status = context.status;
-    }
-    get retryable() {
-        return this.problem.recovery === "retry"
-            && this.problem.operation_outcome !== "unknown";
-    }
-    get requiresAuthorization() {
-        return this.problem.category === "authorization";
-    }
-    get outcomeUnknown() {
-        return this.problem.operation_outcome === "unknown";
-    }
-    get recovery() {
-        return this.problem.recovery;
-    }
-    get details() {
-        return this.problem.details;
-    }
-}
-export function connectProblem(code, message, ...[options = {}]) {
-    const definition = CONNECT_PROBLEM_CATALOG[code];
-    return {
-        problem_version: CONNECT_PROBLEM_VERSION,
-        code,
-        category: definition.category,
-        recovery: definition.recovery,
-        message,
-        ...(options.details === undefined ? {} : { details: options.details }),
-        ...(options.operationOutcome === undefined
-            ? {}
-            : { operation_outcome: options.operationOutcome }),
-        ...(options.traceId === undefined ? {} : { trace_id: options.traceId })
-    };
-}
+import { MdbaseConnectError, connectProblem, normalizeConnectProblem } from "@mdbase-dev/connect-protocol";
+export { MdbaseConnectError, connectError, connectProblem } from "@mdbase-dev/connect-protocol";
 export function unknownConnectProblem(serverCode, message, options = {}) {
     return normalizeConnectProblem(serverCode, message, {
         details: options.details,
@@ -50,13 +7,6 @@ export function unknownConnectProblem(serverCode, message, options = {}) {
         trace_id: options.traceId
     });
 }
-export function connectError(code, message, ...args) {
-    const options = args[0];
-    return new MdbaseConnectError(connectProblem(code, message, ...args), {
-        status: options?.status,
-        cause: options?.cause
-    });
-}
 export function serverConnectError(serverCode, message, options = {}) {
     const { status, cause, ...problemOptions } = options;
     return new MdbaseConnectError(normalizeConnectProblem(serverCode, message, {

package/dist/file-transfer-internals.d.ts

@@ -1,6 +1,7 @@
 import type { FileTransferSession, FileTransferStatus, PreparedFilePart } from "@mdbase-dev/connect-protocol";
 import { MdbaseConnectError } from "./errors.js";
 export declare const MAX_OBJECT_ATTEMPTS = 3;
+export declare function validUploadAttempts(value: number | undefined, noAutoAbort?: boolean): number | undefined;
 export declare const MAX_BUFFERED_DOWNLOAD_BYTES: number;
 export declare const UUID: RegExp;
 export declare const SHA256_DIGEST: RegExp;
@@ -15,7 +16,7 @@ export declare function validPageSize(value: number): number;
 export declare function requireTransferSession(session: FileTransferSession, transferId: string, direction: "upload" | "download"): void;
 export declare function requireTransferStatus(status: FileTransferStatus, session: FileTransferSession): void;
 export declare function chunkLength(totalSize: number, partSize: number, index: number): number;
-export declare function retryChunk<Result>(work: () => Promise<Result>, signal?: AbortSignal): Promise<Result>;
+export declare function retryChunk<Result>(work: () => Promise<Result>, signal?: AbortSignal, maxAttempts?: number): Promise<Result>;
 export declare function requirePreparedPart(part: PreparedFilePart, transferId: string, partIndex: number, offset: number, contentLength: number, method: "PUT"): void;
 export declare function browserObjectHeaders(headers: Record<string, string>): Headers;
 export declare function mapConcurrent<Result>(count: number, concurrency: number, work: (index: number) => Promise<Result>): Promise<Result[]>;

package/dist/file-transfer-internals.js

@@ -5,6 +5,13 @@ const HASH_CHUNK_BYTES = 1024 * 1024;
 const DEFAULT_CONCURRENCY = 4;
 const MAX_CONCURRENCY = 8;
 export const MAX_OBJECT_ATTEMPTS = 3;
+export function validUploadAttempts(value, noAutoAbort) {
+    if ((noAutoAbort !== undefined && typeof noAutoAbort !== "boolean")
+        || (value !== undefined && (!Number.isInteger(value) || value < 1 || value > MAX_TRANSIENT_CHUNK_ATTEMPTS))) {
+        throw connectError("invalid_request", "Invalid upload options.");
+    }
+    return value;
+}
 export const MAX_BUFFERED_DOWNLOAD_BYTES = 64 * 1024 * 1024;
 export const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
 export const SHA256_DIGEST = /^sha256:[0-9a-f]{64}$/u;
@@ -144,15 +151,15 @@ function validTransferStrategy(session) {
 export function chunkLength(totalSize, partSize, index) {
     return Math.min(partSize, Math.max(0, totalSize - index * partSize));
 }
-export async function retryChunk(work, signal) {
-    for (let attempt = 1; attempt <= MAX_TRANSIENT_CHUNK_ATTEMPTS; attempt += 1) {
+export async function retryChunk(work, signal, maxAttempts = MAX_TRANSIENT_CHUNK_ATTEMPTS) {
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
         throwIfAborted(signal);
         try {
             return await work();
         }
         catch (error) {
             if (signal?.aborted
-                || attempt === MAX_TRANSIENT_CHUNK_ATTEMPTS
+                || attempt === maxAttempts
                 || (error instanceof MdbaseConnectError && !error.retryable))
                 throw error;
             await waitForTransientChunkRetry(attempt, signal);