@sequenceholdings/artifact-studio 0.3.1 → 0.5.0

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');
+}

package/dist/project.js

@@ -9,7 +9,7 @@ import { readNextSourceSnapshot } from './next-source.js';
 import { normalizeArtifactPath } from './paths.js';
 const IGNORED_DIRS = new Set(['node_modules', '.git', 'dist', '.next', '.artifact-studio']);
 const TEXT_EXTENSIONS = new Set([
-    '.ts', '.tsx', '.js', '.jsx', '.json', '.css', '.html', '.md', '.yml', '.yaml', '.svg',
+    '.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs', '.json', '.css', '.html', '.md', '.yml', '.yaml', '.svg',
 ]);
 export function hasArtifactStudioManifest(rootDir) {
     return existsSync(join(resolve(rootDir), 'artifact.bundle.yml'));
@@ -83,9 +83,9 @@ function isTextFile(path) {
         TEXT_EXTENSIONS.has(ext));
 }
 function inferContentType(path) {
-    if (path.endsWith('.tsx') || path.endsWith('.ts'))
+    if (/\.(?:tsx?|mts|cts)$/.test(path))
         return 'text/typescript';
-    if (path.endsWith('.jsx') || path.endsWith('.js'))
+    if (/\.(?:jsx?|mjs|cjs)$/.test(path))
         return 'text/javascript';
     if (path.endsWith('.css'))
         return 'text/css';

package/dist/role-definitions-notice.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Capabilities are code, roles are data: roles are created in Atlas, and
+ * `capabilities.roles.definitions` here is a deprecated one-time seed (a
+ * deploy creates any that don't exist yet and never updates them). Atlas only
+ * logs the drift, so tell the author.
+ */
+export declare function warnOnRoleDefinitions(manifest: unknown, warn?: (line: string) => void): void;

package/dist/role-definitions-notice.js

@@ -0,0 +1,19 @@
+/**
+ * Capabilities are code, roles are data: roles are created in Atlas, and
+ * `capabilities.roles.definitions` here is a deprecated one-time seed (a
+ * deploy creates any that don't exist yet and never updates them). Atlas only
+ * logs the drift, so tell the author.
+ */
+export function warnOnRoleDefinitions(manifest, warn = console.warn) {
+    // A non-null, non-array object is safe to index by key; TS can't narrow `object` to a record itself.
+    const record = (value) => typeof value === 'object' && value !== null && !Array.isArray(value) ? value : null;
+    const definitions = record(record(record(record(manifest)?.capabilities)?.roles)?.definitions);
+    if (!definitions)
+        return;
+    const keys = Object.keys(definitions).sort();
+    if (keys.length === 0)
+        return;
+    warn(`[seq-studio] artifact.bundle.yml defines roles (${keys.join(', ')}). Roles in YAML are a deprecated one-time seed: ` +
+        `a deploy creates any that don't exist yet and never updates them after. Create and edit roles in Atlas ` +
+        `(Permissions → Roles); keep capabilities in YAML.`);
+}

package/dist/runtime-contracts.d.ts

@@ -72,9 +72,9 @@ export declare const artifactOperationSchema: z.ZodDiscriminatedUnion<[z.ZodObje
     projectId: z.ZodString;
     environment: z.ZodString;
     kind: z.ZodEnum<{
-        preview: "preview";
         build: "build";
         deploy: "deploy";
+        preview: "preview";
         rollback: "rollback";
         suspend: "suspend";
         delete: "delete";
@@ -92,9 +92,9 @@ export declare const artifactOperationSchema: z.ZodDiscriminatedUnion<[z.ZodObje
     projectId: z.ZodString;
     environment: z.ZodString;
     kind: z.ZodEnum<{
-        preview: "preview";
         build: "build";
         deploy: "deploy";
+        preview: "preview";
         rollback: "rollback";
         suspend: "suspend";
         delete: "delete";
@@ -109,9 +109,9 @@ export declare const artifactOperationSchema: z.ZodDiscriminatedUnion<[z.ZodObje
     projectId: z.ZodString;
     environment: z.ZodString;
     kind: z.ZodEnum<{
-        preview: "preview";
         build: "build";
         deploy: "deploy";
+        preview: "preview";
         rollback: "rollback";
         suspend: "suspend";
         delete: "delete";
@@ -130,9 +130,9 @@ export declare const artifactOperationSchema: z.ZodDiscriminatedUnion<[z.ZodObje
     projectId: z.ZodString;
     environment: z.ZodString;
     kind: z.ZodEnum<{
-        preview: "preview";
         build: "build";
         deploy: "deploy";
+        preview: "preview";
         rollback: "rollback";
         suspend: "suspend";
         delete: "delete";
@@ -147,9 +147,9 @@ export declare const artifactOperationSchema: z.ZodDiscriminatedUnion<[z.ZodObje
     projectId: z.ZodString;
     environment: z.ZodString;
     kind: z.ZodEnum<{
-        preview: "preview";
         build: "build";
         deploy: "deploy";
+        preview: "preview";
         rollback: "rollback";
         suspend: "suspend";
         delete: "delete";
@@ -164,9 +164,9 @@ export declare const artifactRuntimeSessionSchema: z.ZodObject<{
     projectId: z.ZodString;
     environment: z.ZodString;
     mode: z.ZodEnum<{
+        local: "local";
         preview: "preview";
         published: "published";
-        local: "local";
     }>;
     origin: z.ZodString;
     parentOrigin: z.ZodString;
@@ -187,12 +187,12 @@ export declare const artifactLocalDevSessionSchema: z.ZodObject<{
     sourceRevision: z.ZodOptional<z.ZodString>;
     revision: z.ZodNumber;
     state: z.ZodEnum<{
+        offline: "offline";
         failed: "failed";
         starting: "starting";
         compiling: "compiling";
         ready: "ready";
         reconnecting: "reconnecting";
-        offline: "offline";
         revoked: "revoked";
         expired: "expired";
     }>;

package/dist/runtime-contracts.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { ARTIFACT_NEXT_RUNTIME, artifactNextSecretNameSchema } from './manifest-next.js';
 import { MAX_STUDIO_PATH_LENGTH } from './paths.js';
+import { isLoopbackHostname } from './loopback.js';
 export { resolveArtifactNextImages } from './next-image-config.js';
 /** Shared by local collection, repository collection and the bounded source-upload API. */
 export const ARTIFACT_NEXT_SOURCE_LIMITS = Object.freeze({
@@ -42,7 +43,7 @@ export const artifactSourcePathSchema = z.string().min(1).max(MAX_STUDIO_PATH_LE
 export const artifactRuntimeOriginSchema = z.string().max(2048).refine((value) => {
     try {
         const url = new URL(value);
-        return url.protocol === 'https:' && url.origin === value && !url.hostname.includes('*');
+        return (url.protocol === 'https:' || (url.protocol === 'http:' && isLoopbackHostname(url.hostname))) && url.origin === value && !url.hostname.includes('*');
     }
     catch {
         return false;

package/dist/sandbox-lint.js

@@ -42,7 +42,7 @@ const RULES = [
         message: "Direct fetch() to an external origin is blocked (CSP connect-src 'self') — call Atlas routes via seq.api.fetch.",
     },
 ];
-const LINTABLE_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.css', '.html']);
+const LINTABLE_EXTENSIONS = new Set(['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs', '.css', '.html']);
 function extensionOf(path) {
     return path.includes('.') ? path.slice(path.lastIndexOf('.')) : '';
 }

package/dist/sdk-orm.d.ts

@@ -0,0 +1,24 @@
+import { type OperationExecutor } from '@sequenceholdings/orm/client';
+import { type ArtifactOrmJsonScalars } from './orm-json-scalars.js';
+import { type SequenceApi } from './sdk.js';
+export interface ArtifactOrmExecutorConfig {
+    namespace: string;
+    /** The generated operations.manifest.json, validated before any host call. */
+    manifest: unknown;
+    /** Optional action-scoped host client (for example, withTraceAction's client). */
+    sdk?: {
+        api: Pick<SequenceApi, 'fetch'>;
+    };
+    /**
+     * `lossless-v1` returns numeric and bigint values as strings instead of JSON numbers.
+     * The executor refuses any successful result the host does not acknowledge in that form.
+     */
+    jsonScalars?: ArtifactOrmJsonScalars;
+}
+/**
+ * Execute persisted operations as the signed-in Artifact user. The host owns
+ * authentication; this helper never obtains or exposes browser credentials.
+ * Declare the namespace path in capabilities.api.write (queries also use POST).
+ * Namespace grants, capabilities, row policies, and write checks still apply.
+ */
+export declare function createArtifactOrmExecutor({ namespace, manifest, sdk, jsonScalars }: ArtifactOrmExecutorConfig): OperationExecutor;

package/dist/sdk-orm.js

@@ -0,0 +1,28 @@
+import { createOperationExecutorWithTransport, OrmClientError } from '@sequenceholdings/orm/client';
+import { assertJsonScalarsAcknowledged, ORM_JSON_SCALARS_HEADER } from './orm-json-scalars.js';
+import { seq } from './sdk.js';
+/**
+ * Execute persisted operations as the signed-in Artifact user. The host owns
+ * authentication; this helper never obtains or exposes browser credentials.
+ * Declare the namespace path in capabilities.api.write (queries also use POST).
+ * Namespace grants, capabilities, row policies, and write checks still apply.
+ */
+export function createArtifactOrmExecutor({ namespace, manifest, sdk = seq, jsonScalars }) {
+    if (!sdk || typeof sdk.api?.fetch !== 'function') {
+        throw new OrmClientError('Artifact ORM requires the authenticated Artifact Studio host; open the deployed artifact or its Preview');
+    }
+    return createOperationExecutorWithTransport({
+        namespace,
+        manifest,
+        transport: async ({ namespace: target, op, variables, idempotencyKey }) => {
+            const response = await sdk.api.fetch(`/api/data/v2/${target}`, {
+                method: 'POST',
+                body: { op, variables, ...(idempotencyKey === undefined ? {} : { idempotencyKey }) },
+                ...(jsonScalars ? { headers: { [ORM_JSON_SCALARS_HEADER]: jsonScalars } } : {}),
+            });
+            if (response.ok)
+                assertJsonScalarsAcknowledged({ requested: jsonScalars, acknowledged: response.headers?.[ORM_JSON_SCALARS_HEADER], status: response.status });
+            return response;
+        },
+    });
+}

package/dist/sdk.d.ts

@@ -1,4 +1,6 @@
 import { type StartStorageUpload, type StorageUploadSession } from '@sequenceholdings/storage';
+export { createArtifactOrmExecutor, type ArtifactOrmExecutorConfig } from './sdk-orm.js';
+export type { ArtifactOrmJsonScalars } from './orm-json-scalars.js';
 export interface SequenceStorageOptions {
     signal?: AbortSignal;
     timeoutMs?: number;
@@ -47,6 +49,54 @@ export interface SequenceApi {
     patch<TBody = unknown>(path: string, body?: unknown): Promise<TBody>;
     delete<TBody = unknown>(path: string, body?: unknown): Promise<TBody>;
 }
+export type SequenceOfflineRequestMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+export interface SequenceOfflineRequest {
+    method: SequenceOfflineRequestMethod;
+    path: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+}
+export interface SequenceOfflineConnectorExecution<TBody = unknown> {
+    request: SequenceOfflineRequest;
+    /**
+     * Invoke the authenticated Artifact Studio bridge. Authentication remains
+     * host-owned and is never exposed to the connector or durable storage.
+     */
+    network: (request: SequenceOfflineRequest) => Promise<SequenceApiFetchResponse<TBody>>;
+}
+export interface SequenceOfflineNetwork {
+    execute<TBody = unknown>(request: SequenceOfflineRequest): Promise<SequenceApiFetchResponse<TBody>>;
+}
+export interface SequenceOfflineRequestConnector {
+    execute<TBody = unknown>(execution: SequenceOfflineConnectorExecution<TBody>): Promise<SequenceApiFetchResponse<TBody>>;
+    /**
+     * Receives a capability-gated bridge executor for durable outbox replay.
+     * It carries no bearer token and remains subject to the active manifest.
+     */
+    attach?(context: {
+        network: SequenceOfflineNetwork;
+    }): void | (() => void);
+}
+export interface SequenceOffline {
+    /**
+     * Install the artifact's request policy beneath seq.api. Returns a disposer
+     * that restores the network-only default when it still owns registration.
+     */
+    registerConnector(registration: {
+        connector: SequenceOfflineRequestConnector;
+    }): () => void;
+    /** Cache the current artifact shell on this device after the user's opt-in. */
+    enroll(options?: {
+        maxAgeHours?: number;
+    }): Promise<void>;
+    /** Remove this artifact's cached shell. App-owned data should be wiped too. */
+    remove(): Promise<void>;
+    status(): Promise<{
+        enabled: boolean;
+        enrolled: boolean;
+        expiresAt?: number;
+    }>;
+}
 export interface SequenceFunctions {
     invoke<TOutput = unknown>(id: string, params?: Record<string, unknown>, traceAction?: {
         id: string;
@@ -134,6 +184,7 @@ export interface SequenceHost {
 export interface SequenceArtifactSdk {
     storage: SequenceStorage;
     api: SequenceApi;
+    offline: SequenceOffline;
     ai: {
         fetch(path: string, options?: SequenceApiFetchOptions): Promise<Response>;
     };
@@ -210,6 +261,73 @@ export declare function createArtifactStorageClient(sdk?: SequenceArtifactSdk):
                 versionId: string | null;
                 maxBytes: number;
             }>;
+            startBatch: (items: StartStorageUpload[]) => Promise<{
+                items: {
+                    id: string;
+                    fileId: string;
+                    uploadUrl: string | null;
+                    expiresAt: string;
+                    state: "pending" | "complete" | "aborted";
+                    versionId: string | null;
+                    maxBytes: number;
+                }[];
+            }>;
+            list: () => Promise<{
+                items: {
+                    id: string;
+                    fileId: string;
+                    name: string;
+                    state: "pending" | "complete" | "aborted";
+                    expiresAt: string;
+                    maxBytes: number;
+                    expectedSize: number | null;
+                    versionId: string | null;
+                }[];
+                limits: {
+                    perPrincipal: number;
+                    perWorkspace: number;
+                };
+            }>;
+            reconcile: (input?: {
+                abortIncomplete?: boolean;
+            }) => Promise<{
+                completed: {
+                    id: string;
+                    fileId: string;
+                    name: string;
+                    state: "pending" | "complete" | "aborted";
+                    expiresAt: string;
+                    maxBytes: number;
+                    expectedSize: number | null;
+                    versionId: string | null;
+                    code: string;
+                    message: string;
+                }[];
+                aborted: {
+                    id: string;
+                    fileId: string;
+                    name: string;
+                    state: "pending" | "complete" | "aborted";
+                    expiresAt: string;
+                    maxBytes: number;
+                    expectedSize: number | null;
+                    versionId: string | null;
+                    code: string;
+                    message: string;
+                }[];
+                pending: {
+                    id: string;
+                    fileId: string;
+                    name: string;
+                    state: "pending" | "complete" | "aborted";
+                    expiresAt: string;
+                    maxBytes: number;
+                    expectedSize: number | null;
+                    versionId: string | null;
+                    code: string;
+                    message: string;
+                }[];
+            }>;
         };
         get: () => Promise<{
             id: string;
@@ -488,6 +606,15 @@ export declare function createArtifactStorageClient(sdk?: SequenceArtifactSdk):
     capabilities: () => Promise<{
         canProvision: boolean;
         uploadMethods: string[];
+        pendingUploads: {
+            perPrincipal: number;
+            perWorkspace: number;
+        };
+        uploadBatchLimit: number;
+        importConcurrency: {
+            default: number;
+            max: number;
+        };
     }>;
     list: (options?: import("@sequenceholdings/storage").StorageListOptions) => Promise<{
         items: {

package/dist/sdk.js

@@ -1,4 +1,5 @@
 import { storageClient } from '@sequenceholdings/storage';
+export { createArtifactOrmExecutor } from './sdk-orm.js';
 export const seq = typeof window !== 'undefined'
     ? window.seq
     : undefined;