@beignet/core 0.0.13 → 0.0.14

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @beignet/core
 
+## 0.0.14
+
+### Patch Changes
+
+- 0b106c3: Add first-class error reporting primitives and a Sentry-backed error reporting
+  provider.
+- 6828442: Add first-class feature flag primitives, an OpenFeature-backed flags provider,
+  and devtools support for flag evaluation, exposure, and tracking events.
+- edf5ddc: Add first-class entitlement primitives for product access checks, devtools-ready entitlement decision observation, and doctor checks for entitlement wiring drift. Generated billing slices expose a billing-backed entitlements port.
+- bcd3864: Add lease-backed lock primitives and a Redis-backed locks provider.
+- d51a35f: Add the provider-neutral payments port, memory payments adapter, Stripe payments provider, Next.js payment webhook route helper, `beignet make payments`, and first-class payments devtools view.
+- 655c101: Add keyed authorization batch checks and best-effort policy decision observation, plus a first-class devtools watcher/view for policy decision events.
+- bcd3864: Add a provider-neutral search port, memory adapter, and Meilisearch provider.
+
 ## 0.0.13
 
 ### Patch Changes

package/README.md

@@ -8,8 +8,9 @@
 
 This package provides Beignet's framework primitives: contracts, server runtime,
 typed client, use cases, ports, domain helpers, app errors, config, events,
-idempotency, outbox, mail, notifications, schedules, uploads, pagination helpers,
-testing helpers, and OpenAPI generation.
+idempotency, locks, outbox, mail, notifications, payments, search, feature
+flags, error reporting, schedules, uploads, entitlements, pagination helpers, testing
+helpers, and OpenAPI generation.
 
 ## Installation
 
@@ -43,18 +44,24 @@ name the framework area they depend on.
 | `@beignet/core/config` | Environment config validation |
 | `@beignet/core/contracts` | HTTP contract builders, types, path helpers, and contract metadata |
 | `@beignet/core/domain` | Entities, value objects, and domain events |
+| `@beignet/core/entitlements` | Product access decision types, helpers, and static entitlement adapter |
+| `@beignet/core/error-reporting` | Error reporting port, memory adapter, no-op adapter, and helpers |
 | `@beignet/core/errors` | Error catalogs and response helpers |
 | `@beignet/core/events` | Events and listeners |
+| `@beignet/core/flags` | Feature flag definitions, FlagsPort, memory/static adapters, and helpers |
 | `@beignet/core/idempotency` | Retry-safe command, webhook, and job primitives |
 | `@beignet/core/jobs` | Job definitions, retry policies, and inline job dispatch |
+| `@beignet/core/locks` | Lease-backed LocksPort, memory adapter, memory provider, and helpers |
 | `@beignet/core/mail` | Mail port, memory mailer, and memory mailer provider |
 | `@beignet/core/notifications` | Notification definitions, dispatchers, inline notifications provider, mail channels, and test adapters |
 | `@beignet/core/openapi` | OpenAPI generation |
 | `@beignet/core/outbox` | Durable event and job outbox |
+| `@beignet/core/payments` | Payments port, memory payments adapter, and memory payments provider |
 | `@beignet/core/pagination` | Offset/cursor page types, normalizers, and result helpers |
 | `@beignet/core/ports` | App-facing ports, auth, audit, policies, cache, storage, logging, and redaction |
 | `@beignet/core/ports/testing` | Port and policy test helpers |
 | `@beignet/core/providers` | Provider lifecycle and instrumentation primitives |
+| `@beignet/core/search` | Search index definitions, SearchPort, memory adapter, memory provider, and helpers |
 | `@beignet/core/schedules` | Schedule primitives |
 | `@beignet/core/server` | Framework-agnostic server runtime and hook helpers |
 | `@beignet/core/server-only` | Static lint marker for modules that must stay out of client bundles |
@@ -177,6 +184,148 @@ Replace `createMemoryMailerProvider(...)` with a real mail provider such as
 keep the inline notifications provider and run it from jobs or listeners, or
 replace it with an app-owned dispatcher when delivery needs custom semantics.
 
