Connect SDK

Use the Connect SDK to authorize a collection and call typed mdbase operations.

@mdbase/connect is the browser and native-shell SDK for applications that operate on one user-approved local or hosted mdbase collection. The application asks for exact operations. Connect selects the route and the collection authority checks the current grant.

Choose the first result you need

Learn the collection API

Run typed reads and revision-safe changes against an in-memory collection. This path needs no account or running service.

Try the SDK locally

Connect a real application

Add a manifest, authorize one compatible collection, complete the browser callback, and use the approved connection.

Open the Connect guide

Private-beta release status

The production service and protocol 1 are deployed for beta accounts. The npm packages await their first public release. Current developers build or pack the versioned artifacts from theConnect repository.

SDK surfaces

Surface	Use it for	Depends on
`MdbaseConnect`	Application-level manager for web, native-shell, and portable-file authorization	Browser APIs or adapters supplied by a native shell
`MdbaseConnection`	One collection's operations, renewal, routing, notifications, and provider-neutral sync	Browser APIs or adapters supplied by a native shell
`MdbaseBrowserLocation`	Bookmarkable collection selection, authorization return URLs, and browser navigation	A stable `MdbaseConnect` manager and browser history APIs
`MdbaseCollectionClient`	Domain and feature logic that should be independent of OAuth and hosting	A small `MdbaseCollectionTransport`
`createSandbox()`	Fast frontend tests for CRUD, revisions, pagination, defaults, and change cursors	`@mdbase/connect-dev`
`OfflineReplica`	Offline-first applications backed by any sync-capable authority	`@mdbase/connect-sync`

Application structure

Create one MdbaseConnect manager at the application boundary. Pair it with one MdbaseBrowserLocation at the browser application boundary. Resolve its active connection, then pass that MdbaseConnection into feature code. The location helper owns bookmark selection and OAuth return cleanup; the manager owns saved authorizations. A bound connection never changes collections underneath a repository, and feature code written against MdbaseCollectionClient can also run against the developer sandbox or another conforming transport.

A downloaded HTML file supplies distribution: "portable" in its inline manifest. The same manager then uses short-code approval and session-only credentials. See the portable HTML application guide.

tasks.ts

import type { MdbaseCollectionClient } from "@mdbase/connect";

export async function listOpenTasks(client: MdbaseCollectionClient<Task>) {
  return client.queryAll({
    types: ["task"],
    where: 'status == "open"',
    order_by: [{ field: "due", direction: "asc" }]
  });
}

The operation envelope is part of the contract.

Record operations return { valid, result, diagnostics }. Use unwrapOperation() when exceptions suit the calling code, or inspect the envelope when the interface should present validation diagnostics inline.

Package map

Package	Purpose
`@mdbase/connect`	Authorization, routes, operations, notifications, and authority-neutral sync handoff
`@mdbase/connect-dev`	Manifest validation, contract validation, and deterministic sandbox transport
`@mdbase/connect-protocol`	Shared TypeScript types and canonical JSON Schemas
`@mdbase/connect-sync`	Authority-neutral replication state machine, IndexedDB replica, conflicts, and offline mutations
`@mdbase/connect-webhooks`	Server-side verification for signed notification webhooks

Run the local example Connect a browser app Build one HTML file