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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Martin Persson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,174 @@
-# Temporary Holding Version
+# @flowmarkdev/node
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Flowmark observes a process your app already runs. It does not execute,
+schedule, or retry that work. There is no `track()`, `span()`, or `metric()`
+API. Use only the methods below.
+
+This README is the implementation contract. Read it before adding markers.
+
+## Implement
+
+### 1. Pick the entry
+
+| Code | Import |
+| --- | --- |
+| Next.js Route Handler or Server Action | `createFlowmark` from `@flowmarkdev/node/next` |
+| Node worker, script, or long-lived server | `createFlowmark` from `@flowmarkdev/node` |
+| Browser / Client Component | `createFlowmark` from `@flowmarkdev/node/browser` |
+
+Create **one** shared client in a server-only module. Do not construct a new
+client per file. Do not import the Node or Next entry in Client Components.
+`@flowmarkdev/node/next` drains via `after()` — do not call it from middleware,
+render, or the browser.
+
+```ts
+// lib/flowmark.ts — Next.js server
+import { createFlowmark } from "@flowmarkdev/node/next"
+export const flowmark = createFlowmark()
+```
+
+```ts
+// lib/flowmark.ts — Node
+import { createFlowmark } from "@flowmarkdev/node"
+export const flowmark = createFlowmark()
+```
+
+### 2. Server environment
+
+Set these on the server only. Never `NEXT_PUBLIC_*`. Never a browser bundle.
+
+```bash
+FLOWMARK_API_KEY=<project server write key>
+FLOWMARK_API_URL=https://your-flowmark-api.example
+```
+
+`FLOWMARK_API_URL` is the API origin, not `/v1/events`. In development it
+defaults to `http://localhost:3003`. Production requires an explicit origin.
+
+### 3. Public API
+
+This is the entire application surface:
+
+- `createFlowmark()`
+- `flowmark.workflow(name, { id?, properties?, environment?, release?, correlationId?, parentRunId? })`
+- `flow.runId`
+- `flow.step(name, { properties? })`
+- `flow.operation(name, callback)` or `handle.done()` / `handle.fail({ code })`
+- `flow.progress({ completed, total?, unit? })`
+- `flow.error({ code, handled, retryable? })`
+- `flow.setProperties(properties)`
+- `flow.done({ result? })` / `flow.fail({ code, result? })`
+- `flowmark.flush()` / `flowmark.shutdown()` — Node only; Next.js drains itself
+
+Do not invent wrappers, extra clients, or methods.
+
+### 4. One request
+
+Start, mark, then finish in the same handler. Keep the function's return and
+thrown error. Telemetry failures must not change business behavior.
+
+```ts
+import { flowmark } from "./flowmark"
+
+export async function completeCheckout(orderId: string) {
+  const flow = flowmark.workflow("checkout.order", {
+    properties: { orderId },
+  })
+  try {
+    flow.step("payment-captured")
+    const shipment = await flow.operation("create-shipment", () =>
+      createShipment(orderId),
+    )
+    flow.done({ result: { shipmentId: shipment.id } })
+    return shipment
+  } catch (error) {
+    flow.fail({ code: "CHECKOUT_FAILED" })
+    throw error
+  }
+}
+```
+
+### 5. Same process, later request
+
+Pass the same workflow name and `id`. Persist `flow.runId` (or your own
+execution id) on the application record. A second `started` is ignored.
+
+**Do not call `done()` or `fail()` until the whole process is finished.**
+If this handler is only the start, record a step and return.
+
+```ts
+// POST /expeditions — start
+const flow = flowmark.workflow("expedition.run", { id: expedition.id })
+flow.step("draft-started")
+
+// POST /expeditions/:id/claim — later
+const flow = flowmark.workflow("expedition.run", { id: expedition.id })
+await flow.operation("claim-battle", () => claimBattle(expedition.id))
+flow.step("battle-claimed")
+flow.done({ result: { battlesWon: 2 } })
+```
+
+Do not reuse a durable entity id that outlives one execution (the same order
+across retries or later jobs). Put those in `properties`.
+
+### 6. A different process
+
+New `workflow()` plus `correlationId` and/or `parentRunId`. Nothing is
+propagated automatically — pass the ids through your own payload.
+
+### 7. Properties and results
+
+Small JSON-safe objects: counts, status enums, opaque ids you already persist.
+No secrets, emails, tokens, request bodies, raw `Error`s, or unnecessary
+personal data.
+
+Limits: depth 5, 128 keys, 128-character keys, 2,048-character strings, 16 KiB
+per object.
+
+## Configuration
+
+`defineConfig()` is a typed identity helper. It does not read the environment
+or create a client. A `flowmark.config.ts` file is only a convention — import
+it and pass it to `createFlowmark(config)`. Flowmark does not discover files.
+
+Server config may omit credentials and use `FLOWMARK_API_KEY` /
+`FLOWMARK_API_URL`. Browser code must use `@flowmarkdev/node/browser` and a public
+browser key, never the server write key. Keep server and browser clients in
+separate modules.
+
+## `done()`, `fail()`, and operations
+
+`done({ result? })` and `fail({ code, result? })` end the run. The first
+terminal wins. If operations are still open, completion waits until they close.
+`fail()` can supersede a pending `done()`. Later markers are ignored.
+
+`error({ code, handled, retryable? })` stays on the timeline and does not end
+the run. Only `fail()` makes the run failed.
+
+`operation(name, callback)` measures duration, returns the callback result, and
+rethrows the original rejection. It does not fail the workflow.
+
+```ts
+const receipt = await flow.operation("charge-payment", () => chargeCustomer())
+flow.progress({ completed: 125, total: 500, unit: "rows" })
+```
+
+Node processes must `await flowmark.shutdown()` before exit. Long-lived
+workers can `await flowmark.flush()`. Those promises reject on delivery
+failure; `step` / `done` / `fail` never throw delivery errors into app code.
+
+## Browser
+
+`@flowmarkdev/node/browser` never reads server env. Direct delivery needs a public
+browser key and `POST /v1/browser-events`. Or omit the key and proxy through
+`createFlowmarkProxy` from `@flowmarkdev/node/next/proxy` with `FLOWMARK_API_KEY`
+only on the server.
+
+Browser telemetry is untrusted. Create workflows in event handlers or effects,
+not during render.
+
+## Delivery
+
+Best-effort, in memory, not a durable queue. The API deduplicates retries.
+`MemoryTransport` and `workflow(name, { transport, id })` are for tests, not
+ordinary setup.

