@sequenceholdings/artifact-studio 0.4.0 → 0.6.1

package/dist/offline/indexed-db.js

@@ -0,0 +1,104 @@
+import { generateOfflineEncryptionKey } from './crypto.js';
+const OFFLINE_DATABASE_VERSION = 1;
+const META_STORE = 'meta';
+const SECURE_STORES = [
+    'cache',
+    'outbox',
+    'accesslog',
+];
+function requestResult(request) {
+    return new Promise((resolve, reject) => {
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error ?? new Error('IndexedDB request failed'));
+    });
+}
+function transactionComplete(transaction) {
+    return new Promise((resolve, reject) => {
+        transaction.oncomplete = () => resolve();
+        transaction.onerror = () => reject(transaction.error ?? new Error('IndexedDB transaction failed'));
+        transaction.onabort = () => reject(transaction.error ?? new Error('IndexedDB transaction aborted'));
+    });
+}
+export async function openOfflineIndexedDatabase({ databaseName, }) {
+    if (!globalThis.indexedDB)
+        throw new Error('IndexedDB is unavailable');
+    const openRequest = globalThis.indexedDB.open(databaseName, OFFLINE_DATABASE_VERSION);
+    openRequest.onupgradeneeded = () => {
+        const database = openRequest.result;
+        for (const store of SECURE_STORES) {
+            if (!database.objectStoreNames.contains(store)) {
+                database.createObjectStore(store);
+            }
+        }
+        if (!database.objectStoreNames.contains(META_STORE)) {
+            database.createObjectStore(META_STORE);
+        }
+    };
+    const database = await requestResult(openRequest);
+    let invalidated = false;
+    database.onversionchange = () => {
+        invalidated = true;
+        database.close();
+    };
+    function assertOpen() {
+        if (invalidated) {
+            throw new Error('Offline storage was replaced; reopen the artifact before continuing');
+        }
+    }
+    const kv = {
+        async get({ store, key }) {
+            assertOpen();
+            const transaction = database.transaction(store, 'readonly');
+            return requestResult(transaction.objectStore(store).get(key));
+        },
+        async set({ store, key, value }) {
+            assertOpen();
+            const transaction = database.transaction(store, 'readwrite');
+            transaction.objectStore(store).put(value, key);
+            await transactionComplete(transaction);
+        },
+        async delete({ store, key }) {
+            assertOpen();
+            const transaction = database.transaction(store, 'readwrite');
+            transaction.objectStore(store).delete(key);
+            await transactionComplete(transaction);
+        },
+        async keys({ store }) {
+            assertOpen();
+            const transaction = database.transaction(store, 'readonly');
+            const keys = await requestResult(transaction.objectStore(store).getAllKeys());
+            return keys.map(String);
+        },
+    };
+    return {
+        kv,
+        async nextSequence() {
+            assertOpen();
+            const transaction = database.transaction(META_STORE, 'readwrite');
+            const store = transaction.objectStore(META_STORE);
+            const current = await requestResult(store.get('outbox-sequence'));
+            const next = typeof current === 'number' ? current + 1 : 1;
+            store.put(next, 'outbox-sequence');
+            await transactionComplete(transaction);
+            return next;
+        },
+        async getOrCreateEncryptionKey() {
+            assertOpen();
+            const candidate = await generateOfflineEncryptionKey();
+            const transaction = database.transaction(META_STORE, 'readwrite');
+            const store = transaction.objectStore(META_STORE);
+            const existing = await requestResult(store.get('encryption-key'));
+            if (existing instanceof CryptoKey) {
+                await transactionComplete(transaction);
+                return existing;
+            }
+            store.put(candidate, 'encryption-key');
+            await transactionComplete(transaction);
+            return candidate;
+        },
+        close: () => {
+            invalidated = true;
+            database.close();
+        },
+    };
+}

package/dist/offline/management-types.d.ts

