@beignet/core 0.0.13 → 0.0.15

package/src/ports/index.ts

@@ -15,19 +15,29 @@
  * - `AuthPort` – interface for request authentication implementations
  * - `AuditLogPort` – interface for audit/activity log implementations
  * - `ClockPort` – interface for deterministic time
+ * - `EntitlementsPort` – interface for product access checks
  * - `IdGeneratorPort` – interface for deterministic id generation
  * - `LoggerPort` – interface for structured application logging
  * - `GatePort` – interface for application authorization policies
  * - `RateLimitPort` – interface for rate limiting implementations
  * - `CachePort` – interface for cache implementations
  * - `StoragePort` – interface for object/file storage implementations
+ * - `FlagsPort` – interface for feature flag evaluation implementations
+ * - `ErrorReporterPort` – interface for production error reporting
+ * - `LocksPort` – interface for lease-backed distributed locks
  *
  * Dedicated framework areas own their capability-specific APIs:
+ * - `@beignet/core/entitlements` owns product access helpers and test adapters
+ * - `@beignet/core/error-reporting` owns error reporting helpers and test adapters
+ * - `@beignet/core/flags` owns feature flag helpers and test adapters
  * - `@beignet/core/idempotency` owns idempotency helpers and test adapters
+ * - `@beignet/core/locks` owns lease-backed lock helpers and test adapters
  * - `@beignet/core/mail` owns `MailerPort` and mail test adapters
  * - `@beignet/core/notifications` owns notification helpers and test adapters
  * - `@beignet/core/outbox` owns durable outbox helpers and test adapters
+ * - `@beignet/core/payments` owns `PaymentsPort` and payment test adapters
  * - `@beignet/core/schedules` owns schedule definitions and runners
+ * - `@beignet/core/webhooks` owns inbound webhook definitions and verifiers
  */
 
 import { createUnboundPort } from "./unbound.js";
@@ -136,6 +146,89 @@ export interface PortsContext<P extends AnyPorts = AnyPorts> {
   ports: P;
 }
 
+/**
+ * Entitlement port exports.
+ */
+export type {
+  CreateEntitlementsOptions,
+  CreateStaticEntitlementsOptions,
+  EntitlementAllowedDecision,
+  EntitlementCheckInput,
+  EntitlementDecision,
+  EntitlementDeniedDecision,
+  EntitlementKey,
+  EntitlementResolver,
+  EntitlementResolverResult,
+  EntitlementSubject,
+  EntitlementsContext,
+  EntitlementsPort,
+  RequireEntitlementOptions,
+  StaticEntitlementGrantMap,
+} from "../entitlements/index.js";
+/**
+ * Entitlement helper exports.
+ */
+export {
+  allowEntitlement,
+  createEntitlements,
+  createStaticEntitlements,
+  denyEntitlement,
+  EntitlementRequiredError,
+  requireEntitlement,
+} from "../entitlements/index.js";
+/**
+ * Error reporting port exports.
+ */
+export type {
+  ErrorReportContext,
+  ErrorReporterFlushOptions,
+  ErrorReporterPort,
+  ErrorReportJsonValue,
+  ErrorReportLevel,
+  ErrorReportOptions,
+  ErrorReportResult,
+  ErrorReportTags,
+  ErrorReportUser,
+  MemoryErrorReport,
+  MemoryErrorReporterPort,
+  MemoryReportedException,
+  MemoryReportedMessage,
+} from "../error-reporting/index.js";
+/**
+ * Error reporting helper exports.
+ */
+export {
+  createMemoryErrorReporter,
+  createNoopErrorReporter,
+  reportException,
+  reportMessage,
+} from "../error-reporting/index.js";
+/**
+ * Feature flag port exports.
+ */
+export type {
+  FlagDef,
+  FlagEvaluationContext,
+  FlagEvaluationDetails,
+  FlagEvaluationOptions,
+  FlagExposureOptions,
+  FlagsPort,
+  FlagTrackOptions,
+  FlagValue,
+  MemoryFlagsPort,
+} from "../flags/index.js";
+/**
+ * Feature flag helper exports.
+ */
+export {
+  createMemoryFlags,
+  createStaticFlags,
+  defineFlag,
+  defineFlagRegistry,
+  defineFlags,
+  evaluateFlag,
+  getFlagDetails,
+} from "../flags/index.js";
 /**
  * Idempotency port exports.
  */
