@mdbase-dev/connect 0.1.0-beta.21 → 0.1.0-beta.23

package/README.md

@@ -27,49 +27,49 @@ const session = mdbase.createSession({
   selection: new MdbaseBrowserSelection()
 });
 
-await session.start();
+const started = await session.start();
+if (!started.ok) {
+  renderProblem(started.problem);
+  return;
+}
 if (session.getSnapshot().status === "unselected") {
-  await session.authorize("choose");
+  const authorized = await session.authorize("choose");
+  if (!authorized.ok) {
+    renderProblem(authorized.problem);
+    return;
+  }
 }
 
 const snapshot = session.getSnapshot();
 if (snapshot.status !== "ready") throw new Error("Choose an authorized collection.");
 const connection = snapshot.connection;
-const description = await connection.describe();
-const workouts = await connection.query({ types: ["workout"] });
-await connection.update({
+const queried = await connection.query({ types: ["workout"] });
+if (!queried.ok) {
+  renderProblem(queried.problem);
+  return;
+}
+const workouts = queried.value;
+const updated = await connection.update({
   path: "workouts/monday.md",
   patch: { completed: true },
-  if_revision: workouts.result.results[0].revision
-});
-
-const preview = await connection.preflightRename({
-  from: "workouts/monday.md",
-  to: "archive/monday.md",
-  update_refs: true,
-  if_revision: workouts.result.results[0].revision
-});
-console.log(preview.result.references_affected);
-
-const controller = new AbortController();
-await connection.renameWithProgress({
-  from: "workouts/monday.md",
-  to: "archive/monday.md",
-  update_refs: true,
-  if_revision: workouts.result.results[0].revision
-}, {
-  preflight: preview.result,
-  signal: controller.signal,
-  onProgress: ({ state, estimate, cancellable }) => {
-    console.log(state, estimate?.affectedRecords, cancellable);
-  }
+  if_revision: workouts.results[0].revision
 });
+if (!updated.ok) renderProblem(updated.problem);
 
 for await (const change of connection.watch()) {
-  console.log(change.type, change.payload.path);
+  if (!change.ok) {
+    renderProblem(change.problem);
+    break;
+  }
+  console.log(change.value.type, change.value.payload.path);
 }
 ```
 
+Expected failures are returned as typed `ConnectOutcome` values. Exceptions are
+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.
+
 `MdbaseConnect` is the application-level authorization registry.
 `MdbaseSession` is the normal application boundary: it owns active collection
 selection, authorization callback completion, access capabilities, and one
@@ -174,8 +174,8 @@ if (!capabilities.sufficient) {
 `requestOperations()` is a no-op when the current grant is sufficient. When a
 replacement grant is needed, it requests the least-privilege union of the
 already granted operations and the missing requirements. An
-`insufficient_access` error carries the same `grantedOperations`,
-`missingOperations`, and `requiredOperations` metadata with a `reauthorize`
+An `insufficient_access` problem carries the same `granted_operations`,
+`missing_operations`, and `required_operations` metadata with a `reauthorize`
 recovery action.
 
 Applications that declare an `mdbase.runtime.timer.fired` notification criterion can keep
@@ -222,12 +222,15 @@ schema:
 `
 });
 
+if (!created.ok) return renderProblem(created.problem);
 const current = await connection.readType({ name: "workout" });
-await connection.updateType({
-  path: current.result.path,
-  document: current.result.document.replace("version: 1", "version: 2"),
-  if_revision: current.result.revision
+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
 });
+if (!updatedType.ok) renderProblem(updatedType.problem);
 ```
 
 Request `read_type`, `create_type`, and `update_type` during authorization.
@@ -250,7 +253,8 @@ For a local collection, ask for same-computer access from a user gesture:
 
 ```ts
 const status = await connection.checkDirectAccess();