@@ -0,0 +1,25 @@
+export interface SequenceOfflineManagementStatus {
+    supported: boolean;
+    enrolled: boolean;
+    online: boolean;
+    pending: number;
+    failed: number;
+    syncing: boolean;
+    lastSyncAt: number | null;
+    itemCount?: number;
+    itemLabel?: string;
+}
+export interface SequenceOfflineManagementIssue {
+    id: string;
+    label: string;
+    message: string;
+}
+export interface SequenceOfflineManagement {
+    status(): Promise<SequenceOfflineManagementStatus>;
+    setEnrolled(enrolled: boolean): Promise<void>;
+    sync(): Promise<void>;
+    issues(): Promise<SequenceOfflineManagementIssue[]>;
+    retry(id: string): Promise<void>;
+    discard(id: string): Promise<void>;
+    subscribe(listener: () => void): () => void;
+}

package/dist/offline/management-types.js

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

package/dist/offline/outbox.d.ts

@@ -0,0 +1,7 @@
+import type { EncryptedOfflineStore, OfflineOutbox } from './types.js';
+export declare function createOfflineOutbox({ store, nextSequence, createId, clock, }: {
+    store: EncryptedOfflineStore;
+    nextSequence: () => Promise<number>;
+    createId?: () => string;
+    clock?: () => number;
+}): OfflineOutbox;

package/dist/offline/outbox.js

@@ -0,0 +1,46 @@
+export function createOfflineOutbox({ store, nextSequence, createId = () => globalThis.crypto.randomUUID(), clock = () => Date.now(), }) {
+    async function list() {
+        const entries = await Promise.all((await store.keys({ store: 'outbox' })).map((key) => store.get({ store: 'outbox', key })));
+        return entries
+            .filter((entry) => entry !== undefined)
+            .sort((left, right) => left.sequence - right.sequence);
+    }
+    return {
+        async enqueue({ id: suppliedId, request, entity, observed, optimisticId }) {
+            const id = suppliedId ?? createId();
+            const entry = {
+                id,
+                sequence: await nextSequence(),
+                request,
+                entity,
+                capturedAt: new Date(clock()).toISOString(),
+                attempts: 0,
+                status: 'pending',
+                ...(observed === undefined ? {} : { observed }),
+                ...(optimisticId === undefined ? {} : { optimisticId }),
+            };
+            await store.set({ store: 'outbox', key: id, value: entry });
+            return entry;
+        },
+        list,
+        async update({ id, patch }) {
+            const existing = await store.get({
+                store: 'outbox',
+                key: id,
+            });
+            if (!existing)
+                return;
+            await store.set({
+                store: 'outbox',
+                key: id,
+                value: {
+                    ...existing,
+                    ...patch,
+                    id: existing.id,
+                    sequence: existing.sequence,
+                },
+            });
+        },
+        remove: ({ id }) => store.delete({ store: 'outbox', key: id }),
+    };
+}

package/dist/offline/replay.d.ts

@@ -0,0 +1,25 @@
+import type { SequenceOfflineNetwork } from '../sdk.js';
+import type { OfflineFailureKind, OfflineMutationPolicy, OfflineOutbox, OfflineUnresolvedWrite } from './types.js';
+export declare function classifyOfflineReplayFailure(error: unknown): OfflineFailureKind;
+export interface OfflineReplayEngine {
+    attach(context: {
+        network: SequenceOfflineNetwork;
+    }): void;
+    flush(): Promise<void>;
+    listUnresolved(): Promise<OfflineUnresolvedWrite[]>;
+    retry(input: {
+        id: string;
+    }): Promise<void>;
+    keepMine(input: {
+        id: string;
+    }): Promise<void>;
+    discard(input: {
+        id: string;
+    }): Promise<void>;
+}
+export declare function createOfflineReplayEngine({ outbox, mutationPolicy, maxAttempts, onEpoch, }: {
+    outbox: OfflineOutbox;
+    mutationPolicy: OfflineMutationPolicy;
+    maxAttempts?: number;
+    onEpoch?: () => void;
+}): OfflineReplayEngine;

package/dist/offline/replay.js