package/dist/adapters/next.d.ts

@@ -0,0 +1,17 @@
+import type { FlowmarkClient, FlowmarkConfig } from "../types/index.js";
+export type { Flow, FlowmarkClient, FlowmarkConfig, WorkflowDoneOptions, WorkflowFailOptions, WorkflowOptions, WorkflowOperation, WorkflowOperationOptions, WorkflowRunOptions, WorkflowStepOptions, } from "../types/index.js";
+export type { JsonValue, WorkflowRunId, WorkflowError, WorkflowCorrelationId, WorkflowFailure, WorkflowProperties, WorkflowProgress, WorkflowOperationFailure, WorkflowResult, } from "@flowmarkdev/core";
+export { defineConfig } from "../config/define-config.js";
+/**
+ * Next.js server client. Import from `@flowmarkdev/node/next` only.
+ * Use in Route Handlers or Server Actions. Not Client Components, middleware, or render.
+ * Reads FLOWMARK_API_KEY and FLOWMARK_API_URL. Never NEXT_PUBLIC_*.
+ * Drains via after() — do not call shutdown() yourself.
+ * One shared module-level client; wrap the places the developer named.
+ * @example
+ * import { createFlowmark } from "@flowmarkdev/node/next"
+ * export const flowmark = createFlowmark()
+ * const flow = flowmark.workflow("checkout.order")
+ * flow.done({ result: { ok: true } })
+ */
+export declare function createFlowmark(config?: FlowmarkConfig): Pick<FlowmarkClient, "workflow">;

package/dist/adapters/next.js

@@ -0,0 +1,38 @@
+import { after } from "next/server";
+import { createFlowmark as createClient } from "../client/create-client.js";
+export { defineConfig } from "../config/define-config.js";
+/**
+ * Next.js server client. Import from `@flowmarkdev/node/next` only.
+ * Use in Route Handlers or Server Actions. Not Client Components, middleware, or render.
+ * Reads FLOWMARK_API_KEY and FLOWMARK_API_URL. Never NEXT_PUBLIC_*.
+ * Drains via after() — do not call shutdown() yourself.
+ * One shared module-level client; wrap the places the developer named.
+ * @example
+ * import { createFlowmark } from "@flowmarkdev/node/next"
+ * export const flowmark = createFlowmark()
+ * const flow = flowmark.workflow("checkout.order")
+ * flow.done({ result: { ok: true } })
+ */
+export function createFlowmark(config = {}) {
+    return {
+        workflow(name, options) {
+            const lifecycle = {};
+            // Register before starting work so unsupported contexts cannot orphan delivery.
+            after(async () => {
+                const client = lifecycle.client;
+                if (!client) {
+                    return;
+                }
+                try {
+                    await client.shutdown();
+                }
+                catch (cause) {
+                    console.error("[Flowmark] Workflow delivery failed; application changes are unaffected.", cause);
+                }
+            });
+            const client = createClient(config);
+            lifecycle.client = client;
+            return client.workflow(name, options);
+        },
+    };
+}

