@classytic/arc 2.3.0 → 2.4.2

package/dist/rpc/index.mjs

@@ -0,0 +1,248 @@
+import { t as CircuitBreaker } from "../circuitBreaker-BOBOpN2w.mjs";
+//#region src/rpc/serviceClient.ts
+/**
+* Service Client — Resource-Oriented RPC
+*
+* Typed HTTP client that speaks Arc's resource protocol.
+* Built for microservice-to-microservice communication with:
+* - correlationId propagation (distributed tracing)
+* - Retry with exponential backoff (transient failure recovery)
+* - Circuit breaker integration (cascading failure prevention)
+* - Error normalization (consistent error handling)
+* - Lifecycle hooks (observability)
+*
+* Zero external dependencies — uses native fetch + Arc's CircuitBreaker.
+*
+* @example
+* ```typescript
+* import { createServiceClient } from '@classytic/arc/rpc';
+*
+* const catalog = createServiceClient({
+*   baseUrl: 'http://catalog-service:3000',
+*   token: () => getServiceToken(),
+*   correlationId: () => request.id, // propagate trace context
+*   organizationId: req.scope.organizationId,
+*   retry: { maxRetries: 2, backoffMs: 200 },
+*   circuitBreaker: { failureThreshold: 5, resetTimeout: 30000 },
+*   onResponse: ({ method, url, status, durationMs }) => {
+*     metrics.histogram('rpc_duration', durationMs, { method, url, status });
+*   },
+* });
+*
+* const products = await catalog.resource('product').list({ filters: { active: true } });
+* ```
+*/
+const DEFAULT_RETRYABLE_STATUSES = [
+	502,
+	503,
+	504,
+	408,
+	429
+];
+function createServiceClient(options) {
+	const { baseUrl, token, organizationId, correlationId, schemaVersion, headers: extraHeaders = {}, timeout = 1e4, retry: retryConfig, circuitBreaker: cbOpts, healthPath = "/_health/live", onRequest, onResponse } = options;
+	const base = baseUrl.replace(/\/+$/, "");
+	let breaker;
+	if (cbOpts) breaker = new CircuitBreaker(singleFetch, {
+		name: `service-client:${base}`,
+		failureThreshold: cbOpts.failureThreshold ?? 5,
+		resetTimeout: cbOpts.resetTimeout ?? 6e4,
+		timeout: cbOpts.timeout ?? timeout,
+		successThreshold: cbOpts.successThreshold ?? 1
+	});
+	function buildHeaders(hasBody = false) {
+		const h = {
+			accept: "application/json",
+			...extraHeaders
+		};
+		if (hasBody) h["content-type"] = "application/json";
+		const resolvedToken = typeof token === "function" ? token() : token;
+		if (resolvedToken) h.authorization = `Bearer ${resolvedToken}`;
+		if (organizationId) h["x-organization-id"] = organizationId;
+		if (schemaVersion) h["x-arc-schema-version"] = schemaVersion;
+		const resolvedCorrelationId = typeof correlationId === "function" ? correlationId() : correlationId;
+		if (resolvedCorrelationId) h["x-request-id"] = resolvedCorrelationId;
+		return h;
+	}
+	async function singleFetch(url, init) {
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(), timeout);
+		try {
+			const hasBody = !!init.body;
+			const response = await fetch(url, {
+				...init,
+				signal: controller.signal,
+				headers: {
+					...buildHeaders(hasBody),
+					...init.headers ?? {}
+				}
+			});
+			let body;
+			if ((response.headers.get("content-type") ?? "").includes("application/json")) body = await response.json();
+			else {
+				const text = await response.text();
+				body = {
+					success: false,
+					error: response.statusText || "Unknown error",
+					message: text.slice(0, 200),
+					status: response.status
+				};
+			}
+			if (body.status === void 0) body.status = response.status;
+			if (body.success === void 0) body.success = response.ok;
+			return {
+				response,
+				body
+			};
+		} finally {
+			clearTimeout(timer);
+		}
+	}
+	async function execute(method, url, init) {
+		const startTime = performance.now();
+		let lastResponse;
+		let retries = 0;
+		const maxRetries = retryConfig?.maxRetries ?? 0;
+		const backoffMs = retryConfig?.backoffMs ?? 200;
+		const maxBackoffMs = retryConfig?.maxBackoffMs ?? 5e3;
+		const retryableStatuses = retryConfig?.retryableStatuses ?? DEFAULT_RETRYABLE_STATUSES;
+		onRequest?.({
+			method,
+			url
+		});
+		for (let attempt = 0; attempt <= maxRetries; attempt++) try {
+			let result;
+			if (breaker) result = await breaker.call(url, init);
+			else result = await singleFetch(url, init);
+			lastResponse = result.body;
+			if (result.response.ok || !retryableStatuses.includes(result.response.status)) {
+				onResponse?.({
+					method,
+					url,
+					status: result.response.status,
+					durationMs: performance.now() - startTime,
+					retries
+				});
+				return result.body;
+			}
+			if (attempt < maxRetries) {
+				retries++;
+				await sleep(Math.min(backoffMs * 2 ** attempt, maxBackoffMs));
+				continue;
+			}
+			onResponse?.({
+				method,
+				url,
+				status: result.response.status,
+				durationMs: performance.now() - startTime,
+				retries
+			});
+			return result.body;
+		} catch (err) {
+			if (attempt < maxRetries) {
+				retries++;
+				await sleep(Math.min(backoffMs * 2 ** attempt, maxBackoffMs));
+				continue;
+			}
+			const error = err instanceof Error ? err : new Error(String(err));
+			lastResponse = {
+				success: false,
+				error: error.message,
+				status: 0
+			};
+			onResponse?.({
+				method,
+				url,
+				status: 0,
+				durationMs: performance.now() - startTime,
+				retries
+			});
+			if (maxRetries === 0) throw error;
+			return lastResponse;
+		}
+		return lastResponse ?? {
+			success: false,
+			error: "Unknown error",
+			status: 0
+		};
+	}
+	function toQueryString(query) {
+		if (!query || Object.keys(query).length === 0) return "";
+		const params = new URLSearchParams();
+		for (const [key, value] of Object.entries(query)) if (value !== void 0 && value !== null) if (typeof value === "object") {
+			for (const [k, v] of Object.entries(value)) if (v !== void 0 && v !== null) params.set(k, String(v));
+		} else params.set(key, String(value));
+		const qs = params.toString();
+		return qs ? `?${qs}` : "";
+	}
+	function plural(name) {
+		if (name.endsWith("s")) return name;
+		if (name.endsWith("y") && !name.endsWith("ay") && !name.endsWith("ey") && !name.endsWith("oy") && !name.endsWith("uy")) return `${name.slice(0, -1)}ies`;
+		return `${name}s`;
+	}
+	return {
+		resource(name) {
+			const prefix = `${base}/${plural(name)}`;
+			return {
+				async list(query) {
+					return execute("GET", `${prefix}${toQueryString(query?.filters ? query.filters : query)}`, { method: "GET" });
+				},
+				async get(id) {
+					return execute("GET", `${prefix}/${id}`, { method: "GET" });
+				},
+				async create(data) {
+					return execute("POST", prefix, {
+						method: "POST",
+						body: JSON.stringify(data)
+					});
+				},
+				async update(id, data) {
+					return execute("PATCH", `${prefix}/${id}`, {
+						method: "PATCH",
+						body: JSON.stringify(data)
+					});
+				},
+				async delete(id) {
+					return execute("DELETE", `${prefix}/${id}`, { method: "DELETE" });
+				},
+				async action(id, actionName, data) {
+					return execute("POST", `${prefix}/${id}/action`, {
+						method: "POST",
+						body: JSON.stringify({
+							action: actionName,
+							...data
+						})
+					});
+				}
+			};
+		},
+		async call(method, path, body) {
+			const url = `${base}${path}`;
+			const init = { method };
+			if (body !== void 0) init.body = JSON.stringify(body);
+			return execute(method, url, init);
+		},
+		async health() {
+			try {
+				const controller = new AbortController();
+				const timer = setTimeout(() => controller.abort(), timeout);
+				try {
+					return (await fetch(`${base}${healthPath}`, {
+						method: "GET",
+						signal: controller.signal,
+						headers: buildHeaders()
+					})).ok;
+				} finally {
+					clearTimeout(timer);
+				}
+			} catch {
+				return false;
+			}
+		}
+	};
+}
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//#endregion
+export { createServiceClient };