@@ -0,0 +1,192 @@
+class OfflineConflictDetected extends Error {
+    info;
+    constructor(info) {
+        super('Server changed since this offline edit was captured');
+        this.name = 'OfflineConflictDetected';
+        this.info = info;
+    }
+}
+class OfflineReplayHttpError extends Error {
+    status;
+    constructor(status) {
+        super(`Offline replay failed with HTTP ${status}`);
+        this.name = 'OfflineReplayHttpError';
+        this.status = status;
+    }
+}
+function statusFromError(error) {
+    if (error &&
+        typeof error === 'object' &&
+        'status' in error &&
+        typeof error.status === 'number') {
+        return error.status;
+    }
+    return null;
+}
+export function classifyOfflineReplayFailure(error) {
+    const status = statusFromError(error);
+    if (status === null)
+        return 'transient';
+    if (status === 401 || status === 403)
+        return 'auth';
+    if (status === 409 || status === 412)
+        return 'conflict';
+    if (status === 408 || status === 429 || status >= 500)
+        return 'transient';
+    return status >= 400 ? 'invalid' : 'transient';
+}
+async function replayEntry({ entry, descriptor, network, }) {
+    if (entry.force !== true &&
+        descriptor.fetchCurrent &&
+        descriptor.detectConflict) {
+        const current = await descriptor.fetchCurrent({ entry, network });
+        const conflict = descriptor.detectConflict({ entry, current });
+        if (conflict)
+            throw new OfflineConflictDetected(conflict);
+    }
+    const response = await network.execute({
+        ...entry.request,
+        headers: {
+            ...entry.request.headers,
+            'X-Request-Id': entry.id,
+        },
+    });
+    if (!response.ok)
+        throw new OfflineReplayHttpError(response.status);
+    await descriptor.reconcile?.({ entry, response });
+    return response;
+}
+export function createOfflineReplayEngine({ outbox, mutationPolicy, maxAttempts = 5, onEpoch, }) {
+    let network = null;
+    let flushing = false;
+    async function flush() {
+        if (!network || flushing)
+            return;
+        flushing = true;
+        try {
+            for (const entry of await outbox.list()) {
+                if (entry.status !== 'pending' && entry.status !== 'inflight')
+                    continue;
+                const descriptor = mutationPolicy.match(entry.request);
+                if (!descriptor) {
+                    await outbox.update({
+                        id: entry.id,
+                        patch: {
+                            status: 'failed',
+                            failureKind: 'invalid',
+                            lastError: 'No mutation policy matches this queued write',
+                        },
+                    });
+                    continue;
+                }
+                await outbox.update({ id: entry.id, patch: { status: 'inflight' } });
+                try {
+                    await replayEntry({ entry, descriptor, network });
+                    await outbox.remove({ id: entry.id });
+                }
+                catch (error) {
+                    if (error instanceof OfflineConflictDetected) {
+                        await outbox.update({
+                            id: entry.id,
+                            patch: {
+                                status: 'conflict',
+                                failureKind: 'conflict',
+                                conflict: error.info,
+                                lastError: error.message,
+                            },
+                        });
+                        continue;
+                    }
+                    const kind = classifyOfflineReplayFailure(error);
+                    const lastError = error instanceof Error ? error.message : String(error);
+                    if (kind === 'auth') {
+                        await outbox.update({
+                            id: entry.id,
+                            patch: { status: 'pending', failureKind: kind, lastError },
+                        });
+                        break;
+                    }
+                    if (kind === 'invalid' || kind === 'conflict') {
+                        await outbox.update({
+                            id: entry.id,
+                            patch: {
+                                status: kind === 'conflict' ? 'conflict' : 'failed',
+                                failureKind: kind,
+                                lastError,
+                            },
+                        });
+                        continue;
+                    }
+                    const attempts = entry.attempts + 1;
+                    await outbox.update({
+                        id: entry.id,
+                        patch: {
+                            attempts,
+                            status: attempts >= maxAttempts ? 'failed' : 'pending',
+                            failureKind: 'transient',
+                            lastError,
+                        },
+                    });
+                    if (attempts < maxAttempts)
+                        break;
+                }
+            }
+        }
+        finally {
+            flushing = false;
+            onEpoch?.();
+        }
+    }
+    async function rearm({ id, force, }) {
+        await outbox.update({
+            id,
+            patch: {
+                status: 'pending',
+                attempts: 0,
+                force,
+                lastError: undefined,
+                failureKind: undefined,
+                conflict: undefined,
+            },
+        });
+        await flush();
+    }
+    return {
+        attach: ({ network: nextNetwork }) => {
+            network = nextNetwork;
+        },
+        flush,
+        async listUnresolved() {
+            const writes = [];
+            for (const entry of await outbox.list()) {
+                const authPaused = entry.status === 'pending' && entry.failureKind === 'auth';
+                if (entry.status !== 'failed' &&
+                    entry.status !== 'conflict' &&
+                    !authPaused) {
+                    continue;
+                }
+                const descriptor = mutationPolicy.match(entry.request);
+                writes.push({
+                    id: entry.id,
+                    label: descriptor?.label(entry) ?? entry.entity,
+                    capturedAt: entry.capturedAt,
+                    kind: entry.failureKind ??
+                        (entry.status === 'conflict' ? 'conflict' : 'transient'),
+                    ...(entry.lastError === undefined ? {} : { error: entry.lastError }),
+                    ...(entry.conflict === undefined ? {} : { conflict: entry.conflict }),
+                });
+            }
+            return writes;
+        },
+        retry: ({ id }) => rearm({ id }),
+        keepMine: ({ id }) => rearm({ id, force: true }),
+        async discard({ id }) {
+            const entry = (await outbox.list()).find((candidate) => candidate.id === id);
+            if (!entry)
+                return;
+            await mutationPolicy.match(entry.request)?.rollback?.({ entry });
+            await outbox.remove({ id });
+            onEpoch?.();
+        },
+    };
+}

