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

package/README.md

@@ -7,6 +7,13 @@ applications. See the [portable application guide](../../docs/portable-apps.md)
 for the v1 manifest, device-code flow, version-pinned CDN URL, SRI metadata,
 and `file://` storage boundary.
 
+Ordinary applications install only `@mdbase-dev/connect`. Add
+`@mdbase-dev/connect-dev` for declaration/type-pack authoring,
+`@mdbase-dev/connect-testing` for supported test fixtures,
+`@mdbase-dev/connect-sync` for an offline mirror, or the Pickle package only
+when the application uses that feature. Wire and authority implementations use
+`@mdbase-dev/connect-protocol`; ordinary application code does not.
+
 The complete developer guide covers
 [setup](https://mdbase.dev/sdk/quickstart/),
 [manifests and contracts](https://mdbase.dev/sdk/manifest/),
@@ -20,13 +27,21 @@ The complete developer guide covers
 const mdbase = new MdbaseConnect({
   serverUrl: "https://connect.mdbase.dev",
   manifest: new URL(".well-known/mdbase-app.json", location.href).href,
-  redirectUri: "https://workouts.example/auth/mdbase/callback"
+  redirectUri: "https://workouts.example/auth/mdbase/callback",
+  timeouts: {
+    requestMs: 15_000,
+    watchStartMs: 20_000,
+    uploadMs: 120_000,
+    syncMs: 60_000
+  }
 });
-const session = mdbase.createApplicationSession({
+const session = mdbase.application({
   selection: new MdbaseBrowserSelection()
 });
+const unsubscribeSession = session.subscribe(() => render(session.getSnapshot()));
 
-const started = await session.start();
+const startup = new AbortController();
+const started = await session.start({ signal: startup.signal, timeoutMs: 20_000 });
 if (!started.ok) {
   renderProblem(started.problem);
   return;
@@ -49,19 +64,32 @@ if (!queried.ok) {
   return;
 }
 const workouts = queried.value;
+const current = await connection.read({ path: workouts.results[0].path });
+if (!current.ok) {
+  renderProblem(current.problem);
+  return;
+}
 const updated = await connection.update({
-  path: "workouts/monday.md",
+  path: current.value.path,
   patch: { completed: true },
-  if_revision: workouts.results[0].revision
+  ifRevision: current.value.revision
 });
 if (!updated.ok) renderProblem(updated.problem);
 
-for await (const change of connection.watch()) {
-  if (!change.ok) {
-    renderProblem(change.problem);
-    break;
-  }
-  console.log(change.value.type, change.value.payload.path);
+const pageLifetime = new AbortController();
+const watch = await connection.watch(
+  { lifetimeSignal: pageLifetime.signal },
+  { timeoutMs: 20_000 }
+);
+if (!watch.ok) {
+  renderProblem(watch.problem);
+} else {
+  const unsubscribeWatch = watch.value.subscribe(
+    (change) => console.log(change.type, change.payload.path),
+    renderWatchStatus,
+    renderProblem
+  );
+  // On navigation: unsubscribeWatch(); watch.value.close();
 }
 ```
 
@@ -70,6 +98,51 @@ reserved for programming errors and broken SDK invariants. See
 [typed outcomes and recovery](../../docs/sdk-outcomes.md) for the complete
 problem model, setup failures, mutation uncertainty, and UI guidance.
 
+SDK call options, operation inputs, results, descriptors, and progress events
+use camelCase. The client translates canonical snake_case protocol payloads at
+the authority boundary. Versioned JSON documents such as `MdbaseAppManifest`
+and `TypePackProvision`, problem detail objects, diagnostics, and user-owned
+frontmatter retain the exact field names defined by their own schemas.
+
+React applications can use the same session without introducing another state
+owner:
+
+```ts
+const store = externalStore(session);
+
+function useMdbaseSession() {
+  return useSyncExternalStore(
+    store.subscribe,
+    store.getSnapshot,
+    store.getSnapshot
+  );
+}
+```
+
+Browser and native callbacks share the same typed completion boundary:
+
+```ts
+const browserResult = await session.completeAuthorization(location.href, {
+  timeoutMs: 15_000
+});
+const nativeResult = await session.completeAuthorization(deepLinkUrl, {
+  signal: appForeground.signal,
+  timeoutMs: 15_000
+});
+```
+
+Unknown writes are recovered through their durable handles, never by calling
+the original mutation again with reconstructed input:
+
+```ts
+for (const pending of connection.pendingMutations()) {
+  showRecoveryAction(pending.requestId, async () => {
+    const recovered = await pending.recover({ timeoutMs: 30_000 });
+    if (!recovered.ok) renderProblem(recovered.problem);
+  });
+}
+```
+
 `MdbaseConnect` is the application-level authorization registry.
 `MdbaseApplicationSession` is the normal application boundary: it owns active
 collection selection, authorization completion, semantic capabilities,
@@ -78,16 +151,16 @@ versioned capabilities in their manifest; they never maintain a parallel array
 of protocol operations. Use `getSnapshot()` and `subscribe()` directly or
 through your framework's external-store integration.
 
-The session distinguishes `authorization_required`, `checking_definitions`,
-`definition_review_required`, `ready`, `unavailable`, and `blocked`. Definition
+The session distinguishes `authorization_required`, `checking_setup`,
+`setup_review_required`, `ready`, `unavailable`, and `blocked`. Setup
 inspection is read-only. If an update is needed, render the supplied plan and
 apply the exact assessment the user reviewed:
 
 ```ts
 const snapshot = session.getSnapshot();
-if (snapshot.status === "definition_review_required") {
-  renderDefinitionChanges(snapshot.updates);
-  const applied = await session.applyDefinitionUpdates();
+if (snapshot.status === "setup_review_required") {
+  renderCollectionSetup(snapshot.update);
+  const applied = await session.applyCollectionSetup({ timeoutMs: 30_000 });
   if (!applied.ok) renderProblem(applied.problem);
 }
 ```
@@ -213,10 +286,10 @@ one-shot reminders at the collection authority:
 ```ts
 await connection.reconcileTimers({
   namespace: "workout-reminders",
-  criterion_id: "workout.reminder",
+  criterionId: "workout.reminder",
   timers: [{
     id: "workout-42",
-    fire_at: new Date("2026-07-25T10:00:00Z").toISOString()
+    fireAt: new Date("2026-07-25T10:00:00Z").toISOString()
   }]
 });
 ```
@@ -257,7 +330,7 @@ if (!current.ok) return renderProblem(current.problem);
 const updatedType = await connection.updateType({
   path: current.value.path,
   document: current.value.document.replace("version: 1", "version: 2"),
-  if_revision: current.value.revision
+  ifRevision: current.value.revision
 });
 if (!updatedType.ok) renderProblem(updatedType.problem);
 ```
@@ -275,15 +348,15 @@ const provision = await response.json();
 const installedBy = "dev.example.catalog";
 const assessment = await connection.assessTypePack({
   provision,
-  installed_by: installedBy
+  installedBy
 });
 if (!assessment.ok) return renderProblem(assessment.problem);
 
 renderDefinitionChanges(assessment.value);
 const applied = await connection.applyTypePack({
   provision,
-  installed_by: installedBy,
-  expected_assessment_digest: assessment.value.assessment_digest
+  installedBy,
+  expectedAssessmentDigest: assessment.value.assessmentDigest
 });
 if (!applied.ok) return renderProblem(applied.problem);
 ```
@@ -413,10 +486,13 @@ is not granted collection-wide type-management access.
 
 The SDK returns typed outcomes, carries successful mdbase diagnostics alongside
 the value, carries revision tokens in typed record results, and accepts
-`if_revision` on mutations. `describe()` exposes
+`ifRevision` on mutations. `describe()` exposes
 JSON Schemas, portable type definitions, canonical collection settings, and
 first-class data contracts. `watch()` resumes from a local collection cursor;
 the Connect server does not store the change feed.
+`queryAll()` treats `timeoutMs` as one deadline for the complete paginated
+query. The caller-driven `queryPages()` iterator instead accepts
+`pageTimeoutMs`, an independent budget for each page, plus a lifetime `signal`.
 `preflightRename()` and `preflightDelete()` run the canonical collection
 operation without changing records or advancing the change cursor, so an app
 can show authoritative reference impact before asking for confirmation.
@@ -424,10 +500,11 @@ can show authoritative reference impact before asking for confirmation.
 applying, completed, and cancelled phases with an impact estimate. Cancellation
 remains available during an encrypted local/relay mutation because the SDK
 persists its exact encrypted request before dispatch. If waiting is cancelled
-after dispatch, `pendingMutation()` reports the interruption and
-`resumePendingMutation()` safely recovers the connector's durable receipt using
-the exact same input. Other providers are cancellable until apply begins and
-then run to a definitive response.
+after dispatch, `pendingMutations()` exposes durable handles. A handle's
+`recover()` method resends the exact stored request identity and bytes; callers
+never reconstruct or resupply mutation input. Multiple interrupted writes are
+independently recoverable. Other providers are cancellable until apply begins
+and then run to a definitive response.
 Authorization is retained in `localStorage` by default. Access tokens are
 renewed with rotating refresh tokens; passing a custom `Storage` implementation
 allows a host to choose another persistence boundary.
@@ -441,13 +518,14 @@ and the shell passes that URL to `completeAuthorization()`. PKCE prevents the
 callback code from being exchanged without the pending application state and
 verifier.
 
-New authorizations require encrypted relay protocol 1 by default. The SDK keeps
-independent non-extractable P-256 ECDH agreement and ECDSA signing keys plus an
-atomic message counter in IndexedDB. It encrypts operation inputs for the
-connector, decrypts connector results locally, and signs hosted authority
-requests with the independent signing key. Set `relayEncryption: "disabled"`
-only for development where end-to-end relay encryption is intentionally
-unavailable; an encrypted grant never falls back to plaintext.
+New authorizations require operation transport v2 and grant encryption profile
+v1 by default. The SDK keeps independent non-extractable P-256 ECDH agreement
+and ECDSA signing keys plus an atomic message counter in IndexedDB. It encrypts
+operation inputs for the connector, decrypts connector results locally, and
+signs hosted authority requests with the independent signing key. Set
+`relayEncryption: "disabled"` only for development where end-to-end relay
+encryption is intentionally unavailable; an encrypted grant never falls back
+to plaintext.
 
 For a hosted collection, the same authorization exchange returns a short-lived,
 grant-bound provider capability. The SDK routes operations directly to the

package/dist/advanced.d.ts

@@ -0,0 +1,9 @@
+/** Low-level construction and test seams. Ordinary applications use the root package. */
+export { MdbaseCollectionClient } from "./collection-client.js";
+export type { MdbaseCollectionTransport } from "./operation-types.js";
+export { createPkce } from "./runtime-utils.js";
+export { connectError, connectProblem, operationProblem } from "./errors.js";
+export { connectFailure, connectSuccess } from "./outcomes.js";
+export type { MdbaseApplicationVerificationStore, MdbaseApplicationSessionConnect } from "./application-session.js";
+export { MdbaseSession } from "./session.js";
+export type { MdbaseSessionConnect, MdbaseSessionOptions } from "./session.js";

package/dist/advanced.js

@@ -0,0 +1,6 @@
+/** Low-level construction and test seams. Ordinary applications use the root package. */
+export { MdbaseCollectionClient } from "./collection-client.js";
+export { createPkce } from "./runtime-utils.js";
+export { connectError, connectProblem, operationProblem } from "./errors.js";
+export { connectFailure, connectSuccess } from "./outcomes.js";
+export { MdbaseSession } from "./session.js";

package/dist/application-session.d.ts

@@ -1,12 +1,16 @@
-import { type ApplicationCapabilityId, type JsonObject, type MdbaseAppManifest, type TypePackAssessment } from "@mdbase-dev/connect-protocol";
+import { type ApplicationCapabilityId, type JsonObject, type MdbaseAppManifest } from "@mdbase-dev/connect-protocol";
 import { type MdbaseEffectiveCapabilities } from "./capabilities.js";
 import type { MdbaseAuthorizationOutcome, MdbaseAuthorizeOptions, MdbaseConnection } from "./connection.js";
 import type { MdbaseConnectionInfo } from "./connection-types.js";
 import { type ConnectOutcome, type CollectionTypeProblemCode, type AuthorizationProblemCode, type RegistrationProblemCode, type SessionProblemCode } from "./outcomes.js";
 import type { MdbaseApplicationSelection, MdbaseSelectionHistory } from "./selection.js";
+import type { CollectionSetupAssessment, ConfigurationSetupAssessment, ConnectRequestOptions, TypePackAssessment } from "./operation-types.js";
+import { type ResolvedConnectTimeouts } from "./request-budget.js";
+import type { Application } from "./internal-types.js";
 import { type MdbaseSessionConnect, type MdbaseUnavailableReason } from "./session.js";
 export interface MdbaseApplicationSessionConnect<Frontmatter extends JsonObject = JsonObject> extends MdbaseSessionConnect<Frontmatter> {
-    manifest(): Promise<ConnectOutcome<MdbaseAppManifest, RegistrationProblemCode>>;
+    register(options?: ConnectRequestOptions): Promise<ConnectOutcome<Application, RegistrationProblemCode>>;
+    manifest(options?: ConnectRequestOptions): Promise<ConnectOutcome<MdbaseAppManifest, RegistrationProblemCode>>;
 }
 export interface MdbaseApplicationSessionOptions {
     selection: MdbaseApplicationSelection;
@@ -33,7 +37,18 @@ export interface MdbaseDefinitionUpdate {
     currentVersion?: string;
     desiredVersion: string;
     resources: TypePackAssessment["resources"];
-    contractSetups: TypePackAssessment["contract_setups"];
+    contractSetups: TypePackAssessment["contractSetups"];
+    canApply: boolean;
+    reason: string;
+}
+export interface MdbaseCollectionSetupUpdate {
+    status: CollectionSetupAssessment["status"];
+    applicable: boolean;
+    assessmentDigest: string;
+    collectionRevision: string;
+    provisionDigest: string;
+    configuration: ConfigurationSetupAssessment[];
+    typePacks: MdbaseDefinitionUpdate[];
     canApply: boolean;
     reason: string;
 }
@@ -52,10 +67,10 @@ export type MdbaseApplicationSessionSnapshot = {
 } | ({
     status: "authorization_required";
 } & ApplicationSessionContext) | ({
-    status: "checking_definitions";
+    status: "checking_setup";
 } & ApplicationSessionContext) | ({
-    status: "definition_review_required";
-    updates: MdbaseDefinitionUpdate[];
+    status: "setup_review_required";
+    update: MdbaseCollectionSetupUpdate;
 } & ApplicationSessionContext) | ({
     status: "ready";
     verification: "cached" | "verified";
@@ -75,22 +90,29 @@ export type MdbaseApplicationSessionSnapshot = {
 /**
  * The application-level lifecycle boundary. It derives authorization from the
  * bundled manifest, exposes semantic capabilities, and never mutates collection
- * definitions without an explicit `applyDefinitionUpdates` call.
+ * setup without an explicit `applyCollectionSetup` call.
  */
 export declare class MdbaseApplicationSession<Frontmatter extends JsonObject = JsonObject> {
     private readonly connect;
     private readonly options;
+    private readonly timeouts;
     private readonly listeners;
     private readonly verificationStore;
     private snapshot;
     private manifest;
+    private application;
     private base;
     private stopBase?;
-    private reviewEntries;
+    private setupAssessment;
     private verificationGeneration;
-    constructor(connect: MdbaseApplicationSessionConnect<Frontmatter>, options: MdbaseApplicationSessionOptions);
-    start(): Promise<ConnectOutcome<MdbaseApplicationSessionSnapshot, SessionProblemCode>>;
+    private lifecycleGeneration;
+    private startOperation;
+    constructor(connect: MdbaseApplicationSessionConnect<Frontmatter>, options: MdbaseApplicationSessionOptions, timeouts?: ResolvedConnectTimeouts);
+    start(options?: ConnectRequestOptions): Promise<ConnectOutcome<MdbaseApplicationSessionSnapshot, SessionProblemCode>>;
+    private beginStart;
+    private startWithinBudget;
     destroy(): void;
+    private cleanupBase;
     getSnapshot(): MdbaseApplicationSessionSnapshot;
     subscribe(listener: () => void): () => void;
     connection(): MdbaseConnection<Frontmatter> | null;
@@ -104,17 +126,20 @@ export declare class MdbaseApplicationSession<Frontmatter extends JsonObject = J
     authorize(target: "choose" | "selected" | {
         collectionId: string;
     }, options?: Omit<MdbaseAuthorizeOptions, "operations" | "returnTo" | "target">): Promise<ConnectOutcome<MdbaseAuthorizationOutcome<Frontmatter>, SessionProblemCode>>;
-    handleAuthorizationCallback(callbackUrl: string): Promise<ConnectOutcome<MdbaseConnection<Frontmatter>, AuthorizationProblemCode>>;
-    ensureCapabilities(capabilities: ApplicationCapabilityId[]): Promise<ConnectOutcome<MdbaseAuthorizationOutcome<Frontmatter> | {
+    handleAuthorizationCallback(callbackUrl: string | URL, options?: ConnectRequestOptions): Promise<ConnectOutcome<MdbaseConnection<Frontmatter>, AuthorizationProblemCode>>;
+    completeAuthorization(callbackUrl?: string | URL, options?: ConnectRequestOptions): Promise<ConnectOutcome<MdbaseConnection<Frontmatter>, AuthorizationProblemCode>>;
+    ensureCapabilities(capabilities: ApplicationCapabilityId[], options?: ConnectRequestOptions): Promise<ConnectOutcome<MdbaseAuthorizationOutcome<Frontmatter> | {
         kind: "unchanged";
         connection: MdbaseConnection<Frontmatter>;
     }, SessionProblemCode>>;
-    applyDefinitionUpdates(): Promise<ConnectOutcome<MdbaseApplicationSessionSnapshot, CollectionTypeProblemCode | "collection_not_ready">>;
+    applyCollectionSetup(options?: ConnectRequestOptions): Promise<ConnectOutcome<MdbaseApplicationSessionSnapshot, CollectionTypeProblemCode | "collection_not_ready">>;
     private refresh;
-    private verifyDefinitions;
+    private verifySetup;
+    private collectionSetupInput;
     private context;
     private publish;
     private requireBase;
     private requireManifest;
+    private requireApplication;
 }
 export {};