@@ -146,6 +239,32 @@ export type {
   IdempotencyReservation,
   IdempotencyReserveInput,
 } from "../idempotency/index.js";
+/**
+ * Lease-backed lock port exports.
+ */
+export type {
+  CreateMemoryLocksOptions,
+  LeaseAcquireOptions,
+  LeaseAcquireResult,
+  LeaseHandle,
+  LeaseMetadata,
+  LeaseRenewOptions,
+  LocksPort,
+  MemoryLeaseRecord,
+  MemoryLocksPort,
+  MemoryLocksProviderOptions,
+  MemoryLocksProviderPorts,
+} from "../locks/index.js";
+/**
+ * Lease-backed lock helper exports.
+ */
+export {
+  acquireLease,
+  createMemoryLocks,
+  createMemoryLocksProvider,
+  LeaseOptionsError,
+  withLease,
+} from "../locks/index.js";
 /**
  * Notification port exports.
  */
@@ -171,6 +290,111 @@ export type {
   OutboxMessageStatus,
   OutboxPort,
 } from "../outbox/index.js";
+/**
+ * Payments port exports.
+ */
+export type {
+  BillingPortalSession,
+  CheckoutSession,
+  CreateBillingPortalSessionInput,
+  CreateCheckoutSessionInput,
+  CreateRefundInput,
+  MemoryBillingPortalSession,
+  MemoryCheckoutSession,
+  MemoryPaymentsPort,
+  MemoryRefund,
+  PaymentCheckoutLineItem,
+  PaymentCheckoutMode,
+  PaymentMetadata,
+  PaymentRefundReason,
+  PaymentsPort,
+  PaymentWebhookEvent,
+  PaymentWebhookRawBody,
+  Refund,
+  VerifyPaymentWebhookInput,
+} from "../payments/index.js";
+/**
+ * Payments helper exports.
+ */
+export {
+  createMemoryPayments,
+  createMemoryPaymentsProvider,
+  PaymentProviderError,
+} from "../payments/index.js";
+/**
+ * Search port exports.
+ *
+ * Search has a dedicated subpath. Re-export the common app port types and
+ * helpers here so apps can import shared port surfaces from one place.
+ */
+export type {
+  DefineSearchIndexOptions,
+  MemorySearchIndexState,
+  MemorySearchPort,
+  MemorySearchProviderOptions,
+  MemorySearchProviderPorts,
+  SearchDeleteResult,
+  SearchDocument,
+  SearchDocumentBase,
+  SearchFilters,
+  SearchFilterValue,
+  SearchIndexDef,
+  SearchIndexResult,
+  SearchPort,
+  SearchPrimitive,
+  SearchQuery,
+  SearchResultPage,
+  SearchResults,
+  SearchSort,
+  SearchValue,
+} from "../search/index.js";
+/**
+ * Search helper exports.
+ */
+export {
+  createMemorySearch,
+  createMemorySearchProvider,
+  defineSearchIndex,
+  indexSearchDocuments,
+  SearchOptionsError,
+  searchDocuments,
+} from "../search/index.js";
+/**
+ * Webhook exports.
+ *
+ * Webhooks have a dedicated subpath. Re-export the common app-facing
+ * definitions and helpers here so production concerns can be imported from one
+ * shared port toolbox when useful.
+ */
+export type {
+  CreateHmacWebhookVerifierOptions,
+  CreateMemoryWebhookVerifierOptions,
+  DefineWebhookOptions,
+  InferSchemaOutput,
+  InferWebhookEvent,
+  MemoryWebhookVerifier,
+  VerifyWebhookInput,
+  VerifyWebhookOptions,
+  WebhookDef,
+  WebhookEvent,
+  WebhookEventSchemas,
+  WebhookHeaders,
+  WebhookRawBody,
+  WebhookVerifier,
+} from "../webhooks/index.js";
+/**
+ * Webhook helper exports.
+ */
+export {
+  createHmacWebhookVerifier,
+  createMemoryWebhookVerifier,
+  defineWebhook,
+  parseWebhookEvent,
+  verifyWebhook,
+  WebhookOptionsError,
+  WebhookValidationError,
+  WebhookVerificationError,
+} from "../webhooks/index.js";
 /**
  * Audit log port exports.
  */
