@voltro/shared 0.86.0 → 0.88.0

package/README.md

@@ -24,3 +24,5 @@ deliberately short so there is nothing here to drift out of date.
 
 Proprietary. © 2026 Voltro UG. Your use is governed by the
 [Terms of Service](https://voltro.cloud/legal/terms). See the bundled `LICENSE`.
+
+`newTraceId()` creates a nonzero 128-bit trace ID as 32 lowercase hexadecimal characters, using the same implementation re-exported by `@voltro/runtime`. It is browser-safe and diagnostic; it is not a security token.

package/THIRD-PARTY-NOTICES.md

@@ -1,6 +1,6 @@
 # Third-Party Notices — @voltro/shared
 
-This package uses the open-source software listed below. Each is the
+This package uses the third-party software listed below. Each is the
 property of its respective copyright holders and is used under the terms of
 its license. This file is provided for attribution; it grants no rights in
 @voltro/shared itself, which is proprietary (see LICENSE).

package/dist/circuitBreaker.js

@@ -0,0 +1,71 @@
+import { Cause as e, Clock as t, Duration as n, Effect as r, Ref as i, Schema as a } from "effect";
+// src/circuitBreaker.ts
+var o = class extends a.TaggedError()("CircuitOpen", {
+	name: a.String,
+	retryAfterMs: a.Number
+}) {}, s = {
+	tag: "closed",
+	failureCount: 0,
+	halfOpenSuccesses: 0,
+	openedAt: 0
+}, c = { make: (a) => r.gen(function* () {
+	let c = a.name ?? "circuit", l = n.toMillis(n.fromInputUnsafe(a.resetTimeout)), u = a.halfOpenSuccessThreshold ?? 1, d = a.isFailure ?? (() => !0), f = yield* i.make(s), p = r.gen(function* () {
+		let e = yield* i.get(f);
+		if (e.tag === "half-open") {
+			let t = e.halfOpenSuccesses + 1;
+			yield* i.set(f, t >= u ? s : {
+				...e,
+				halfOpenSuccesses: t
+			});
+		} else e.failureCount !== 0 && (yield* i.set(f, s));
+	}), m = r.gen(function* () {
+		let e = yield* t.currentTimeMillis, n = yield* i.get(f);
+		if (n.tag === "half-open" || n.tag === "open") {
+			yield* i.set(f, {
+				tag: "open",
+				failureCount: a.failureThreshold,
+				halfOpenSuccesses: 0,
+				openedAt: e
+			});
+			return;
+		}
+		let r = n.failureCount + 1;
+		yield* i.set(f, r >= a.failureThreshold ? {
+			tag: "open",
+			failureCount: r,
+			halfOpenSuccesses: 0,
+			openedAt: e
+		} : {
+			...n,
+			failureCount: r
+		});
+	}), h = r.gen(function* () {
+		let e = yield* i.get(f);
+		if (e.tag !== "open") return null;
+		let n = (yield* t.currentTimeMillis) - e.openedAt;
+		return n >= l ? (yield* i.set(f, {
+			tag: "half-open",
+			failureCount: 0,
+			halfOpenSuccesses: 0,
+			openedAt: e.openedAt
+		}), null) : l - n;
+	}), g = (t) => r.gen(function* () {
+		let n = yield* h;
+		return n === null ? yield* t.pipe(r.tap(() => p), r.tapCause((t) => {
+			if (e.hasInterruptsOnly(t)) return r.void;
+			let n = e.findErrorOption(t), i = n._tag === "Some" ? n.value : void 0;
+			return d(i) ? m : r.void;
+		})) : yield* r.fail(new o({
+			name: c,
+			retryAfterMs: n
+		}));
+	}), _ = ((e) => g(e));
+	return Object.defineProperty(_, "state", {
+		value: i.get(f).pipe(r.map((e) => e.tag)),
+		enumerable: !0
+	}), Object.defineProperty(_, "reset", {
+		value: i.set(f, s),
+		enumerable: !0
+	}), _;
+}) };
+export { c as CircuitBreaker, o as CircuitOpen };

package/dist/errors.js

@@ -1,5 +1,4 @@
 import { Data as e } from "effect";
-//#region src/errors.ts
+// src/errors.ts
 var t = "@voltro/error", n = class extends e.TaggedError(`${t}/FrameworkError`) {}, r = class extends e.TaggedError(`${t}/I18nError`) {}, i = class extends e.TaggedError(`${t}/Unauthorized`) {}, a = class extends e.TaggedError(`${t}/Forbidden`) {}, o = class extends e.TaggedError(`${t}/NotFound`) {}, s = class extends e.TaggedError(`${t}/Conflict`) {}, c = class extends e.TaggedError(`${t}/BadRequest`) {}, l = class extends e.TaggedError(`${t}/RateLimitExceeded`) {}, u = class extends e.TaggedError(`${t}/DatabaseUnavailable`) {}, d = class extends e.TaggedError(`${t}/ServiceUnavailable`) {}, f = class extends e.TaggedError(`${t}/TenantContextMissing`) {}, p = class extends e.TaggedError(`${t}/CrossTenantAccessDenied`) {};
-//#endregion
 export { c as BadRequest, s as Conflict, p as CrossTenantAccessDenied, u as DatabaseUnavailable, a as Forbidden, n as FrameworkError, r as I18nError, o as NotFound, l as RateLimitExceeded, d as ServiceUnavailable, f as TenantContextMissing, i as Unauthorized };

package/dist/ids.js

@@ -1,5 +1,4 @@
 import { Schema as e } from "effect";
-//#region src/ids.ts
+// src/ids.ts
 var t = (t) => e.NonEmptyString.pipe(e.brand(t)), n = t("SubscriptionId"), r = t("CallId"), i = t("TenantId"), a = t("UserId"), o = t("ApiKeyId"), s = t("WorkflowExecutionId"), c = t("ConnectionId"), l = t("RouteId"), u = t("TraceId");
-//#endregion
 export { o as ApiKeyId, r as CallId, c as ConnectionId, l as RouteId, n as SubscriptionId, i as TenantId, u as TraceId, a as UserId, s as WorkflowExecutionId };

package/dist/index.d.ts

@@ -1,3 +1,6 @@
+import { Cause } from 'effect';
+import { Duration } from 'effect';
+import { Effect } from 'effect';
 import { Schema } from 'effect';
 import { VoidIfEmpty } from 'effect/Types';
 import { YieldableError } from 'effect/Cause';
@@ -19,6 +22,51 @@ export declare const CallId: Schema.brand<Schema.NonEmptyString, "CallId">;
 
 export declare type CallId = typeof CallId.Type;
 
+export declare interface CircuitBreaker {
+    /** Run an effect through the breaker. OPEN ⇒ fails fast with CircuitOpen. */
+    <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E | CircuitOpen, R>;
+    /** Current state — reads the Ref. */
+    readonly state: Effect.Effect<CircuitState>;
+    /** Force the breaker back to closed (clears counters). */
+    readonly reset: Effect.Effect<void>;
+}
+
+export declare const CircuitBreaker: {
+    /** Construct a breaker. Effect-returning because it allocates a Ref. */
+    readonly make: (options: CircuitBreakerOptions) => Effect.Effect<CircuitBreaker>;
+};
+
+export declare interface CircuitBreakerOptions {
+    /** Consecutive failures before the breaker opens. */
+    readonly failureThreshold: number;
+    /** Wait before transitioning open → half-open (Duration or string). */
+    readonly resetTimeout: Duration.Input;
+    /** Successes required in half-open before closing again. Default 1. */
+    readonly halfOpenSuccessThreshold?: number;
+    /** Predicate: does this error count toward the threshold? Default: all
+     *  typed failures count. Interruptions NEVER count (they're not a
+     *  downstream failure — the caller went away). */
+    readonly isFailure?: (error: unknown) => boolean;
+    /** Optional name for inspect / metrics + dashboard surfacing. */
+    readonly name?: string;
+}
+
+/**
+ * Tagged error the breaker fails with while OPEN. Declarable on a
+ * mutation / workflow `error:` schema so it marshals typed to the client.
+ */
+export declare class CircuitOpen extends CircuitOpen_base {
+}
+
+declare const CircuitOpen_base: Schema.Class<CircuitOpen, Schema.TaggedStruct<"CircuitOpen", {
+    /** Breaker name (the `name` option, or `'circuit'` when unnamed). */
+    readonly name: Schema.String;
+    /** Best-effort ms until the breaker next admits a probe call. */
+    readonly retryAfterMs: Schema.Number;
+}>, Cause.YieldableError>;
+
+export declare type CircuitState = 'closed' | 'open' | 'half-open';
+
 export declare class Conflict extends Conflict_base<{
     readonly resource: string;
     readonly reason: string;
@@ -88,18 +136,37 @@ declare const I18nError_base: new <A extends Record<string, any> = {}>(args: Voi
     readonly _tag: "@voltro/error/I18nError";
 } & Readonly<A>;
 
-export declare const JsonValue: Schema.Codec<JsonValue_2>;
+export declare type JsonValue = JsonValueData;
 
-declare type JsonValue_2 = null | boolean | number | string | ReadonlyArray<JsonValue_2> | {
-    readonly [key: string]: JsonValue_2;
-};
+export declare const JsonValue: Schema.Codec<JsonValueData>;
 
-declare const JsonValue: Schema.Codec<JsonValue_2>;
+declare type JsonValueData = null | boolean | number | string | ReadonlyArray<JsonValueData> | {
+    readonly [key: string]: JsonValueData;
+};
 
 export declare const LocaleTag: Schema.brand<Schema.String, "LocaleTag">;
 
 export declare type LocaleTag = typeof LocaleTag.Type;
 
+/**
+ * A fresh trace id for work that has NO incoming span to continue — a webhook
+ * delivery, a schedule firing, a devtools invoke, a REST or gRPC entry point.
+ *
+ * 128 random bits as 32 lowercase hex, the shape `TRACEPARENT_RE` above accepts
+ * and the shape a collector, a log pipeline or `voltro traces` can join on.
+ *
+ * The reason this exists as ONE function: every entry point that minted its own
+ * had drifted somewhere different, and three of the shapes were not ids at all.
+ * `incoming:<webhookId>`, `reaction:<workflow>` and the literal
+ * `'webhooks:trigger'` are CONSTANTS — they were the caller's `source` label
+ * copied into the id field, so every delivery a process ever handled shared one
+ * trace and the waterfall merged unrelated work. `public-`/`grpc-`/`rest-` plus
+ * eight base36 characters carried ~41 bits, which collides long before a busy
+ * day is over. The entry-point kind is not lost by fixing this: it lives in the
+ * `source` field beside the id, which is where it was already being written.
+ */
+export declare const newTraceId: () => string;
+
 export declare class NotFound extends NotFound_base<{
     readonly resource: string;
     readonly id?: string;

package/dist/index.js

@@ -1,4 +1,6 @@
 import { BadRequest as e, Conflict as t, CrossTenantAccessDenied as n, DatabaseUnavailable as r, Forbidden as i, FrameworkError as a, I18nError as o, NotFound as s, RateLimitExceeded as c, ServiceUnavailable as l, TenantContextMissing as u, Unauthorized as d } from "./errors.js";
 import { ApiKeyId as f, CallId as p, ConnectionId as m, RouteId as h, SubscriptionId as g, TenantId as _, TraceId as v, UserId as y, WorkflowExecutionId as b } from "./ids.js";
 import { EmailAddress as x, JsonValue as S, LocaleTag as C, TimestampISO as w, TimezoneName as T } from "./schemas.js";
-export { f as ApiKeyId, e as BadRequest, p as CallId, t as Conflict, m as ConnectionId, n as CrossTenantAccessDenied, r as DatabaseUnavailable, x as EmailAddress, i as Forbidden, a as FrameworkError, o as I18nError, S as JsonValue, C as LocaleTag, s as NotFound, c as RateLimitExceeded, h as RouteId, l as ServiceUnavailable, g as SubscriptionId, u as TenantContextMissing, _ as TenantId, w as TimestampISO, T as TimezoneName, v as TraceId, d as Unauthorized, y as UserId, b as WorkflowExecutionId };
+import { CircuitBreaker as E, CircuitOpen as D } from "./circuitBreaker.js";
+import { newTraceId as O } from "./traceId.js";
+export { f as ApiKeyId, e as BadRequest, p as CallId, E as CircuitBreaker, D as CircuitOpen, t as Conflict, m as ConnectionId, n as CrossTenantAccessDenied, r as DatabaseUnavailable, x as EmailAddress, i as Forbidden, a as FrameworkError, o as I18nError, S as JsonValue, C as LocaleTag, s as NotFound, c as RateLimitExceeded, h as RouteId, l as ServiceUnavailable, g as SubscriptionId, u as TenantContextMissing, _ as TenantId, w as TimestampISO, T as TimezoneName, v as TraceId, d as Unauthorized, y as UserId, b as WorkflowExecutionId, O as newTraceId };

package/dist/schemas.js

@@ -1,5 +1,5 @@
 import { Schema as e } from "effect";
-//#region src/schemas.ts
+// src/schemas.ts
 var t = e.DateFromString, n = e.suspend(() => e.Union([
 	e.Null,
 	e.Boolean,
@@ -8,5 +8,4 @@ var t = e.DateFromString, n = e.suspend(() => e.Union([
 	e.Array(n),
 	e.Record(e.String, n)
 ])), r = e.String.pipe(e.check(e.isPattern(/^[^\s@]+@[^\s@]+\.[^\s@]+$/, { message: "invalid email address" })), e.brand("EmailAddress")), i = e.String.pipe(e.check(e.isPattern(/^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$/)), e.brand("LocaleTag")), a = e.String.pipe(e.check(e.isPattern(/^[A-Za-z]+(\/[A-Za-z_-]+)*$/)), e.brand("TimezoneName"));
-//#endregion
 export { r as EmailAddress, n as JsonValue, i as LocaleTag, t as TimestampISO, a as TimezoneName };

package/dist/traceId.js

@@ -0,0 +1,15 @@
+// src/traceId.ts
+var e = () => {
+	let e = globalThis.crypto, t = /* @__PURE__ */ new Uint8Array(16);
+	if (e?.getRandomValues !== void 0) e.getRandomValues(t);
+	else {
+		let e = `${Date.now().toString(16)}${Math.random().toString(16).slice(2)}`;
+		for (let n = 0; n < t.length; n += 1) {
+			let r = e.slice(n * 2 % e.length, n * 2 % e.length + 2);
+			t[n] = (parseInt(r, 16) || n + 1) ^ (Math.random() * 256 | 0);
+		}
+	}
+	let n = Array.from(t, (e) => e.toString(16).padStart(2, "0")).join("");
+	return n === "0".repeat(32) ? `${"0".repeat(31)}1` : n;
+};
+export { e as newTraceId };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/shared",
-  "version": "0.86.0",
+  "version": "0.88.0",
   "description": "Internal shared utilities used across the @voltro/* packages.",
   "keywords": [
     "voltro",
@@ -33,7 +33,7 @@
     "node": ">=24.0.0"
   },
   "peerDependencies": {
-    "effect": "4.0.1"
+    "effect": "4.1.0"
   },
   "publishConfig": {
     "access": "public"