@mdbase-dev/connect 0.1.0-beta.21

package/dist/notifications.js

@@ -0,0 +1,52 @@
+import { MdbaseConnectError } from "./errors.js";
+export function parseMdbasePushPayload(value) {
+    if (!value || typeof value !== "object") {
+        throw new MdbaseConnectError("invalid_push_payload", "The push payload is not an object.");
+    }
+    const payload = value;
+    if (payload.type !== "mdbase.notification"
+        || payload.version !== 1
+        || typeof payload.signal_id !== "string"
+        || typeof payload.criterion_id !== "string"
+        || typeof payload.cursor !== "string"
+        || !payload.presentation
+        || typeof payload.presentation.title !== "string") {
+        throw new MdbaseConnectError("invalid_push_payload", "The push payload is not an mdbase notification.");
+    }
+    return payload;
+}
+/** Parse the string-valued data attached to an APNs/FCM notification. */
+export function parseMdbaseNativeNotificationData(value) {
+    if (!value || typeof value !== "object") {
+        throw new MdbaseConnectError("invalid_push_payload", "The native notification data is not an object.");
+    }
+    const data = value;
+    if (data.type !== "mdbase.notification"
+        || (data.version !== 1 && data.version !== "1")
+        || typeof data.signal_id !== "string"
+        || typeof data.criterion_id !== "string"
+        || typeof data.cursor !== "string") {
+        throw new MdbaseConnectError("invalid_push_payload", "The native notification data is not an mdbase notification.");
+    }
+    return {
+        type: "mdbase.notification",
+        version: 1,
+        signal_id: data.signal_id,
+        criterion_id: data.criterion_id,
+        cursor: data.cursor
+    };
+}
+/** Display a validated mdbase push from a service worker `push` handler. */
+export function showMdbasePushNotification(registration, value) {
+    const payload = parseMdbasePushPayload(value);
+    return registration.showNotification(payload.presentation.title, {
+        ...(payload.presentation.body ? { body: payload.presentation.body } : {}),
+        ...(payload.presentation.tag ? { tag: payload.presentation.tag } : {}),
+        data: {
+            type: payload.type,
+            signal_id: payload.signal_id,
+            criterion_id: payload.criterion_id,
+            cursor: payload.cursor
+        }
+    });
+}

package/dist/operation-helpers.d.ts

@@ -0,0 +1,24 @@
+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";
+export type LoopbackRequestInit = RequestInit & {
+    targetAddressSpace?: "loopback";
+};
+export declare function loopbackRequest(init: RequestInit): LoopbackRequestInit;
+export declare function localNetworkPermission(): Promise<PermissionState | null>;
+export declare function directFallbackStatus(status: number): boolean;
+export declare function isMutation(operation: CollectionOperation, input?: unknown): boolean;
+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): 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;
+export declare function renameEstimate(input: RenameInput, preview: RenamePreflightResult): MutationEstimate;
+export declare function deleteEstimate(preview: DeletePreflightResult): MutationEstimate;
+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 uncertainDirectMutation(cause: unknown): MdbaseConnectError;

package/dist/operation-helpers.js