@@ -299,10 +523,17 @@ export type {
   GateAllowedDecision,
   GateContext,
   GateDecision,
+  GateDecisionObservation,
+  GateDecisionObserver,
+  GateDecisionSource,
   GateDeniedDecision,
   GateDenyHandler,
   GatePolicyResult,
   GatePort,
+  PolicyBatch,
+  PolicyBatchBooleanMap,
+  PolicyBatchCheck,
+  PolicyBatchDecisionMap,
   PolicyContextFromDefinitions,
   PolicyDefinition,
   PolicyMapFromDefinitions,

package/src/ports/policy.ts

@@ -77,6 +77,54 @@ export type PolicySubjectArgs<TResolver> = TResolver extends (
     : []
   : [];
 
+/**
+ * One authorization check accepted by batch gate APIs.
+ */
+export type PolicyBatchCheck<TPolicies extends readonly PolicyDefinition[]> = {
+  [TAbility in keyof PolicyMapFromDefinitions<TPolicies> & string]: readonly [
+    ability: TAbility,
+    ...subject: PolicySubjectArgs<
+      PolicyMapFromDefinitions<TPolicies>[TAbility]
+    >,
+  ];
+}[keyof PolicyMapFromDefinitions<TPolicies> & string];
+
+/**
+ * Keyed authorization checks accepted by `inspectMany(...)` and `canMany(...)`.
+ */
+export type PolicyBatch<TPolicies extends readonly PolicyDefinition[]> = Record<
+  string,
+  PolicyBatchCheck<TPolicies>
+>;
+
+/**
+ * Full decision map returned by `inspectMany(...)`.
+ */
+export type PolicyBatchDecisionMap<
+  TBatch extends PolicyBatch<readonly PolicyDefinition[]>,
+> = {
+  [TKey in keyof TBatch]: GateDecision;
+};
+
+/**
+ * Boolean decision map returned by `canMany(...)`.
+ */
+export type PolicyBatchBooleanMap<
+  TBatch extends PolicyBatch<readonly PolicyDefinition[]>,
+> = {
+  [TKey in keyof TBatch]: boolean;
+};
+
+/**
+ * Gate method that produced a policy decision observation.
+ */
+export type GateDecisionSource =
+  | "can"
+  | "inspect"
+  | "authorize"
+  | "canMany"
+  | "inspectMany";
+
 type UnionToIntersection<T> = (
   T extends unknown
     ? (value: T) => void
@@ -126,6 +174,12 @@ export type BoundGate<TPolicies extends readonly PolicyDefinition[]> = {
     ability: TAbility,
     ...subject: PolicySubjectArgs<PolicyMapFromDefinitions<TPolicies>[TAbility]>
   ): Promise<boolean>;
+  /**
+   * Return keyed boolean decisions for several abilities.
+   */
+  canMany<const TBatch extends PolicyBatch<TPolicies>>(
+    checks: TBatch,
+  ): Promise<PolicyBatchBooleanMap<TBatch>>;
   /**
    * Return the full allow/deny decision without throwing.
    */
@@ -133,6 +187,12 @@ export type BoundGate<TPolicies extends readonly PolicyDefinition[]> = {
     ability: TAbility,
     ...subject: PolicySubjectArgs<PolicyMapFromDefinitions<TPolicies>[TAbility]>
   ): Promise<GateDecision>;
+  /**
+   * Return keyed allow/deny decisions for several abilities.
+   */
+  inspectMany<const TBatch extends PolicyBatch<TPolicies>>(
+    checks: TBatch,
+  ): Promise<PolicyBatchDecisionMap<TBatch>>;
   /**
    * Return an allowed decision or throw for denied abilities.
    */
@@ -193,6 +253,13 @@ export type GatePort<
     ability: TAbility,
     ...subject: PolicySubjectArgs<PolicyMapFromDefinitions<TPolicies>[TAbility]>
   ): Promise<boolean>;
+  /**
+   * Return keyed boolean decisions for several abilities.
+   */
+  canMany<const TBatch extends PolicyBatch<TPolicies>>(
+    ctx: TContext,
+    checks: TBatch,
+  ): Promise<PolicyBatchBooleanMap<TBatch>>;
   /**
    * Return the full allow/deny decision for a context without throwing.
    */
@@ -201,6 +268,13 @@ export type GatePort<
     ability: TAbility,
     ...subject: PolicySubjectArgs<PolicyMapFromDefinitions<TPolicies>[TAbility]>
   ): Promise<GateDecision>;
+  /**
+   * Return keyed allow/deny decisions for several abilities.
+   */
+  inspectMany<const TBatch extends PolicyBatch<TPolicies>>(
+    ctx: TContext,
+    checks: TBatch,
+  ): Promise<PolicyBatchDecisionMap<TBatch>>;
   /**
    * Return an allowed decision or throw for denied abilities.
    */
@@ -225,6 +299,63 @@ export type GateDenyHandler<TContext> = (
   },
 ) => MaybePromise<Error | undefined>;
 