package/dist/adapters/proxy.d.ts

@@ -0,0 +1,25 @@
+import type { FlowmarkConfig } from "../types/index.js";
+/** Server-only proxy options. Never pass client-supplied destinations or credentials. */
+export interface FlowmarkProxyConfig extends Pick<FlowmarkConfig, "apiKey" | "apiUrl"> {
+    /**
+     * Your session/rate-limit check, run before reading the body.
+     * Return false for HTTP 403; errors are logged and produce HTTP 502.
+     * Optional for public demos only: Origin validation alone is not authentication or rate limiting.
+     */
+    readonly authorize?: (request: Request) => boolean | Promise<boolean>;
+}
+/**
+ * Creates a server-only Web Request/Response POST handler for a same-origin browser SDK proxy.
+ * Works with Next.js Route Handlers or any backend supporting standard Request/Response.
+ * Adds the server's write key, validates events, and limits streamed input to 64 KiB.
+ * Requires an Origin matching request.url; register this behind the browser's own origin.
+ * Returns 202 after upstream acceptance, 400 for bad input, 403 for denied access,
+ * 409/429 for upstream conflict/throttling, or 502 for delivery/configuration failures.
+ * @param config Server credentials/API origin (default FLOWMARK_* env) and a production access check.
+ * @example
+ * import { createFlowmarkProxy } from "@flowmarkdev/node/proxy"
+ * export const POST = createFlowmarkProxy({
+ *   authorize: async (request) => Boolean(await getSession(request)),
+ * })
+ */
+export declare function createFlowmarkProxy(config?: FlowmarkProxyConfig): (request: Request) => Promise<Response>;

package/dist/adapters/proxy.js

