@happyvertical/smrt-subscriptions 0.30.0

package/dist/index.js

@@ -0,0 +1,1271 @@
+import { ObjectRegistry, smrt, SmrtObject, SmrtCollection, foreignKey } from "@happyvertical/smrt-core";
+import { tenantId, TenantScoped } from "@happyvertical/smrt-tenancy";
+ObjectRegistry.registerPackageManifest(
+  new URL("./manifest.json", import.meta.url)
+);
+const THRESHOLD_WINDOWS = [
+  "day",
+  "week",
+  "month",
+  "year",
+  "rolling"
+];
+const THRESHOLD_ENFORCEMENTS = [
+  "observe",
+  "warn",
+  "block"
+];
+function parseJsonArray(value, fallback = []) {
+  if (!value) {
+    return fallback;
+  }
+  try {
+    const parsed = JSON.parse(value);
+    return Array.isArray(parsed) ? parsed : fallback;
+  } catch {
+    return fallback;
+  }
+}
+function parseJsonObject(value, fallback) {
+  if (!value) {
+    return fallback;
+  }
+  try {
+    const parsed = JSON.parse(value);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : fallback;
+  } catch {
+    return fallback;
+  }
+}
+function stringifyJson(value) {
+  return JSON.stringify(value ?? null);
+}
+function normalizeFeatureGrants(grants) {
+  return grants.map(
+    (grant) => typeof grant === "string" ? { featureKey: grant, enabled: true } : grant
+  );
+}
+function normalizeSubscriber(input) {
+  const rawExternalId = input.subscriberExternalId;
+  const externalIdAbsent = rawExternalId === null || rawExternalId === void 0;
+  const externalId = externalIdAbsent ? "" : String(rawExternalId);
+  const rawKind = input.subscriberKind;
+  const kind = rawKind === null || rawKind === void 0 ? "tenant" : rawKind;
+  if (kind !== "tenant" && kind !== "external") {
+    throw new Error(
+      `subscriberKind must be "tenant" or "external" (got ${JSON.stringify(rawKind)})`
+    );
+  }
+  if (kind === "tenant") {
+    if (externalId !== "") {
+      throw new Error(
+        'subscriberExternalId is set but subscriberKind is "tenant"; set subscriberKind="external" explicitly or omit subscriberExternalId'
+      );
+    }
+    return { kind: "tenant", tenantId: input.tenantId };
+  }
+  if (externalId === "") {
+    throw new Error(
+      'subscriberKind="external" requires a non-empty subscriberExternalId'
+    );
+  }
+  return {
+    kind: "external",
+    tenantId: input.tenantId,
+    externalId
+  };
+}
+function subscriberToColumns(subscriber) {
+  if (subscriber.kind === "tenant") {
+    return {
+      tenantId: subscriber.tenantId,
+      subscriberKind: "tenant",
+      subscriberExternalId: ""
+    };
+  }
+  return {
+    tenantId: subscriber.tenantId,
+    subscriberKind: "external",
+    subscriberExternalId: subscriber.externalId
+  };
+}
+function assertSubscriberInvariant(modelName, fields) {
+  if (fields.subscriberKind !== "tenant" && fields.subscriberKind !== "external") {
+    throw new Error(
+      `${modelName}: subscriberKind must be "tenant" or "external" (got ${describe(
+        fields.subscriberKind
+      )})`
+    );
+  }
+  if (typeof fields.subscriberExternalId !== "string") {
+    throw new Error(
+      `${modelName}: subscriberExternalId must be a string (got ${describe(
+        fields.subscriberExternalId
+      )})`
+    );
+  }
+  if (fields.subscriberKind === "tenant" && fields.subscriberExternalId !== "") {
+    throw new Error(
+      `${modelName}: subscriberExternalId must be empty when subscriberKind is "tenant"`
+    );
+  }
+  if (fields.subscriberKind === "external" && fields.subscriberExternalId === "") {
+    throw new Error(
+      `${modelName}: subscriberKind="external" requires a non-empty subscriberExternalId`
+    );
+  }
+}
+function describe(value) {
+  if (value === null) return "null";
+  if (value === void 0) return "undefined";
+  if (typeof value === "string") return `"${value}"`;
+  return String(value);
+}
+function getWindowForThreshold(thresholdWindow, now = /* @__PURE__ */ new Date()) {
+  switch (thresholdWindow) {
+    case "day":
+      return utcWindow(now, "day");
+    case "week":
+      return utcWindow(now, "week");
+    case "month":
+      return utcWindow(now, "month");
+    case "year":
+      return utcWindow(now, "year");
+    case "rolling":
+      return {
+        start: new Date(now.getTime() - 30 * 24 * 60 * 60 * 1e3),
+        end: now
+      };
+  }
+}
+function getWindowKey(window) {
+  return `${window.start.toISOString()}..${window.end.toISOString()}`;
+}
+function isValidThreshold(threshold) {
+  return typeof threshold.metricKey === "string" && threshold.metricKey.length > 0 && Number.isFinite(threshold.limit) && threshold.limit >= 0 && isThresholdWindow(threshold.window) && isThresholdEnforcement(threshold.enforcement) && (threshold.warningRatio === void 0 || Number.isFinite(threshold.warningRatio) && threshold.warningRatio >= 0 && threshold.warningRatio <= 1);
+}
+function isThresholdWindow(value) {
+  return typeof value === "string" && THRESHOLD_WINDOWS.includes(value);
+}
+function isThresholdEnforcement(value) {
+  return typeof value === "string" && THRESHOLD_ENFORCEMENTS.includes(value);
+}
+function utcWindow(now, unit) {
+  const start = new Date(
+    Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate())
+  );
+  if (unit === "week") {
+    const day = start.getUTCDay();
+    const mondayOffset = day === 0 ? -6 : 1 - day;
+    start.setUTCDate(start.getUTCDate() + mondayOffset);
+  }
+  if (unit === "month") {
+    start.setUTCDate(1);
+  }
+  if (unit === "year") {
+    start.setUTCMonth(0, 1);
+  }
+  const end = new Date(start);
+  switch (unit) {
+    case "day":
+      end.setUTCDate(end.getUTCDate() + 1);
+      break;
+    case "week":
+      end.setUTCDate(end.getUTCDate() + 7);
+      break;
+    case "month":
+      end.setUTCMonth(end.getUTCMonth() + 1);
+      break;
+    case "year":
+      end.setUTCFullYear(end.getUTCFullYear() + 1);
+      break;
+  }
+  return { start, end };
+}
+var __defProp$2 = Object.defineProperty;
+var __getOwnPropDesc$2 = Object.getOwnPropertyDescriptor;
+var __decorateClass$2 = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$2(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp$2(target, key, result);
+  return result;
+};
+let SubscriptionPlan = class extends SmrtObject {
+  tenantId = null;
+  planKey = "";
+  name = "";
+  description = "";
+  status = "active";
+  sortOrder = 0;
+  priceAmount = 0;
+  currency = "USD";
+  billingInterval = "month";
+  externalProvider = "stripe";
+  stripeProductId = "";
+  stripePriceId = "";
+  features = "[]";
+  thresholds = "[]";
+  metadata = "{}";
+  constructor(options = {}) {
+    super(options);
+    if (options.tenantId !== void 0) this.tenantId = options.tenantId;
+    if (options.planKey !== void 0) this.planKey = options.planKey;
+    if (options.name !== void 0) this.name = options.name;
+    if (options.description !== void 0)
+      this.description = options.description;
+    if (options.status !== void 0) this.status = options.status;
+    if (options.sortOrder !== void 0) this.sortOrder = options.sortOrder;
+    if (options.priceAmount !== void 0)
+      this.priceAmount = options.priceAmount;
+    if (options.currency !== void 0) this.currency = options.currency;
+    if (options.billingInterval !== void 0) {
+      this.billingInterval = options.billingInterval;
+    }
+    if (options.externalProvider !== void 0) {
+      this.externalProvider = options.externalProvider;
+    }
+    if (options.stripeProductId !== void 0) {
+      this.stripeProductId = options.stripeProductId;
+    }
+    if (options.stripePriceId !== void 0) {
+      this.stripePriceId = options.stripePriceId;
+    }
+    if (options.features !== void 0) this.features = options.features;
+    if (options.thresholds !== void 0) this.thresholds = options.thresholds;
+    if (options.metadata !== void 0) this.metadata = options.metadata;
+  }
+  isActive() {
+    return this.status === "active";
+  }
+  getFeatureGrants() {
+    return normalizeFeatureGrants(
+      parseJsonArray(this.features)
+    );
+  }
+  setFeatureGrants(grants) {
+    this.features = stringifyJson(normalizeFeatureGrants(grants));
+  }
+  getFeatureKeys() {
+    return this.getFeatureGrants().filter((grant) => grant.enabled !== false).map((grant) => grant.featureKey);
+  }
+  getThresholds() {
+    return parseJsonArray(this.thresholds).filter(
+      (threshold) => threshold.metricKey
+    );
+  }
+  setThresholds(thresholds) {
+    this.thresholds = stringifyJson(thresholds);
+  }
+  getMetadata() {
+    return parseJsonObject(this.metadata, {});
+  }
+  setMetadata(metadata) {
+    this.metadata = stringifyJson(metadata);
+  }
+};
+__decorateClass$2([
+  tenantId({ nullable: true })
+], SubscriptionPlan.prototype, "tenantId", 2);
+SubscriptionPlan = __decorateClass$2([
+  TenantScoped({ mode: "optional" }),
+  smrt({
+    tableName: "_smrt_subscription_plans",
+    api: { include: ["list", "get", "create", "update"] },
+    cli: true,
+    mcp: { include: ["list", "get"] },
+    conflictColumns: ["plan_key"]
+  })
+], SubscriptionPlan);
+class SubscriptionPlanCollection extends SmrtCollection {
+  static _itemClass = SubscriptionPlan;
+  async findByPlanKey(planKey) {
+    const plans = await this.list({ where: { planKey }, limit: 1 });
+    return plans[0] ?? null;
+  }
+  async findActive() {
+    return this.list({
+      where: { status: "active" },
+      orderBy: "sortOrder ASC"
+    });
+  }
+  async findByStripePriceId(stripePriceId) {
+    const plans = await this.list({ where: { stripePriceId }, limit: 1 });
+    return plans[0] ?? null;
+  }
+}
+var __defProp$1 = Object.defineProperty;
+var __getOwnPropDesc$1 = Object.getOwnPropertyDescriptor;
+var __decorateClass$1 = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$1(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp$1(target, key, result);
+  return result;
+};
+let TenantSubscription = class extends SmrtObject {
+  tenantId;
+  /**
+   * Discriminator for the subscriber identity.
+   *
+   * - `'tenant'` (default): the subscriber IS the owning `tenantId` — the
+   *   pre-polymorphic shape. All existing rows continue to behave this way.
+   * - `'external'`: the subscriber is `subscriberExternalId`, scoped under the
+   *   issuing `tenantId`. Used for B2C buyers, anonymous-email subscribers,
+   *   agent identities, and any other caller-defined identity.
+   */
+  subscriberKind = "tenant";
+  /**
+   * Caller-namespaced opaque identifier for the subscriber when
+   * `subscriberKind === 'external'`. Empty string when kind is `'tenant'`.
+   *
+   * The package treats this as opaque — no FK, no inferred semantics. Callers
+   * are expected to namespace (e.g. `buyer-contact:abc123`,
+   * `agent:hermes-7`, `email:foo@example.com`).
+   */
+  subscriberExternalId = "";
+  planId = "";
+  status = "incomplete";
+  startedAt = /* @__PURE__ */ new Date();
+  currentPeriodStart = null;
+  currentPeriodEnd = null;
+  trialEndsAt = null;
+  cancelAtPeriodEnd = false;
+  canceledAt = null;
+  externalProvider = "stripe";
+  stripeCustomerId = "";
+  stripeSubscriptionId = "";
+  stripeCheckoutSessionId = "";
+  metadata = "{}";
+  constructor(options = {}) {
+    super(options);
+    if (options.tenantId !== void 0) this.tenantId = options.tenantId;
+    if (options.subscriberKind !== void 0)
+      this.subscriberKind = options.subscriberKind;
+    if (options.subscriberExternalId !== void 0)
+      this.subscriberExternalId = options.subscriberExternalId;
+    assertSubscriberInvariant("TenantSubscription", {
+      subscriberKind: this.subscriberKind,
+      subscriberExternalId: this.subscriberExternalId
+    });
+    if (options.planId !== void 0) this.planId = options.planId;
+    if (options.status !== void 0) this.status = options.status;
+    if (options.startedAt !== void 0) this.startedAt = options.startedAt;
+    if (options.currentPeriodStart !== void 0) {
+      this.currentPeriodStart = options.currentPeriodStart;
+    }
+    if (options.currentPeriodEnd !== void 0) {
+      this.currentPeriodEnd = options.currentPeriodEnd;
+    }
+    if (options.trialEndsAt !== void 0)
+      this.trialEndsAt = options.trialEndsAt;
+    if (options.cancelAtPeriodEnd !== void 0) {
+      this.cancelAtPeriodEnd = options.cancelAtPeriodEnd;
+    }
+    if (options.canceledAt !== void 0) this.canceledAt = options.canceledAt;
+    if (options.externalProvider !== void 0) {
+      this.externalProvider = options.externalProvider;
+    }
+    if (options.stripeCustomerId !== void 0) {
+      this.stripeCustomerId = options.stripeCustomerId;
+    }
+    if (options.stripeSubscriptionId !== void 0) {
+      this.stripeSubscriptionId = options.stripeSubscriptionId;
+    }
+    if (options.stripeCheckoutSessionId !== void 0) {
+      this.stripeCheckoutSessionId = options.stripeCheckoutSessionId;
+    }
+    if (options.metadata !== void 0) this.metadata = options.metadata;
+  }
+  /**
+   * Validates the subscriber XOR invariant before every save. Critical for the
+   * generated update path: `SmrtCollection.update()` mutates the existing
+   * instance via `Object.assign()` and calls `save()` directly — the
+   * constructor never re-runs, so without this hook a partial update like
+   * `{ subscriberExternalId: 'buyer:alice' }` on a tenant-kind row would
+   * persist a malformed conflict key and let two tenant-kind rows coexist
+   * under the same tenant.
+   */
+  async validateBeforeSave() {
+    await super.validateBeforeSave();
+    assertSubscriberInvariant("TenantSubscription", {
+      subscriberKind: this.subscriberKind,
+      subscriberExternalId: this.subscriberExternalId
+    });
+  }
+  isEntitled(now = /* @__PURE__ */ new Date()) {
+    if (this.status !== "active" && this.status !== "trialing") {
+      return false;
+    }
+    if (this.currentPeriodEnd && this.currentPeriodEnd.getTime() < now.getTime()) {
+      return false;
+    }
+    return true;
+  }
+  /**
+   * Project this row's polymorphic subscriber columns onto the
+   * {@link Subscriber} discriminated union. Returns `null` when the owning
+   * tenant is absent — that's an invalid row that should not be acted on.
+   */
+  getSubscriber() {
+    if (!this.tenantId) {
+      return null;
+    }
+    if (this.subscriberKind === "external") {
+      if (!this.subscriberExternalId) {
+        return null;
+      }
+      return {
+        kind: "external",
+        tenantId: this.tenantId,
+        externalId: this.subscriberExternalId
+      };
+    }
+    return { kind: "tenant", tenantId: this.tenantId };
+  }
+  getMetadata() {
+    return parseJsonObject(this.metadata, {});
+  }
+  setMetadata(metadata) {
+    this.metadata = stringifyJson(metadata);
+  }
+};
+__decorateClass$1([
+  tenantId()
+], TenantSubscription.prototype, "tenantId", 2);
+__decorateClass$1([
+  foreignKey("SubscriptionPlan")
+], TenantSubscription.prototype, "planId", 2);
+TenantSubscription = __decorateClass$1([
+  TenantScoped({ mode: "required" }),
+  smrt({
+    tableName: "_smrt_tenant_subscriptions",
+    api: { include: ["list", "get", "create", "update"] },
+    cli: true,
+    mcp: { include: ["list", "get"] },
+    // The conflict key includes the subscriber discriminator so an issuing tenant
+    // can host many distinct external subscribers without collisions on the
+    // unique index:
+    //   - tenant-kind rows always have subscriber_external_id = '' → uniqueness
+    //     reduces to (tenant_id, 'tenant', '') = at most one tenant-kind row per
+    //     tenant (preserves the pre-polymorphic invariant).
+    //   - external-kind rows are unique on (tenant_id, 'external', externalId) =
+    //     at most one active subscription per (issuer, external subscriber).
+    //
+    // UPGRADE NOTE: databases created against the pre-#1454 conflict key
+    // ['tenant_id'] still carry the legacy `_smrt_tenant_subscriptions_tenant_id_idx`.
+    // `smrt db:migrate` does not sweep orphan indexes by default, so the legacy
+    // index persists and continues to reject external subscriptions until it's
+    // dropped. Run scripts/migrate-1454-drop-legacy-conflict-index.ts once on
+    // upgrade, or pass `--drop-indexes` to `db:migrate`. Fresh databases need
+    // neither — the generated schema already reflects the new key.
+    conflictColumns: ["tenant_id", "subscriber_kind", "subscriber_external_id"]
+  })
+], TenantSubscription);
+class TenantSubscriptionCollection extends SmrtCollection {
+  static _itemClass = TenantSubscription;
+  /**
+   * List subscriptions whose owning tenant scope is `tenantId`. Includes both
+   * `'tenant'`-kind (subscriber == owner) and `'external'`-kind (subscriber is
+   * an external identity scoped under this tenant) rows.
+   */
+  async findByTenant(tenantId2) {
+    return this.list({
+      where: { tenantId: tenantId2 },
+      orderBy: "created_at DESC"
+    });
+  }
+  /**
+   * Legacy single-tenant accessor: returns the current subscription where the
+   * tenant IS the subscriber (`subscriberKind = 'tenant'`). External-kind rows
+   * scoped under this tenant are intentionally excluded so existing callers
+   * are not surprised by buyer/agent subscriptions.
+   */
+  async findCurrentForTenant(tenantId2, now = /* @__PURE__ */ new Date()) {
+    return this.findCurrentForSubscriber({ kind: "tenant", tenantId: tenantId2 }, now);
+  }
+  /**
+   * Polymorphic current-subscription accessor.
+   *
+   * For `'tenant'` subscribers we match rows with `subscriberKind = 'tenant'`
+   * under the same `tenantId`. For `'external'` subscribers we match by
+   * `(tenantId, subscriberExternalId)` with `subscriberKind = 'external'`.
+   */
+  async findCurrentForSubscriber(subscriber, now = /* @__PURE__ */ new Date()) {
+    const where = {
+      tenantId: subscriber.tenantId,
+      subscriberKind: subscriber.kind
+    };
+    if (subscriber.kind === "external") {
+      where.subscriberExternalId = subscriber.externalId;
+    }
+    const subscriptions = await this.list({
+      where,
+      orderBy: "created_at DESC"
+    });
+    return subscriptions.find((subscription) => subscription.isEntitled(now)) ?? subscriptions[0] ?? null;
+  }
+  async findByStripeSubscriptionId(stripeSubscriptionId) {
+    const subscriptions = await this.list({
+      where: { stripeSubscriptionId },
+      limit: 1
+    });
+    return subscriptions[0] ?? null;
+  }
+}
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+let TenantUsageMetric = class extends SmrtObject {
+  tenantId;
+  /**
+   * Discriminator for which subscriber identity recorded this usage.
+   * `'tenant'` (default) preserves the legacy shape; `'external'` indicates
+   * the subscriber is `subscriberExternalId` under the issuing `tenantId`.
+   */
+  subscriberKind = "tenant";
+  /**
+   * Opaque caller-namespaced subscriber id when `subscriberKind === 'external'`.
+   * Empty string when kind is `'tenant'`.
+   */
+  subscriberExternalId = "";
+  metricKey = "";
+  quantity = 0;
+  windowStart = /* @__PURE__ */ new Date();
+  windowEnd = /* @__PURE__ */ new Date();
+  source = "";
+  sourceId = "";
+  dimensions = "{}";
+  constructor(options = {}) {
+    super(options);
+    if (options.tenantId !== void 0) this.tenantId = options.tenantId;
+    if (options.subscriberKind !== void 0)
+      this.subscriberKind = options.subscriberKind;
+    if (options.subscriberExternalId !== void 0)
+      this.subscriberExternalId = options.subscriberExternalId;
+    assertSubscriberInvariant("TenantUsageMetric", {
+      subscriberKind: this.subscriberKind,
+      subscriberExternalId: this.subscriberExternalId
+    });
+    if (options.metricKey !== void 0) this.metricKey = options.metricKey;
+    if (options.quantity !== void 0) this.quantity = options.quantity;
+    if (options.windowStart !== void 0)
+      this.windowStart = options.windowStart;
+    if (options.windowEnd !== void 0) this.windowEnd = options.windowEnd;
+    if (options.source !== void 0) this.source = options.source;
+    if (options.sourceId !== void 0) this.sourceId = options.sourceId;
+    if (options.dimensions !== void 0) this.dimensions = options.dimensions;
+  }
+  /** See `TenantSubscription.validateBeforeSave` for the rationale. */
+  async validateBeforeSave() {
+    await super.validateBeforeSave();
+    assertSubscriberInvariant("TenantUsageMetric", {
+      subscriberKind: this.subscriberKind,
+      subscriberExternalId: this.subscriberExternalId
+    });
+  }
+  /**
+   * Project this row's polymorphic subscriber columns onto the
+   * {@link Subscriber} discriminated union.
+   */
+  getSubscriber() {
+    if (!this.tenantId) {
+      return null;
+    }
+    if (this.subscriberKind === "external") {
+      if (!this.subscriberExternalId) {
+        return null;
+      }
+      return {
+        kind: "external",
+        tenantId: this.tenantId,
+        externalId: this.subscriberExternalId
+      };
+    }
+    return { kind: "tenant", tenantId: this.tenantId };
+  }
+  getDimensions() {
+    return parseJsonObject(this.dimensions, {});
+  }
+  setDimensions(dimensions) {
+    this.dimensions = stringifyJson(dimensions);
+  }
+};
+__decorateClass([
+  tenantId()
+], TenantUsageMetric.prototype, "tenantId", 2);
+TenantUsageMetric = __decorateClass([
+  TenantScoped({ mode: "required" }),
+  smrt({
+    tableName: "_smrt_tenant_usage_metrics",
+    api: { include: ["list", "get", "create"] },
+    cli: true,
+    mcp: { include: ["list", "get"] }
+  })
+], TenantUsageMetric);
+class TenantUsageMetricCollection extends SmrtCollection {
+  static _itemClass = TenantUsageMetric;
+  async recordUsage(options) {
+    const subscriber = normalizeSubscriber({
+      tenantId: options.tenantId,
+      subscriberKind: options.subscriberKind,
+      subscriberExternalId: options.subscriberExternalId
+    });
+    const columns = subscriberToColumns(subscriber);
+    const metric = await this.create({
+      tenantId: columns.tenantId,
+      subscriberKind: columns.subscriberKind,
+      subscriberExternalId: columns.subscriberExternalId,
+      metricKey: options.metricKey,
+      quantity: options.quantity,
+      windowStart: options.windowStart,
+      windowEnd: options.windowEnd,
+      source: options.source ?? "",
+      sourceId: options.sourceId ?? "",
+      dimensions: stringifyJson(options.dimensions ?? {})
+    });
+    return metric;
+  }
+  /**
+   * Legacy accessor — finds metrics for `subscriberKind = 'tenant'` under the
+   * given tenant. External-kind rows scoped to the same tenant are excluded.
+   */
+  async findByTenantAndMetric(tenantId2, metricKey) {
+    return this.list({
+      where: { tenantId: tenantId2, metricKey, subscriberKind: "tenant" },
+      orderBy: "windowStart DESC"
+    });
+  }
+  async summarizeUsage(options) {
+    const subscriber = normalizeSubscriber({
+      tenantId: options.tenantId,
+      subscriberKind: options.subscriberKind,
+      subscriberExternalId: options.subscriberExternalId
+    });
+    const columns = subscriberToColumns(subscriber);
+    const where = {
+      tenantId: columns.tenantId,
+      subscriberKind: columns.subscriberKind,
+      metricKey: options.metricKey,
+      "windowStart <": options.window.end.toISOString(),
+      "windowEnd >": options.window.start.toISOString()
+    };
+    if (subscriber.kind === "external") {
+      where.subscriberExternalId = columns.subscriberExternalId;
+    }
+    const metrics = await this.list({ where });
+    const baseSummary = {
+      tenantId: columns.tenantId,
+      metricKey: options.metricKey,
+      quantity: metrics.reduce((sum, metric) => sum + metric.quantity, 0),
+      windowStart: options.window.start,
+      windowEnd: options.window.end
+    };
+    if (subscriber.kind === "external") {
+      return {
+        ...baseSummary,
+        subscriberKind: "external",
+        subscriberExternalId: subscriber.externalId
+      };
+    }
+    return baseSummary;
+  }
+  async summarizeUsageBatch(options) {
+    const metricKeys = Array.from(new Set(options.metricKeys));
+    if (metricKeys.length === 0) {
+      return [];
+    }
+    const subscriber = normalizeSubscriber({
+      tenantId: options.tenantId,
+      subscriberKind: options.subscriberKind,
+      subscriberExternalId: options.subscriberExternalId
+    });
+    const columns = subscriberToColumns(subscriber);
+    const metricPlaceholders = metricKeys.map(() => "?").join(", ");
+    const params = [
+      columns.tenantId,
+      columns.subscriberKind,
+      ...metricKeys,
+      options.window.end.toISOString(),
+      options.window.start.toISOString()
+    ];
+    let subscriberSql = "";
+    if (subscriber.kind === "external") {
+      subscriberSql = "AND subscriber_external_id = ?";
+      params.splice(2, 0, columns.subscriberExternalId);
+    }
+    const result = await this.db.query(
+      `SELECT
+          metric_key,
+          COALESCE(SUM(quantity), 0) AS quantity
+        FROM _smrt_tenant_usage_metrics
+        WHERE tenant_id = ?
+          AND subscriber_kind = ?
+          ${subscriberSql}
+          AND metric_key IN (${metricPlaceholders})
+          AND window_start < ?
+          AND window_end > ?
+        GROUP BY metric_key`,
+      ...params
+    );
+    const quantityByMetric = /* @__PURE__ */ new Map();
+    for (const row of resultRows(result)) {
+      const metricKey = String(row.metric_key ?? row.metricKey ?? "");
+      if (metricKey) {
+        quantityByMetric.set(metricKey, numberFromRow(row, "quantity"));
+      }
+    }
+    return metricKeys.map((metricKey) => {
+      const baseSummary = {
+        tenantId: columns.tenantId,
+        metricKey,
+        quantity: quantityByMetric.get(metricKey) ?? 0,
+        windowStart: options.window.start,
+        windowEnd: options.window.end
+      };
+      if (subscriber.kind === "external") {
+        return {
+          ...baseSummary,
+          subscriberKind: "external",
+          subscriberExternalId: subscriber.externalId
+        };
+      }
+      return baseSummary;
+    });
+  }
+  /**
+   * Summarize persisted AI usage for a tenant within a window.
+   *
+   * Reads the framework `_smrt_ai_usage` system table via a raw aggregate
+   * query. This deliberately uses `this.db.query` rather than the inherited
+   * `query()`: those rows are framework usage records, not `TenantUsageMetric`
+   * instances, so model hydration would discard the aggregate columns. Tenant
+   * scoping is applied explicitly through the `tenant_id` filter.
+   *
+   * Named distinctly from the inherited `SmrtClass.summarizeAiUsage` (which
+   * returns grouped stats across all tenants) to avoid overriding it.
+   */
+  async summarizeTenantAiUsage(options) {
+    const result = await this.db.query(
+      `SELECT
+          COALESCE(SUM(prompt_tokens), 0) AS prompt_tokens,
+          COALESCE(SUM(completion_tokens), 0) AS completion_tokens,
+          COALESCE(SUM(total_tokens), 0) AS total_tokens,
+          COALESCE(SUM(estimated_cost), 0) AS estimated_cost,
+          COUNT(*) AS request_count
+        FROM _smrt_ai_usage
+        WHERE tenant_id = ?
+          AND created_at >= ?
+          AND created_at < ?`,
+      options.tenantId,
+      options.window.start.toISOString(),
+      options.window.end.toISOString()
+    );
+    const row = firstRow(result);
+    return {
+      tenantId: options.tenantId,
+      promptTokens: numberFromRow(row, "prompt_tokens"),
+      completionTokens: numberFromRow(row, "completion_tokens"),
+      totalTokens: numberFromRow(row, "total_tokens"),
+      estimatedCost: numberFromRow(row, "estimated_cost"),
+      requestCount: numberFromRow(row, "request_count"),
+      windowStart: options.window.start,
+      windowEnd: options.window.end
+    };
+  }
+}
+function firstRow(result) {
+  const rows = resultRows(result);
+  return rows[0] ?? {};
+}
+function resultRows(result) {
+  return Array.isArray(result) ? result : result?.rows ?? [];
+}
+function numberFromRow(row, key) {
+  const value = row[key];
+  if (typeof value === "number") {
+    return value;
+  }
+  if (typeof value === "bigint") {
+    return Number(value);
+  }
+  if (typeof value === "string") {
+    return Number.parseFloat(value) || 0;
+  }
+  return 0;
+}
+function evaluateThreshold(threshold, usage) {
+  const ratio = threshold.limit === 0 ? usage.quantity > 0 ? Infinity : 0 : usage.quantity / threshold.limit;
+  const warningRatio = threshold.warningRatio ?? 0.8;
+  const blocked = threshold.enforcement === "block" && (threshold.limit === 0 ? usage.quantity > 0 : usage.quantity >= threshold.limit);
+  const warned = !blocked && ratio >= warningRatio;
+  return {
+    threshold,
+    usage,
+    ratio,
+    state: blocked ? "blocked" : warned ? "warn" : "ok",
+    allowed: !blocked,
+    remaining: Math.max(0, threshold.limit - usage.quantity)
+  };
+}
+function evaluateThresholds(thresholds, usage) {
+  const usageByMetric = new Map(
+    usage.map((summary) => [summary.metricKey, summary])
+  );
+  return thresholds.map((threshold) => {
+    const summary = usageByMetric.get(threshold.metricKey) ?? emptyUsageSummary$2(threshold.metricKey);
+    return evaluateThreshold(threshold, summary);
+  });
+}
+function emptyUsageSummary$2(metricKey) {
+  const now = /* @__PURE__ */ new Date();
+  return {
+    tenantId: "",
+    metricKey,
+    quantity: 0,
+    windowStart: now,
+    windowEnd: now
+  };
+}
+class TenantUsageMeter {
+  constructor(metrics, classOptions = {}) {
+    this.metrics = metrics;
+    this.classOptions = classOptions;
+  }
+  metrics;
+  classOptions;
+  static async create(classOptions = {}) {
+    const metrics = await TenantUsageMetricCollection.create(classOptions);
+    return new TenantUsageMeter(metrics, classOptions);
+  }
+  /**
+   * Record one usage row.
+   *
+   * Accepts the polymorphic subscriber fields directly on the options object
+   * (`subscriberKind`/`subscriberExternalId`); when omitted defaults to a
+   * `'tenant'`-kind row keyed off `tenantId`. The collection layer enforces
+   * the XOR invariant — passing `subscriberKind: 'external'` without a
+   * non-empty `subscriberExternalId` throws.
+   */
+  async record(options) {
+    await this.metrics.recordUsage(options);
+  }
+  /**
+   * Summarize usage over a window for a given subscriber.
+   *
+   * The `ai.*` short-circuit only fires for `'tenant'`-kind subscribers since
+   * the `_smrt_ai_usage` system table is tenant-scoped; external subscribers
+   * fall through to the normal `_smrt_tenant_usage_metrics` aggregation.
+   */
+  async summarize(options) {
+    normalizeSubscriber({
+      tenantId: options.tenantId,
+      subscriberKind: options.subscriberKind,
+      subscriberExternalId: options.subscriberExternalId
+    });
+    const aiSummary = await this.trySummarizeAiMetric(options);
+    if (aiSummary) {
+      return aiSummary;
+    }
+    return this.metrics.summarizeUsage(options);
+  }
+  async summarizeBatch(options) {
+    const subscriber = normalizeSubscriber({
+      tenantId: options.tenantId,
+      subscriberKind: options.subscriberKind,
+      subscriberExternalId: options.subscriberExternalId
+    });
+    const metricKeys = Array.from(new Set(options.metricKeys));
+    if (metricKeys.length === 0) {
+      return [];
+    }
+    const useTenantAiSummary = subscriber.kind === "tenant";
+    const aiMetricKeys = useTenantAiSummary ? metricKeys.filter((metricKey) => metricKey.startsWith("ai.")) : [];
+    const persistedMetricKeys = useTenantAiSummary ? metricKeys.filter((metricKey) => !metricKey.startsWith("ai.")) : metricKeys;
+    const summaries = /* @__PURE__ */ new Map();
+    if (aiMetricKeys.length > 0) {
+      const aiSummary = await this.summarizeAiUsage({
+        tenantId: options.tenantId,
+        window: options.window
+      });
+      const quantityByMetric = aiQuantityByMetric(aiSummary);
+      for (const metricKey of aiMetricKeys) {
+        summaries.set(metricKey, {
+          tenantId: options.tenantId,
+          metricKey,
+          quantity: quantityByMetric[metricKey] ?? 0,
+          windowStart: options.window.start,
+          windowEnd: options.window.end
+        });
+      }
+    }
+    const persistedSummaries = await this.metrics.summarizeUsageBatch({
+      ...options,
+      metricKeys: persistedMetricKeys
+    });
+    for (const summary of persistedSummaries) {
+      summaries.set(summary.metricKey, summary);
+    }
+    return metricKeys.map(
+      (metricKey) => summaries.get(metricKey) ?? emptyUsageSummary$1(subscriber, metricKey, options.window)
+    );
+  }
+  async summarizeAiUsage(options) {
+    return this.metrics.summarizeTenantAiUsage(options);
+  }
+  getOptions() {
+    return this.classOptions;
+  }
+  async trySummarizeAiMetric(options) {
+    if (!options.metricKey.startsWith("ai.")) {
+      return null;
+    }
+    const kind = options.subscriberKind ?? "tenant";
+    if (kind !== "tenant") {
+      return null;
+    }
+    const summary = await this.summarizeAiUsage({
+      tenantId: options.tenantId,
+      window: options.window
+    });
+    const quantityByMetric = {
+      ...aiQuantityByMetric(summary)
+    };
+    return {
+      tenantId: options.tenantId,
+      metricKey: options.metricKey,
+      quantity: quantityByMetric[options.metricKey] ?? 0,
+      windowStart: options.window.start,
+      windowEnd: options.window.end
+    };
+  }
+}
+function aiQuantityByMetric(summary) {
+  return {
+    "ai.tokens.prompt": summary.promptTokens,
+    "ai.tokens.completion": summary.completionTokens,
+    "ai.tokens.total": summary.totalTokens,
+    "ai.cost.estimated": summary.estimatedCost,
+    "ai.requests": summary.requestCount
+  };
+}
+function emptyUsageSummary$1(subscriber, metricKey, window) {
+  const summary = {
+    tenantId: subscriber.tenantId,
+    metricKey,
+    quantity: 0,
+    windowStart: window.start,
+    windowEnd: window.end
+  };
+  if (subscriber.kind === "external") {
+    return {
+      ...summary,
+      subscriberKind: "external",
+      subscriberExternalId: subscriber.externalId
+    };
+  }
+  return summary;
+}
+class SubscriptionResolver {
+  constructor(readers) {
+    this.readers = readers;
+  }
+  readers;
+  /**
+   * Build the default resolver readers once for a request or app lifecycle and
+   * reuse the returned resolver across entitlement checks.
+   */
+  static async create(classOptions = {}) {
+    const [plans, subscriptions, usage] = await Promise.all([
+      SubscriptionPlanCollection.create(classOptions),
+      TenantSubscriptionCollection.create(classOptions),
+      TenantUsageMeter.create(classOptions)
+    ]);
+    return new SubscriptionResolver({ plans, subscriptions, usage });
+  }
+  /**
+   * Load the subscription/plan pair used by entitlement resolution. Callers
+   * that need both the entitlement snapshot and the backing records can load
+   * this once, then pass it back via `options.context`.
+   */
+  async loadEntitlementContext(subscriberOrTenantId, options = {}) {
+    const subscriber = toSubscriber(subscriberOrTenantId);
+    const now = options.now ?? /* @__PURE__ */ new Date();
+    const subscription = await this.resolveSubscription(
+      subscriber,
+      now,
+      options.context
+    );
+    const plan = await this.resolvePlan(subscription, options.context);
+    return { subscription, plan };
+  }
+  /**
+   * Polymorphic entitlement resolution. Works for both `'tenant'`-kind and
+   * `'external'`-kind subscribers and is the preferred surface — the
+   * `resolveTenantEntitlements(tenantId)` method below is a thin wrapper.
+   */
+  async resolveEntitlements(subscriber, options = {}) {
+    const now = options.now ?? /* @__PURE__ */ new Date();
+    const { subscription, plan } = await this.loadEntitlementContext(
+      subscriber,
+      { ...options, now }
+    );
+    if (!subscription) {
+      return emptyResolution(subscriber);
+    }
+    if (!plan || !plan.isActive() || !subscription.isEntitled(now)) {
+      return {
+        ...emptyResolution(subscriber),
+        planId: plan?.id ?? subscription.planId ?? null,
+        planKey: plan?.planKey ?? null,
+        subscriptionId: subscription.id ?? null,
+        status: subscription.status
+      };
+    }
+    const thresholds = plan.getThresholds().filter(isValidThreshold);
+    const thresholdEvaluations = await this.resolveThresholdEvaluations(
+      subscriber,
+      thresholds,
+      now,
+      options
+    );
+    return {
+      tenantId: subscriber.tenantId,
+      subscriber,
+      planId: plan.id ?? null,
+      planKey: plan.planKey,
+      subscriptionId: subscription.id ?? null,
+      status: subscription.status,
+      featureKeys: plan.getFeatureKeys(),
+      thresholds,
+      thresholdEvaluations,
+      allowed: thresholdEvaluations.every((evaluation) => evaluation.allowed)
+    };
+  }
+  /**
+   * Legacy single-tenant wrapper around {@link resolveEntitlements}. Kept so
+   * existing tenant-only callers don't need to update their call sites.
+   */
+  async resolveTenantEntitlements(tenantId2, options = {}) {
+    return this.resolveEntitlements({ kind: "tenant", tenantId: tenantId2 }, options);
+  }
+  async isFeatureEnabled(subscriberOrTenantId, featureKey, options = {}) {
+    const resolution = await this.resolveEntitlements(
+      toSubscriber(subscriberOrTenantId),
+      options
+    );
+    return resolution.featureKeys.includes(featureKey);
+  }
+  async assertWithinThresholds(subscriberOrTenantId, options = {}) {
+    const subscriber = toSubscriber(subscriberOrTenantId);
+    const resolution = await this.resolveEntitlements(subscriber, options);
+    const blocked = resolution.thresholdEvaluations.find(
+      (evaluation) => !evaluation.allowed
+    );
+    if (blocked) {
+      const subject = subscriber.kind === "external" ? `external:${subscriber.externalId}` : `Tenant ${subscriber.tenantId}`;
+      throw new Error(
+        `${subject} exceeded subscription threshold ${blocked.threshold.metricKey}`
+      );
+    }
+  }
+  async resolveSubscription(subscriber, now, context) {
+    if (hasContextValue(context, "subscription")) {
+      const subscription = context?.subscription ?? null;
+      assertSubscriptionMatchesSubscriber(subscription, subscriber);
+      return subscription;
+    }
+    return this.findCurrentSubscription(subscriber, now);
+  }
+  async resolvePlan(subscription, context) {
+    if (!subscription?.planId) {
+      return null;
+    }
+    if (hasContextValue(context, "plan")) {
+      const plan = context?.plan ?? null;
+      assertPlanMatchesSubscription(plan, subscription);
+      return plan;
+    }
+    return this.readers.plans.get({ id: subscription.planId });
+  }
+  /**
+   * Bridge the legacy and polymorphic reader contracts.
+   *
+   * Prefers `findCurrentForSubscriber` when the reader provides it (the
+   * preferred shape). For `'tenant'` subscribers we fall back to the legacy
+   * `findCurrentForTenant`. For `'external'` subscribers the reader MUST
+   * implement `findCurrentForSubscriber` — otherwise we have no way to scope
+   * the lookup and we throw rather than silently returning the tenant's
+   * primary subscription.
+   */
+  async findCurrentSubscription(subscriber, now) {
+    if (this.readers.subscriptions.findCurrentForSubscriber) {
+      return this.readers.subscriptions.findCurrentForSubscriber(
+        subscriber,
+        now
+      );
+    }
+    if (subscriber.kind === "tenant") {
+      return this.readers.subscriptions.findCurrentForTenant(
+        subscriber.tenantId,
+        now
+      );
+    }
+    throw new Error(
+      "External-subscriber resolution requires a TenantSubscriptionReader that implements findCurrentForSubscriber()"
+    );
+  }
+  async resolveThresholdEvaluations(subscriber, thresholds, now, options) {
+    if (thresholds.length === 0) {
+      return [];
+    }
+    if (!this.readers.usage.summarizeBatch) {
+      const evaluations2 = [];
+      for (const threshold of thresholds) {
+        const window = options.usageWindows?.[threshold.window] ?? getWindowForThreshold(threshold.window, now);
+        const usage = await this.readers.usage.summarize({
+          tenantId: subscriber.tenantId,
+          subscriberKind: subscriber.kind,
+          subscriberExternalId: subscriber.kind === "external" ? subscriber.externalId : void 0,
+          metricKey: threshold.metricKey,
+          window
+        });
+        evaluations2.push(evaluateThreshold(threshold, usage));
+      }
+      return evaluations2;
+    }
+    const groups = /* @__PURE__ */ new Map();
+    thresholds.forEach((threshold, index) => {
+      const window = options.usageWindows?.[threshold.window] ?? getWindowForThreshold(threshold.window, now);
+      const key = getWindowKey(window);
+      const group = groups.get(key) ?? { window, entries: [] };
+      group.entries.push({ index, threshold });
+      groups.set(key, group);
+    });
+    const evaluations = new Array(thresholds.length);
+    await Promise.all(
+      Array.from(groups.values()).map(async ({ window, entries }) => {
+        const metricKeys = uniqueMetricKeys(
+          entries.map((entry) => entry.threshold.metricKey)
+        );
+        const summaries = await this.readers.usage.summarizeBatch?.({
+          tenantId: subscriber.tenantId,
+          subscriberKind: subscriber.kind,
+          subscriberExternalId: subscriber.kind === "external" ? subscriber.externalId : void 0,
+          metricKeys,
+          window
+        });
+        const summaryByMetric = new Map(
+          (summaries ?? []).map((summary) => [summary.metricKey, summary])
+        );
+        for (const { index, threshold } of entries) {
+          const usage = summaryByMetric.get(threshold.metricKey) ?? emptyUsageSummary(subscriber, threshold.metricKey, window);
+          evaluations[index] = evaluateThreshold(threshold, usage);
+        }
+      })
+    );
+    return evaluations;
+  }
+}
+function toSubscriber(input) {
+  if (typeof input === "string") {
+    return { kind: "tenant", tenantId: input };
+  }
+  return input;
+}
+function emptyResolution(subscriber) {
+  return {
+    tenantId: subscriber.tenantId,
+    subscriber,
+    planId: null,
+    planKey: null,
+    subscriptionId: null,
+    status: "none",
+    featureKeys: [],
+    thresholds: [],
+    thresholdEvaluations: [],
+    allowed: false
+  };
+}
+function hasContextValue(context, key) {
+  return context?.[key] !== void 0;
+}
+function assertSubscriptionMatchesSubscriber(subscription, subscriber) {
+  if (!subscription) {
+    return;
+  }
+  const subscriptionSubscriber = subscription.getSubscriber();
+  if (!subscriptionSubscriber || !sameSubscriber(subscriptionSubscriber, subscriber)) {
+    throw new Error(
+      "Provided entitlement context subscription does not match requested subscriber"
+    );
+  }
+}
+function assertPlanMatchesSubscription(plan, subscription) {
+  if (!plan) {
+    return;
+  }
+  if (!plan.id || plan.id !== subscription.planId) {
+    throw new Error(
+      "Provided entitlement context plan does not match subscription.planId"
+    );
+  }
+}
+function sameSubscriber(left, right) {
+  if (left.kind !== right.kind || left.tenantId !== right.tenantId) {
+    return false;
+  }
+  if (left.kind === "tenant") {
+    return true;
+  }
+  return right.kind === "external" && left.externalId === right.externalId;
+}
+function uniqueMetricKeys(metricKeys) {
+  return Array.from(new Set(metricKeys));
+}
+function emptyUsageSummary(subscriber, metricKey, window) {
+  const summary = {
+    tenantId: subscriber.tenantId,
+    metricKey,
+    quantity: 0,
+    windowStart: window.start,
+    windowEnd: window.end
+  };
+  if (subscriber.kind === "external") {
+    return {
+      ...summary,
+      subscriberKind: "external",
+      subscriberExternalId: subscriber.externalId
+    };
+  }
+  return summary;
+}
+export {
+  SubscriptionPlan,
+  SubscriptionPlanCollection,
+  SubscriptionResolver,
+  TenantSubscription,
+  TenantSubscriptionCollection,
+  TenantUsageMeter,
+  TenantUsageMetric,
+  TenantUsageMetricCollection,
+  assertSubscriberInvariant,
+  evaluateThreshold,
+  evaluateThresholds,
+  getWindowForThreshold,
+  getWindowKey,
+  isValidThreshold,
+  normalizeFeatureGrants,
+  normalizeSubscriber,
+  subscriberToColumns
+};
+//# sourceMappingURL=index.js.map