@flowmarkdev/node 0.0.0-stage → 0.1.0-alpha.1

package/dist/features/workflows/workflow-engine.js

@@ -0,0 +1,232 @@
+import { Clock, Context, Effect, Layer, Ref } from "effect";
+import { DeliveryQueue } from "../delivery/delivery-queue.js";
+export class WorkflowEngine extends Context.Tag("@flowmarkdev/node/WorkflowEngine")() {
+    static layer = Layer.effect(WorkflowEngine, Effect.gen(function* () {
+        const delivery = yield* DeliveryQueue;
+        const start = Effect.fn("Flowmark.WorkflowEngine.start")(function* (workflow, options) {
+            const runId = options.id ??
+                (yield* Effect.sync(() => globalThis.crypto.randomUUID()));
+            const ordering = yield* Effect.makeSemaphore(1);
+            const finished = yield* Ref.make(false);
+            const completionRequested = yield* Ref.make(false);
+            const pendingCompletion = yield* Ref.make(undefined);
+            const activeOperations = yield* Ref.make(new Set());
+            const record = Effect.fn("Flowmark.WorkflowEngine.record")(function* (createEvent) {
+                const now = yield* Clock.currentTimeMillis;
+                yield* delivery.enqueue(createEvent(new Date(now).toISOString()), ordering);
+            });
+            yield* record((timestamp) => ({
+                type: "started",
+                workflow,
+                runId,
+                timestamp,
+                ...(options.properties === undefined
+                    ? {}
+                    : { properties: options.properties }),
+                ...(options.environment === undefined
+                    ? {}
+                    : { environment: options.environment }),
+                ...(options.release === undefined
+                    ? {}
+                    : { release: options.release }),
+                ...(options.correlationId === undefined
+                    ? {}
+                    : { correlationId: options.correlationId }),
+                ...(options.parentRunId === undefined
+                    ? {}
+                    : { parentRunId: options.parentRunId }),
+            }));
+            const step = Effect.fn("Flowmark.WorkflowEngine.step")(function* (name, stepOptions) {
+                if ((yield* Ref.get(finished)) ||
+                    (yield* Ref.get(completionRequested))) {
+                    return;
+                }
+                yield* record((timestamp) => ({
+                    type: "step",
+                    workflow,
+                    runId,
+                    timestamp,
+                    step: name,
+                    ...(stepOptions?.properties === undefined
+                        ? {}
+                        : { properties: stepOptions.properties }),
+                }));
+            });
+            const complete = Effect.fn("Flowmark.WorkflowEngine.complete")(function* (doneOptions) {
+                if (yield* Ref.getAndSet(finished, true)) {
+                    return;
+                }
+                yield* record((timestamp) => ({
+                    type: "completed",
+                    workflow,
+                    runId,
+                    timestamp,
+                    ...(doneOptions?.result === undefined
+                        ? {}
+                        : { result: doneOptions.result }),
+                }));
+            });
+            const done = Effect.fn("Flowmark.WorkflowEngine.done")(function* (doneOptions) {
+                if ((yield* Ref.get(finished)) ||
+                    (yield* Ref.get(completionRequested))) {
+                    return;
+                }
+                yield* Ref.set(completionRequested, true);
+                yield* Ref.set(pendingCompletion, doneOptions);
+                if ((yield* Ref.get(activeOperations)).size > 0) {
+                    return;
+                }
+                yield* complete(doneOptions);
+            });
+            const fail = Effect.fn("Flowmark.WorkflowEngine.fail")(function* (options) {
+                if (yield* Ref.getAndSet(finished, true)) {
+                    return;
+                }
+                yield* Ref.set(completionRequested, false);
+                yield* Ref.set(pendingCompletion, undefined);
+                yield* Ref.set(activeOperations, new Set());
+                const { result, ...failure } = options;
+                yield* record((timestamp) => ({
+                    type: "failed",
+                    workflow,
+                    runId,
+                    timestamp,
+                    failure,
+                    ...(result === undefined ? {} : { result }),
+                }));
+            });
+            const error = Effect.fn("Flowmark.WorkflowEngine.error")(function* (failure) {
+                if ((yield* Ref.get(finished)) ||
+                    (yield* Ref.get(completionRequested))) {
+                    return;
+                }
+                yield* record((timestamp) => ({
+                    type: "error",
+                    workflow,
+                    runId,
+                    timestamp,
+                    error: failure,
+                }));
+            });
+            const setProperties = Effect.fn("Flowmark.WorkflowEngine.setProperties")(function* (properties) {
+                if (yield* Ref.get(finished) || (yield* Ref.get(completionRequested))) {
+                    return;
+                }
+                yield* record((timestamp) => ({
+                    type: "properties",
+                    workflow,
+                    runId,
+                    timestamp,
+                    properties,
+                }));
+            });
+            const progress = Effect.fn("Flowmark.WorkflowEngine.progress")(function* (progress) {
+                if ((yield* Ref.get(finished)) ||
+                    (yield* Ref.get(completionRequested))) {
+                    return;
+                }
+                yield* record((timestamp) => ({
+                    type: "progress",
+                    workflow,
+                    runId,
+                    timestamp,
+                    ...progress,
+                }));
+            });
+            const operation = Effect.fn("Flowmark.WorkflowEngine.operation")(function* (operationName, operationOptions) {
+                const operationId = yield* Effect.sync(() => globalThis.crypto.randomUUID());
+                const startedAt = yield* Effect.sync(() => performance.now());
+                const operationFinished = yield* Ref.make(false);
+                const canStart = !(yield* Ref.get(finished)) &&
+                    !(yield* Ref.get(completionRequested));
+                if (canStart) {
+                    yield* Ref.update(activeOperations, (active) => new Set(active).add(operationId));
+                    yield* record((timestamp) => ({
+                        type: "operation_started",
+                        workflow,
+                        runId,
+                        timestamp,
+                        operationId,
+                        operationName,
+                        ...(operationOptions?.properties === undefined
+                            ? {}
+                            : { properties: operationOptions.properties }),
+                    }));
+                }
+                const duration = Effect.sync(() => Math.max(0, performance.now() - startedAt));
+                const done = Effect.gen(function* () {
+                    if (yield* Ref.getAndSet(operationFinished, true)) {
+                        return;
+                    }
+                    if ((yield* Ref.get(finished)) || !canStart) {
+                        return;
+                    }
+                    if (canStart) {
+                        yield* Ref.update(activeOperations, (active) => {
+                            const next = new Set(active);
+                            next.delete(operationId);
+                            return next;
+                        });
+                    }
+                    const durationMs = yield* duration;
+                    yield* record((timestamp) => ({
+                        type: "operation_completed",
+                        workflow,
+                        runId,
+                        timestamp,
+                        operationId,
+                        operationName,
+                        durationMs,
+                    }));
+                    const active = yield* Ref.get(activeOperations);
+                    if (active.size === 0 && (yield* Ref.get(completionRequested))) {
+                        yield* complete(yield* Ref.get(pendingCompletion));
+                    }
+                });
+                const fail = Effect.fn("Flowmark.WorkflowEngine.operation.fail")(function* (failure) {
+                    if (yield* Ref.getAndSet(operationFinished, true)) {
+                        return;
+                    }
+                    if ((yield* Ref.get(finished)) || !canStart) {
+                        return;
+                    }
+                    if (canStart) {
+                        yield* Ref.update(activeOperations, (active) => {
+                            const next = new Set(active);
+                            next.delete(operationId);
+                            return next;
+                        });
+                    }
+                    const durationMs = yield* duration;
+                    yield* record((timestamp) => ({
+                        type: "operation_failed",
+                        workflow,
+                        runId,
+                        timestamp,
+                        operationId,
+                        operationName,
+                        durationMs,
+                        failure,
+                    }));
+                    const active = yield* Ref.get(activeOperations);
+                    if (active.size === 0 &&
+                        (yield* Ref.get(completionRequested))) {
+                        yield* complete(yield* Ref.get(pendingCompletion));
+                    }
+                });
+                return { operationId, done, fail };
+            });
+            return {
+                runId,
+                step,
+                done,
+                fail,
+                error,
+                setProperties,
+                operation,
+                progress,
+            };
+        });
+        return WorkflowEngine.of({ start });
+    }));
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { createFlowmark, workflow } from "./client/create-client.js";
+export { defineConfig } from "./config/define-config.js";
+export { FlowmarkConfigError, FlowmarkDeliveryError, FlowmarkHttpError, FlowmarkQueueError, WorkflowTransportError, } from "./errors/index.js";
+export { WorkflowTransport } from "./features/delivery/ports/workflow-transport.js";
+export { MemoryTransport } from "./features/delivery/adapters/memory-transport.js";
+export type { Flow, FlowmarkClient, FlowmarkConfig, InstrumentationErrorHandler, WorkflowOptions, WorkflowRunOptions, WorkflowDoneOptions, WorkflowFailOptions, WorkflowStepOptions, WorkflowOperation, WorkflowOperationOptions, } from "./types/index.js";
+export type { JsonValue, WorkflowRunId, WorkflowError, WorkflowCorrelationId, WorkflowEvent, WorkflowFailure, WorkflowProperties, WorkflowProgress, WorkflowOperationFailure, WorkflowResult, } from "@flowmarkdev/core";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { createFlowmark, workflow } from "./client/create-client.js";
+export { defineConfig } from "./config/define-config.js";
+export { FlowmarkConfigError, FlowmarkDeliveryError, FlowmarkHttpError, FlowmarkQueueError, WorkflowTransportError, } from "./errors/index.js";
+export { WorkflowTransport } from "./features/delivery/ports/workflow-transport.js";
+export { MemoryTransport } from "./features/delivery/adapters/memory-transport.js";

package/dist/types/index.d.ts

@@ -0,0 +1,167 @@
+import type { WorkflowEvent, WorkflowName, WorkflowCorrelationId, WorkflowError, WorkflowFailure, WorkflowProperties, WorkflowProgress, WorkflowResult, WorkflowRunId, WorkflowStepName } from "@flowmarkdev/core";
+import type { DeliveryFailure } from "../errors/index.js";
+import type { WorkflowTransport } from "../features/delivery/ports/workflow-transport.js";
+/**
+ * Receives delivery/validation failures without throwing them into application code.
+ * Throwing from this callback is logged and contained by the SDK.
+ */
+export type InstrumentationErrorHandler = (error: DeliveryFailure, event: WorkflowEvent) => void;
+/** Server-only client options. Omit values to read FLOWMARK_* environment variables. */
+export interface FlowmarkConfig {
+    /**
+     * Secret project write key. Defaults to FLOWMARK_API_KEY.
+     * Server only — never NEXT_PUBLIC_* or a browser bundle.
+     */
+    readonly apiKey?: string;
+    /**
+     * Flowmark API origin, not an ingestion path.
+     * Defaults to FLOWMARK_API_URL or http://localhost:3003 outside production.
+     * Production requires an explicit origin. HTTPS is required except on localhost.
+     */
+    readonly apiUrl?: string;
+    /** Optional deployment environment added to each started event. */
+    readonly environment?: string;
+    /** Optional release/version added to each started event. */
+    readonly release?: string;
+    /** Receives typed failures. If omitted, the SDK logs delivery warnings. */
+    readonly onInstrumentationError?: InstrumentationErrorHandler;
+}
+/** Optional metadata for one execution of a workflow. */
+export interface WorkflowRunOptions {
+    /**
+     * ID for this execution. A UUID is generated if omitted.
+     * Same name + same id on a later request continues this run (second started is ignored).
+     * Do not call done() until that whole process ends.
+     * Do not reuse a durable entity id that outlives one execution; put those in properties.
+     */
+    readonly id?: WorkflowRunId;
+    /** Bounded JSON-safe context sent with the start event. Never include secrets or unnecessary personal data. */
+    readonly properties?: WorkflowProperties;
+    /** Optional deployment environment; overrides the client default. */
+    readonly environment?: string;
+    /** Optional release/version; overrides the client default. */
+    readonly release?: string;
+    /**
+     * Explicit identifier grouping related runs. Keep it bounded and non-sensitive;
+     * it is not an automatic trace ID or proof of a causal relationship.
+     */
+    readonly correlationId?: WorkflowCorrelationId;
+    /**
+     * Parent run's external SDK run ID, explicitly propagated by application code.
+     * It is not the dashboard's internal UUID. Browser-supplied values are
+     * untrusted and must not be treated as identity.
+     */
+    readonly parentRunId?: WorkflowRunId;
+}
+/** Optional context attached to a semantic step without executing business logic. */
+export interface WorkflowStepOptions {
+    readonly properties?: WorkflowProperties;
+}
+/** Optional JSON-safe result recorded when the workflow completes. */
+export interface WorkflowDoneOptions {
+    readonly result?: WorkflowResult;
+}
+/**
+ * Structured terminal failure. `code` is required; `result` is the same kind of
+ * bounded business summary accepted by done().
+ */
+export interface WorkflowFailOptions extends WorkflowFailure {
+    readonly result?: WorkflowResult;
+}
+/** Optional context attached when an operation starts. */
+export interface WorkflowOperationOptions {
+    readonly properties?: WorkflowProperties;
+}
+/** Explicit lifecycle handle for a single independently identified operation. */
+export interface WorkflowOperation {
+    /** Unique UUID identifying this operation event family. */
+    readonly operationId: string;
+    /** Marks the operation successful and records its monotonic duration. */
+    done(): void;
+    /** Marks the operation failed and records its monotonic duration. */
+    fail(failure: WorkflowFailure): void;
+}
+/** Advanced custom-transport options. Normal consumers should use createFlowmark(). */
+export interface WorkflowOptions extends WorkflowRunOptions {
+    /** Required, unique execution ID for the low-level workflow() API. */
+    readonly id: WorkflowRunId;
+    /** Effect-based event destination; not required by configured clients. */
+    readonly transport: WorkflowTransport;
+    /** Receives typed failures without interrupting the host application. */
+    readonly onInstrumentationError?: InstrumentationErrorHandler;
+}
+/**
+ * Markers for one workflow run. Delivery happens asynchronously in the background.
+ * Properties/results must be JSON-safe objects within the shared @flowmarkdev/core
+ * limits: 5 nested levels, 128 keys, 128-character keys, 2,048-character
+ * strings, and 16 KiB encoded per object.
+ */
+export interface Flow {
+    /** This run's SDK identifier (options.id, or a generated UUID). */
+    readonly runId: WorkflowRunId;
+    /**
+     * Records a meaningful checkpoint. Does not execute the step's business logic.
+     * Calls after done() or fail() are ignored.
+     * @param name A stable semantic name, such as "payment-created".
+     * @param options Optional step-local bounded JSON properties.
+     */
+    step(name: WorkflowStepName, options?: WorkflowStepOptions): void;
+    /**
+     * Ends the run as successful. Call only when the whole process is finished —
+     * not in the first handler of a multi-request flow.
+     * If operations are open, completion waits until they close. First terminal wins.
+     */
+    done(options?: WorkflowDoneOptions): void;
+    /**
+     * Ends the run as failed without throwing. Call only when the whole process
+     * is finished. `code` is required. Can supersede a pending done().
+     */
+    fail(options: WorkflowFailOptions): void;
+    /**
+     * Records an error without terminating the run.
+     * `handled` describes application handling; only fail() makes the run failed.
+     */
+    error(error: WorkflowError): void;
+    /**
+     * Appends a shallow context amendment; previous event history is never rewritten.
+     * When keys repeat, the newest value applies to the run's current context.
+     */
+    setProperties(properties: WorkflowProperties): void;
+    /**
+     * Starts an independently identified operation.
+     * Operations may overlap; each returned handle must be closed by its caller.
+     * An operation callback reports its own success/failure and preserves the
+     * callback's result or original rejection; it never fails the workflow.
+     */
+    operation(name: WorkflowStepName, options?: WorkflowOperationOptions): WorkflowOperation;
+    operation<T>(name: WorkflowStepName, callback: () => PromiseLike<T>, options?: WorkflowOperationOptions): Promise<T>;
+    /** Records an absolute progress snapshot; invalid values are rejected by validation. */
+    progress(progress: WorkflowProgress): void;
+}
+/** Ordinary TypeScript client; Effect execution is managed internally. */
+export interface FlowmarkClient {
+    /**
+     * Starts a run, or continues one when `options.id` matches an existing run
+     * of the same workflow name. Omit `id` for a new execution.
+     * Persist `flow.runId` if a later request should append to this run.
+     * @param name Stable process name, such as "checkout.order" or "expedition.run".
+     * @throws FlowmarkConfigError If configuration/context is invalid or the client was shut down.
+     * @example
+     * const flow = flowmark.workflow("checkout.order", { properties: { orderId } })
+     * flow.step("payment-captured")
+     * flow.done({ result: { shipmentId } })
+     */
+    workflow(name: WorkflowName, options?: WorkflowRunOptions): Flow;
+    /**
+     * Waits for pending deliveries without closing the client.
+     * Rejects with FlowmarkDeliveryError if delivery failed or the queue overflowed.
+     * Browser clients can use this before full-page navigation; it does not guarantee offline delivery.
+     */
+    flush(): Promise<void>;
+    /**
+     * Stops accepting workflows, drains pending deliveries, and releases SDK resources.
+     * Call before a Node.js process/job exits. The Next.js adapter handles this automatically.
+     * Rejects with FlowmarkDeliveryError when draining reports delivery failures.
+     */
+    shutdown(): Promise<void>;
+}

package/dist/types/index.js

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

package/dist/utils/failure-from-unknown.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowFailure } from "@flowmarkdev/core";
+/** Maps a thrown callback value to a structured operation failure. */
+export declare const failureFromUnknown: (cause: unknown) => WorkflowFailure;