@@ -0,0 +1,94 @@
+import { FetchHttpClient, HttpClient, HttpClientRequest, } from "@effect/platform";
+import { Data, Effect, Exit, Match, Schema, Stream } from "effect";
+import { EventEnvelopeSchema } from "@flowmarkdev/core";
+import { resolveSettings } from "../config/settings.js";
+class InvalidProxyInput extends Data.TaggedError("InvalidProxyInput") {
+}
+class ProxyForbidden extends Data.TaggedError("ProxyForbidden") {
+}
+class ProxyAuthorizationError extends Data.TaggedError("ProxyAuthorizationError") {
+}
+const readEnvelope = Effect.fn("Flowmark.Proxy.readEnvelope")(function* (request) {
+    const stream = request.body;
+    if (Number(request.headers.get("content-length")) > 65536 || !stream) {
+        return yield* Effect.fail(new InvalidProxyInput({
+            cause: "Body is required and must not exceed 64 KiB",
+        }));
+    }
+    const decoder = new TextDecoder();
+    const body = yield* Stream.fromReadableStream({
+        evaluate: () => stream,
+        onError: (cause) => new InvalidProxyInput({ cause }),
+        releaseLockOnEnd: true,
+    }).pipe(Stream.runFoldEffect({ size: 0, text: "" }, (state, chunk) => {
+        const size = state.size + chunk.byteLength;
+        return size > 65536
+            ? Effect.fail(new InvalidProxyInput({ cause: "Body exceeds 64 KiB" }))
+            : Effect.succeed({
+                size,
+                text: state.text + decoder.decode(chunk, { stream: true }),
+            });
+    }), Effect.ensuring(Effect.tryPromise({
+        try: () => stream.cancel(),
+        catch: (cause) => new InvalidProxyInput({ cause }),
+    }).pipe(Effect.catchAll((error) => Effect.logWarning("[Flowmark proxy] Could not cancel request body", error)))));
+    return yield* Schema.decodeUnknown(Schema.parseJson(EventEnvelopeSchema))(body.text + decoder.decode()).pipe(Effect.mapError((cause) => new InvalidProxyInput({ cause })));
+});
+/**
+ * Creates a server-only Web Request/Response POST handler for a same-origin browser SDK proxy.
+ * Works with Next.js Route Handlers or any backend supporting standard Request/Response.
+ * Adds the server's write key, validates events, and limits streamed input to 64 KiB.
+ * Requires an Origin matching request.url; register this behind the browser's own origin.
+ * Returns 202 after upstream acceptance, 400 for bad input, 403 for denied access,
+ * 409/429 for upstream conflict/throttling, or 502 for delivery/configuration failures.
+ * @param config Server credentials/API origin (default FLOWMARK_* env) and a production access check.
+ * @example
+ * import { createFlowmarkProxy } from "@flowmarkdev/node/proxy"
+ * export const POST = createFlowmarkProxy({
+ *   authorize: async (request) => Boolean(await getSession(request)),
+ * })
+ */
+export function createFlowmarkProxy(config = {}) {
+    return async function POST(request) {
+        const operation = Effect.gen(function* () {
+            const origin = new URL(request.url).origin;
+            if (request.method !== "POST" ||
+                request.headers.get("origin") !== origin ||
+                request.headers.get("sec-fetch-site") === "cross-site") {
+                return yield* Effect.fail(new ProxyForbidden());
+            }
+            const authorize = config.authorize;
+            if (authorize) {
+                const allowed = yield* Effect.tryPromise({
+                    try: async () => authorize(request),
+                    catch: (cause) => new ProxyAuthorizationError({ cause }),
+                });
+                if (!allowed) {
+                    return yield* Effect.fail(new ProxyForbidden());
+                }
+            }
+            const envelope = yield* readEnvelope(request);
+            const settings = yield* Effect.try(() => resolveSettings(config));
+            const client = (yield* HttpClient.HttpClient).pipe(HttpClient.withScope);
+            const upstream = yield* HttpClientRequest.post(new URL("/v1/events", settings.apiUrl).toString()).pipe(HttpClientRequest.bearerToken(settings.apiKey), HttpClientRequest.bodyJson(envelope));
+            const response = yield* Effect.scoped(client.execute(upstream)).pipe(Effect.timeout("10 seconds"));
+            return Match.value(response.status).pipe(Match.when(202, () => Response.json({ accepted: true }, { status: 202 })), Match.when((status) => [400, 409, 429].includes(status), (status) => Response.json({ error: "Workflow event rejected." }, { status })), Match.orElse(() => {
+                console.error(`[Flowmark proxy] Ingestion returned HTTP ${response.status}`);
+                return Response.json({ error: "Workflow delivery is unavailable." }, { status: 502 });
+            }));
+        }).pipe(Effect.catchTags({
+            ProxyForbidden: () => Effect.succeed(Response.json({ error: "Workflow proxy access denied." }, { status: 403 })),
+            InvalidProxyInput: () => Effect.succeed(Response.json({ error: "Invalid workflow event (maximum 64 KiB)." }, { status: 400 })),
+        }), Effect.provide(FetchHttpClient.layer));
+        const result = await Effect.runPromiseExit(operation, {
+            signal: request.signal,
+        });
+        return Exit.match(result, {
+            onSuccess: (response) => response,
+            onFailure: (cause) => {
+                console.error("[Flowmark proxy] Delivery failed", cause);
+                return Response.json({ error: "Workflow delivery is unavailable." }, { status: 502 });
+            },
+        });
+    };
+}

package/dist/browser/index.d.ts