@@ -0,0 +1,129 @@
+import { MdbaseConnectError } from "./errors.js";
+import { bytesToBase64Url } from "./base64.js";
+export function loopbackRequest(init) {
+    return { ...init, credentials: "omit", targetAddressSpace: "loopback" };
+}
+export async function localNetworkPermission() {
+    if (typeof navigator === "undefined" || !navigator.permissions?.query)
+        return null;
+    try {
+        const status = await navigator.permissions.query({
+            name: "local-network-access"
+        });
+        return status.state;
+    }
+    catch {
+        return null;
+    }
+}
+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 === "install_type_pack"
+        || operation === "put_timer"
+        || operation === "cancel_timer"
+        || operation === "reconcile_timers";
+}
+export function uniqueOperations(operations) {
+    return [...new Set(operations)];
+}
+export function sameAuthorization(left, right) {
+    if (left.grantId || right.grantId) {
+        return left.grantId === right.grantId
+            && left.keyHandle === right.keyHandle
+            && left.encryption?.key_id === right.encryption?.key_id;
+    }
+    return left.accessToken === right.accessToken;
+}
+export function throwIfCancelled(signal) {
+    if (!signal?.aborted)
+        return;
+    throw new MdbaseConnectError("operation_cancelled", "The operation was cancelled before it changed the collection.", { recovery: "none", cause: signal.reason });
+}
+export function operationTransportError(error, signal, outcomeUnknown) {
+    if (signal?.aborted) {
+        return new MdbaseConnectError("operation_cancelled", outcomeUnknown
+            ? "Waiting was cancelled after the mutation was sent. Resume the pending mutation to recover its authoritative result."
+            : "The operation was cancelled before it changed the collection.", {
+            outcomeUnknown,
+            recovery: outcomeUnknown ? "resolve_outcome" : "none",
+            cause: error
+        });
+    }
+    if (outcomeUnknown) {
+        if (error instanceof MdbaseConnectError && error.outcomeUnknown)
+            return error;
+        return uncertainDirectMutation(error);
+    }
+    return error instanceof Error ? error : new Error(String(error));
+}
+export function isCancellation(error, signal) {
+    return signal?.aborted === true
+        || (error instanceof MdbaseConnectError && error.code === "operation_cancelled");
+}
+export function assertRenamePreview(input, preview) {
+    if (preview.dry_run !== true || preview.would_rename !== true
+        || preview.from !== input.from || preview.to !== input.to) {
+        throw new MdbaseConnectError("invalid_preflight", "The rename preview does not match this mutation. Run the preview again.", { recovery: "fix_request" });
+    }
+}
+export function assertDeletePreview(input, preview) {
+    if (preview.dry_run !== true || preview.would_delete !== true || preview.path !== input.path) {
+        throw new MdbaseConnectError("invalid_preflight", "The delete preview does not match this mutation. Run the preview again.", { recovery: "fix_request" });
+    }
+}
+export function renameEstimate(input, preview) {
+    if (input.update_refs === false) {
+        return { affectedRecords: 0, totalUnits: 1, warnings: 0 };
+    }
+    const references = preview.references_affected ?? [];
+    return {
+        affectedRecords: new Set(references.map((reference) => reference.path)).size,
+        totalUnits: 1 + references.length,
+        warnings: preview.warnings?.length ?? 0
+    };
+}
+export function deleteEstimate(preview) {
+    return {
+        affectedRecords: new Set((preview.broken_links ?? []).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));
+}
+export function canonicalJson(value) {
+    return JSON.stringify(sortJson(value));
+}
+export function sortJson(value) {
+    if (Array.isArray(value))
+        return value.map((item) => sortJson(item));
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value)
+            .filter(([, item]) => item !== undefined)
+            .sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)
+            .map(([key, item]) => [key, sortJson(item)]));
+    }
+    return value;
+}
+export function uncertainDirectMutation(cause) {
+    return new MdbaseConnectError("direct_outcome_unknown", "The direct write may have completed, and mdbase could not recover its receipt through the relay. Retry the exact same write to recover safely.", { cause });
+}

package/dist/operation-types.d.ts

