@warpgogol/werkstatt-shared 0.2.0

package/src/share/entitlement.ts

@@ -0,0 +1,172 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC-0169: the closed paid-feature catalog, the resolved-entitlements shape, and the
+isEntitled() reader. Stripe Entitlements is the source of truth; this module is the framework-
+agnostic contract consumed by the build-time resolver, the feature gates, and runtime endpoints.</purpose>
+<non-goals>
+  <item>Do not call Stripe here — the resolver command (site OS) performs network I/O and passes
+        the mapped lookup keys to resolveEntitlements().</item>
+  <item>Do not build a custom entitlements store — Stripe is the source of truth.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0169: initial implementation.</item>
+  <item>RFC-0706: add nachweis feature for Nachweisregister commercial module.</item>
+  <item>RFC-0741: add multi-currency feature for multi-currency build pipeline.</item>
+</CHANGE_SUMMARY>
+*/
+
+/** Closed catalog of paid features that can gate a site's compiled modules. */
+export const ENTITLED_FEATURES = [
+  "blog",
+  "integrations.channels",
+  "integrations.crm",
+  "integrations.chat",
+  "analytics",
+  "pseo",
+  "team.profiles",
+  // RFC-0240: Angebot modular productization
+  "offer",
+  "booking",
+  "trust",
+  "i18n-extra",
+  "automation",
+  // RFC-0288: Agent Surface action tier (AI-agent-invocable capabilities)
+  "agent.actions",
+  // RFC-0706 / ADR-0028: Nachweisregister commercial module
+  "nachweis",
+  // RFC-0741: multi-currency entitled feature
+  "multi-currency",
+] as const;
+
+export type EntitledFeature = (typeof ENTITLED_FEATURES)[number];
+
+/** Stripe Feature `lookup_key` → EntitledFeature. The single mapping point. */
+export const STRIPE_FEATURE_LOOKUP_MAP: Record<string, EntitledFeature> = {
+  feature_blog: "blog",
+  feature_integrations_channels: "integrations.channels",
+  feature_integrations_crm: "integrations.crm",
+  feature_integrations_chat: "integrations.chat",
+  feature_analytics: "analytics",
+  feature_pseo: "pseo",
+  feature_team_profiles: "team.profiles",
+  // RFC-0240
+  feature_offer: "offer",
+  feature_booking: "booking",
+  feature_trust: "trust",
+  feature_i18n_extra: "i18n-extra",
+  feature_automation: "automation",
+  // RFC-0288
+  feature_agent_actions: "agent.actions",
+  // RFC-0706
+  feature_nachweis: "nachweis",
+  // RFC-0741
+  feature_multi_currency: "multi-currency",
+};
+
+/**
+ * RFC-0196: Stripe Feature `lookup_key` → Programmatic Surface index budget (top-K indexable pages
+ * by substance). A site's tier is the highest budget among its active entitlement lookup-keys.
+ */
+export const PSEO_TIER_BUDGET: Record<string, number> = {
+  feature_pseo: 12, // base tier "Быть найденным" — ≈12 target pages
+  feature_pseo_regional: 500, // regional-hub upsell — unlocks d3–d4
+  feature_pseo_pro: 5000,
+  feature_pseo_scale: 50000,
+};
+
+/** RFC-0240: tiers that unlock the d3 (region) and d4 levels of the local family. */
+export const PSEO_REGIONAL_TIERS = [
+  "feature_pseo_regional",
+  "feature_pseo_pro",
+  "feature_pseo_scale",
+] as const;
+
+/** Resolve the index budget for a set of active Stripe lookup-keys (max tier; undefined ⇒ none). */
+export function resolvePseoBudget(lookupKeys: readonly string[]): number | undefined {
+  let budget: number | undefined;
+  for (const key of lookupKeys) {
+    const tier = PSEO_TIER_BUDGET[key];
+    if (tier !== undefined) budget = budget === undefined ? tier : Math.max(budget, tier);
+  }
+  return budget;
+}
+
+export type EntitlementSource = "stripe" | "override" | "none";
+
+/** The generated, content-driven feature set written by `entitlements.resolve`. */
+export interface ResolvedEntitlements {
+  customerId: string | null;
+  features: EntitledFeature[];
+  source: EntitlementSource;
+  /**
+   * RFC-0196: Programmatic Surface tier. `indexBudget` caps the number of indexable generated
+   * pages (top-K by substance score); absent ⇒ unbounded (fail-open). Set by the tier mapping.
+   */
+  pseo?: {
+    indexBudget?: number;
+    /** RFC-0240: whether the resolved tier is the regional-hub tier or higher (unlocks d3–d4). */
+    regionalUnlocked?: boolean;
+  };
+}
+
+export function isValidFeature(value: string): value is EntitledFeature {
+  return (ENTITLED_FEATURES as readonly string[]).includes(value);
+}
+
+/**
+ * Pure resolver. The site-OS command performs the Stripe network call and passes the
+ * mapped lookup keys as `stripeFeatures`; an offline `override` wins for dev/CI.
+ */
+export function resolveEntitlements(input: {
+  customerId: string | null;
+  override?: string[];
+  stripeFeatures?: string[];
+  /** RFC-0196: optional Programmatic Surface index budget (tier-derived). */
+  pseoIndexBudget?: number;
+  /**
+   * RFC-0240: explicit regional-hub-or-higher unlock for offline/override mode, where no Stripe
+   * lookup key is available to derive it from.
+   */
+  pseoRegionalUnlocked?: boolean;
+  /** RFC-0240: raw Stripe lookup keys (Stripe mode only) — used to derive the regional-tier unlock. */
+  stripeLookupKeys?: string[];
+}): ResolvedEntitlements {
+  const dedupe = (values: string[]): EntitledFeature[] =>
+    Array.from(new Set(values.filter(isValidFeature)));
+  const regionalUnlocked =
+    input.pseoRegionalUnlocked ??
+    (input.stripeLookupKeys ?? []).some((key) =>
+      (PSEO_REGIONAL_TIERS as readonly string[]).includes(key),
+    );
+  const pseo =
+    typeof input.pseoIndexBudget === "number" || regionalUnlocked
+      ? { pseo: { indexBudget: input.pseoIndexBudget, regionalUnlocked } }
+      : {};
+
+  if (input.override && input.override.length > 0) {
+    return {
+      customerId: input.customerId,
+      features: dedupe(input.override),
+      source: "override",
+      ...pseo,
+    };
+  }
+  if (input.stripeFeatures) {
+    return {
+      customerId: input.customerId,
+      features: dedupe(input.stripeFeatures),
+      source: "stripe",
+      ...pseo,
+    };
+  }
+  return { customerId: input.customerId, features: [], source: "none", ...pseo };
+}
+
+/** Reader used by build gates (which modules compile) and runtime endpoints. */
+export function isEntitled(
+  resolved: ResolvedEntitlements | null | undefined,
+  feature: EntitledFeature,
+): boolean {
+  return !!resolved?.features.includes(feature);
+}