+/**
+ * Best-effort policy decision observation emitted by a gate.
+ *
+ * Observers are for diagnostics and audit-style integrations only. They do not
+ * participate in authorization control flow and thrown/rejected observer errors
+ * are ignored.
+ */
+export type GateDecisionObservation<TContext> = {
+  /**
+   * Gate method that produced the decision.
+   */
+  source: GateDecisionSource;
+  /**
+   * Key from a batch input object, when the decision came from a batch call.
+   */
+  batchKey?: string;
+  /**
+   * Application context used for policy evaluation.
+   */
+  ctx: TContext;
+  /**
+   * Ability being evaluated.
+   */
+  ability: string;
+  /**
+   * Optional subject passed to the policy.
+   */
+  subject?: unknown;
+  /**
+   * Normalized decision, when policy evaluation returned normally.
+   */
+  decision?: GateDecision;
+  /**
+   * Error thrown by the policy resolver, when evaluation failed.
+   */
+  error?: unknown;
+  /**
+   * Policy evaluation duration, excluding observer work.
+   */
+  durationMs: number;
+  /**
+   * Correlation fields copied from the context when present.
+   */
+  requestId?: string;
+  traceId?: string;
+  spanId?: string;
+  parentSpanId?: string;
+  traceparent?: string;
+};
+
+/**
+ * Best-effort observer called after each gate decision or resolver error.
+ */
+export type GateDecisionObserver<TContext> = (
+  observation: GateDecisionObservation<TContext>,
+) => MaybePromise<void>;
+
 /**
  * Options for `createGate(...)`.
  */
@@ -240,6 +371,12 @@ export type CreateGateOptions<
    * Optional mapper for denied authorization decisions.
    */
   onDeny?: GateDenyHandler<TContext>;