-if (status === "permission_required") {
+if (!status.ok) return renderProblem(status.problem);
+if (status.value === "permission_required") {
   directButton.onclick = () => connection.requestDirectAccess();
 }
 
@@ -353,8 +357,9 @@ installs each missing type pack transactionally, verifies its exact contracts
 and implementations, and creates the scoped grant afterward. The application
 is not granted collection-wide type-management access.
 
-The SDK returns the mdbase operation envelope, carries revision tokens in typed
-record results, and accepts `if_revision` on mutations. `describe()` exposes
+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
 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.
@@ -399,6 +404,71 @@ local and hosted authorities.
 provider credential. It refreshes the grant-bound capability as needed and can
 be passed directly to `@mdbase-dev/connect-sync` for an offline application cache.
 
+Applications request non-Markdown files separately from record contracts:
+
+```ts
+requirements: {
+  contracts: [],
+  files: {
+    actions: ["list", "read", "add", "replace", "move", "delete"],
+    scope: { kind: "selected_folders", folders: ["Photos"] }
+  }
+}
+```
+
+The granted connection exposes one storage-neutral facade. Hosted uploads go
+directly to private R2 objects through short-lived prepared requests. Downloads
+use authenticated bounded ranges so the authority can recheck access between
+parts. Object keys, multipart ETags, provider credentials, retries, and
+integrity checks stay inside the SDK.
+
+```ts
+const saved = await connection.files.upload("Photos/image.jpg", browserFile, {
+  onProgress: ({ phase, transferredBytes, totalBytes }) => {
+    console.log(phase, transferredBytes, totalBytes);
+  }
+});
+
+const large = await connection.files.uploadStream("Media/video.mp4", {
+  size: manifest.size,
+  contentDigest: manifest.sha256,
+  stream: response.body!
+});
+
+for await (const file of connection.files.list({ folder: "Photos" })) {
+  const stream = await connection.files.downloadStream(file);
+  await stream.pipeTo(destination);
+}
+
+const moved = await connection.files.move(saved, "Archive/image.jpg");
+await connection.files.delete(moved);
+```
+
+`download()` and `downloadBytes()` are convenient for values up to 64 MiB.
+Use `downloadStream()` for larger files; it verifies the pinned revision while
+forwarding response chunks with native stream backpressure rather than
+buffering a complete hosted range.
+The live stream retries unopened chunks and can switch a local download between
+direct and relay. It does not persist progress after consumption stops or
+resume a hosted range after part of that range has reached the consumer;
+restart `downloadStream()` to reopen the pinned revision in those cases.
+
+`upload()` accepts `Blob`, `ArrayBuffer`, and typed-array values and hashes them
+before opening the transfer. `uploadStream()` accepts a `ReadableStream` or
+async iterable plus its exact size and `sha256:…` commitment. It verifies the
+stream while uploading sequentially without accumulating multiple file parts.
+SDK memory is bounded by one assembled negotiated part plus at most one source
+chunk; a single-part upload may therefore hold the complete file. Yielded
+source chunks must fit within the authority's negotiated upload part; ordinary
+browser and Node streams already produce much smaller chunks. After an
+ambiguous failure, call it again with a newly opened source and the same
+`transferId` to resume safely.
+
+Both lifecycle methods are optimistic and use the descriptor revision by
+default. Pass a stable `mutationId` when retrying after an ambiguous network
+failure; the authority returns the original durable receipt instead of applying
+the change twice.
+
 Record-facing code can depend on `MdbaseCollectionClient` instead of the OAuth
 client. It accepts a small `MdbaseCollectionTransport`, which is the stable seam
 used by Connect, the developer sandbox, and future hosted providers. This keeps

package/dist/authorization-url.d.ts

@@ -1,3 +1,4 @@
+import type { ConnectProblem } from "@mdbase-dev/connect-protocol";
 export declare function cleanAuthorizationParameters(url: URL): URL;
 export declare function isAuthorizationCallbackUrl(value: string): boolean;
-export declare function authorizationReturnToFromError(error: unknown): string | undefined;
+export declare function authorizationReturnToFromProblem(problem: ConnectProblem): string | undefined;

package/dist/authorization-url.js

@@ -1,4 +1,3 @@
-import { MdbaseConnectError } from "./errors.js";
 export function cleanAuthorizationParameters(url) {
     for (const parameter of ["code", "state", "error", "error_description"]) {
         url.searchParams.delete(parameter);
@@ -16,12 +15,11 @@ export function isAuthorizationCallbackUrl(value) {
     return url.searchParams.has("state")
         && (url.searchParams.has("code") || url.searchParams.has("error"));
 }
-export function authorizationReturnToFromError(error) {
-    if (!(error instanceof MdbaseConnectError)
-        || !error.details
-        || typeof error.details !== "object"
-        || Array.isArray(error.details))
+export function authorizationReturnToFromProblem(problem) {
+    if (!problem.details
+        || typeof problem.details !== "object"
+        || Array.isArray(problem.details))
         return undefined;
-    const returnTo = error.details.returnTo;
+    const returnTo = problem.details.return_to;
     return typeof returnTo === "string" ? returnTo : undefined;
 }

package/dist/browser/integrity.json

@@ -1,4 +1,4 @@
 {
   "file": "mdbase-connect.min.js",
-  "integrity": "sha384-u+z1WOpeMWPwuYV9kDMHHAqQEZKGn+NwX9tjAYtNztyMD7WJbsdj+Be++i43R9nY"
+  "integrity": "sha384-5i/BVtYUAqTluHzqWtHkb2tI4mKjuOsQMdAKhtXjddN95BAkTPOpub7++MQX+fU0"
 }