@sequenceholdings/artifact-studio 0.4.0 → 0.5.0

package/dist/server/broker-contract.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+export { ORM_JSON_SCALARS_HEADER, ORM_LOSSLESS_JSON_SCALARS, type ArtifactOrmJsonScalars } from '../orm-json-scalars.js';
 export declare const artifactServerMethodSchema: z.ZodEnum<{
     GET: "GET";
     POST: "POST";
@@ -8,17 +9,38 @@ export declare const artifactServerMethodSchema: z.ZodEnum<{
     PATCH: "PATCH";
 }>;
 export declare const artifactServerModeSchema: z.ZodDefault<z.ZodEnum<{
-    user: "user";
     service: "service";
+    user: "user";
 }>>;
 /** Reject paths that intermediaries can normalize into a different authorization target. */
 export declare function isArtifactApiPath(path: string): boolean;
+/** A Lattice run's lifecycle status, as `GET /api/lattice/runs` filters it. */
+export declare const ARTIFACT_PROCESS_RUN_STATUSES: readonly ["pending", "running", "completed", "failed", "cancelled", "timed_out"];
+/** Lattice lists at most this many runs per call. */
+export declare const ARTIFACT_PROCESS_RUNS_LIMIT = 500;
+/** Which of the user's human steps to list: parked and waiting on them, or already done. */
+export declare const ARTIFACT_PROCESS_TASK_VIEWS: readonly ["active", "completed"];
+/** Lattice lists at most this many human steps per call, as its own inbox does. */
+export declare const ARTIFACT_PROCESS_TASKS_LIMIT = 500;
+/** A grant or revocation names at most this many users and groups together. */
+export declare const ARTIFACT_PROCESS_PRINCIPALS_PER_CALL = 100;
+/** A principal search returns at most this many users and groups together, as Lattice's own picker. */
+export declare const ARTIFACT_PROCESS_PRINCIPAL_SEARCH_LIMIT = 50;
+export declare const ARTIFACT_PROCESS_PRINCIPAL_TYPES: readonly ["user", "group"];
+/** A start seeds assignments for at most this many human nodes. */
+export declare const ARTIFACT_PROCESS_START_ASSIGNMENT_NODES = 64;
+export declare const ARTIFACT_FLAGS_PER_REQUEST = 32;
+/** The audit actions an application may record. Sign-in, identity merges and webhooks stay Atlas's. */
+export declare const ARTIFACT_AUDIT_ACTIONS: readonly ["view", "search", "create", "update", "delete", "download", "upload", "export", "import", "share", "submit", "approve", "reject", "execute"];
+/** One bulk action (archive the 100 selected applications) is one event naming each of them. */
+export declare const ARTIFACT_AUDIT_RESOURCES_PER_EVENT = 100;
+export declare const ARTIFACT_AUDIT_METADATA_KEYS = 32;
 /** Atlas validates these operations against current manifest, bindings and principal grants. */
 export declare const artifactServerRequestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     operation: z.ZodLiteral<"api">;
     mode: z.ZodDefault<z.ZodEnum<{
-        user: "user";
         service: "service";
+        user: "user";
     }>>;
     method: z.ZodEnum<{
         GET: "GET";
@@ -33,17 +55,18 @@ export declare const artifactServerRequestSchema: z.ZodDiscriminatedUnion<[z.Zod
 }, z.core.$strict>, z.ZodObject<{
     operation: z.ZodLiteral<"orm">;
     mode: z.ZodDefault<z.ZodEnum<{
-        user: "user";
         service: "service";
+        user: "user";
     }>>;
     namespace: z.ZodString;
     op: z.ZodString;
     variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    jsonScalars: z.ZodOptional<z.ZodLiteral<"lossless-v1">>;
 }, z.core.$strict>, z.ZodObject<{
     operation: z.ZodLiteral<"storage">;
     mode: z.ZodDefault<z.ZodEnum<{
-        user: "user";
         service: "service";
+        user: "user";
     }>>;
     method: z.ZodEnum<{
         GET: "GET";
@@ -58,11 +81,174 @@ export declare const artifactServerRequestSchema: z.ZodDiscriminatedUnion<[z.Zod
 }, z.core.$strict>, z.ZodObject<{
     operation: z.ZodLiteral<"function">;
     mode: z.ZodDefault<z.ZodEnum<{
-        user: "user";
         service: "service";
+        user: "user";
     }>>;
     id: z.ZodString;
     params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"lattice">;
+    mode: z.ZodDefault<z.ZodEnum<{
+        service: "service";
+        user: "user";
+    }>>;
+    process: z.ZodString;
+    runId: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    entity: z.ZodOptional<z.ZodObject<{
+        type: z.ZodString;
+        id: z.ZodString;
+    }, z.core.$strict>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    assignments: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        users: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        groups: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"lattice_runs">;
+    mode: z.ZodDefault<z.ZodEnum<{
+        service: "service";
+        user: "user";
+    }>>;
+    process: z.ZodString;
+    status: z.ZodOptional<z.ZodEnum<{
+        running: "running";
+        failed: "failed";
+        cancelled: "cancelled";
+        pending: "pending";
+        completed: "completed";
+        timed_out: "timed_out";
+    }>>;
+    entity: z.ZodOptional<z.ZodObject<{
+        type: z.ZodString;
+        id: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    archived: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"lattice_run">;
+    mode: z.ZodDefault<z.ZodEnum<{
+        service: "service";
+        user: "user";
+    }>>;
+    runId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"lattice_process">;
+    mode: z.ZodDefault<z.ZodEnum<{
+        service: "service";
+        user: "user";
+    }>>;
+    process: z.ZodString;
+    version: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"lattice_tasks">;
+    mode: z.ZodDefault<z.ZodEnum<{
+        service: "service";
+        user: "user";
+    }>>;
+    processes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    view: z.ZodOptional<z.ZodEnum<{
+        active: "active";
+        completed: "completed";
+    }>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"lattice_advance">;
+    mode: z.ZodDefault<z.ZodEnum<{
+        service: "service";
+        user: "user";
+    }>>;
+    runId: z.ZodString;
+    stepId: z.ZodOptional<z.ZodString>;
+    edgeId: z.ZodOptional<z.ZodString>;
+    payload: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>, z.ZodObject<{
+    users: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    groups: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    operation: z.ZodLiteral<"lattice_assign">;
+    mode: z.ZodDefault<z.ZodEnum<{
+        service: "service";
+        user: "user";
+    }>>;
+    runId: z.ZodString;
+    stepId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"lattice_viewers">;
+    mode: z.ZodDefault<z.ZodEnum<{
+        service: "service";
+        user: "user";
+    }>>;
+    runId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    users: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    groups: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    operation: z.ZodLiteral<"lattice_viewer_grant">;
+    mode: z.ZodDefault<z.ZodEnum<{
+        service: "service";
+        user: "user";
+    }>>;
+    runId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    users: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    groups: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    operation: z.ZodLiteral<"lattice_viewer_revoke">;
+    mode: z.ZodDefault<z.ZodEnum<{
+        service: "service";
+        user: "user";
+    }>>;
+    runId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"lattice_principals">;
+    mode: z.ZodDefault<z.ZodEnum<{
+        service: "service";
+        user: "user";
+    }>>;
+    q: z.ZodString;
+    types: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        user: "user";
+        group: "group";
+    }>>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"flags">;
+    mode: z.ZodDefault<z.ZodEnum<{
+        service: "service";
+        user: "user";
+    }>>;
+    names: z.ZodArray<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    eventId: z.ZodUUID;
+    action: z.ZodEnum<{
+        search: "search";
+        delete: "delete";
+        import: "import";
+        share: "share";
+        upload: "upload";
+        submit: "submit";
+        view: "view";
+        create: "create";
+        update: "update";
+        download: "download";
+        export: "export";
+        approve: "approve";
+        reject: "reject";
+        execute: "execute";
+    }>;
+    detail: z.ZodString;
+    resources: z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        id: z.ZodString;
+    }, z.core.$strict>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+    operation: z.ZodLiteral<"audit">;
+    mode: z.ZodDefault<z.ZodEnum<{
+        service: "service";
+        user: "user";
+    }>>;
 }, z.core.$strict>], "operation">;
 export type ArtifactServerRequest = z.infer<typeof artifactServerRequestSchema>;
 export type ArtifactServerMode = z.infer<typeof artifactServerModeSchema>;
+export type ArtifactAuditAction = (typeof ARTIFACT_AUDIT_ACTIONS)[number];
+export type ArtifactProcessRunStatus = (typeof ARTIFACT_PROCESS_RUN_STATUSES)[number];
+export type ArtifactProcessTaskView = (typeof ARTIFACT_PROCESS_TASK_VIEWS)[number];
+export type ArtifactProcessPrincipalType = (typeof ARTIFACT_PROCESS_PRINCIPAL_TYPES)[number];

package/dist/server/broker-contract.js

@@ -1,4 +1,6 @@
 import { z } from 'zod';
+import { ORM_LOSSLESS_JSON_SCALARS } from '../orm-json-scalars.js';
+export { ORM_JSON_SCALARS_HEADER, ORM_LOSSLESS_JSON_SCALARS } from '../orm-json-scalars.js';
 export const artifactServerMethodSchema = z.enum(['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE']);
 export const artifactServerModeSchema = z.enum(['user', 'service']).default('user');
 /** Reject paths that intermediaries can normalize into a different authorization target. */
@@ -21,13 +23,152 @@ const path = z.string().min(6).max(8192).refine(isArtifactApiPath, 'Expected a c
 const method = artifactServerMethodSchema;
 const mode = artifactServerModeSchema;
 const id = z.string().min(1).max(255).regex(/^[a-zA-Z0-9_-]+$/);
+// Lattice ids become FGA object ids, so they keep to the FGA-safe class.
+const latticeId = z.string().min(2).max(128).regex(/^[A-Za-z0-9._-]+$/);
+// A process version is the registry's own label (the bundle hash prefix today); FGA-safe class.
+const latticeVersion = z.string().min(1).max(128).regex(/^[A-Za-z0-9._-]+$/);
+/** A Lattice run's lifecycle status, as `GET /api/lattice/runs` filters it. */
+export const ARTIFACT_PROCESS_RUN_STATUSES = ['pending', 'running', 'completed', 'failed', 'cancelled', 'timed_out'];
+/** Lattice lists at most this many runs per call. */
+export const ARTIFACT_PROCESS_RUNS_LIMIT = 500;
+/** Which of the user's human steps to list: parked and waiting on them, or already done. */
+export const ARTIFACT_PROCESS_TASK_VIEWS = ['active', 'completed'];
+/** Lattice lists at most this many human steps per call, as its own inbox does. */
+export const ARTIFACT_PROCESS_TASKS_LIMIT = 500;
+/** A grant or revocation names at most this many users and groups together. */
+export const ARTIFACT_PROCESS_PRINCIPALS_PER_CALL = 100;
+/** A principal search returns at most this many users and groups together, as Lattice's own picker. */
+export const ARTIFACT_PROCESS_PRINCIPAL_SEARCH_LIMIT = 50;
+export const ARTIFACT_PROCESS_PRINCIPAL_TYPES = ['user', 'group'];
+// A user's Auth0 `sub` or a chat group id, as FGA subjects are keyed: no whitespace, `:`, `#` or `*`.
+const principalId = z.string().min(1).max(255).regex(/^[^\s:#*]+$/);
+/** The users and groups a grant, revocation or reassignment names: at least one principal, bounded. */
+const principalSet = {
+    users: z.array(principalId).max(ARTIFACT_PROCESS_PRINCIPALS_PER_CALL).optional(),
+    groups: z.array(principalId).max(ARTIFACT_PROCESS_PRINCIPALS_PER_CALL).optional(),
+};
+function namesPrincipals(value) {
+    const count = (value.users?.length ?? 0) + (value.groups?.length ?? 0);
+    return count > 0 && count <= ARTIFACT_PROCESS_PRINCIPALS_PER_CALL;
+}
+const PRINCIPAL_SET_MESSAGE = `Between 1 and ${ARTIFACT_PROCESS_PRINCIPALS_PER_CALL} users and groups`;
+/** A start seeds assignments for at most this many human nodes. */
+export const ARTIFACT_PROCESS_START_ASSIGNMENT_NODES = 64;
+// A human node of the started run (`execute`), or one inside a nested subprocess (`application::qa_review`).
+const assignmentNodeKey = z.string().min(1).max(255).regex(/^[A-Za-z0-9._-]+(?:::[A-Za-z0-9._-]+)*$/);
+/**
+ * Per-run default assignees for human nodes, as `POST /api/lattice/runs` takes them: each node's
+ * principals become its advancers when the run reaches it. Atlas refuses principals it has tombstoned.
+ */
+const runAssignments = z.record(assignmentNodeKey, z.object(principalSet).strict().refine(namesPrincipals, PRINCIPAL_SET_MESSAGE))
+    .refine((value) => Object.keys(value).length > 0 && Object.keys(value).length <= ARTIFACT_PROCESS_START_ASSIGNMENT_NODES, `Between 1 and ${ARTIFACT_PROCESS_START_ASSIGNMENT_NODES} assigned nodes`);
+const entityRef = z.string().min(1).max(255);
+// Unleash feature names are URL-safe.
+const flagName = z.string().min(1).max(255).regex(/^[A-Za-z0-9._~-]+$/);
+export const ARTIFACT_FLAGS_PER_REQUEST = 32;
+/** The audit actions an application may record. Sign-in, identity merges and webhooks stay Atlas's. */
+export const ARTIFACT_AUDIT_ACTIONS = [
+    'view', 'search', 'create', 'update', 'delete', 'download', 'upload', 'export', 'import', 'share', 'submit', 'approve', 'reject', 'execute',
+];
+/** One bulk action (archive the 100 selected applications) is one event naming each of them. */
+export const ARTIFACT_AUDIT_RESOURCES_PER_EVENT = 100;
+export const ARTIFACT_AUDIT_METADATA_KEYS = 32;
+// Resource types are identifiers, as Atlas's own (`application`, `applicationDocument`), so an
+// application that takes over a product's routes can keep the types its audit queries filter on.
+const auditResourceType = z.string().regex(/^[A-Za-z][A-Za-z0-9_]{0,63}$/);
+const auditMetadataKey = z.string().regex(/^[A-Za-z][A-Za-z0-9_]{0,63}$/);
+const auditEvent = {
+    /** Names the logical event. A retry of the same event reuses it, so the audit sink keeps one copy. */
+    eventId: z.uuid(),
+    action: z.enum(ARTIFACT_AUDIT_ACTIONS),
+    /** What happened, as the product names it (`applications.view`). Recorded as the event's `action_detail`. */
+    detail: z.string().regex(/^[a-z][a-z0-9_.-]{0,95}$/),
+    // None for an event about no one record (a list or a settings view), as Atlas's own list events.
+    resources: z.array(z.object({ type: auditResourceType, id: z.string().min(1).max(255) }).strict())
+        .max(ARTIFACT_AUDIT_RESOURCES_PER_EVENT),
+    // Scalars only: an audit record names what happened, it doesn't copy payloads.
+    metadata: z.record(auditMetadataKey, z.union([z.string().max(256), z.number(), z.boolean(), z.null()]))
+        .refine(value => Object.keys(value).length <= ARTIFACT_AUDIT_METADATA_KEYS, `At most ${ARTIFACT_AUDIT_METADATA_KEYS} metadata keys`)
+        .optional(),
+};
 /** Atlas validates these operations against current manifest, bindings and principal grants. */
 export const artifactServerRequestSchema = z.discriminatedUnion('operation', [
     z.object({ operation: z.literal('api'), mode, method, path, body: z.unknown().optional() }).strict(),
-    z.object({ operation: z.literal('orm'), mode, namespace: id, op: z.string().regex(/^sha256:[a-f0-9]{64}$/), variables: z.record(z.string(), z.unknown()).optional() }).strict(),
+    // jsonScalars asks the data plane for exact numeric and bigint strings; Atlas forwards it as
+    // the data plane's own header and passes the acknowledgment back.
+    z.object({
+        operation: z.literal('orm'), mode, namespace: id, op: z.string().regex(/^sha256:[a-f0-9]{64}$/),
+        variables: z.record(z.string(), z.unknown()).optional(), jsonScalars: z.literal(ORM_LOSSLESS_JSON_SCALARS).optional(),
+    }).strict(),
     z.object({ operation: z.literal('storage'), mode, method, path: path.refine(value => {
             const pathname = value.split('?')[0];
             return pathname === '/api/storage' || pathname.startsWith('/api/storage/');
         }, 'Expected a Storage API path'), body: z.unknown().optional() }).strict(),
     z.object({ operation: z.literal('function'), mode, id, params: z.record(z.string(), z.unknown()).optional() }).strict(),
+    // Starts a run of a declared process, as `POST /api/lattice/runs` does: the application names the
+    // run, passes its input and may seed who works each human node. The start node, version and
+    // engine stay with the process and its owning routes.
+    z.object({
+        operation: z.literal('lattice'), mode, process: latticeId, runId: latticeId.optional(),
+        title: z.string().max(500).optional(),
+        entity: z.object({ type: entityRef, id: entityRef }).strict().optional(),
+        metadata: z.record(z.string(), z.unknown()).optional(),
+        assignments: runAssignments.optional(),
+    }).strict(),
+    // Lists runs of a declared process, as `GET /api/lattice/runs` does: newest first, only the runs
+    // the user may view. Soft-archived runs are excluded unless `archived` is set.
+    z.object({
+        operation: z.literal('lattice_runs'), mode, process: latticeId,
+        status: z.enum(ARTIFACT_PROCESS_RUN_STATUSES).optional(),
+        entity: z.object({ type: entityRef, id: entityRef.optional() }).strict().optional(),
+        limit: z.number().int().min(1).max(ARTIFACT_PROCESS_RUNS_LIMIT).optional(),
+        archived: z.boolean().optional(),
+    }).strict(),
+    // Reads one run the user may view, as `GET /api/lattice/runs/[runId]` does: the run, its steps, the
+    // collapsed per-node states and the event cursor to resume its stream from.
+    z.object({ operation: z.literal('lattice_run'), mode, runId: latticeId }).strict(),
+    // Describes a declared process — the applied template its runs are filled in from: nodes, edges and
+    // what a person working each human step is shown. The active version, or the one a run pinned.
+    z.object({ operation: z.literal('lattice_process'), mode, process: latticeId, version: latticeVersion.optional() }).strict(),
+    // Lists the user's own human steps across declared processes (a subset, or every declared one),
+    // as `GET /api/lattice/inbox` does for the Tasks app: newest first, from the assignment index.
+    z.object({
+        operation: z.literal('lattice_tasks'), mode,
+        processes: z.array(latticeId).min(1).max(256).optional(),
+        view: z.enum(ARTIFACT_PROCESS_TASK_VIEWS).optional(),
+        limit: z.number().int().min(1).max(ARTIFACT_PROCESS_TASKS_LIMIT).optional(),
+    }).strict(),
+    // Completes one of the user's parked human steps on a run of a process declared under
+    // `processes.act`, as `POST /api/lattice/runs/[runId]/advance` does. The user's own step
+    // `advancer` grant decides; the application cannot complete it as someone else.
+    z.object({
+        operation: z.literal('lattice_advance'), mode, runId: latticeId,
+        stepId: latticeId.optional(), edgeId: z.string().min(1).max(255).optional(),
+        payload: z.record(z.string(), z.unknown()).optional(),
+    }).strict(),
+    // Reassigns a parked human step to users and groups, as `POST .../steps/[stepId]/assign` does.
+    // The user's run `owner` relation decides; the node's assignee allowlist still applies.
+    z.object({ operation: z.literal('lattice_assign'), mode, runId: latticeId, stepId: latticeId, ...principalSet }).strict()
+        .refine(namesPrincipals, PRINCIPAL_SET_MESSAGE),
+    // The explicit viewer grants on a run, for its owner.
+    z.object({ operation: z.literal('lattice_viewers'), mode, runId: latticeId }).strict(),
+    // Shares a run with users and groups (grants `viewer`), or takes a share back. Owner-gated;
+    // grants Atlas has tombstoned (disabled users, deleted groups) are refused.
+    z.object({ operation: z.literal('lattice_viewer_grant'), mode, runId: latticeId, ...principalSet }).strict()
+        .refine(namesPrincipals, PRINCIPAL_SET_MESSAGE),
+    z.object({ operation: z.literal('lattice_viewer_revoke'), mode, runId: latticeId, ...principalSet }).strict()
+        .refine(namesPrincipals, PRINCIPAL_SET_MESSAGE),
+    // Finds users in the user's own tenant and groups they may see, to name in an assignment or a
+    // share. The user is the directory's own, so no manifest binding beyond `processes.act` applies.
+    z.object({
+        operation: z.literal('lattice_principals'), mode, q: z.string().trim().max(200),
+        types: z.array(z.enum(ARTIFACT_PROCESS_PRINCIPAL_TYPES)).min(1).max(2).optional(),
+        limit: z.number().int().min(1).max(ARTIFACT_PROCESS_PRINCIPAL_SEARCH_LIMIT).optional(),
+    }).strict(),
+    // Evaluates feature flags as Atlas evaluates its own: for the user, or with no user in service mode.
+    // A read: it needs no manifest declaration, as the browser bridge's flags.isEnabled needs none.
+    z.object({ operation: z.literal('flags'), mode, names: z.array(flagName).min(1).max(ARTIFACT_FLAGS_PER_REQUEST) }).strict(),
+    // Records an audit event for the request's user, under the service `server.capabilities.audit`
+    // declares. It changes no data, so read-only and stale contexts may record what they read.
+    z.object({ operation: z.literal('audit'), mode, ...auditEvent }).strict(),
 ]);

package/dist/server/client.d.ts

@@ -1,15 +1,14 @@
 import { storageClient } from '@sequenceholdings/storage';
 import { type OperationExecutor } from '@sequenceholdings/orm/client';
 import type { SequenceApiFetchResponse } from '../sdk.js';
-import { type ArtifactServerMode, type ArtifactServerRequest } from './broker-contract.js';
+import { type ArtifactAuditAction, type ArtifactServerMode, type ArtifactServerRequest } from './broker-contract.js';
+import { type ArtifactServerProcesses } from './processes.js';
+import { type ArtifactOrmJsonScalars } from '../orm-json-scalars.js';
 import { createArtifactLogger, type ArtifactLogRecord } from './logger.js';
 import { type ArtifactRequestContext } from './request-context.js';
 import { type ArtifactRuntimeConfig, type ArtifactRequestHeaders } from './runtime-config.js';
-export declare class ArtifactServerError extends Error {
-    readonly status: number;
-    readonly code: string;
-    constructor(status: number, code: string, message: string);
-}
+export { ArtifactServerError } from './errors.js';
+export type * from './processes.js';
 export interface ArtifactServerFetchOptions {
     method?: 'GET' | 'HEAD' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
     body?: unknown;
@@ -29,6 +28,49 @@ export interface ArtifactOrmOperations {
         readonly requires?: unknown;
     }>>;
 }
+export interface ArtifactOrmOptions {
+    namespace: string;
+    manifest: ArtifactOrmOperations;
+    /**
+     * `lossless-v1` returns numeric and bigint values as strings instead of JSON numbers,
+     * so money and large ids survive a read-then-write. The executor refuses any successful
+     * result Atlas does not acknowledge in that form. Omit it for the JSON-number default.
+     */
+    jsonScalars?: ArtifactOrmJsonScalars;
+}
+/**
+ * Feature flags, evaluated by Atlas for this request's user (with no user in service mode), the
+ * same evaluation Atlas routes make. Any flag may be read, as in the browser's `seq.flags`. A
+ * refused or failed request rejects with ArtifactServerError; treat that as off where a flag gates
+ * a change.
+ */
+export interface ArtifactServerFlags {
+    isEnabled(flagName: string): Promise<boolean>;
+    /** Up to ARTIFACT_FLAGS_PER_REQUEST flags in one broker call. */
+    evaluate(flagNames: readonly string[]): Promise<Record<string, boolean>>;
+}
+/** One audit event, recorded for this request's user under the manifest's `server.capabilities.audit` service. */
+export interface ArtifactAuditEvent {
+    action: ArtifactAuditAction;
+    /** What happened, as the product names it (`applications.view`). Recorded as the event's `action_detail`. */
+    detail: string;
+    /** What it happened to, at most ARTIFACT_AUDIT_RESOURCES_PER_EVENT: `{ type: 'application', id }`. Empty for a list. */
+    resources: ReadonlyArray<{
+        type: string;
+        id: string;
+    }>;
+    /** Scalars that qualify the event (counts, kinds, outcomes). Never payloads, document contents or secrets. */
+    metadata?: Readonly<Record<string, string | number | boolean | null>>;
+    /** Names the logical event; one is generated when omitted. Pass the same id to retry the same event. */
+    eventId?: string;
+}
+/**
+ * Audit events, delivered before `record` resolves. A refused or undeliverable event rejects with
+ * ArtifactServerError; decide per route whether that should fail the request.
+ */
+export interface ArtifactServerAudit {
+    record(event: ArtifactAuditEvent): Promise<void>;
+}
 export interface ArtifactServerClient {
     context: ArtifactRequestContext;
     mode: ArtifactServerMode;
@@ -38,10 +80,10 @@ export interface ArtifactServerClient {
     functions: {
         invoke<TOutput = unknown>(id: string, params?: Record<string, unknown>): Promise<TOutput>;
     };
-    orm(input: {
-        namespace: string;
-        manifest: ArtifactOrmOperations;
-    }): OperationExecutor;
+    processes: ArtifactServerProcesses;
+    flags: ArtifactServerFlags;
+    audit: ArtifactServerAudit;
+    orm(input: ArtifactOrmOptions): OperationExecutor;
     asService(): ArtifactServerClient;
 }
 /** One instance per incoming request. Never cache it at module scope. */
@@ -63,7 +105,14 @@ type ClientArguments = {
     logSink?: (record: ArtifactLogRecord) => void;
 };
 type BrokerTransport = ReturnType<typeof createBrokerTransport>;
-declare function createBrokerTransport({ context, token, getRuntime, fetcher }: ClientArguments): (input: ArtifactServerRequest, signal?: AbortSignal) => Promise<Response>;
+interface BrokerCallOptions {
+    signal?: AbortSignal;
+    /** Whether sending the call twice is harmless. Defaults to the operation's own answer (isReadOperation). */
+    replaySafe?: boolean;
+}
+declare function createBrokerTransport({ context, token, getRuntime, fetcher, log }: ClientArguments & {
+    log: ReturnType<typeof createArtifactLogger>;
+}): (input: ArtifactServerRequest, { signal, replaySafe }?: BrokerCallOptions) => Promise<Response>;
 declare function createApiClient({ mode, request, json }: {
     mode: ArtifactServerMode;
     request: BrokerTransport;
@@ -78,4 +127,3 @@ declare function createApiClient({ mode, request, json }: {
     patch: <T = unknown>(path: string, body?: unknown) => Promise<T>;
     delete: <T = unknown>(path: string, body?: unknown) => Promise<T>;
 };
-export {};