package/dist/utils/failure-from-unknown.js

@@ -0,0 +1,36 @@
+const codeLimit = 128;
+const messageLimit = 2048;
+const isRecord = (value) => typeof value === "object" && value !== null;
+const boundedCode = (value) => typeof value === "string" &&
+    value.length > 0 &&
+    value.length <= codeLimit &&
+    value.trim().length > 0
+    ? value
+    : undefined;
+const boundedMessage = (value) => typeof value === "string" && value.length > 0
+    ? value.slice(0, messageLimit)
+    : undefined;
+/** Maps a thrown callback value to a structured operation failure. */
+export const failureFromUnknown = (cause) => {
+    if (isRecord(cause)) {
+        const code = boundedCode(cause.code);
+        if (code !== undefined) {
+            return {
+                code,
+                ...(boundedMessage(cause.message) === undefined
+                    ? {}
+                    : { message: boundedMessage(cause.message) }),
+                ...(typeof cause.retryable === "boolean"
+                    ? { retryable: cause.retryable }
+                    : {}),
+            };
+        }
+    }
+    if (cause instanceof Error) {
+        const message = boundedMessage(cause.message);
+        return message === undefined
+            ? { code: "operation_failed" }
+            : { code: "operation_failed", message };
+    }
+    return { code: "operation_failed" };
+};