package/dist/offline/secure-store.d.ts

@@ -0,0 +1,6 @@
+import type { EncryptedOfflineStore, OfflineCrypto, OfflineKvStore } from './types.js';
+export declare function createEncryptedOfflineStore({ kv, crypto, namespace, }: {
+    kv: OfflineKvStore;
+    crypto: OfflineCrypto;
+    namespace: string;
+}): EncryptedOfflineStore;

package/dist/offline/secure-store.js

@@ -0,0 +1,51 @@
+function isEncryptedRecord(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    return ('iv' in value &&
+        'ciphertext' in value &&
+        Array.isArray(value.iv) &&
+        Array.isArray(value.ciphertext));
+}
+export function createEncryptedOfflineStore({ kv, crypto, namespace, }) {
+    if (namespace.length === 0 || namespace.includes('\n')) {
+        throw new Error('Offline storage namespace is required');
+    }
+    const prefix = `${namespace}:`;
+    const scopedKey = (key) => `${prefix}${key}`;
+    async function scopedKeys(store) {
+        return (await kv.keys({ store }))
+            .filter((key) => key.startsWith(prefix))
+            .map((key) => key.slice(prefix.length));
+    }
+    return {
+        async get({ store, key, }) {
+            const scoped = scopedKey(key);
+            const record = await kv.get({ store, key: scoped });
+            if (!isEncryptedRecord(record))
+                return undefined;
+            try {
+                // The caller owns each logical key's schema; the encrypted store is
+                // intentionally heterogeneous and cannot infer T after JSON decode.
+                return (await crypto.decrypt({ record }));
+            }
+            catch {
+                await kv.delete({ store, key: scoped });
+                return undefined;
+            }
+        },
+        async set({ store, key, value }) {
+            await kv.set({
+                store,
+                key: scopedKey(key),
+                value: await crypto.encrypt({ value }),
+            });
+        },
+        async delete({ store, key }) {
+            await kv.delete({ store, key: scopedKey(key) });
+        },
+        keys: ({ store }) => scopedKeys(store),
+        async clear({ store }) {
+            await Promise.all((await scopedKeys(store)).map((key) => kv.delete({ store, key: scopedKey(key) })));
+        },
+    };
+}