+## Entitlements
+
+Use `@beignet/core/entitlements` for product access decisions derived from
+app-owned billing or plan state. The resolver maps durable app state to
+allow/deny decisions; `requireEntitlement(...)` enforces the decision from a
+use case and throws a framework-owned 403 by default.
+
+```typescript
+import {
+  createEntitlements,
+  type EntitlementDecisionObserver,
+  requireEntitlement,
+} from "@beignet/core/entitlements";
+
+function createBillingEntitlements(
+  billing: BillingRepository,
+  recordDecision?: EntitlementDecisionObserver,
+) {
+  return createEntitlements({
+    async inspect(input) {
+      const account = await billing.findByTenantId(input.subject.id);
+      return account?.status === "active";
+    },
+    onDecision: recordDecision,
+  });
+}
+
+await requireEntitlement(ctx, {
+  entitlement: "todos.create",
+  subject: { type: "tenant", id: tenantId },
+});
+```
+
+`onDecision` is diagnostic only. Observer errors are ignored and cannot change
+the entitlement result.
+
+## Feature flags
+
+Use `@beignet/core/flags` for typed feature flag definitions and
+provider-neutral evaluation. Flags always carry a default value, and provider
+failures return that default instead of throwing into product workflows.
+
+```typescript
+import { defineFlag, defineFlags } from "@beignet/core/flags";
+
+export const billingFlags = defineFlags({
+  newCheckout: defineFlag.boolean("billing.new-checkout", {
+    default: false,
+  }),
+});
+
+const enabled = await ctx.ports.flags.evaluate(billingFlags.newCheckout, {
+  context: {
+    targetingKey: ctx.actor.id,
+    tenant: ctx.tenant,
+    requestId: ctx.requestId,
+  },
+});
+```
+
+Plain evaluation does not record exposure. Call `recordExposure(...)`
+explicitly when a user actually sees or can be affected by the flagged
+behavior. Use `createMemoryFlags(...)` or `createStaticFlags(...)` in tests, or
+install `@beignet/provider-flags-openfeature` for production providers.
+String and number flags widen to `string` and `number` by default; pass a
+generic when an app wants a closed variant union.
+
+## Error reporting
+
+Use `@beignet/core/error-reporting` for provider-neutral exception and message
+capture. The port accepts severity, tags, user, contexts, extra metadata, and
+request/trace correlation IDs.
+
+```typescript
+import { createMemoryErrorReporter } from "@beignet/core/error-reporting";
+
+await ctx.ports.errorReporter.captureException(error, {
+  level: "error",
+  requestId: ctx.requestId,
+  traceId: ctx.traceId,
+  tags: { feature: "billing" },
+});
+
+const errorReporter = createMemoryErrorReporter();
+```
+
+Use `createMemoryErrorReporter(...)` in tests, `createNoopErrorReporter()` when
+an app needs a bound port without capture, or install
+`@beignet/provider-error-reporting-sentry` for production providers.
+
+## Locks and leases
+
+Use `@beignet/core/locks` for provider-neutral lease-backed lock coordination.
+Locks prevent overlapping schedules, singleton jobs, cache stampedes, and short
+critical sections across multiple workers or servers.
+
+```typescript
+import { createMemoryLocks } from "@beignet/core/locks";
+
+await ctx.ports.locks.withLease(
+  "schedule:daily-report",
+  { ttlMs: 60_000, waitMs: 0 },
+  async ({ lease }) => {
+    await runDailyReport(ctx, { fencingToken: lease.fencingToken });
+  },
+);
+
+const locks = createMemoryLocks();
+```
+
+Use `createMemoryLocks(...)` in tests, `createMemoryLocksProvider()` for local
+provider wiring, or install `@beignet/provider-locks-redis` for production
+leases.
+
+## Search
+
+Use `@beignet/core/search` for provider-neutral search index definitions,
+document indexing, and querying searchable read models.
+
+```typescript
+import { defineSearchIndex } from "@beignet/core/search";
+
+const issueSearchIndex = defineSearchIndex("issues", {
+  searchableAttributes: ["key", "title", "description"],
+  filterableAttributes: ["tenantId", "status"],
+  sortableAttributes: ["createdAt"],
+});
+
+await ctx.ports.search.indexDocuments(issueSearchIndex, issueDocument);
+
+const results = await ctx.ports.search.search(issueSearchIndex, {
+  query: "billing",
+  filters: { tenantId },
+  sort: ["createdAt:desc"],
+  limit: 20,
+});
+```
+
+Use `createMemorySearch(...)` in tests, `createMemorySearchProvider()` for local
+provider wiring, or install `@beignet/provider-search-meilisearch` for
+production search.
+
 ## Provider metadata
 
 Reusable provider packages should declare static metadata in `package.json`
@@ -665,6 +814,11 @@ await tester.assertMatrix([
   },
 ]);
 