package/dist/utils/operation-args.d.ts

@@ -0,0 +1,5 @@
+import type { WorkflowOperationOptions } from "../types/index.js";
+export declare const splitOperationArgs: <T>(callbackOrOptions?: (() => PromiseLike<T>) | WorkflowOperationOptions, options?: WorkflowOperationOptions) => {
+    readonly callback?: () => PromiseLike<T>;
+    readonly options?: WorkflowOperationOptions;
+};

package/dist/utils/operation-args.js

@@ -0,0 +1,3 @@
+export const splitOperationArgs = (callbackOrOptions, options) => typeof callbackOrOptions === "function"
+    ? { callback: callbackOrOptions, options }
+    : { options: callbackOrOptions };

package/dist/utils/operation-callback.d.ts

@@ -0,0 +1,2 @@
+import type { WorkflowOperation } from "../types/index.js";
+export declare function withOperationCallback<T>(operation: WorkflowOperation, callback: () => PromiseLike<T>): Promise<T>;

package/dist/utils/operation-callback.js

@@ -0,0 +1,18 @@
+import { failureFromUnknown } from "./failure-from-unknown.js";
+export function withOperationCallback(operation, callback) {
+    let result;
+    try {
+        result = callback();
+    }
+    catch (cause) {
+        operation.fail(failureFromUnknown(cause));
+        return Promise.reject(cause);
+    }
+    return Promise.resolve(result).then((value) => {
+        operation.done();
+        return value;
+    }, (cause) => {
+        operation.fail(failureFromUnknown(cause));
+        throw cause;
+    });
+}