package/dist/offline/types.d.ts

@@ -0,0 +1,162 @@
+import type { SequenceApiFetchResponse, SequenceOfflineNetwork, SequenceOfflineRequest } from '../sdk.js';
+export type OfflineStoreName = 'cache' | 'outbox' | 'accesslog';
+export interface OfflineKvStore {
+    get(input: {
+        store: OfflineStoreName;
+        key: string;
+    }): Promise<unknown>;
+    set(input: {
+        store: OfflineStoreName;
+        key: string;
+        value: unknown;
+    }): Promise<void>;
+    delete(input: {
+        store: OfflineStoreName;
+        key: string;
+    }): Promise<void>;
+    keys(input: {
+        store: OfflineStoreName;
+    }): Promise<string[]>;
+}
+export interface OfflineEncryptedRecord {
+    iv: number[];
+    ciphertext: number[];
+}
+export interface OfflineCrypto {
+    encrypt(input: {
+        value: unknown;
+    }): Promise<OfflineEncryptedRecord>;
+    decrypt(input: {
+        record: OfflineEncryptedRecord;
+    }): Promise<unknown>;
+}
+export interface EncryptedOfflineStore {
+    get<T = unknown>(input: {
+        store: OfflineStoreName;
+        key: string;
+    }): Promise<T | undefined>;
+    set(input: {
+        store: OfflineStoreName;
+        key: string;
+        value: unknown;
+    }): Promise<void>;
+    delete(input: {
+        store: OfflineStoreName;
+        key: string;
+    }): Promise<void>;
+    keys(input: {
+        store: OfflineStoreName;
+    }): Promise<string[]>;
+    clear(input: {
+        store: OfflineStoreName;
+    }): Promise<void>;
+}
+export type OfflineFailureKind = 'transient' | 'invalid' | 'auth' | 'conflict';
+export type OfflineOutboxStatus = 'pending' | 'inflight' | 'failed' | 'conflict';
+export interface OfflineConflictField {
+    key: string;
+    mine: unknown;
+    theirs: unknown;
+}
+export interface OfflineConflictInfo {
+    fields: OfflineConflictField[];
+    observedAt?: string;
+    serverUpdatedAt?: string;
+}
+export interface OfflineOutboxEntry {
+    id: string;
+    sequence: number;
+    request: SequenceOfflineRequest;
+    entity: string;
+    capturedAt: string;
+    attempts: number;
+    status: OfflineOutboxStatus;
+    observed?: Record<string, unknown>;
+    optimisticId?: string;
+    failureKind?: OfflineFailureKind;
+    lastError?: string;
+    conflict?: OfflineConflictInfo;
+    force?: boolean;
+}
+export interface OfflineOutbox {
+    enqueue(input: {
+        id?: string;
+        request: SequenceOfflineRequest;
+        entity: string;
+        observed?: Record<string, unknown>;
+        optimisticId?: string;
+    }): Promise<OfflineOutboxEntry>;
+    list(): Promise<OfflineOutboxEntry[]>;
+    update(input: {
+        id: string;
+        patch: Partial<OfflineOutboxEntry>;
+    }): Promise<void>;
+    remove(input: {
+        id: string;
+    }): Promise<void>;
+}
+export interface OfflineReadDescriptor {
+    key: string;
+    ttlMs: number;
+    entity: string;
+}
+export interface OfflineReadPolicy {
+    match(request: SequenceOfflineRequest): OfflineReadDescriptor | null;
+}
+export interface OfflineCacheEntry {
+    response: SequenceApiFetchResponse;
+    cachedAt: number;
+    expiresAt: number;
+    entity: string;
+}
+export interface OfflineCache {
+    read(input: {
+        key: string;
+    }): Promise<OfflineCacheEntry | undefined>;
+    write(input: {
+        key: string;
+        entry: OfflineCacheEntry;
+    }): Promise<void>;
+    remove(input: {
+        key: string;
+    }): Promise<void>;
+}
+export interface OfflineMutationDescriptor {
+    entity: string;
+    label(entry: OfflineOutboxEntry): string;
+    capture?(input: {
+        request: SequenceOfflineRequest;
+    }): Promise<Record<string, unknown> | undefined>;
+    optimisticApply?(input: {
+        entry: OfflineOutboxEntry;
+    }): Promise<void> | void;
+    optimisticResponse?(input: {
+        entry: OfflineOutboxEntry;
+    }): SequenceApiFetchResponse;
+    fetchCurrent?(input: {
+        entry: OfflineOutboxEntry;
+        network: SequenceOfflineNetwork;
+    }): Promise<unknown>;
+    detectConflict?(input: {
+        entry: OfflineOutboxEntry;
+        current: unknown;
+    }): OfflineConflictInfo | null;
+    reconcile?(input: {
+        entry: OfflineOutboxEntry;
+        response: SequenceApiFetchResponse;
+    }): Promise<void> | void;
+    rollback?(input: {
+        entry: OfflineOutboxEntry;
+    }): Promise<void> | void;
+}
+export interface OfflineMutationPolicy {
+    match(request: SequenceOfflineRequest): OfflineMutationDescriptor | null;
+}
+export interface OfflineUnresolvedWrite {
+    id: string;
+    label: string;
+    capturedAt: string;
+    kind: OfflineFailureKind;
+    error?: string;
+    conflict?: OfflineConflictInfo;
+}