package/src/share/env.d.ts

@@ -0,0 +1,73 @@
+/***********************************************
+<MODULE_CONTRACT>
+<purpose>Defines type declarations for middleware and content management in the Astro framework.</purpose>
+<non-goals>
+  <item>Do not implement middleware logic or content retrieval.</item>
+  <item>Do not handle raw data parsing or transformation.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Tidied by compass.changesummary.tidy; see git history for prior entries.</item>
+</CHANGE_SUMMARY>
+***********************************************/
+
+/// <reference types="astro/client" />
+declare module "astro:middleware" {
+  export function defineMiddleware(fn: any): any;
+  export function sequence(...middlewares: any[]): any;
+}
+declare module "astro:content" {
+  export function getEntry(collection: string, id: string): Promise<any>;
+  export function getCollection(collection: string, filter?: any): Promise<any[]>;
+}
+// Ambient shim for the per-app GENERATED env schema (api.routes.generate writes the
+// real schema into apps/*/src/env.schema.generated.mjs). In the package-typecheck
+// context there is no app schema, so we declare the secret names the section API
+// handlers import. Keep in sync with the Integration Port secret catalog
+// (@warpgogol/werkstatt-site/integration) + section `api[].secrets`. All optional — a missing
+// value degrades to the handler's error path, never a build/runtime throw.
+declare module "astro:env/server" {
+  // RFC-0168 Integration Port — channels + CRM (send-message handler).
+  export const INTEGRATION_TELEGRAM_BOT_TOKEN: string | undefined;
+  export const INTEGRATION_TELEGRAM_CHAT_ID: string | undefined;
+  // RFC-0181: email is sent via Cloudflare Email Routing (no Resend API key). TO is a
+  // verified destination address; FROM a verified sender on the zone domain.
+  export const INTEGRATION_EMAIL_TO: string | undefined;
+  export const INTEGRATION_EMAIL_FROM: string | undefined;
+  export const INTEGRATION_WHATSAPP_TOKEN: string | undefined;
+  export const INTEGRATION_WHATSAPP_PHONE_ID: string | undefined;
+  export const INTEGRATION_WHATSAPP_TO: string | undefined;
+  export const INTEGRATION_PIPEDRIVE_API_TOKEN: string | undefined;
+  export const INTEGRATION_PIPEDRIVE_DOMAIN: string | undefined;
+  // RFC-0176 inbound hub (chat-widget inbound handler).
+  export const INTEGRATION_INBOUND_SECRET: string | undefined;
+  // RFC-0181 EU-resident delivery — Upstash QStash + Redis (eu-central-1).
+  export const UPSTASH_QSTASH_URL: string | undefined;
+  export const UPSTASH_QSTASH_TOKEN: string | undefined;
+  export const UPSTASH_QSTASH_CURRENT_SIGNING_KEY: string | undefined;
+  export const UPSTASH_QSTASH_NEXT_SIGNING_KEY: string | undefined;
+  export const UPSTASH_REDIS_REST_URL: string | undefined;
+  export const UPSTASH_REDIS_REST_TOKEN: string | undefined;
+  // Lagebild MVP: Supabase CRM buffer (self-enabling — adapter skips when absent).
+  export const SUPABASE_BUFFER_URL: string | undefined;
+  export const SUPABASE_BUFFER_SERVICE_KEY: string | undefined;
+  export const SUPABASE_BUFFER_TENANT_ID: string | undefined;
+  // RFC-0191: Stripe billing — the webhook signing secret (stripe-webhook route) and the
+  // server API key (billing client). Per-tenant; self-enabling — handlers fail-closed when absent.
+  export const STRIPE_WEBHOOK_SECRET: string | undefined;
+  export const STRIPE_SECRET_KEY: string | undefined;
+}
+
+// RFC-0176/0181: Cloudflare Workers runtime bindings. Astro v6 removed
+// Astro.locals.runtime.env — handlers read bindings from this global instead.
+// RFC-0181 uses the send_email binding for Cloudflare Email Routing.
+declare module "cloudflare:workers" {
+  export const env: Record<string, unknown>;
+}
+
+// RFC-0181: Cloudflare Email Routing message type (send_email binding).
+declare module "cloudflare:email" {
+  export class EmailMessage {
+    constructor(from: string, to: string, raw: string);
+  }
+}