package/package.json

@@ -1,6 +1,78 @@
 {
   "name": "@flowmarkdev/node",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-alpha.1",
+  "description": "Workflow observability for Node.js application code",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./next": {
+      "types": "./dist/adapters/next.d.ts",
+      "import": "./dist/adapters/next.js"
+    },
+    "./browser": {
+      "types": "./dist/browser/index.d.ts",
+      "import": "./dist/browser/index.js"
+    },
+    "./next/proxy": {
+      "types": "./dist/adapters/proxy.d.ts",
+      "import": "./dist/adapters/proxy.js"
+    },
+    "./proxy": {
+      "types": "./dist/adapters/proxy.d.ts",
+      "import": "./dist/adapters/proxy.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mumma6/flowmark.git",
+    "directory": "packages/sdk"
+  },
+  "homepage": "https://docs.flowmark.dev",
+  "bugs": {
+    "url": "https://github.com/Mumma6/flowmark/issues"
+  },
+  "engines": {
+    "node": ">=20.19"
+  },
+  "dependencies": {
+    "@effect/platform": "^0.97.2",
+    "effect": "^3.22.4",
+    "@flowmarkdev/core": "0.1.0-alpha.1"
+  },
+  "peerDependencies": {
+    "next": ">=16"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "next": "^16.4.2",
+    "@types/node": "^22.18.6",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "dev": "tsc -p tsconfig.build.json --watch --preserveWatchOutput",
+    "build": "tsc -p tsconfig.build.json",
+    "lint": "eslint src test",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
 }