package/dist/offline/types.js

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

package/dist/orm-json-scalars.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The ORM data plane's opt-in exact-number wire form (orm-data-plane/src/protocol.ts).
+ * By default numeric and bigint values come back as JSON numbers, which JavaScript
+ * rounds past 15-17 significant digits. With `lossless-v1` they come back as strings
+ * ("250000.00", "9007199254740993"), and a successful response acknowledges the form
+ * with the same header. Variables may carry numeric and bigint values as decimal
+ * strings in either form.
+ */
+export declare const ORM_JSON_SCALARS_HEADER = "x-sequence-orm-json-scalars";
+export declare const ORM_LOSSLESS_JSON_SCALARS = "lossless-v1";
+export type ArtifactOrmJsonScalars = typeof ORM_LOSSLESS_JSON_SCALARS;
+/**
+ * An executor that asked for exact numbers refuses a successful result the platform
+ * did not acknowledge, because its numbers may already be rounded. Failed responses
+ * never acknowledge and keep their own error.
+ */
+export declare function assertJsonScalarsAcknowledged({ requested, acknowledged, status }: {
+    requested: ArtifactOrmJsonScalars | undefined;
+    acknowledged: string | null | undefined;
+    status: number;
+}): void;

package/dist/orm-json-scalars.js

@@ -0,0 +1,21 @@
+import { OrmOperationError } from '@sequenceholdings/orm/client';
+/**
+ * The ORM data plane's opt-in exact-number wire form (orm-data-plane/src/protocol.ts).
+ * By default numeric and bigint values come back as JSON numbers, which JavaScript
+ * rounds past 15-17 significant digits. With `lossless-v1` they come back as strings
+ * ("250000.00", "9007199254740993"), and a successful response acknowledges the form
+ * with the same header. Variables may carry numeric and bigint values as decimal
+ * strings in either form.
+ */
+export const ORM_JSON_SCALARS_HEADER = 'x-sequence-orm-json-scalars';
+export const ORM_LOSSLESS_JSON_SCALARS = 'lossless-v1';
+/**
+ * An executor that asked for exact numbers refuses a successful result the platform
+ * did not acknowledge, because its numbers may already be rounded. Failed responses
+ * never acknowledge and keep their own error.
+ */
+export function assertJsonScalarsAcknowledged({ requested, acknowledged, status }) {
+    if (requested === undefined || acknowledged === requested)
+        return;
+    throw new OrmOperationError(`Atlas did not confirm ${requested} numbers for this ORM response, so its numeric and bigint values may be rounded; update Atlas before relying on exact numbers`, status, 'LOSSLESS_TRANSPORT_UNAVAILABLE');
+}