package/dist/{schemaConverter-Dtg0Kt9T.mjs → schemaConverter-DjzHpFam.mjs}

@@ -93,6 +93,5 @@ function convertRouteSchema(schema) {
 	}
 	return result;
 }
-
 //#endregion
-export { toJsonSchema as a, isZodSchema as i, convertRouteSchema as n, isJsonSchema as r, convertOpenApiSchemas as t };
+export { toJsonSchema as a, isZodSchema as i, convertRouteSchema as n, isJsonSchema as r, convertOpenApiSchemas as t };

package/dist/schemas/index.d.mts

@@ -1,63 +1,63 @@
-import * as _sinclair_typebox0 from "@sinclair/typebox";
-import { Static, TObject, TSchema, TSchema as TSchema$1, Type } from "@sinclair/typebox";
 import { FastifyPluginAsyncTypebox, FastifyPluginCallbackTypebox, TypeBoxTypeProvider, TypeBoxValidatorCompiler } from "@fastify/type-provider-typebox";
+import * as _$_sinclair_typebox0 from "@sinclair/typebox";
+import { Static, TObject, TSchema, TSchema as TSchema$1, Type } from "@sinclair/typebox";
 
 //#region src/schemas/index.d.ts
 /**
  * Paginated list response — matches Arc's runtime format:
  * `{ success, docs: [...], page, limit, total, pages, hasNext, hasPrev }`
  */