+  /**
+   * Optional best-effort observer for policy decisions.
+   *
+   * This hook is diagnostic only: it cannot change decisions or thrown errors.
+   */
+  onDecision?: GateDecisionObserver<TContext>;
 };
 
 /**
@@ -330,6 +467,7 @@ export function createGate<
   options: CreateGateOptions<TContext, TPolicies>,
 ): GatePort<TContext, TPolicies> {
   const registry = new Map<string, PolicyResolver>();
+  const observeDecision = createDecisionObserver(options.onDecision);
 
   for (const definition of options.policies) {
     for (const [ability, resolver] of Object.entries(definition.policies)) {
@@ -341,21 +479,62 @@ export function createGate<
     }
   }
 
-  async function inspect(
+  async function evaluate(
     ctx: TContext,
     ability: string,
     subject?: unknown,
+    source: GateDecisionSource = "inspect",
+    batchKey?: string,
   ): Promise<GateDecision> {
+    const startedAt = policyNow();
     const resolver = registry.get(ability);
     if (!resolver) {
-      return deny({
+      const decision = deny({
         reason: `No policy registered for "${ability}".`,
         code: "POLICY_NOT_FOUND",
       });
+
+      observeDecision({
+        source,
+        batchKey,
+        ctx,
+        ability,
+        subject,
+        decision,
+        durationMs: policyNow() - startedAt,
+      });
+
+      return decision;
     }
 
-    const result = await resolver(ctx as never, subject as never);
-    return normalizeDecision(result);
+    try {
+      const result = await resolver(ctx as never, subject as never);
+      const decision = normalizeDecision(result);
+
+      observeDecision({
+        source,
+        batchKey,
+        ctx,
+        ability,
+        subject,
+        decision,
+        durationMs: policyNow() - startedAt,
+      });
+
+      return decision;
+    } catch (error) {
+      observeDecision({
+        source,
+        batchKey,
+        ctx,
+        ability,
+        subject,
+        error,
+        durationMs: policyNow() - startedAt,
+      });
+
+      throw error;
+    }
   }
 
   async function authorize(
@@ -363,18 +542,44 @@ export function createGate<
     ability: string,
     subject?: unknown,
   ): Promise<GateAllowedDecision> {
-    const decision = await inspect(ctx, ability, subject);
+    const decision = await evaluate(ctx, ability, subject, "authorize");
     if (decision.allowed) return decision;
 
     const thrown = await options.onDeny?.(decision, { ctx, ability, subject });
     throw thrown ?? new GateAuthorizationError(decision);
   }
 
+  async function inspectMany<const TBatch extends PolicyBatch<TPolicies>>(
+    ctx: TContext,
+    checks: TBatch,
+    source: "canMany" | "inspectMany",
+  ): Promise<PolicyBatchDecisionMap<TBatch>> {
+    const decisions: Record<string, GateDecision> = {};
+
+    for (const [batchKey, check] of Object.entries(checks)) {
+      const [ability, subject] = check as unknown as readonly [
+        string,
+        unknown?,
+      ];
+      decisions[batchKey] = await evaluate(
+        ctx,
+        ability,
+        subject,
+        source,
+        batchKey,
+      );
+    }
+
+    return decisions as PolicyBatchDecisionMap<TBatch>;
+  }
+
   function bind(ctx: TContext): BoundGate<TPolicies> {
     return {
       can: async (ability, ...subject) => gate.can(ctx, ability, ...subject),
+      canMany: async (checks) => gate.canMany(ctx, checks),
       inspect: async (ability, ...subject) =>
         gate.inspect(ctx, ability, ...subject),
+      inspectMany: async (checks) => gate.inspectMany(ctx, checks),
       authorize: async (ability, ...subject) =>
         gate.authorize(ctx, ability, ...subject),
     };
@@ -398,10 +603,22 @@ export function createGate<
     bind,
     attach,
     async can(ctx, ability, ...subject) {
-      return (await inspect(ctx, ability, firstSubject(subject))).allowed;
+      return (await evaluate(ctx, ability, firstSubject(subject), "can"))
+        .allowed;
+    },
+    async canMany(ctx, checks) {
+      const decisions = await inspectMany(ctx, checks, "canMany");
+      const result: Record<string, boolean> = {};
+
+      for (const [key, decision] of Object.entries(decisions)) {
+        result[key] = decision.allowed;
+      }
+
+      return result as PolicyBatchBooleanMap<typeof checks>;
     },
     inspect: async (ctx, ability, ...subject) =>
-      inspect(ctx, ability, firstSubject(subject)),
+      evaluate(ctx, ability, firstSubject(subject), "inspect"),
+    inspectMany: async (ctx, checks) => inspectMany(ctx, checks, "inspectMany"),
     authorize: async (ctx, ability, ...subject) =>
       authorize(ctx, ability, firstSubject(subject)),
   };
@@ -420,3 +637,51 @@ function normalizeDecision(result: GatePolicyResult): GateDecision {
 function firstSubject(subject: readonly unknown[]): unknown {
   return subject[0];
 }
+
+function policyNow(): number {
+  return typeof performance !== "undefined" ? performance.now() : Date.now();
+}
+
+function contextStringField(ctx: unknown, field: string): string | undefined {
+  if (!ctx || typeof ctx !== "object") return undefined;
+  const value = (ctx as Record<string, unknown>)[field];
+  return typeof value === "string" ? value : undefined;
+}
+
+function enrichObservation<TContext>(
+  observation: GateDecisionObservation<TContext>,
+): GateDecisionObservation<TContext> {
+  return {
+    ...observation,
+    requestId: contextStringField(observation.ctx, "requestId"),
+    traceId: contextStringField(observation.ctx, "traceId"),
+    spanId: contextStringField(observation.ctx, "spanId"),
+    parentSpanId: contextStringField(observation.ctx, "parentSpanId"),
+    traceparent: contextStringField(observation.ctx, "traceparent"),
+  };
+}
+
+function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+  return (
+    value !== null &&
+    (typeof value === "object" || typeof value === "function") &&
+    typeof (value as { then?: unknown }).then === "function"
+  );
+}
+
+function createDecisionObserver<TContext>(
+  observer: GateDecisionObserver<TContext> | undefined,
+): (observation: GateDecisionObservation<TContext>) => void {
+  return (observation) => {
+    if (!observer) return;
+
+    try {
+      const result = observer(enrichObservation(observation));
+      if (isPromiseLike(result)) {
+        Promise.resolve(result).catch(() => undefined);
+      }
+    } catch {
+      // Observers are diagnostic only and must not affect authorization.
+    }
+  };
+}