@@ -0,0 +1,52 @@
+import type { FlowmarkClient, InstrumentationErrorHandler } from "../types/index.js";
+export type { Flow, FlowmarkClient, WorkflowDoneOptions, WorkflowFailOptions, WorkflowOptions, WorkflowOperation, WorkflowOperationOptions, WorkflowRunOptions, WorkflowStepOptions, } from "../types/index.js";
+export type { JsonValue, WorkflowRunId, WorkflowError, WorkflowCorrelationId, WorkflowFailure, WorkflowProperties, WorkflowProgress, WorkflowOperationFailure, WorkflowResult, } from "@flowmarkdev/core";
+/** Browser options: a public browser key for direct delivery, or a same-origin proxy path. Never include server secrets. */
+export interface BrowserFlowmarkConfig {
+    /** Same-origin absolute proxy path, default "/api/flowmark". External URLs, queries, and fragments are rejected. */
+    readonly proxyPath?: string;
+    /**
+     * Public browser-only project key for direct delivery without your own backend.
+     * Never supply a secret server write key. Requires apiUrl; cannot be combined with proxyPath.
+     */
+    readonly publicKey?: string;
+    /** Flowmark API origin for direct delivery. Required with publicKey; never an ingestion path. */
+    readonly apiUrl?: string;
+    /** Optional deployment environment sent with each started workflow. */
+    readonly environment?: string;
+    /** Optional release/version sent with each started workflow. */
+    readonly release?: string;
+    /** Receives typed delivery failures. If omitted, warnings are logged without interrupting UI code. */
+    readonly onInstrumentationError?: InstrumentationErrorHandler;
+}
+/**
+ * Defines browser configuration with autocomplete and preserved literal types.
+ * Returns the same object without accessing browser globals or creating a client.
+ * Safe during SSR; validation happens when the client starts its first workflow.
+ * Export from flowmark.config.ts and pass to createFlowmark(); the file is not auto-loaded.
+ * Only public browser keys belong here, never secret server keys.
+ * @example
+ * export default defineConfig({
+ *   publicKey: "fm_browser_...",
+ *   apiUrl: "http://localhost:3003",
+ * })
+ */
+export declare function defineConfig<const T extends BrowserFlowmarkConfig>(config: T & Record<Exclude<keyof T, keyof BrowserFlowmarkConfig>, never>): T;
+/**
+ * Creates a browser client. Works in ordinary React/Vite apps as well as Next.js.
+ * Pass publicKey and apiUrl to send directly to Flowmark without your own backend.
+ * Without these options, uses your same-origin backend proxy at /api/flowmark.
+ * Never pass a secret server write key or import `@flowmarkdev/node` / `@flowmarkdev/node/next` here.
+ * Safe to create during SSR, but call workflow() only in browser event handlers or effects.
+ * Delivery starts automatically and uses keepalive; offline/unload delivery is not guaranteed.
+ * No config file, React provider, or Next.js dependency is required.
+ * @param config Public browser key/API origin for direct delivery, or a proxy path; optional error callback.
+ * @example
+ * import { createFlowmark } from "@flowmarkdev/node/browser"
+ * const flowmark = createFlowmark({ publicKey: "fm_browser_...", apiUrl: "https://your-flowmark-api" })
+ * // Inside a click/submit handler:
+ * const flow = flowmark.workflow("checkout.ui")
+ * flow.step("form-submitted")
+ * flow.done()
+ */
+export declare function createFlowmark(config?: BrowserFlowmarkConfig): FlowmarkClient;

package/dist/browser/index.js