package/src/share/feature-policy.ts

@@ -0,0 +1,367 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Runtime resolver for RFC-0183 Feature Policy embedded in RFC-0047 content domains.</purpose>
+<non-goals>
+  <item>Do not import from astro:content or other framework-specific modules.</item>
+  <item>Do not modify content files.</item>
+  <item>Do not handle remote feature flag services.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0183: Initial runtime resolver for Feature Policy without Feature Graph dependency.</item>
+  <item>Removed false async from resolveFeaturePolicy; resolveFeaturePolicySync is now a thin alias.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type {
+  FeaturePolicy,
+  FeaturePolicyBehaviorValue,
+  FeaturePolicyTargetRef,
+  FeaturePolicyVisibility,
+  ResolvedFeaturePolicy,
+} from "./schemas/features.ts";
+
+// Re-export types for consumers
+export type {
+  FeaturePolicy,
+  FeaturePolicyBehaviorValue,
+  FeaturePolicyTargetKind,
+  FeaturePolicyTargetRef,
+  FeaturePolicyVisibility,
+  ResolvedFeaturePolicy,
+} from "./schemas/features.ts";
+
+export interface FeaturePolicyResolverOptions {
+  /**
+   * Default language code for policy resolution when localized policy absent.
+   */
+  defaultLanguage?: string;
+  /**
+   * Whether to cache resolved policy. Default true.
+   */
+  cache?: boolean;
+  /**
+   * Platform default visibility when no policy found anywhere.
+   * RFC-0183 default is "enabled".
+   */
+  platformDefaultVisibility?: FeaturePolicyVisibility;
+}
+
+/**
+ * Narrow interface for content nodes that may carry policy.
+ * Resolver works with any object matching this shape, allowing
+ * framework-neutral resolution from Astro content, plain objects, etc.
+ */
+export interface PolicyCarryingNode {
+  id?: string;
+  policy?: FeaturePolicy;
+  blocks?: PolicyCarryingNode[];
+  items?: PolicyCarryingNode[];
+  components?: PolicyCarryingNode[];
+  [key: string]: unknown;
+}
+
+/**
+ * Content context passed to resolver.
+ * Contains already-loaded content from RFC-0047 domains.
+ */
+export interface FeaturePolicyContentContext {
+  /** Site-level policy defaults from system.md */
+  systemPolicy?: FeaturePolicy;
+  /** Site-level defaults from site/{lang}/config or similar */
+  siteDefaults?: FeaturePolicy;
+  /** Current page content node */
+  page?: PolicyCarryingNode;
+  /** Current language */
+  lang?: string;
+  /** Default language for fallback */
+  defaultLanguage?: string;
+}
+
+// Resolution is pure given (context, target, lang, platformDefault). The cache is
+// therefore scoped to the content CONTEXT — a WeakMap keyed by context identity — so two
+// different contexts never share resolved policy for the same target+lang.
+// Bug history (RFC-0183): a module-global array keyed by target+lang ALONE silently
+// returned one context's result for another, clobbering page-level policy. Do not
+// reintroduce a context-agnostic global cache.
+const MAX_CACHE_SIZE = 100;
+let contextCaches = new WeakMap<FeaturePolicyContentContext, Map<string, ResolvedFeaturePolicy>>();
+
+function getCacheKey(
+  target: FeaturePolicyTargetRef,
+  lang: string,
+  platformDefault: FeaturePolicyVisibility,
+): string {
+  const parts = [target.kind, lang, `d:${platformDefault}`];
+  if (target.pageId) parts.push(`p:${target.pageId}`);
+  if (target.blockId) parts.push(`b:${target.blockId}`);
+  if (target.componentId) parts.push(`c:${target.componentId}`);
+  if (target.itemId) parts.push(`i:${target.itemId}`);
+  return parts.join("|");
+}
+
+function getCached(
+  context: FeaturePolicyContentContext,
+  key: string,
+): ResolvedFeaturePolicy | undefined {
+  return contextCaches.get(context)?.get(key);
+}
+
+function setCached(
+  context: FeaturePolicyContentContext,
+  key: string,
+  result: ResolvedFeaturePolicy,
+): void {
+  let cache = contextCaches.get(context);
+  if (!cache) {
+    cache = new Map();
+    contextCaches.set(context, cache);
+  }
+  // Evict oldest (Map preserves insertion order) when at capacity.
+  if (cache.size >= MAX_CACHE_SIZE) {
+    const oldest = cache.keys().next().value;
+    if (oldest !== undefined) cache.delete(oldest);
+  }
+  cache.set(key, result);
+}
+
+/** Drops all cached resolutions. Per-context caches are also GC'd with their context. */
+export function clearFeaturePolicyCache(): void {
+  contextCaches = new WeakMap();
+}
+
+/**
+ * Search for policy in a node tree by id path.
+ * Handles nested structures: page → blocks → components → items.
+ */
+function findPolicyInNode(
+  node: PolicyCarryingNode,
+  target: FeaturePolicyTargetRef,
+): FeaturePolicy | null {
+  // Direct match on current node
+  if (
+    (target.blockId && node.id === target.blockId) ||
+    (target.componentId && node.id === target.componentId) ||
+    (target.itemId && node.id === target.itemId)
+  ) {
+    return node.policy ?? null;
+  }
+
+  // Search in blocks
+  if (target.blockId && node.blocks) {
+    for (const block of node.blocks) {
+      if (block.id === target.blockId) {
+        // If looking for nested component/item within this block
+        if (target.componentId && block.components) {
+          const comp = block.components.find((c) => c.id === target.componentId);
+          if (comp) {
+            if (target.itemId && comp.items) {
+              const item = comp.items.find((i) => i.id === target.itemId);
+              if (item?.policy) return item.policy;
+            }
+            return comp.policy ?? null;
+          }
+        }
+        return block.policy ?? null;
+      }
+      // Deep search if not matched by id
+      const deep = findPolicyInNode(block, target);
+      if (deep) return deep;
+    }
+  }
+
+  // Search in items (for shared components)
+  if (target.itemId && node.items) {
+    const item = node.items.find((i) => i.id === target.itemId);
+    if (item?.policy) return item.policy;
+  }
+
+  // Search in components
+  if (target.componentId && node.components) {
+    const comp = node.components.find((c) => c.id === target.componentId);
+    if (comp) {
+      if (target.itemId && comp.items) {
+        const item = comp.items.find((i) => i.id === target.itemId);
+        if (item?.policy) return item.policy;
+      }
+      return comp.policy ?? null;
+    }
+  }
+
+  // Recursive search in any nested structure
+  const nestedArrays = [node.blocks, node.components, node.items].filter(Boolean);
+  for (const arr of nestedArrays) {
+    for (const child of arr ?? []) {
+      const found = findPolicyInNode(child, target);
+      if (found) return found;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * RFC-0183 resolution order:
+ * 1. Explicit policy on content node
+ * 2. Page-level policy (via page content context)
+ * 3. System-level policy for matching ids
+ * 4. Site-level defaults
+ * 5. Platform default: visibility=enabled, empty behavior
+ */
+function resolvePolicyInternal(
+  target: FeaturePolicyTargetRef,
+  context: FeaturePolicyContentContext,
+  platformDefault: FeaturePolicyVisibility,
+): ResolvedFeaturePolicy {
+  const lang = target.lang ?? context.lang;
+  const defaultLang = context.defaultLanguage;
+  if (!lang || !defaultLang) {
+    throw new Error("[feature-policy] lang and defaultLanguage are required.");
+  }
+
+  // 1. Try explicit node policy via page context
+  let foundPolicy: FeaturePolicy | null = null;
+  let inheritedFrom: FeaturePolicyTargetRef | undefined;
+
+  if (context.page) {
+    foundPolicy = findPolicyInNode(context.page, target);
+    if (foundPolicy) {
+      inheritedFrom = { ...target, lang };
+    }
+  }
+
+  // 2. Try system-level policy if id-based lookup exists there
+  // (System policy stored as flat record keyed by "page:home/block:hero")
+  if (!foundPolicy && context.systemPolicy) {
+    const systemKey = buildSystemKey(target);
+    if (systemKey && (context.systemPolicy as Record<string, FeaturePolicy>)[systemKey]) {
+      foundPolicy = (context.systemPolicy as Record<string, FeaturePolicy>)[systemKey];
+      inheritedFrom = { kind: "page" as const, lang: defaultLang }; // system is lang-agnostic
+    }
+  }
+
+  // 3. Site-level defaults
+  if (!foundPolicy && context.siteDefaults) {
+    foundPolicy = context.siteDefaults;
+    inheritedFrom = { kind: "page" as const, lang: defaultLang };
+  }
+
+  // 4. Build resolved result with defaults
+  const resolved: ResolvedFeaturePolicy = {
+    target,
+    visibility: foundPolicy?.visibility ?? platformDefault,
+    behavior: foundPolicy?.behavior ?? {},
+    sourcePath: buildSourcePath(foundPolicy, inheritedFrom),
+    inheritedFrom,
+  };
+
+  return resolved;
+}
+
+function buildSystemKey(target: FeaturePolicyTargetRef): string | null {
+  const parts: string[] = [];
+  if (target.pageId) parts.push(`page:${target.pageId}`);
+  if (target.blockId) parts.push(`block:${target.blockId}`);
+  if (target.componentId) parts.push(`component:${target.componentId}`);
+  if (target.itemId) parts.push(`item:${target.itemId}`);
+  return parts.length > 0 ? parts.join("/") : null;
+}
+
+function buildSourcePath(policy: FeaturePolicy | null, inherited?: FeaturePolicyTargetRef): string {
+  if (!policy) return "platform-default";
+  if (inherited) {
+    const parts: string[] = [inherited.kind];
+    if (inherited.pageId) parts.push(inherited.pageId);
+    if (inherited.blockId) parts.push(inherited.blockId);
+    if (inherited.componentId) parts.push(inherited.componentId);
+    if (inherited.itemId) parts.push(inherited.itemId);
+    return parts.join("/");
+  }
+  return "node-explicit";
+}
+
+/**
+ * Resolve feature policy for a target.
+ * Resolution is synchronous given loaded content context.
+ * Kept as the canonical name; resolveFeaturePolicySync is an alias.
+ */
+export function resolveFeaturePolicy(
+  target: FeaturePolicyTargetRef,
+  context: FeaturePolicyContentContext,
+  options: FeaturePolicyResolverOptions = {},
+): ResolvedFeaturePolicy {
+  const { cache = true, platformDefaultVisibility = "enabled" } = options;
+  const lang = target.lang ?? context.lang;
+  if (!lang) {
+    throw new Error("[feature-policy] lang is required.");
+  }
+
+  if (cache) {
+    const key = getCacheKey(target, lang, platformDefaultVisibility);
+    const cached = getCached(context, key);
+    if (cached) return cached;
+
+    const result = resolvePolicyInternal(target, context, platformDefaultVisibility);
+    setCached(context, key, result);
+    return result;
+  }
+
+  return resolvePolicyInternal(target, context, platformDefaultVisibility);
+}
+
+/**
+ * Alias for resolveFeaturePolicy (kept for call sites that explicitly want the
+ * synchronous signature). Resolution was always synchronous.
+ */
+export function resolveFeaturePolicySync(
+  target: FeaturePolicyTargetRef,
+  context: FeaturePolicyContentContext,
+  options: FeaturePolicyResolverOptions = {},
+): ResolvedFeaturePolicy {
+  return resolveFeaturePolicy(target, context, options);
+}
+
+/**
+ * Factory for creating a configured resolver bound to specific content context.
+ */
+export function createFeaturePolicyResolver(
+  context: FeaturePolicyContentContext,
+  options: FeaturePolicyResolverOptions = {},
+) {
+  return {
+    resolve: (target: FeaturePolicyTargetRef) => resolveFeaturePolicy(target, context, options),
+    resolveSync: (target: FeaturePolicyTargetRef) =>
+      resolveFeaturePolicySync(target, context, options),
+    isEnabled: (target: FeaturePolicyTargetRef) =>
+      isPolicyEnabled(resolveFeaturePolicySync(target, context, options)),
+    getBehavior: (
+      target: FeaturePolicyTargetRef,
+      key: string,
+      defaultValue?: FeaturePolicyBehaviorValue,
+    ) => getPolicyBehavior(resolveFeaturePolicySync(target, context, options), key, defaultValue),
+  };
+}
+
+/**
+ * Predicate: is the resolved policy effectively enabled?
+ * Treats "enabled" as true, "disabled"/"hidden" as false, "draft" depends on environment.
+ */
+export function isPolicyEnabled(policy: ResolvedFeaturePolicy, isDraftAllowed = false): boolean {
+  if (policy.visibility === "enabled") return true;
+  if (policy.visibility === "disabled" || policy.visibility === "hidden") return false;
+  if (policy.visibility === "draft") return isDraftAllowed;
+  return true; // unknown defaults to enabled per RFC-0183
+}
+
+/**
+ * Extract behavior value with optional default.
+ */
+export function getPolicyBehavior(
+  policy: ResolvedFeaturePolicy,
+  key: string,
+  defaultValue?: FeaturePolicyBehaviorValue,
+): FeaturePolicyBehaviorValue {
+  const value = policy.behavior[key];
+  if (value === undefined) return defaultValue ?? null;
+  return value as FeaturePolicyBehaviorValue;
+}