@@ -0,0 +1,254 @@
+import type { CollectionOperation, JsonObject, QueryRecord, RecordDocument } from "@mdbase-dev/connect-protocol";
+import type { MdbaseConnectError } from "./errors.js";
+export interface MdbaseDesiredTimer {
+    /** Stable within the timer namespace. */
+    id: string;
+    /** RFC 3339 instant at which the authority should fire the timer. */
+    fire_at: string;
+    /** Private application data retained by the collection authority. */
+    data?: unknown;
+}
+export interface MdbaseTimer extends MdbaseDesiredTimer {
+    criterion_id: string;
+    generation: number;
+    status: "scheduled" | "firing" | "fired" | "cancelled";
+    created_at: string;
+    updated_at: string;
+    fired_at: string | null;
+}
+export interface MdbaseTimerList {
+    namespace: string;
+    timers: MdbaseTimer[];
+}
+export interface MdbaseTimerReconciliation extends MdbaseTimerList {
+    cancelled_ids: string[];
+}
+export interface ReadInput {
+    path: string;
+    /** Select an exact approved contract view when more than one is possible. */
+    contract?: DataContractSelector;
+    /** Include the exact UTF-8 Markdown source; requires full-collection access. */
+    include_document?: boolean;
+}
+export interface DataContractSelector {
+    id: string;
+    version: string;
+    /** Required when several approved types implement the selected contract. */
+    type?: string;
+}
+export interface QueryInput {
+    /**
+     * Contract-scoped queries accept only `types`, pagination,
+     * `frontmatter_mode`, and `contract`; filter normalized fields in the app.
+     */
+    types?: string[];
+    where?: unknown;
+    order_by?: unknown;
+    limit?: number;
+    offset?: number;
+    /** Opaque token returned by the first metadata page for consistent, fast pagination. */
+    snapshot?: string;
+    include_body?: boolean;
+    frontmatter_mode?: "effective" | "persisted" | "both";
+    /** Narrow a contract-scoped query to one exact contract/provider view. */
+    contract?: DataContractSelector;
+    [key: string]: unknown;
+}
+export interface QueryResult<Record extends JsonObject = JsonObject> {
+    results: Array<QueryRecord<Record> & JsonObject>;
+    meta?: {
+        total_count: number;
+        has_more: boolean;
+        snapshot?: string;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+export interface QueryPagesOptions<Record extends JsonObject = JsonObject> {
+    firstPageSize?: number;
+    pageSize?: number;
+    signal?: AbortSignal;
+    onProgress?: (page: QueryPage<Record>) => void;
+}
+export interface QueryPage<Record extends JsonObject = JsonObject> {
+    results: QueryResult<Record>["results"];
+    meta?: QueryResult<Record>["meta"];
+    page: number;
+    offset: number;
+    loaded: number;
+    complete: boolean;
+    snapshot?: string;
+}
+export interface OperationRequestOptions {
+    signal?: AbortSignal;
+}
+export interface MutationEstimate {
+    /** Records whose links may be affected, excluding the record being mutated. */
+    affectedRecords: number;
+    /** Estimated atomic changes: the mutation itself plus known reference updates. */
+    totalUnits: number;
+    warnings: number;
+}
+export type MutationProgressState = "preflighting" | "ready" | "applying" | "completed" | "cancelled";
+export interface MutationProgress {
+    operation: "rename" | "delete";
+    state: MutationProgressState;
+    elapsedMs: number;
+    cancellable: boolean;
+    resumed: boolean;
+    completedUnits: number;
+    estimate?: MutationEstimate;
+}
+export interface MutationProgressOptions {
+    signal?: AbortSignal;
+    onProgress?: (progress: MutationProgress) => void;
+}
+export interface RenameProgressOptions extends MutationProgressOptions {
+    /** Reuse an authoritative preview already shown to the user. */
+    preflight?: RenamePreflightResult;
+}
+export interface DeleteProgressOptions extends MutationProgressOptions {
+    /** Reuse an authoritative preview already shown to the user. */
+    preflight?: DeletePreflightResult;
+}
+export interface PendingMutationSummary {
+    operation: CollectionOperation;
+    createdAt: number;
+    resumable: true;
+}
+export interface CreateInput<Frontmatter extends JsonObject = JsonObject> {
+    path?: string;
+    type?: string;
+    contract?: DataContractSelector;
+    frontmatter?: Partial<Frontmatter> & JsonObject;
+    /** Requires full-collection access; contract creates are frontmatter-only. */
+    body?: string;
+    if_revision?: string;
+    /** Include the resulting exact Markdown source in `result.document`. */
+    include_document?: boolean;
+}
+interface UpdateInputBase {
+    path: string;
+    contract?: DataContractSelector;
+    if_revision?: string;
+    /** Include the resulting exact Markdown source; requires full-collection access. */
+    include_document?: boolean;
+}
+export type UpdateInput<Frontmatter extends JsonObject = JsonObject> = UpdateInputBase & ({
+    patch: Partial<Frontmatter> & JsonObject;
+    body?: string;
+    document?: never;
+} | {
+    /**
+     * Replace the complete Markdown source. This is mutually exclusive with
+     * `patch` and `body`, and implies `include_document`.
+     */
+    document: string;
+    patch?: never;
+    body?: never;
+});
+export interface DeleteInput {
+    path: string;
+    contract?: DataContractSelector;
+    check_backlinks?: boolean;
+    if_revision?: string;
+}
+export interface DeleteResult {
+    path: string;
+    deleted: boolean;
+    broken_links?: Array<{
+        path: string;
+    }>;
+}
+export interface DeletePreflightResult {
+    path: string;
+    deleted: false;
+    dry_run: true;
+    would_delete: true;
+    broken_links?: Array<{
+        path: string;
+    }>;
+}
+export interface RenameInput {
+    from: string;
+    to: string;
+    contract?: DataContractSelector;
+    update_refs?: boolean;
+    if_revision?: string;
+    /** Include the resulting exact Markdown source in `result.document`. */
+    include_document?: boolean;
+}
+export interface RenameResult extends RecordDocument {
+    from: string;
+    to: string;
+    references_updated?: JsonObject[];
+}
+export interface RenamePreflightResult {
+    from: string;
+    to: string;
+    dry_run: true;
+    would_rename: true;
+    references_affected?: Array<{
+        path: string;
+        field?: string;
+        location?: string;
+    }>;
+    warnings?: Array<{
+        path: string;
+        message: string;
+    }>;
+}
+export interface ReadTypeInput {
+    name?: string;
+    path?: string;
+}
+export interface CreateTypeInput {
+    document: string;
+    path?: string;
+}
+export interface UpdateTypeInput extends ReadTypeInput {
+    document: string;
+    if_revision: string;
+}
+export interface ChangesInput {
+    after?: number;
+    limit?: number;
+}
+export interface WatchOptions {
+    cursor?: number;
+    pollIntervalMs?: number;
+    signal?: AbortSignal;
+    /** Set to false to surface transient transport failures immediately. */
+    retry?: false | WatchRetryOptions;
+    onStatus?: (status: WatchStatus) => void;
+}
+export interface WatchRetryOptions {
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+    multiplier?: number;
+    /** Number of consecutive transient failures. Omit to keep reconnecting. */
+    maxAttempts?: number;
+}
+export type WatchStatus = {
+    state: "connecting";
+    cursor?: number;
+} | {
+    state: "connected";
+    cursor: number;
+    recovered: boolean;
+} | {
+    state: "reconnecting";
+    cursor?: number;
+    attempt: number;
+    retryInMs: number;
+    error: unknown;
+} | {
+    state: "reset_required";
+    cursor: number;
+    error: MdbaseConnectError;
+};
+/** Provider-neutral operation transport used by the typed collection client. */
+export interface MdbaseCollectionTransport {
+    operation<Result>(operation: CollectionOperation, input: unknown, options?: OperationRequestOptions): Promise<Result>;
+}
+export {};

package/dist/operation-types.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime-utils.d.ts

@@ -0,0 +1,33 @@
+import type { GrantEncryption, GrantScope, MdbaseAppManifest } from "@mdbase-dev/connect-protocol";
+import { MdbaseConnectError } from "./errors.js";
+import type { StoredToken } from "./internal-types.js";
+import type { MdbaseDeviceAuthorization } from "./authorization-types.js";
+export declare function canonicalLoopbackUrl(value: string): string;
+export declare function createPkce(): Promise<{
+    verifier: string;
+    challenge: string;
+}>;
+export declare function apiError(body: any, fallbackCode: string, fallbackMessage: string, status?: number): MdbaseConnectError;
+export declare function oauthErrorCode(body: any): string | undefined;
+export declare function validAuthorityTokenResponse(value: unknown, collectionId: unknown): boolean;
+export declare function validStoredAuthority(authority: StoredToken["authority"], collectionId: string): boolean;
+export declare function validStoredEncryption(encryption: StoredToken["encryption"], collectionId: string): encryption is GrantEncryption;
+export declare function parseDeviceAuthorization(body: any): MdbaseDeviceAuthorization;
+export declare function parseStored<T>(value: string | null): T | null;
+export declare function parseGrantScope(value: unknown): GrantScope | null;
+export declare function stripTrailingSlash(value: string): string;
+export declare function defaultManifestSource(): string;
+export declare function defaultRedirectUri(): string;
+export declare function defaultCallbackUrl(): string;
+export declare function defaultStorage(memoryOnly: boolean): Storage;
+export declare class MemoryStorage implements Storage {
+    private readonly values;
+    get length(): number;
+    clear(): void;
+    getItem(key: string): string | null;
+    key(index: number): string | null;
+    removeItem(key: string): void;
+    setItem(key: string, value: string): void;
+}
+export declare function isOpaquePortableManifest(manifest: MdbaseAppManifest | string): boolean;
+export declare function manifestStorageFingerprint(manifest: MdbaseAppManifest): string;