@classytic/arc 2.9.1 → 2.10.3

package/dist/policies/index.mjs

@@ -1,318 +0,0 @@
-//#region src/policies/helpers.ts
-/**
-* Helper to create Fastify middleware from any PolicyEngine implementation
-*
-* This is a convenience function that provides a standard middleware pattern.
-* Most policies can use this instead of implementing toMiddleware() manually.
-*
-* @param policy - Policy engine instance
-* @param operation - Operation name (list, get, create, update, delete)
-* @returns Fastify preHandler middleware
-*
-* @example
-* ```typescript
-* class SimplePolicy implements PolicyEngine {
-*   can(user, operation) {
-*     return { allowed: user.isActive };
-*   }
-*
-*   toMiddleware(operation) {
-*     return createPolicyMiddleware(this, operation);
-*   }
-* }
-* ```
-*/
-function createPolicyMiddleware(policy, operation) {
-	return async function policyMiddleware(request, reply) {
-		const context = {
-			document: request.document,
-			body: request.body,
-			params: request.params,
-			query: request.query
-		};
-		const result = await policy.can(request.user, operation, context);
-		if (!result.allowed) return reply.code(403).send({
-			success: false,
-			error: "Access denied",
-			message: result.reason || "You do not have permission to perform this action"
-		});
-		request.policyResult = result;
-		if (result.filters && Object.keys(result.filters).length > 0) request._policyFilters = result.filters;
-		if (result.fieldMask) request.fieldMask = result.fieldMask;
-		if (result.metadata) request.policyMetadata = result.metadata;
-	};
-}
-/**
-* Combine multiple policies with AND logic
-*
-* All policies must allow the operation for it to succeed.
-* First denial stops evaluation and returns the denial reason.
-*
-* @param policies - Array of policy engines to combine
-* @returns Combined policy engine
-*
-* @example
-* ```typescript
-* const combinedPolicy = combinePolicies(
-*   rbacPolicy,        // Must have correct role
-*   ownershipPolicy,   // Must own the resource
-*   auditPolicy,       // Logs access for compliance
-* );
-*
-* // All three policies must pass for the operation to succeed
-* const result = await combinedPolicy.can(user, 'update', context);
-* ```
-*
-* @example Multi-tenant + RBAC
-* ```typescript
-* const policy = combinePolicies(
-*   definePolicy({ tenant: { field: 'organizationId' } }),
-*   definePolicy({ roles: { update: ['admin', 'editor'] } }),
-* );
-* ```
-*/
-function combinePolicies(...policies) {
-	if (policies.length === 0) throw new Error("combinePolicies requires at least one policy");
-	if (policies.length === 1) return policies[0];
-	return {
-		async can(user, operation, context) {
-			const results = [];
-			for (const policy of policies) {
-				const result = await policy.can(user, operation, context);
-				if (!result.allowed) return result;
-				results.push(result);
-			}
-			const mergedResult = {
-				allowed: true,
-				filters: {},
-				metadata: {}
-			};
-			for (const result of results) if (result.filters) Object.assign(mergedResult.filters, result.filters);
-			const allExcludes = /* @__PURE__ */ new Set();
-			const allIncludes = [];
-			for (const result of results) {
-				if (result.fieldMask?.exclude) for (const field of result.fieldMask.exclude) allExcludes.add(field);
-				if (result.fieldMask?.include) allIncludes.push(new Set(result.fieldMask.include));
-			}
-			if (allExcludes.size > 0 || allIncludes.length > 0) {
-				mergedResult.fieldMask = {};
-				if (allExcludes.size > 0) mergedResult.fieldMask.exclude = Array.from(allExcludes);
-				if (allIncludes.length > 0) {
-					const intersection = allIncludes.reduce((acc, set) => {
-						return new Set([...acc].filter((x) => set.has(x)));
-					});
-					if (intersection.size > 0) mergedResult.fieldMask.include = Array.from(intersection);
-				}
-			}
-			for (const result of results) if (result.metadata) Object.assign(mergedResult.metadata, result.metadata);
-			if (Object.keys(mergedResult.filters).length === 0) delete mergedResult.filters;
-			if (Object.keys(mergedResult.metadata).length === 0) delete mergedResult.metadata;
-			return mergedResult;
-		},
-		toMiddleware(operation) {
-			const middlewares = policies.map((p) => p.toMiddleware(operation));
-			return async (request, reply) => {
-				for (const middleware of middlewares) {
-					await middleware(request, reply);
-					if (reply.sent) return;
-				}
-			};
-		}
-	};
-}
-/**
-* Combine multiple policies with OR logic
-*
-* At least one policy must allow the operation for it to succeed.
-* If all policies deny, returns the first denial reason.
-*
-* @param policies - Array of policy engines to combine
-* @returns Combined policy engine
-*
-* @example
-* ```typescript
-* const policy = anyPolicy(
-*   ownerPolicy,    // User owns the resource
-*   adminPolicy,    // OR user is admin
-*   publicPolicy,   // OR resource is public
-* );
-*
-* // Any one of these policies passing allows the operation
-* ```
-*/
-function anyPolicy(...policies) {
-	if (policies.length === 0) throw new Error("anyPolicy requires at least one policy");
-	if (policies.length === 1) return policies[0];
-	return {
-		async can(user, operation, context) {
-			let firstDenial = null;
-			for (const policy of policies) {
-				const result = await policy.can(user, operation, context);
-				if (result.allowed) return result;
-				if (!firstDenial) firstDenial = result;
-			}
-			return firstDenial;
-		},
-		toMiddleware(operation) {
-			return async (request, reply) => {
-				const results = [];
-				for (const policy of policies) {
-					const result = await policy.can(request.user, operation, {
-						document: request.document,
-						body: request.body,
-						params: request.params,
-						query: request.query
-					});
-					if (result.allowed) {
-						request.policyResult = result;
-						if (result.filters) request._policyFilters = result.filters;
-						if (result.fieldMask) request.fieldMask = result.fieldMask;
-						if (result.metadata) request.policyMetadata = result.metadata;
-						return;
-					}
-					results.push(result);
-				}
-				return reply.code(403).send({
-					success: false,
-					error: "Access denied",
-					message: results[0]?.reason || "You do not have permission to perform this action"
-				});
-			};
-		}
-	};
-}
-/**
-* Create a pass-through policy that always allows
-*
-* Useful for testing or for routes that don't need authorization.
-*
-* @example
-* ```typescript
-* const policy = allowAll();
-* const result = await policy.can(user, 'any-operation');
-* // result.allowed === true
-* ```
-*/
-function allowAll() {
-	return {
-		can() {
-			return { allowed: true };
-		},
-		toMiddleware() {
-			return async () => {};
-		}
-	};
-}
-/**
-* Create a policy that always denies
-*
-* Useful for explicitly blocking operations or for testing.
-*
-* @param reason - Denial reason
-*
-* @example
-* ```typescript
-* const policy = denyAll('This resource is deprecated');
-* const result = await policy.can(user, 'any-operation');
-* // result.allowed === false
-* // result.reason === 'This resource is deprecated'
-* ```
-*/
-function denyAll(reason = "Operation not allowed") {
-	return {
-		can() {
-			return {
-				allowed: false,
-				reason
-			};
-		},
-		toMiddleware() {
-			return async (_request, reply) => {
-				return reply.code(403).send({
-					success: false,
-					error: "Access denied",
-					message: reason
-				});
-			};
-		}
-	};
-}
-//#endregion
-//#region src/policies/PolicyInterface.ts
-/**
-* Create a PermissionCheck from access control statements.
-*
-* Maps Better Auth's statement-based access control model to Arc's
-* PermissionCheck function, which can be used directly in resource permissions.
-*
-* The returned PermissionCheck:
-* 1. Looks up the resource + action in the statements list
-* 2. If no matching statement exists, denies access
-* 3. If a matching statement exists and `checkPermission` is provided,
-*    calls it for dynamic verification (e.g., check org role)
-* 4. If `checkPermission` is not provided, allows access based on static statements
-*
-* @example Static statements only
-* ```typescript
-* import { createAccessControlPolicy } from '@classytic/arc/policies';
-*
-* const editorPermissions = createAccessControlPolicy({
-*   statements: [
-*     { resource: 'product', action: ['create', 'update'] },
-*     { resource: 'order', action: ['read'] },
-*   ],
-* });
-*
-* // Use in resource config
-* defineResource({
-*   name: 'product',
-*   permissions: {
-*     create: editorPermissions,
-*     update: editorPermissions,
-*   },
-* });
-* ```
-*
-* @example With dynamic permission check (Better Auth org roles)
-* ```typescript
-* const policy = createAccessControlPolicy({
-*   statements: [
-*     { resource: 'product', action: ['create', 'update'] },
-*     { resource: 'order', action: ['read'] },
-*   ],
-*   checkPermission: async (userId, resource, action) => {
-*     return hasOrgPermission(userId, resource, action);
-*   },
-* });
-* ```
-*/
-function createAccessControlPolicy(options) {
-	const statementMap = /* @__PURE__ */ new Map();
-	for (const statement of options.statements) {
-		const existing = statementMap.get(statement.resource);
-		if (existing) for (const action of statement.action) existing.add(action);
-		else statementMap.set(statement.resource, new Set(statement.action));
-	}
-	const permissionCheck = async (context) => {
-		const { user, resource, action } = context;
-		if (!statementMap.get(resource)?.has(action)) return {
-			granted: false,
-			reason: `Action '${action}' is not permitted on resource '${resource}'`
-		};
-		if (options.checkPermission) {
-			const userId = user?.id ?? user?._id;
-			if (!userId) return {
-				granted: false,
-				reason: "Authentication required"
-			};
-			if (!await options.checkPermission(String(userId), resource, action)) return {
-				granted: false,
-				reason: `User does not have '${action}' permission on '${resource}'`
-			};
-		}
-		return { granted: true };
-	};
-	return permissionCheck;
-}
-//#endregion
-export { allowAll, anyPolicy, combinePolicies, createAccessControlPolicy, createPolicyMiddleware, denyAll };