@@ -0,0 +1,115 @@
+import { FetchHttpClient } from "@effect/platform";
+import { Either, Layer, Redacted, Schema } from "effect";
+import { makeHttpTransport } from "../features/delivery/adapters/http-transport.js";
+import { FlowmarkConfigError } from "../errors/index.js";
+import { makeClient } from "../client/runtime.js";
+import { WorkflowTransport } from "../features/delivery/ports/workflow-transport.js";
+import { ApiOriginSchema } from "../config/api-origin.js";
+/**
+ * Defines browser configuration with autocomplete and preserved literal types.
+ * Returns the same object without accessing browser globals or creating a client.
+ * Safe during SSR; validation happens when the client starts its first workflow.
+ * Export from flowmark.config.ts and pass to createFlowmark(); the file is not auto-loaded.
+ * Only public browser keys belong here, never secret server keys.
+ * @example
+ * export default defineConfig({
+ *   publicKey: "fm_browser_...",
+ *   apiUrl: "http://localhost:3003",
+ * })
+ */
+export function defineConfig(config) {
+    return config;
+}
+/**
+ * Creates a browser client. Works in ordinary React/Vite apps as well as Next.js.
+ * Pass publicKey and apiUrl to send directly to Flowmark without your own backend.
+ * Without these options, uses your same-origin backend proxy at /api/flowmark.
+ * Never pass a secret server write key or import `@flowmarkdev/node` / `@flowmarkdev/node/next` here.
+ * Safe to create during SSR, but call workflow() only in browser event handlers or effects.
+ * Delivery starts automatically and uses keepalive; offline/unload delivery is not guaranteed.
+ * No config file, React provider, or Next.js dependency is required.
+ * @param config Public browser key/API origin for direct delivery, or a proxy path; optional error callback.
+ * @example
+ * import { createFlowmark } from "@flowmarkdev/node/browser"
+ * const flowmark = createFlowmark({ publicKey: "fm_browser_...", apiUrl: "https://your-flowmark-api" })
+ * // Inside a click/submit handler:
+ * const flow = flowmark.workflow("checkout.ui")
+ * flow.step("form-submitted")
+ * flow.done()
+ */
+export function createFlowmark(config = {}) {
+    let client;
+    let closed = false;
+    const getClient = () => {
+        if (closed) {
+            throw new FlowmarkConfigError({ cause: "Client has been shut down" });
+        }
+        if (!client) {
+            const location = globalThis.location;
+            if (!location) {
+                throw new FlowmarkConfigError({
+                    cause: "Browser workflows must run in the browser, not during server rendering",
+                });
+            }
+            const direct = config.publicKey !== undefined || config.apiUrl !== undefined;
+            let endpoint;
+            let publicKey;
+            if (direct) {
+                if (config.proxyPath !== undefined) {
+                    throw new FlowmarkConfigError({
+                        cause: "Choose either direct browser delivery or proxyPath, not both",
+                    });
+                }
+                const settings = Either.match(Schema.decodeUnknownEither(Schema.Struct({
+                    publicKey: Schema.NonEmptyString,
+                    apiUrl: ApiOriginSchema,
+                }))({ publicKey: config.publicKey, apiUrl: config.apiUrl }), {
+                    onLeft: (cause) => {
+                        throw new FlowmarkConfigError({ cause });
+                    },
+                    onRight: (value) => value,
+                });
+                endpoint = new URL("/v1/browser-events", settings.apiUrl);
+                publicKey = settings.publicKey;
+            }
+            else {
+                const path = config.proxyPath ?? "/api/flowmark";
+                if (!path.startsWith("/") ||
+                    path.startsWith("//") ||
+                    path.includes("\\") ||
+                    path.includes("?") ||
+                    path.includes("#")) {
+                    throw new FlowmarkConfigError({
+                        cause: "proxyPath must be a same-origin absolute path",
+                    });
+                }
+                endpoint = new URL(path, location.origin);
+                if (endpoint.origin !== location.origin) {
+                    throw new FlowmarkConfigError({
+                        cause: "Proxy must be on the same origin",
+                    });
+                }
+            }
+            const http = FetchHttpClient.layer.pipe(Layer.provide(Layer.succeed(FetchHttpClient.RequestInit, {
+                credentials: direct ? "omit" : "same-origin",
+                mode: direct ? "cors" : "same-origin",
+                keepalive: true,
+            })));
+            client = makeClient(Layer.effect(WorkflowTransport, makeHttpTransport({
+                endpoint: endpoint.toString(),
+                ...(publicKey === undefined
+                    ? {}
+                    : { apiKey: Redacted.make(publicKey) }),
+            })).pipe(Layer.provide(http)), config.onInstrumentationError, { environment: config.environment, release: config.release });
+        }
+        return client;
+    };
+    return {
+        workflow: (name, options) => getClient().workflow(name, options),
+        flush: () => client?.flush() ?? Promise.resolve(),
+        shutdown() {
+            closed = true;
+            return client?.shutdown() ?? Promise.resolve();
+        },
+    };
+}

package/dist/client/create-client.d.ts

@@ -0,0 +1,21 @@
+import type { Flow, FlowmarkClient, FlowmarkConfig, WorkflowOptions } from "../types/index.js";
+import type { WorkflowName } from "@flowmarkdev/core";
+/**
+ * Node server client. Import this from `@flowmarkdev/node` in workers and scripts.
+ * Next.js Route Handlers must import createFlowmark from `@flowmarkdev/node/next`.
+ * Browser code must import it from `@flowmarkdev/node/browser`.
+ * Reads FLOWMARK_API_KEY and FLOWMARK_API_URL; never put those in NEXT_PUBLIC_*.
+ * Call shutdown() before process exit. Create one shared client.
+ * @throws FlowmarkConfigError If credentials or API origin are invalid.
+ */
+export declare function createFlowmark(config?: FlowmarkConfig): FlowmarkClient;
+/**
+ * Advanced entry point for a custom Effect transport, primarily tests and custom integrations.
+ * Use createFlowmark().workflow() for ordinary application code.
+ * Delivery resources are drained and released after terminal completion. If
+ * operations are open, done() waits for their handles to close first.
+ * @param name Stable workflow name.
+ * @param options Explicit execution ID, transport, and optional diagnostics/metadata.
+ * @throws FlowmarkConfigError If no transport is supplied.
+ */
+export declare function workflow(name: WorkflowName, options: WorkflowOptions): Flow;