-declare function ArcListResponse<T extends TSchema$1>(itemSchema: T): _sinclair_typebox0.TObject<{
-  success: _sinclair_typebox0.TBoolean;
-  docs: _sinclair_typebox0.TArray<T>;
-  page: _sinclair_typebox0.TInteger;
-  limit: _sinclair_typebox0.TInteger;
-  total: _sinclair_typebox0.TInteger;
-  pages: _sinclair_typebox0.TInteger;
-  hasNext: _sinclair_typebox0.TBoolean;
-  hasPrev: _sinclair_typebox0.TBoolean;
+declare function ArcListResponse<T extends TSchema$1>(itemSchema: T): _$_sinclair_typebox0.TObject<{
+  success: _$_sinclair_typebox0.TBoolean;
+  docs: _$_sinclair_typebox0.TArray<T>;
+  page: _$_sinclair_typebox0.TInteger;
+  limit: _$_sinclair_typebox0.TInteger;
+  total: _$_sinclair_typebox0.TInteger;
+  pages: _$_sinclair_typebox0.TInteger;
+  hasNext: _$_sinclair_typebox0.TBoolean;
+  hasPrev: _$_sinclair_typebox0.TBoolean;
 }>;
 /**
  * Single item response — `{ success, data: {...} }`
  */
-declare function ArcItemResponse<T extends TSchema$1>(itemSchema: T): _sinclair_typebox0.TObject<{
-  success: _sinclair_typebox0.TBoolean;
+declare function ArcItemResponse<T extends TSchema$1>(itemSchema: T): _$_sinclair_typebox0.TObject<{
+  success: _$_sinclair_typebox0.TBoolean;
   data: T;
 }>;
 /**
  * Mutation (create/update) response — `{ success, data: {...}, message? }`
  */
-declare function ArcMutationResponse<T extends TSchema$1>(itemSchema: T): _sinclair_typebox0.TObject<{
-  success: _sinclair_typebox0.TBoolean;
+declare function ArcMutationResponse<T extends TSchema$1>(itemSchema: T): _$_sinclair_typebox0.TObject<{
+  success: _$_sinclair_typebox0.TBoolean;
   data: T;
-  message: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
+  message: _$_sinclair_typebox0.TOptional<_$_sinclair_typebox0.TString>;
 }>;
 /**
  * Delete response — `{ success, message }`
  */
-declare function ArcDeleteResponse(): _sinclair_typebox0.TObject<{
-  success: _sinclair_typebox0.TBoolean;
-  message: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
+declare function ArcDeleteResponse(): _$_sinclair_typebox0.TObject<{
+  success: _$_sinclair_typebox0.TBoolean;
+  message: _$_sinclair_typebox0.TOptional<_$_sinclair_typebox0.TString>;
 }>;
 /**
  * Error response schema
  */
-declare function ArcErrorResponse(): _sinclair_typebox0.TObject<{
-  success: _sinclair_typebox0.TLiteral<false>;
-  error: _sinclair_typebox0.TString;
-  code: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
-  message: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
+declare function ArcErrorResponse(): _$_sinclair_typebox0.TObject<{
+  success: _$_sinclair_typebox0.TLiteral<false>;
+  error: _$_sinclair_typebox0.TString;
+  code: _$_sinclair_typebox0.TOptional<_$_sinclair_typebox0.TString>;
+  message: _$_sinclair_typebox0.TOptional<_$_sinclair_typebox0.TString>;
 }>;
 /**
  * Standard pagination + sorting + filtering query parameters.
  * Matches Arc's list endpoint conventions.
  */
-declare function ArcPaginationQuery(): _sinclair_typebox0.TObject<{
-  page: _sinclair_typebox0.TOptional<_sinclair_typebox0.TInteger>;
-  limit: _sinclair_typebox0.TOptional<_sinclair_typebox0.TInteger>;
-  sort: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
-  select: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
-  populate: _sinclair_typebox0.TOptional<_sinclair_typebox0.TAny>;
+declare function ArcPaginationQuery(): _$_sinclair_typebox0.TObject<{
+  page: _$_sinclair_typebox0.TOptional<_$_sinclair_typebox0.TInteger>;
+  limit: _$_sinclair_typebox0.TOptional<_$_sinclair_typebox0.TInteger>;
+  sort: _$_sinclair_typebox0.TOptional<_$_sinclair_typebox0.TString>;
+  select: _$_sinclair_typebox0.TOptional<_$_sinclair_typebox0.TString>;
+  populate: _$_sinclair_typebox0.TOptional<_$_sinclair_typebox0.TAny>;
 }>;
 //#endregion
 export { ArcDeleteResponse, ArcErrorResponse, ArcItemResponse, ArcListResponse, ArcMutationResponse, ArcPaginationQuery, type FastifyPluginAsyncTypebox, type FastifyPluginCallbackTypebox, type Static, type TObject, type TSchema, Type, type TypeBoxTypeProvider, TypeBoxValidatorCompiler };

package/dist/schemas/index.mjs

@@ -1,6 +1,5 @@
-import { Type, Type as Type$1 } from "@sinclair/typebox";
 import { TypeBoxValidatorCompiler } from "@fastify/type-provider-typebox";
-
+import { Type, Type as Type$1 } from "@sinclair/typebox";
 //#region src/schemas/index.ts
 /**
 * Paginated list response — matches Arc's runtime format:
@@ -77,6 +76,5 @@ function ArcPaginationQuery() {
 		populate: Type$1.Optional(Type$1.Any())
 	}, { additionalProperties: true });
 }
-
 //#endregion
-export { ArcDeleteResponse, ArcErrorResponse, ArcItemResponse, ArcListResponse, ArcMutationResponse, ArcPaginationQuery, Type, TypeBoxValidatorCompiler };
+export { ArcDeleteResponse, ArcErrorResponse, ArcItemResponse, ArcListResponse, ArcMutationResponse, ArcPaginationQuery, Type, TypeBoxValidatorCompiler };

package/dist/scope/index.d.mts

@@ -1,6 +1,17 @@
-import { a as AUTHENTICATED_SCOPE, c as getOrgId, d as hasOrgAccess, f as isAuthenticated, i as elevationPlugin, l as getOrgRoles, m as isMember, n as ElevationOptions, o as PUBLIC_SCOPE, p as isElevated, r as _default, s as RequestScope, t as ElevationEvent, u as getTeamId } from "../elevation-DGo5shaX.mjs";
+import { a as AUTHENTICATED_SCOPE, c as getOrgId, d as getUserId, f as getUserRoles, g as isMember, h as isElevated, i as elevationPlugin, l as getOrgRoles, m as isAuthenticated, n as ElevationOptions, o as PUBLIC_SCOPE, p as hasOrgAccess, r as _default, s as RequestScope, t as ElevationEvent, u as getTeamId } from "../elevation-Ca_yveIO.mjs";
 import { FastifyReply, FastifyRequest } from "fastify";
 
+//#region src/scope/rateLimitKey.d.ts
+interface RateLimitKeyContext {
+  ip: string;
+  scope?: RequestScope;
+}
+interface TenantKeyGeneratorOptions {
+  /** Custom strategy — overrides default scope-based logic */
+  strategy?: (ctx: RateLimitKeyContext) => string;
+}
+declare function createTenantKeyGenerator(opts?: TenantKeyGeneratorOptions): (ctx: RateLimitKeyContext) => string;
+//#endregion
 //#region src/scope/resolveOrgFromHeader.d.ts
 interface ResolveOrgFromHeaderOptions {
   /** Header name (default: 'x-organization-id') */
@@ -18,4 +29,4 @@ interface ResolveOrgFromHeaderOptions {
  */
 declare function resolveOrgFromHeader(options: ResolveOrgFromHeaderOptions): (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
 //#endregion
-export { AUTHENTICATED_SCOPE, type ElevationEvent, type ElevationOptions, PUBLIC_SCOPE, type RequestScope, type ResolveOrgFromHeaderOptions, _default as elevationPlugin, elevationPlugin as elevationPluginFn, getOrgId, getOrgRoles, getTeamId, hasOrgAccess, isAuthenticated, isElevated, isMember, resolveOrgFromHeader };
+export { AUTHENTICATED_SCOPE, type ElevationEvent, type ElevationOptions, PUBLIC_SCOPE, type RateLimitKeyContext, type RequestScope, type ResolveOrgFromHeaderOptions, type TenantKeyGeneratorOptions, createTenantKeyGenerator, _default as elevationPlugin, elevationPlugin as elevationPluginFn, getOrgId, getOrgRoles, getTeamId, getUserId, getUserRoles, hasOrgAccess, isAuthenticated, isElevated, isMember, resolveOrgFromHeader };

package/dist/scope/index.mjs

@@ -1,6 +1,18 @@
-import { a as getTeamId, c as isElevated, i as getOrgRoles, l as isMember, n as PUBLIC_SCOPE, o as hasOrgAccess, r as getOrgId, s as isAuthenticated, t as AUTHENTICATED_SCOPE } from "../types-Beqn1Un7.mjs";
-import { n as elevation_default, t as elevationPlugin } from "../elevation-DSTbVvYj.mjs";
-
+import { a as getTeamId, c as hasOrgAccess, d as isMember, i as getOrgRoles, l as isAuthenticated, n as PUBLIC_SCOPE, o as getUserId, r as getOrgId, s as getUserRoles, t as AUTHENTICATED_SCOPE, u as isElevated } from "../types-C6TQjtdi.mjs";
+import { n as normalizeRoles } from "../types-ZUu_h0jp.mjs";
+import { n as elevation_default, t as elevationPlugin } from "../elevation-BEdACOLB.mjs";
+//#region src/scope/rateLimitKey.ts
+function createTenantKeyGenerator(opts) {
+	if (opts?.strategy) return opts.strategy;
+	return (ctx) => {
+		const scope = ctx.scope;
+		if (!scope || scope.kind === "public") return ctx.ip;
+		if (scope.kind === "member") return scope.organizationId;
+		if (scope.kind === "elevated") return scope.organizationId ?? scope.userId ?? ctx.ip;
+		return scope.userId ?? ctx.ip;
+	};
+}
+//#endregion
 //#region src/scope/resolveOrgFromHeader.ts
 /**
 * Create a preHandler hook that resolves org scope from a header.
@@ -55,11 +67,12 @@ function resolveOrgFromHeader(options) {
 		}
 		request.scope = {
 			kind: "member",
+			userId: userId || void 0,
+			userRoles: normalizeRoles(user.role),
 			organizationId: orgId,
 			orgRoles: membership.roles
 		};
 	};
 }
-
 //#endregion
-export { AUTHENTICATED_SCOPE, PUBLIC_SCOPE, elevation_default as elevationPlugin, elevationPlugin as elevationPluginFn, getOrgId, getOrgRoles, getTeamId, hasOrgAccess, isAuthenticated, isElevated, isMember, resolveOrgFromHeader };
+export { AUTHENTICATED_SCOPE, PUBLIC_SCOPE, createTenantKeyGenerator, elevation_default as elevationPlugin, elevationPlugin as elevationPluginFn, getOrgId, getOrgRoles, getTeamId, getUserId, getUserRoles, hasOrgAccess, isAuthenticated, isElevated, isMember, resolveOrgFromHeader };

package/dist/{sessionManager-D_iEHjQl.d.mts → sessionManager-wbkYj2HL.d.mts}

@@ -41,7 +41,7 @@ interface SessionCookieOptions {
   /** Prevent client-side JavaScript access (default: true) */
   httpOnly?: boolean;
   /** SameSite attribute (default: 'lax') */
-  sameSite?: 'strict' | 'lax' | 'none';
+  sameSite?: "strict" | "lax" | "none";
   /** Cookie path (default: '/') */
   path?: string;
   /** Cookie domain */
@@ -75,7 +75,7 @@ interface SessionManagerResult {
   /** PreHandler that rejects requests without a fresh session */
   requireFresh: (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
 }
-declare module 'fastify' {
+declare module "fastify" {
   interface FastifyInstance {
     /** Authenticate middleware — validates session and sets request.user */
     authenticate: (request: FastifyRequest, reply: FastifyReply) => Promise<void>;

package/dist/{sse-DkqQ1uxb.mjs → sse-BkViJPlT.mjs}

@@ -1,28 +1,8 @@
-import { t as __exportAll } from "./chunk-C7Uep-_p.mjs";
-import { n as PUBLIC_SCOPE, r as getOrgId } from "./types-Beqn1Un7.mjs";
-import { t as arcLog } from "./logger-ByrvQWZO.mjs";
+import { t as __exportAll } from "./chunk-BpYLSNr0.mjs";
+import { n as PUBLIC_SCOPE, r as getOrgId } from "./types-C6TQjtdi.mjs";
+import { t as arcLog } from "./logger-Dz3j1ItV.mjs";
 import fp from "fastify-plugin";
-
 //#region src/plugins/sse.ts
-/**
-* SSE Plugin (Server-Sent Events)
-*
-* Streams domain events to clients over HTTP using Server-Sent Events.
-* Requires the events plugin (`arc-events`) to be registered first.
-*
-* @example
-* import { ssePlugin } from '@classytic/arc/plugins';
-*
-* // Basic — stream all events at /events/stream
-* await fastify.register(ssePlugin);
-*
-* // Filtered + org-scoped
-* await fastify.register(ssePlugin, {
-*   path: '/api/events',
-*   patterns: ['order.*', 'product.*'],
-*   orgScoped: true,
-* });
-*/
 var sse_exports = /* @__PURE__ */ __exportAll({
 	default: () => sse_default,
 	ssePlugin: () => ssePlugin
@@ -118,6 +98,5 @@ var sse_default = fp(ssePlugin, {
 	fastify: "5.x",
 	dependencies: ["arc-events"]
 });
-
 //#endregion
-export { sse_default as n, sse_exports as r, ssePlugin as t };
+export { sse_default as n, sse_exports as r, ssePlugin as t };