package/dist/rpc/index.d.mts

@@ -1,90 +0,0 @@
-import { r as CircuitBreakerOptions } from "../circuitBreaker-CvXkjfrW.mjs";
-
-//#region src/rpc/serviceClient.d.ts
-interface RetryConfig {
-  /** Max retry attempts (not counting initial attempt). Default: 2 */
-  maxRetries?: number;
-  /** Initial backoff delay in ms. Doubles on each retry. Default: 200 */
-  backoffMs?: number;
-  /** Max backoff cap in ms. Default: 5000 */
-  maxBackoffMs?: number;
-  /**
-   * HTTP status codes to retry on. Default: [502, 503, 504, 408, 429]
-   * 4xx errors (except 408, 429) are NOT retried — they are client errors.
-   */
-  retryableStatuses?: number[];
-}
-interface RequestInfo {
-  method: string;
-  url: string;
-  headers?: Record<string, string>;
-}
-interface ResponseInfo {
-  method: string;
-  url: string;
-  status: number;
-  durationMs: number;
-  retries: number;
-}
-interface ServiceClientOptions {
-  /** Base URL of the remote Arc service (e.g., 'http://catalog-service:3000') */
-  baseUrl: string;
-  /** Static bearer token, or function that returns one (for rotation) */
-  token?: string | (() => string);
-  /** Organization ID — sent as x-organization-id header */
-  organizationId?: string;
-  /**
-   * Correlation ID for distributed tracing — sent as x-request-id header.
-   * Static string or function (e.g., () => request.id from current request context).
-   */
-  correlationId?: string | (() => string);
-  /** Schema version — sent as x-arc-schema-version header for contract compatibility */
-  schemaVersion?: string;
-  /** Additional headers sent with every request */
-  headers?: Record<string, string>;
-  /** Request timeout in ms (default: 10000) */
-  timeout?: number;
-  /** Retry config for transient failures (default: disabled) */
-  retry?: RetryConfig;
-  /** Circuit breaker config (default: disabled) */
-  circuitBreaker?: Pick<CircuitBreakerOptions, "failureThreshold" | "resetTimeout" | "timeout" | "successThreshold">;
-  /** Health check path (default: '/_health/live' — matches Arc's health plugin) */
-  healthPath?: string;
-  /** Called before each request (for logging, metrics, tracing) */
-  onRequest?: (info: RequestInfo) => void;
-  /** Called after each response (for logging, metrics, tracing) */
-  onResponse?: (info: ResponseInfo) => void;
-}
-interface ResourceClient {
-  /** GET /{resource}s?...query */
-  list(query?: Record<string, unknown>): Promise<ServiceResponse>;
-  /** GET /{resource}s/:id */
-  get(id: string): Promise<ServiceResponse>;
-  /** POST /{resource}s */
-  create(data: Record<string, unknown>): Promise<ServiceResponse>;
-  /** PATCH /{resource}s/:id */
-  update(id: string, data: Record<string, unknown>): Promise<ServiceResponse>;
-  /** DELETE /{resource}s/:id */
-  delete(id: string): Promise<ServiceResponse>;
-  /** POST /{resource}s/:id/action */
-  action(id: string, actionName: string, data?: Record<string, unknown>): Promise<ServiceResponse>;
-}
-interface ServiceResponse<T = any> {
-  success: boolean;
-  data?: T;
-  error?: string;
-  message?: string;
-  status?: number;
-  meta?: Record<string, unknown>;
-}
-interface ServiceClient {
-  /** Get a typed resource client for CRUD + actions */
-  resource(name: string): ResourceClient;
-  /** Raw call to any path (for non-resource endpoints) */
-  call(method: string, path: string, body?: unknown): Promise<ServiceResponse>;
-  /** Health check — returns true if service is reachable */
-  health(): Promise<boolean>;
-}
-declare function createServiceClient(options: ServiceClientOptions): ServiceClient;
-//#endregion
-export { type RequestInfo, type ResourceClient, type ResponseInfo, type RetryConfig, type ServiceClient, type ServiceClientOptions, type ServiceResponse, createServiceClient };

package/dist/rpc/index.mjs

@@ -1,248 +0,0 @@
-import { t as CircuitBreaker } from "../circuitBreaker-l18oRgL5.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 };