@mdbase-dev/connect 0.1.0-beta.31 → 0.1.0-beta.33

package/dist/local-file-transport.js

@@ -3,7 +3,7 @@ import { decryptRelayResponse, encryptRelayRequest } from "./crypto.js";
 import { MdbaseConnectError, connectError, serverConnectError } from "./errors.js";
 import { GrantFileTransferCipher } from "./file-crypto.js";
 import { directFallbackStatus, loopbackRequest } from "./operation-helpers.js";
-import { apiError } from "./runtime-utils.js";
+import { apiError, decodeJsonResponse } from "./runtime-utils.js";
 /** Keeps grant-bound file crypto and loopback framing out of the operation transport. */
 export class LocalFileTransport {
     options;
@@ -39,7 +39,7 @@ export class LocalFileTransport {
         }
         response = await this.sendRelayControl(token, encryptedRequest, signal);
         if (await refreshableBindingFailure(response, token)) {
-            token = await this.options.refreshAuthorization();
+            token = await this.options.refreshAuthorization(signal);
             requireLocalFileToken(token);
             encryptedRequest = await this.encryptControl(token, controlInput);
             response = await this.sendRelayControl(token, encryptedRequest, signal);
@@ -49,7 +49,7 @@ export class LocalFileTransport {
         return this.decryptControlResponse(token, encryptedRequest, response);
     }
     async decryptControlResponse(token, encryptedRequest, response) {
-        const body = await response.json().catch(() => ({}));
+        const body = await decodeJsonResponse(response, "invalid_operation_response", "The collection authority returned an invalid file control response.");
         if (!response.ok) {
             throw apiError(body, "operation_failed", "Collection file request failed.", response.status);
         }
@@ -63,7 +63,7 @@ export class LocalFileTransport {
         return decrypted.result;
     }
     async uploadChunk(session, chunkIndex, bytes, signal) {
-        const token = await this.localFileToken(session, "upload");
+        const token = await this.localFileToken(session, "upload", signal);
         let deliveryToken = token;
         let encoded = await encryptedUploadChunk(this.options.keyStore, deliveryToken, session, chunkIndex, bytes);
         let response;
@@ -86,19 +86,19 @@ export class LocalFileTransport {
         }
         response = await this.sendRelayUpload(deliveryToken, encoded, signal);
         if (response.status === 401 && deliveryToken.refreshToken) {
-            deliveryToken = await this.options.refreshAuthorization();
+            deliveryToken = await this.options.refreshAuthorization(signal);
             requireLocalFileToken(deliveryToken);
             encoded = await encryptedUploadChunk(this.options.keyStore, deliveryToken, session, chunkIndex, bytes);
             response = await this.sendRelayUpload(deliveryToken, encoded, signal);
         }
         if (!response.ok) {
-            const body = await response.json().catch(() => ({}));
+            const body = await decodeJsonResponse(response, "invalid_operation_response", "The collection authority returned an invalid file upload response.");
             throw apiError(body, "operation_failed", "Encrypted file chunk upload failed.", response.status);
         }
         this.options.onRelayAvailable();
     }
     async downloadChunk(session, chunkIndex, signal) {
-        let token = await this.localFileToken(session, "download");
+        let token = await this.localFileToken(session, "download", signal);
         let response;
         if (await this.options.shouldAttemptDirect(token)) {
             try {
@@ -119,7 +119,7 @@ export class LocalFileTransport {
         }
         response = await this.sendRelayDownload(token, session, chunkIndex, signal);
         if (response.status === 401 && token.refreshToken) {
-            token = await this.options.refreshAuthorization();
+            token = await this.options.refreshAuthorization(signal);
             requireLocalFileToken(token);
             response = await this.sendRelayDownload(token, session, chunkIndex, signal);
         }
@@ -129,7 +129,7 @@ export class LocalFileTransport {
     }
     async decryptDownloadResponse(token, session, chunkIndex, response) {
         if (!response.ok) {
-            const body = await response.json().catch(() => ({}));
+            const body = await decodeJsonResponse(response, "invalid_operation_response", "The collection authority returned an invalid file download response.");
             throw apiError(body, "operation_failed", "Encrypted file chunk download failed.", response.status);
         }
         if (response.headers.get("content-type")?.split(";", 1)[0]
@@ -184,8 +184,8 @@ export class LocalFileTransport {
             signal
         });
     }
-    async localFileToken(session, direction) {
-        const token = await this.options.authorizedToken();
+    async localFileToken(session, direction, signal) {
+        const token = await this.options.authorizedToken(signal);
         if (!token || token.authority || !token.fileCapability || !token.encryption
             || !token.grantId || !token.keyHandle
             || session.direction !== direction
@@ -218,7 +218,7 @@ function fileUploadRequest(encoded, signal) {
 async function requireSuccessfulChunkResponse(response, message) {
     if (response.ok)
         return;
-    const body = await response.json().catch(() => ({}));
+    const body = await decodeJsonResponse(response, "invalid_operation_response", "The collection authority returned an invalid file transfer response.");
     throw apiError(body, "operation_failed", message, response.status);
 }
 async function refreshableBindingFailure(response, token) {
@@ -228,7 +228,7 @@ async function refreshableBindingFailure(response, token) {
         return true;
     if (response.status !== 409)
         return false;
-    const body = await response.clone().json().catch(() => null);
+    const body = await decodeJsonResponse(response.clone(), "invalid_operation_response", "The collection authority returned an invalid file response.").catch(() => null);
     return body?.error?.code === "encryption_binding_stale";
 }
 function requireEncryption(token) {

package/dist/mdbase-connect.d.ts

@@ -6,15 +6,17 @@ import { type AuthorizationProblemCode, type ConnectOutcome, type RegistrationPr
 import { MdbaseApplicationSession, type MdbaseApplicationSessionOptions } from "./application-session.js";
 import type { MdbaseUnavailableReason } from "./session.js";
 import type { Application } from "./internal-types.js";
+import type { ConnectRequestOptions } from "./operation-types.js";
 export declare class MdbaseConnect<Frontmatter extends JsonObject = JsonObject> {
     private readonly internals;
     constructor(options: MdbaseConnectOptions);
-    register(): Promise<ConnectOutcome<Application, RegistrationProblemCode>>;
+    register(options?: ConnectRequestOptions): Promise<ConnectOutcome<Application, RegistrationProblemCode>>;
     authorize(options?: MdbaseAuthorizeOptions): Promise<ConnectOutcome<MdbaseAuthorizationOutcome<Frontmatter>, AuthorizationProblemCode>>;
-    createApplicationSession(options: MdbaseApplicationSessionOptions): MdbaseApplicationSession<Frontmatter>;
-    manifest(): Promise<ConnectOutcome<import("@mdbase-dev/connect-protocol").MdbaseAppManifest, RegistrationProblemCode>>;
+    /** The ordinary application lifecycle entry point. */
+    application(options: MdbaseApplicationSessionOptions): MdbaseApplicationSession<Frontmatter>;
+    manifest(options?: ConnectRequestOptions): Promise<ConnectOutcome<import("@mdbase-dev/connect-protocol").MdbaseAppManifest, RegistrationProblemCode>>;
     environment(): MdbaseConnectEnvironment;
-    completeAuthorization(callbackUrl?: string): Promise<ConnectOutcome<MdbaseAuthorizationResult<Frontmatter>, AuthorizationProblemCode>>;
+    completeAuthorization(callbackUrl?: string | URL, options?: ConnectRequestOptions): Promise<ConnectOutcome<MdbaseAuthorizationResult<Frontmatter>, AuthorizationProblemCode>>;
     connections(): MdbaseConnectionInfo[];
     connection(collectionId: string): MdbaseConnection<Frontmatter> | null;
     unavailableReason(collectionId: string): MdbaseUnavailableReason | null;

package/dist/mdbase-connect.js

@@ -7,23 +7,24 @@ export class MdbaseConnect {
     constructor(options) {
         this.internals = new MdbaseConnectInternals(options);
     }
-    register() {
-        return captureConnectOutcome(() => this.internals.register(), REGISTRATION_PROBLEM_CODES);
+    register(options) {
+        return captureConnectOutcome(() => this.internals.register(options), REGISTRATION_PROBLEM_CODES);
     }
     authorize(options = {}) {
         return captureConnectOutcome(() => this.internals.authorize(options), AUTHORIZATION_PROBLEM_CODES);
     }
-    createApplicationSession(options) {
-        return new MdbaseApplicationSession(this, options);
+    /** The ordinary application lifecycle entry point. */
+    application(options) {
+        return new MdbaseApplicationSession(this, options, this.internals.timeouts);
     }
-    manifest() {
-        return captureConnectOutcome(() => this.internals.manifestDeclaration(), REGISTRATION_PROBLEM_CODES);
+    manifest(options) {
+        return captureConnectOutcome(() => this.internals.manifestDeclaration(options), REGISTRATION_PROBLEM_CODES);
     }
     environment() {
         return this.internals.environment();
     }
-    completeAuthorization(callbackUrl) {
-        return captureConnectOutcome(() => this.internals.completeAuthorization(callbackUrl ?? defaultCallbackUrl()), AUTHORIZATION_PROBLEM_CODES);
+    completeAuthorization(callbackUrl, options) {
+        return captureConnectOutcome(() => this.internals.completeAuthorization(callbackUrl === undefined ? defaultCallbackUrl() : String(callbackUrl), options), AUTHORIZATION_PROBLEM_CODES);
     }
     connections() {
         return this.internals.connections();

package/dist/notifications.d.ts

@@ -1,4 +1,5 @@
-export interface MdbaseNotificationRegistrationOptions {
+import type { ConnectRequestOptions } from "./operation-types.js";
+export interface MdbaseNotificationRegistrationOptions extends ConnectRequestOptions {
     serviceWorker: ServiceWorkerRegistration;
     /** Manifest criterion IDs to enable. Omit to enable every declared criterion. */
     criteria?: string[];
@@ -10,7 +11,7 @@ export interface MdbaseNotificationRegistration {
     installationId: string;
     criteria: string[];
 }
-export interface MdbaseNativeNotificationRegistrationOptions {
+export interface MdbaseNativeNotificationRegistrationOptions extends ConnectRequestOptions {
     /** Current FCM registration token. Refresh by calling this method again. */
     token: string;
     /** Manifest criterion IDs to enable. Omit to enable every declared criterion. */

package/dist/operation-helpers.d.ts

@@ -1,4 +1,4 @@
-import type { CollectionOperation } from "@mdbase-dev/connect-protocol";
+import { type CollectionOperation } from "@mdbase-dev/connect-protocol";
 import { MdbaseConnectError } from "./errors.js";
 import type { StoredToken } from "./internal-types.js";
 import type { DeleteInput, DeletePreflightResult, MutationEstimate, RenameInput, RenamePreflightResult } from "./operation-types.js";
@@ -12,7 +12,7 @@ export declare function isMutation(operation: CollectionOperation, input?: unkno
 export declare function uniqueOperations(operations: CollectionOperation[]): CollectionOperation[];
 export declare function sameAuthorization(left: StoredToken, right: StoredToken): boolean;
 export declare function throwIfCancelled(signal?: AbortSignal): void;
-export declare function operationTransportError(error: unknown, signal: AbortSignal | undefined, outcomeUnknown: boolean, unavailableCode: "hosted_provider_unavailable" | "relay_unavailable"): Error;
+export declare function operationTransportError(error: unknown, signal: AbortSignal | undefined, pendingRequestId: string | undefined, unavailableCode: "hosted_provider_unavailable" | "relay_unavailable"): Error;
 export declare function isCancellation(error: unknown, signal?: AbortSignal): boolean;
 export declare function assertRenamePreview(input: RenameInput, preview: RenamePreflightResult): void;
 export declare function assertDeletePreview(input: DeleteInput, preview: DeletePreflightResult): void;
@@ -21,4 +21,4 @@ export declare function deleteEstimate(preview: DeletePreflightResult): Mutation
 export declare function operationFingerprint(operation: CollectionOperation, input: unknown): Promise<string>;
 export declare function canonicalJson(value: unknown): string;
 export declare function sortJson(value: unknown): unknown;
-export declare function unknownMutationOutcome(cause: unknown): MdbaseConnectError;
+export declare function unknownMutationOutcome(requestId: string, cause: unknown): MdbaseConnectError;

package/dist/operation-helpers.js

@@ -1,5 +1,5 @@
+import { isMutatingOperation, mutationFingerprint } from "@mdbase-dev/connect-protocol";
 import { MdbaseConnectError, connectError } from "./errors.js";
-import { bytesToBase64Url } from "./base64.js";
 export function loopbackRequest(init) {
     return { ...init, credentials: "omit", targetAddressSpace: "loopback" };
 }
@@ -20,24 +20,7 @@ export function directFallbackStatus(status) {
     return status === 404 || status === 405 || status === 426 || status >= 500;
 }
 export function isMutation(operation, input) {
-    if (input && typeof input === "object" && !Array.isArray(input)
-        && input.dry_run === true)
-        return false;
-    return (operation === "sync"
-        && input !== null
-        && typeof input === "object"
-        && !Array.isArray(input)
-        && input.action === "mutate")
-        || operation === "create"
-        || operation === "update"
-        || operation === "delete"
-        || operation === "rename"
-        || operation === "create_type"
-        || operation === "update_type"
-        || operation === "apply_type_pack"
-        || operation === "put_timer"
-        || operation === "cancel_timer"
-        || operation === "reconcile_timers";
+    return isMutatingOperation(operation, input);
 }
 export function uniqueOperations(operations) {
     return [...new Set(operations)];
@@ -55,19 +38,21 @@ export function throwIfCancelled(signal) {
         return;
     throw connectError("operation_cancelled", "The operation was cancelled before it changed the collection.", { operationOutcome: "not_sent", cause: signal.reason });
 }
-export function operationTransportError(error, signal, outcomeUnknown, unavailableCode) {
+export function operationTransportError(error, signal, pendingRequestId, unavailableCode) {
     // Problems raised before transport dispatch already describe the
     // authoritative outcome. Do not overwrite them merely because an older
     // pending mutation also exists in storage.
     if (error instanceof MdbaseConnectError)
         return error;
     if (signal?.aborted) {
-        if (outcomeUnknown)
-            return unknownMutationOutcome(error);
+        if (pendingRequestId)
+            return unknownMutationOutcome(pendingRequestId, error);
+        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: error });
     }
-    if (outcomeUnknown) {
-        return unknownMutationOutcome(error);
+    if (pendingRequestId) {
+        return unknownMutationOutcome(pendingRequestId, error);
     }
     if (error instanceof TypeError) {
         return connectError(unavailableCode, unavailableCode === "hosted_provider_unavailable"
@@ -81,21 +66,21 @@ export function isCancellation(error, signal) {
         || (error instanceof MdbaseConnectError && error.code === "operation_cancelled");
 }
 export function assertRenamePreview(input, preview) {
-    if (preview.dry_run !== true || preview.would_rename !== true
+    if (preview.dryRun !== true || preview.wouldRename !== true
         || preview.from !== input.from || preview.to !== input.to) {
         throw connectError("invalid_preflight", "The rename preview does not match this mutation. Run the preview again.");
     }
 }
 export function assertDeletePreview(input, preview) {
-    if (preview.dry_run !== true || preview.would_delete !== true || preview.path !== input.path) {
+    if (preview.dryRun !== true || preview.wouldDelete !== true || preview.path !== input.path) {
         throw connectError("invalid_preflight", "The delete preview does not match this mutation. Run the preview again.");
     }
 }
 export function renameEstimate(input, preview) {
-    if (input.update_refs === false) {
+    if (input.updateRefs === false) {
         return { affectedRecords: 0, totalUnits: 1, warnings: 0 };
     }
-    const references = preview.references_affected ?? [];
+    const references = preview.referencesAffected ?? [];
     return {
         affectedRecords: new Set(references.map((reference) => reference.path)).size,
         totalUnits: 1 + references.length,
@@ -104,15 +89,13 @@ export function renameEstimate(input, preview) {
 }
 export function deleteEstimate(preview) {
     return {
-        affectedRecords: new Set((preview.broken_links ?? []).map((reference) => reference.path)).size,
+        affectedRecords: new Set((preview.brokenLinks ?? []).map((reference) => reference.path)).size,
         totalUnits: 1,
         warnings: 0
     };
 }
 export async function operationFingerprint(operation, input) {
-    const encoded = new TextEncoder().encode(`${operation}\0${canonicalJson(input ?? {})}`);
-    const digest = await crypto.subtle.digest("SHA-256", encoded);
-    return bytesToBase64Url(new Uint8Array(digest));
+    return mutationFingerprint(operation, input ?? {});
 }
 export function canonicalJson(value) {
     return JSON.stringify(sortJson(value));
@@ -128,6 +111,6 @@ export function sortJson(value) {
     }
     return value;
 }
-export function unknownMutationOutcome(cause) {
-    return connectError("operation_outcome_unknown", "The write may have completed, but mdbase could not recover its authoritative result. Retry the exact same write to recover safely.", { operationOutcome: "unknown", cause });
+export function unknownMutationOutcome(requestId, cause) {
+    return connectError("operation_outcome_unknown", "The write may have completed, but mdbase could not recover its authoritative result. Retry the exact same write to recover safely.", { operationOutcome: "unknown", details: { request_id: requestId }, cause });
 }