+const permissions = await tester.gate.canMany(activity, {
+  publish: ["posts.publish", post],
+});
+expect(permissions.publish).toBe(true);
+
 assertAuditEntry(audit.entries, {
   action: "posts.publish",
   actorId: "user_1",

package/dist/entitlements/index.d.ts

@@ -0,0 +1,234 @@
+/**
+ * @beignet/core/entitlements
+ *
+ * Provider-neutral product access primitives for Beignet applications.
+ */
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * Stable app-defined capability key, such as "issues.create".
+ */
+export type EntitlementKey = string;
+/**
+ * Principal whose product access is being checked.
+ */
+export type EntitlementSubject = {
+    /**
+     * App-defined subject type, commonly "tenant" or "account".
+     */
+    type: string;
+    /**
+     * Stable subject identifier.
+     */
+    id: string;
+};
+/**
+ * Input for checking whether a subject has access to a capability.
+ */
+export type EntitlementCheckInput<TKey extends EntitlementKey = EntitlementKey> = {
+    /**
+     * Capability being checked.
+     */
+    entitlement: TKey;
+    /**
+     * Tenant, account, or other app-owned subject whose product access is checked.
+     */
+    subject: EntitlementSubject;
+};
+/**
+ * An entitlement decision that allows the capability.
+ */
+export type EntitlementAllowedDecision = {
+    allowed: true;
+};
+/**
+ * An entitlement decision that denies the capability.
+ */
+export type EntitlementDeniedDecision = {
+    allowed: false;
+    reason?: string;
+    code?: string;
+    details?: unknown;
+};
+/**
+ * Normalized entitlement decision.
+ */
+export type EntitlementDecision = EntitlementAllowedDecision | EntitlementDeniedDecision;
+/**
+ * Value an entitlement resolver may return.
+ */
+export type EntitlementResolverResult = boolean | EntitlementDecision;
+/**
+ * Entitlement port method that produced a decision.
+ */
+export type EntitlementDecisionSource = "can" | "inspect" | "require";
+/**
+ * Optional context for entitlement checks.
+ */
+export type EntitlementCheckOptions<TContext = unknown> = {
+    /**
+     * Application context used for the check. Observers can use this to copy
+     * request correlation fields without coupling the resolver to app context.
+     */
+    ctx?: TContext;
+    /**
+     * Source to report to observers. Port methods set this automatically.
+     */
+    source?: EntitlementDecisionSource;
+};
+/**
+ * App-facing product access port.
+ */
+export type EntitlementsPort<TKey extends EntitlementKey = EntitlementKey, TContext = unknown> = {
+    /**
+     * Return only whether the capability is allowed.
+     */
+    can(input: EntitlementCheckInput<TKey>, options?: EntitlementCheckOptions<TContext>): Promise<boolean>;
+    /**
+     * Return the full allow/deny decision without throwing.
+     */
+    inspect(input: EntitlementCheckInput<TKey>, options?: EntitlementCheckOptions<TContext>): Promise<EntitlementDecision>;
+};
+/**
+ * Function that decides whether an entitlement is granted.
+ */
+export type EntitlementResolver<TKey extends EntitlementKey = EntitlementKey> = (input: EntitlementCheckInput<TKey>) => MaybePromise<EntitlementResolverResult>;
+/**
+ * Best-effort entitlement decision observation emitted by an entitlements port.
+ *
+ * Observers are diagnostic only. They do not participate in entitlement
+ * control flow and thrown/rejected observer errors are ignored.
+ */
+export type EntitlementDecisionObservation<TContext = unknown, TKey extends EntitlementKey = EntitlementKey> = {
+    /**
+     * Port helper that produced the decision.
+     */
+    source: EntitlementDecisionSource;
+    /**
+     * Application context passed by the caller, when available.
+     */
+    ctx?: TContext;
+    /**
+     * Capability being evaluated.
+     */
+    entitlement: TKey;
+    /**
+     * Subject whose product access is checked.
+     */
+    subject: EntitlementSubject;
+    /**
+     * Normalized decision, when resolver evaluation returned normally.
+     */
+    decision?: EntitlementDecision;
+    /**
+     * Error thrown by the resolver, when evaluation failed.
+     */
+    error?: unknown;
+    /**
+     * Resolver 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 entitlement decision or resolver
+ * error.
+ */
+export type EntitlementDecisionObserver<TContext = unknown, TKey extends EntitlementKey = EntitlementKey> = (observation: EntitlementDecisionObservation<TContext, TKey>) => MaybePromise<void>;
+/**
+ * Options for `createEntitlements(...)`.
+ */
+export type CreateEntitlementsOptions<TKey extends EntitlementKey = EntitlementKey, TContext = unknown> = {
+    /**
+     * Resolver that maps app-owned product state to an entitlement decision.
+     */
+    inspect: EntitlementResolver<TKey>;
+    /**
+     * Optional best-effort observer for entitlement decisions.
+     *
+     * This hook is diagnostic only: it cannot change decisions or thrown errors.
+     */
+    onDecision?: EntitlementDecisionObserver<TContext, TKey>;
+};
+/**
+ * Static grant map keyed by subject key.
+ */
+export type StaticEntitlementGrantMap<TKey extends EntitlementKey = EntitlementKey> = Record<string, readonly TKey[]>;
+/**
+ * Options for `createStaticEntitlements(...)`.
+ */
+export type CreateStaticEntitlementsOptions<TKey extends EntitlementKey = EntitlementKey, TContext = unknown> = {
+    /**
+     * Granted capabilities keyed by subject. The default key is
+     * `${subject.type}:${subject.id}`.
+     */
+    grants: StaticEntitlementGrantMap<TKey>;
+    /**
+     * Optional subject key mapper.
+     */
+    subjectKey?: (subject: EntitlementSubject) => string;
+    /**
+     * Default denial decision fields.
+     */
+    denied?: Omit<EntitlementDeniedDecision, "allowed">;
+    /**
+     * Optional best-effort observer for entitlement decisions.
+     */
+    onDecision?: EntitlementDecisionObserver<TContext, TKey>;
+};
+/**
+ * Options accepted by `requireEntitlement(...)`.
+ */
+export type RequireEntitlementOptions<TKey extends EntitlementKey = EntitlementKey> = {
+    /**
+     * Create the error to throw instead of the framework default.
+     */
+    error?: (decision: EntitlementDeniedDecision, input: EntitlementCheckInput<TKey>) => unknown;
+};
+/**
+ * Context shape consumed by `requireEntitlement(...)`.
+ */
+export type EntitlementsContext<TKey extends EntitlementKey = EntitlementKey> = {
+    ports: {
+        entitlements: EntitlementsPort<TKey>;
+    };
+};
+/**
+ * Error thrown by `requireEntitlement(...)` when product access is denied.
+ */
+export declare class EntitlementRequiredError extends Error {
+    readonly code: string;
+    readonly status = 403;
+    readonly details?: unknown;
+    readonly entitlement: string;
+    readonly subject: EntitlementSubject;
+    constructor(input: EntitlementCheckInput, decision?: EntitlementDeniedDecision);
+}
+/**
+ * Create an explicit allow decision.
+ */
+export declare function allowEntitlement(): EntitlementAllowedDecision;
+/**
+ * Create an explicit deny decision.
+ */
+export declare function denyEntitlement(reasonOrDecision?: string | Omit<EntitlementDeniedDecision, "allowed">): EntitlementDeniedDecision;
+/**
+ * Create an entitlement port from an app-owned resolver.
+ */
+export declare function createEntitlements<TKey extends EntitlementKey = EntitlementKey, TContext = unknown>(options: CreateEntitlementsOptions<TKey, TContext>): EntitlementsPort<TKey, TContext>;
+/**
+ * Create a static entitlement port for tests, starters, and simple apps.
+ */
+export declare function createStaticEntitlements<TKey extends EntitlementKey = EntitlementKey, TContext = unknown>(options: CreateStaticEntitlementsOptions<TKey, TContext>): EntitlementsPort<TKey, TContext>;
+/**
+ * Require an entitlement or throw a framework-owned 403 error.
+ */
+export declare function requireEntitlement<TKey extends EntitlementKey = EntitlementKey>(ctx: EntitlementsContext<TKey>, input: EntitlementCheckInput<TKey>, options?: RequireEntitlementOptions<TKey>): Promise<EntitlementAllowedDecision>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/entitlements/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/entitlements/index.ts"],"names":[],"mappings":"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"}

package/dist/entitlements/index.js

@@ -0,0 +1,172 @@
+/**
+ * @beignet/core/entitlements
+ *
+ * Provider-neutral product access primitives for Beignet applications.
+ */
+/**
+ * Error thrown by `requireEntitlement(...)` when product access is denied.
+ */
+export class EntitlementRequiredError extends Error {
+    code;
+    status = 403;
+    details;
+    entitlement;
+    subject;
+    constructor(input, decision = denyEntitlement()) {
+        super(decision.reason ??
+            `Entitlement "${input.entitlement}" is required for this action.`);
+        this.name = "EntitlementRequiredError";
+        this.code = decision.code ?? "ENTITLEMENT_REQUIRED";
+        this.details = decision.details;
+        this.entitlement = input.entitlement;
+        this.subject = input.subject;
+    }
+}
+/**
+ * Create an explicit allow decision.
+ */
+export function allowEntitlement() {
+    return { allowed: true };
+}
+/**
+ * Create an explicit deny decision.
+ */
+export function denyEntitlement(reasonOrDecision) {
+    if (typeof reasonOrDecision === "string") {
+        return { allowed: false, reason: reasonOrDecision };
+    }
+    return {
+        allowed: false,
+        ...reasonOrDecision,
+    };
+}
+/**
+ * Create an entitlement port from an app-owned resolver.
+ */
+export function createEntitlements(options) {
+    const observeDecision = createDecisionObserver(options.onDecision);
+    async function evaluate(input, checkOptions) {
+        const startedAt = entitlementNow();
+        try {
+            const decision = normalizeEntitlementDecision(await options.inspect(input));
+            observeDecision({
+                source: checkOptions?.source ?? "inspect",
+                ctx: checkOptions?.ctx,
+                entitlement: input.entitlement,
+                subject: input.subject,
+                decision,
+                durationMs: entitlementNow() - startedAt,
+            });
+            return decision;
+        }
+        catch (error) {
+            observeDecision({
+                source: checkOptions?.source ?? "inspect",
+                ctx: checkOptions?.ctx,
+                entitlement: input.entitlement,
+                subject: input.subject,
+                error,
+                durationMs: entitlementNow() - startedAt,
+            });
+            throw error;
+        }
+    }
+    return {
+        async can(input, checkOptions) {
+            return (await evaluate(input, { ...checkOptions, source: "can" }))
+                .allowed;
+        },
+        inspect(input, checkOptions) {
+            return evaluate(input, {
+                ...checkOptions,
+                source: checkOptions?.source ?? "inspect",
+            });
+        },
+    };
+}
+/**
+ * Create a static entitlement port for tests, starters, and simple apps.
+ */
+export function createStaticEntitlements(options) {
+    const subjectKey = options.subjectKey ?? defaultSubjectKey;
+    return createEntitlements({
+        inspect(input) {
+            const granted = options.grants[subjectKey(input.subject)] ?? [];
+            if (granted.includes(input.entitlement))
+                return allowEntitlement();
+            return denyEntitlement({
+                reason: `Entitlement "${input.entitlement}" is not granted.`,
+                code: "ENTITLEMENT_NOT_GRANTED",
+                details: {
+                    entitlement: input.entitlement,
+                    subject: input.subject,
+                },
+                ...options.denied,
+            });
+        },
+        onDecision: options.onDecision,
+    });
+}
+/**
+ * Require an entitlement or throw a framework-owned 403 error.
+ */
+export async function requireEntitlement(ctx, input, options) {
+    const decision = await ctx.ports.entitlements.inspect(input, {
+        ctx,
+        source: "require",
+    });
+    if (decision.allowed)
+        return decision;
+    throw options?.error
+        ? options.error(decision, input)
+        : new EntitlementRequiredError(input, decision);
+}
+function normalizeEntitlementDecision(result) {
+    if (typeof result === "boolean") {
+        return result ? allowEntitlement() : denyEntitlement();
+    }
+    return result;
+}
+function entitlementNow() {
+    return typeof performance !== "undefined" ? performance.now() : Date.now();
+}
+function contextStringField(ctx, field) {
+    if (!ctx || typeof ctx !== "object")
+        return undefined;
+    const value = ctx[field];
+    return typeof value === "string" ? value : undefined;
+}
+function enrichObservation(observation) {
+    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) {
+    return (value !== null &&
+        (typeof value === "object" || typeof value === "function") &&
+        typeof value.then === "function");
+}
+function createDecisionObserver(observer) {
+    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 entitlement checks.
+        }
+    };
+}
+function defaultSubjectKey(subject) {
+    return `${subject.type}:${subject.id}`;
+}
+//# sourceMappingURL=index.js.map

package/dist/entitlements/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/entitlements/index.ts"],"names":[],"mappings":"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"}