alepha 0.20.6 → 0.20.7

package/dist/api/subscriptions/index.d.ts

@@ -0,0 +1,1695 @@
+import * as _$alepha from "alepha";
+import { Alepha, Middleware, Static, TNull, TObject, TOptional, TSchema, TUnion } from "alepha";
+import * as _$alepha_server0 from "alepha/server";
+import * as _$alepha_orm0 from "alepha/orm";
+import { Page } from "alepha/orm";
+import * as _$alepha_api_parameters0 from "alepha/api/parameters";
+import { DateTimeProvider } from "alepha/datetime";
+import * as _$alepha_logger0 from "alepha/logger";
+import * as _$alepha_api_jobs0 from "alepha/api/jobs";
+import { PaymentService } from "alepha/api/payments";
+import * as _$alepha_api_notifications0 from "alepha/api/notifications";
+import { CacheProvider } from "alepha/cache";
+import * as _$typebox from "typebox";
+import { BuildExtraConfigColumns, SQL } from "drizzle-orm";
+import { PgColumnBuilderBase, PgSequenceOptions, PgTableExtraConfigValue, UpdateDeleteAction } from "drizzle-orm/pg-core";
+//#region ../../src/orm/core/schemas/insertSchema.d.ts
+/**
+ * Transforms a TObject schema for insert operations.
+ * All default properties at the root level are made optional.
+ * Generated columns are excluded entirely.
+ *
+ * @example
+ * Before: { name: string; age: number(default=0); fullName: generated }
+ * After:  { name: string; age?: number; }
+ */
+type TObjectInsert<T extends TObject> = TObject<{ [K in keyof T["properties"] as T["properties"][K] extends {
+  [PG_GENERATED]: any;
+} ? never : K]: T["properties"][K] extends {
+  [PG_DEFAULT]: any;
+} | {
+  [PG_ORGANIZATION]: any;
+} | {
+  "~optional": true;
+} ? TOptional<T["properties"][K]> : T["properties"][K] }>;
+//#endregion
+//#region ../../src/orm/core/schemas/updateSchema.d.ts
+/**
+ * Transforms a TObject schema for update operations.
+ * All optional properties at the root level are made nullable (i.e., `T | null`).
+ * Generated columns are excluded entirely.
+ *
+ * @example
+ * Before: { name?: string; age: number; fullName: generated }
+ * After:  { name?: string | null; age: number; }
+ */
+type TObjectUpdate<T extends TObject> = TObject<{ [K in keyof T["properties"] as T["properties"][K] extends {
+  [PG_GENERATED]: any;
+} ? never : K]: T["properties"][K] extends TOptional<infer U> ? TOptional<TUnion<[U, TNull]>> : T["properties"][K] }>;
+//#endregion
+//#region ../../src/orm/core/primitives/$entity.d.ts
+interface EntityPrimitiveOptions<T extends TObject, Keys = keyof Static<T>> {
+  /**
+   * The database table name that will be created for this entity.
+   * If not provided, name will be inferred from the $repository variable name.
+   */
+  name: string;
+  /**
+   * TypeBox schema defining the table structure and column types.
+   */
+  schema: T;
+  /**
+   * Database indexes to create for query optimization.
+   */
+  indexes?: (Keys | {
+    /**
+     * Single column to index.
+     */
+    column: Keys;
+    /**
+     * Whether this should be a unique index (enforces uniqueness constraint).
+     */
+    unique?: boolean;
+    /**
+     * Custom name for the index. If not provided, generates name automatically.
+     */
+    name?: string;
+    /**
+     * Partial index condition. Only rows matching this SQL expression are indexed.
+     */
+    where?: SQL;
+  } | {
+    /**
+     * Multiple columns for composite index (order matters for query optimization).
+     */
+    columns: Keys[];
+    /**
+     * Whether this should be a unique index (enforces uniqueness constraint).
+     */
+    unique?: boolean;
+    /**
+     * Custom name for the index. If not provided, generates name automatically.
+     */
+    name?: string;
+    /**
+     * Partial index condition. Only rows matching this SQL expression are indexed.
+     */
+    where?: SQL;
+  } | {
+    /**
+     * SQL expressions for expression-based indexes.
+     *
+     * Can include column references and SQL functions like `LOWER()`, `UPPER()`, etc.
+     * Columns and expressions can be mixed together.
+     *
+     * @example
+     * ```ts
+     * // Case-insensitive unique username per realm
+     * indexes: [{
+     *   expressions: (self) => [self.realm, sql`LOWER(${self.username})`],
+     *   unique: true,
+     *   name: "users_realm_username_lower_idx",
+     * }]
+     * ```
+     */
+    expressions: (self: Record<Keys & string, any>) => (SQL | any)[];
+    /**
+     * Whether this should be a unique index (enforces uniqueness constraint).
+     */
+    unique?: boolean;
+    /**
+     * Custom name for the index. If not provided, generates name automatically.
+     */
+    name: string;
+    /**
+     * Partial index condition. Only rows matching this SQL expression are indexed.
+     */
+    where?: SQL;
+  })[];
+  /**
+   * Foreign key constraints to maintain referential integrity.
+   */
+  foreignKeys?: Array<{
+    /**
+     * Optional name for the foreign key constraint.
+     */
+    name?: string;
+    /**
+     * Local columns that reference the foreign table.
+     */
+    columns: Array<keyof Static<T>>;
+    /**
+     * Referenced columns in the foreign table.
+     * Must be EntityColumn references from other entities.
+     */
+    foreignColumns: Array<() => EntityColumn<any>>;
+  }>;
+  /**
+   * Additional table constraints for data validation.
+   *
+   * Constraints enforce business rules at the database level, providing
+   * an additional layer of data integrity beyond application validation.
+   *
+   * **Constraint Types**:
+   * - **Unique constraints**: Prevent duplicate values across columns
+   * - **Check constraints**: Enforce custom validation rules with SQL expressions
+   *
+   * @example
+   * ```ts
+   * constraints: [
+   *   {
+   *     name: "unique_user_email",
+   *     columns: ["email"],
+   *     unique: true
+   *   },
+   *   {
+   *     name: "valid_age_range",
+   *     columns: ["age"],
+   *     check: sql`age >= 0 AND age <= 150`
+   *   },
+   *   {
+   *     name: "unique_user_username_per_tenant",
+   *     columns: ["tenantId", "username"],
+   *     unique: true
+   *   }
+   * ]
+   * ```
+   */
+  constraints?: Array<{
+    /**
+     * Columns involved in this constraint.
+     */
+    columns: Array<keyof Static<T>>;
+    /**
+     * Optional name for the constraint.
+     */
+    name?: string;
+    /**
+     * Whether this is a unique constraint.
+     */
+    unique?: boolean | {};
+    /**
+     * SQL expression for check constraint validation.
+     */
+    check?: SQL;
+  }>;
+  /**
+   * Advanced Drizzle ORM configuration for complex table setups.
+   */
+  config?: (self: BuildExtraConfigColumns<string, FromSchema<T>, "pg">) => PgTableExtraConfigValue[];
+}
+declare class EntityPrimitive<T extends TObject = TObject> {
+  readonly options: EntityPrimitiveOptions<T>;
+  constructor(options: EntityPrimitiveOptions<T>);
+  alias(alias: string): this;
+  get cols(): EntityColumns<T>;
+  get name(): string;
+  get schema(): T;
+  get insertSchema(): TObjectInsert<T>;
+  get updateSchema(): TObjectUpdate<T>;
+}
+/**
+ * Convert a schema to columns.
+ */
+type FromSchema<T extends TObject> = { [key in keyof T["properties"]]: PgColumnBuilderBase };
+type EntityColumn<T extends TObject> = {
+  name: string;
+  entity: EntityPrimitive<T>;
+};
+type EntityColumns<T extends TObject> = { [key in keyof T["properties"]]: EntityColumn<T> };
+//#endregion
+//#region ../../src/orm/core/constants/PG_SYMBOLS.d.ts
+declare const PG_DEFAULT: unique symbol;
+declare const PG_PRIMARY_KEY: unique symbol;
+declare const PG_CREATED_AT: unique symbol;
+declare const PG_UPDATED_AT: unique symbol;
+declare const PG_DELETED_AT: unique symbol;
+declare const PG_VERSION: unique symbol;
+declare const PG_IDENTITY: unique symbol;
+declare const PG_ENUM: unique symbol;
+declare const PG_REF: unique symbol;
+declare const PG_GENERATED: unique symbol;
+declare const PG_ORGANIZATION: unique symbol;
+/**
+ * @deprecated Use `PG_IDENTITY` instead.
+ */
+declare const PG_SERIAL: unique symbol;
+type PgSymbols = {
+  [PG_DEFAULT]: {};
+  [PG_PRIMARY_KEY]: {};
+  [PG_CREATED_AT]: {};
+  [PG_UPDATED_AT]: {};
+  [PG_DELETED_AT]: {};
+  [PG_VERSION]: {};
+  [PG_IDENTITY]: PgIdentityOptions;
+  [PG_REF]: PgRefOptions;
+  [PG_ENUM]: PgEnumOptions;
+  [PG_GENERATED]: PgGeneratedOptions;
+  [PG_ORGANIZATION]: {};
+  /**
+   * @deprecated Use `PG_IDENTITY` instead.
+   */
+  [PG_SERIAL]: {};
+};
+type PgSymbolKeys = keyof PgSymbols;
+type PgIdentityOptions = {
+  mode: "always" | "byDefault";
+} & PgSequenceOptions & {
+  name?: string;
+};
+interface PgEnumOptions {
+  name?: string;
+  description?: string;
+}
+interface PgGeneratedOptions {
+  /**
+   * SQL expression for the generated column.
+   */
+  expression: SQL;
+  /**
+   * Storage mode for the generated column.
+   * - `"stored"` — value is computed on write and stored on disk (default for PostgreSQL).
+   * - `"virtual"` — value is computed on read (default for SQLite).
+   */
+  mode?: "stored" | "virtual";
+}
+interface PgRefOptions {
+  ref: () => {
+    name: string;
+    entity: EntityPrimitive;
+  };
+  actions?: {
+    onUpdate?: UpdateDeleteAction;
+    onDelete?: UpdateDeleteAction;
+  };
+}
+//#endregion
+//#region ../../src/orm/core/helpers/pgAttr.d.ts
+/**
+ * Type representation.
+ */
+type PgAttr<T extends TSchema, TAttr extends PgSymbolKeys> = T & { [K in TAttr]: PgSymbols[K] };
+//#endregion
+//#region ../../src/orm/core/schemas/databaseEnvSchema.d.ts
+/**
+ * Base database environment schema.
+ *
+ * Defines the `DATABASE_URL` connection string used by all ORM providers
+ * to determine the database driver and connection target.
+ *
+ * Supported URL formats:
+ * - `sqlite://:memory:` or `sqlite://./path/to/db` — SQLite (Node.js or Bun)
+ * - `postgres://user:password@host:port/database` — PostgreSQL (Node.js or Bun)
+ * - `pglite://:memory:` or `pglite://./path` — PGlite (embedded Postgres)
+ * - `d1://BINDING_NAME` — Cloudflare D1
+ * - `hyperdrive://BINDING_NAME` — Cloudflare Hyperdrive
+ */
+declare const databaseEnvSchema: _$typebox.TObject<{
+  DATABASE_URL: _$typebox.TOptional<_$typebox.TString>;
+  /**
+   * Enable or disable push-based schema synchronization (drizzle-kit push).
+   *
+   * Defaults to `true` in development and test, `false` in production.
+   * Set to `false` in development to skip automatic schema sync
+   * (e.g. when managing migrations manually).
+   */
+  DATABASE_SYNC: _$typebox.TOptional<_$typebox.TBoolean>;
+}>;
+declare module "alepha" {
+  interface Env extends Partial<Static<typeof databaseEnvSchema>> {}
+} //# sourceMappingURL=databaseEnvSchema.d.ts.map
+//#endregion
+//#region ../../src/api/subscriptions/schemas/planDefinitionSchema.d.ts
+declare const planDefinitionSchema: _$typebox.TObject<{
+  /**
+   * Unique plan identifier (e.g., "free", "starter", "pro", "enterprise").
+   */
+  id: _$typebox.TString;
+  /**
+   * Display name (e.g., "Pro Plan").
+   */
+  name: _$typebox.TString;
+  /**
+   * Optional description.
+   */
+  description: _$typebox.TOptional<_$typebox.TString>;
+  /**
+   * Whether this plan is available for new subscriptions.
+   */
+  available: _$typebox.TBoolean;
+  /**
+   * Pricing per billing interval.
+   * Multiple entries for monthly/yearly.
+   */
+  pricing: _$typebox.TArray<_$typebox.TObject<{
+    interval: _$typebox.TUnsafe<"monthly" | "yearly">;
+    amount: _$typebox.TInteger;
+    currency: _$typebox.TString;
+  }>>;
+  /**
+   * Trial configuration for this plan.
+   * Overrides global settings.trialDays if set.
+   */
+  trial: _$typebox.TOptional<_$typebox.TObject<{
+    days: _$typebox.TInteger;
+    requirePaymentMethod: _$typebox.TBoolean;
+  }>>;
+  /**
+   * Feature entitlements. Boolean flags for feature access.
+   * Checked via SubscriptionService.can("feature-name").
+   */
+  features: _$typebox.TArray<_$typebox.TString>;
+  /**
+   * Usage limits. Numeric caps on resources.
+   * Checked via SubscriptionService.limit("resource-name").
+   * -1 = unlimited.
+   */
+  limits: _$typebox.TRecord<"^.*$", _$typebox.TInteger>;
+  /**
+   * Sort order for display (lower = first).
+   */
+  order: _$typebox.TInteger;
+  /**
+   * Metadata for app-specific plan data.
+   */
+  metadata: _$typebox.TOptional<_$typebox.TRecord<"^.*$", _$typebox.TAny>>;
+}>;
+type PlanDefinition = Static<typeof planDefinitionSchema>;
+//#endregion
+//#region ../../src/api/subscriptions/schemas/subscriptionSettingsSchema.d.ts
+declare const subscriptionSettingsSchema: _$typebox.TObject<{
+  /**
+   * Default trial days (overridden per-plan if plan.trial.days is set).
+   */
+  trialDays: _$typebox.TInteger;
+  /**
+   * Days after payment failure before suspension.
+   * During grace period, subscription remains active but flagged.
+   */
+  gracePeriodDays: _$typebox.TInteger;
+  /**
+   * Days after first payment failure to retry, relative to the failure date.
+   * e.g., [1, 3, 5, 7] means retry on day 1, 3, 5, 7 after failure.
+   */
+  dunningSchedule: _$typebox.TArray<_$typebox.TInteger>;
+  /**
+   * When user cancels, wait until period end (true) or cancel immediately (false).
+   */
+  cancelAtPeriodEnd: _$typebox.TBoolean;
+  /**
+   * Prorate charges when changing plans mid-cycle.
+   */
+  prorateOnChange: _$typebox.TBoolean;
+}>;
+type SubscriptionSettings = Static<typeof subscriptionSettingsSchema>;
+//#endregion
+//#region ../../src/api/subscriptions/services/SubscriptionConfig.d.ts
+declare class SubscriptionConfig {
+  protected readonly plans: _$alepha_api_parameters0.ParameterPrimitive<_$typebox.TObject<{
+    plans: _$typebox.TArray<_$typebox.TObject<{
+      id: _$typebox.TString;
+      name: _$typebox.TString;
+      description: _$typebox.TOptional<_$typebox.TString>;
+      available: _$typebox.TBoolean;
+      pricing: _$typebox.TArray<_$typebox.TObject<{
+        interval: _$typebox.TUnsafe<"monthly" | "yearly">;
+        amount: _$typebox.TInteger;
+        currency: _$typebox.TString;
+      }>>;
+      trial: _$typebox.TOptional<_$typebox.TObject<{
+        days: _$typebox.TInteger;
+        requirePaymentMethod: _$typebox.TBoolean;
+      }>>;
+      features: _$typebox.TArray<_$typebox.TString>;
+      limits: _$typebox.TRecord<"^.*$", _$typebox.TInteger>;
+      order: _$typebox.TInteger;
+      metadata: _$typebox.TOptional<_$typebox.TRecord<"^.*$", _$typebox.TAny>>;
+    }>>;
+  }>>;
+  protected readonly settings: _$alepha_api_parameters0.ParameterPrimitive<_$typebox.TObject<{
+    trialDays: _$typebox.TInteger;
+    gracePeriodDays: _$typebox.TInteger;
+    dunningSchedule: _$typebox.TArray<_$typebox.TInteger>;
+    cancelAtPeriodEnd: _$typebox.TBoolean;
+    prorateOnChange: _$typebox.TBoolean;
+  }>>;
+  getPlans(): Promise<PlanDefinition[]>;
+  getSettings(): Promise<SubscriptionSettings>;
+  getPlan(planId: string): Promise<PlanDefinition>;
+  getPlanPricing(planId: string, interval: "monthly" | "yearly"): Promise<{
+    interval: "monthly" | "yearly";
+    amount: number;
+    currency: string;
+  }>;
+}
+//#endregion
+//#region ../../src/api/subscriptions/entities/subscriptionEvents.d.ts
+declare const subscriptionEvents: _$alepha_orm0.EntityPrimitive<_$typebox.TObject<{
+  id: _$alepha_orm0.PgAttr<_$alepha_orm0.PgAttr<_$typebox.TString, typeof _$alepha_orm0.PG_PRIMARY_KEY>, typeof _$alepha_orm0.PG_DEFAULT>;
+  createdAt: _$alepha_orm0.PgAttr<_$alepha_orm0.PgAttr<_$typebox.TString, typeof _$alepha_orm0.PG_CREATED_AT>, typeof _$alepha_orm0.PG_DEFAULT>;
+  subscriptionId: _$alepha_orm0.PgAttr<_$typebox.TString, typeof _$alepha_orm0.PG_REF>;
+  organizationId: _$alepha_orm0.PgAttr<_$typebox.TString, typeof _$alepha_orm0.PG_ORGANIZATION>;
+  type: _$typebox.TUnsafe<"past_due" | "suspended" | "cancelled" | "expired" | "created" | "trial_started" | "trial_ended" | "activated" | "renewed" | "payment_failed" | "payment_retried" | "reactivated" | "plan_changed" | "plan_change_scheduled" | "resumed">;
+  previousStatus: _$typebox.TOptional<_$typebox.TString>;
+  newStatus: _$typebox.TOptional<_$typebox.TString>;
+  previousPlanId: _$typebox.TOptional<_$typebox.TString>;
+  newPlanId: _$typebox.TOptional<_$typebox.TString>;
+  paymentIntentId: _$typebox.TOptional<_$typebox.TString>;
+  amount: _$typebox.TOptional<_$typebox.TInteger>;
+  currency: _$typebox.TOptional<_$typebox.TString>;
+  triggeredBy: _$typebox.TOptional<_$typebox.TString>;
+  userId: _$typebox.TOptional<_$typebox.TString>;
+  note: _$typebox.TOptional<_$typebox.TString>;
+}>>;
+type SubscriptionEventEntity = Static<typeof subscriptionEvents.schema>;
+//#endregion
+//#region ../../src/api/subscriptions/entities/subscriptions.d.ts
+declare const subscriptions: _$alepha_orm0.EntityPrimitive<_$typebox.TObject<{
+  id: _$alepha_orm0.PgAttr<_$alepha_orm0.PgAttr<_$typebox.TString, typeof _$alepha_orm0.PG_PRIMARY_KEY>, typeof _$alepha_orm0.PG_DEFAULT>;
+  version: _$alepha_orm0.PgAttr<_$alepha_orm0.PgAttr<_$typebox.TInteger, typeof _$alepha_orm0.PG_VERSION>, typeof _$alepha_orm0.PG_DEFAULT>;
+  createdAt: _$alepha_orm0.PgAttr<_$alepha_orm0.PgAttr<_$typebox.TString, typeof _$alepha_orm0.PG_CREATED_AT>, typeof _$alepha_orm0.PG_DEFAULT>;
+  updatedAt: _$alepha_orm0.PgAttr<_$alepha_orm0.PgAttr<_$typebox.TString, typeof _$alepha_orm0.PG_UPDATED_AT>, typeof _$alepha_orm0.PG_DEFAULT>;
+  organizationId: _$alepha_orm0.PgAttr<_$typebox.TString, typeof _$alepha_orm0.PG_ORGANIZATION>;
+  planId: _$typebox.TString;
+  interval: _$typebox.TUnsafe<"monthly" | "yearly">;
+  status: _$typebox.TUnsafe<"trialing" | "active" | "past_due" | "suspended" | "cancelled" | "expired">;
+  currentPeriodStart: _$typebox.TString;
+  currentPeriodEnd: _$typebox.TString;
+  trialStart: _$typebox.TOptional<_$typebox.TString>;
+  trialEnd: _$typebox.TOptional<_$typebox.TString>;
+  cancelledAt: _$typebox.TOptional<_$typebox.TString>;
+  cancelReason: _$typebox.TOptional<_$typebox.TString>;
+  cancelAtPeriodEnd: _$typebox.TBoolean;
+  lastPaymentIntentId: _$typebox.TOptional<_$typebox.TString>;
+  lastPaymentAt: _$typebox.TOptional<_$typebox.TString>;
+  nextBillingAt: _$typebox.TOptional<_$typebox.TString>;
+  dunningStartedAt: _$typebox.TOptional<_$typebox.TString>;
+  dunningAttempt: _$typebox.TInteger;
+  dunningNextRetryAt: _$typebox.TOptional<_$typebox.TString>;
+  pendingPlanId: _$typebox.TOptional<_$typebox.TString>;
+  pendingInterval: _$typebox.TOptional<_$typebox.TUnsafe<"monthly" | "yearly">>;
+  metadata: _$typebox.TOptional<_$typebox.TRecord<"^.*$", _$typebox.TAny>>;
+}>>;
+type SubscriptionEntity = Static<typeof subscriptions.schema>;
+//#endregion
+//#region ../../src/api/subscriptions/schemas/entitlementsSchema.d.ts
+declare const entitlementsSchema: _$typebox.TObject<{
+  planId: _$typebox.TString;
+  planName: _$typebox.TString;
+  status: _$typebox.TUnsafe<"trialing" | "active" | "past_due" | "suspended" | "cancelled" | "expired">;
+  features: _$typebox.TArray<_$typebox.TString>;
+  limits: _$typebox.TRecord<"^.*$", _$typebox.TInteger>;
+  trialEndsAt: _$typebox.TOptional<_$typebox.TString>;
+  periodEndsAt: _$typebox.TString;
+  cancelledAt: _$typebox.TOptional<_$typebox.TString>;
+}>;
+type Entitlements = Static<typeof entitlementsSchema>;
+//#endregion
+//#region ../../src/api/subscriptions/schemas/subscriptionQuerySchema.d.ts
+declare const subscriptionQuerySchema: _$typebox.TObject<{
+  page: _$typebox.TOptional<_$typebox.TInteger>;
+  size: _$typebox.TOptional<_$typebox.TInteger>;
+  sort: _$typebox.TOptional<_$typebox.TString>;
+  status: _$typebox.TOptional<_$typebox.TUnsafe<"trialing" | "active" | "past_due" | "suspended" | "cancelled" | "expired">>;
+  planId: _$typebox.TOptional<_$typebox.TString>;
+  organizationId: _$typebox.TOptional<_$typebox.TString>;
+}>;
+type SubscriptionQuery = Static<typeof subscriptionQuerySchema>;
+//#endregion
+//#region ../../src/api/subscriptions/schemas/subscriptionStatsSchema.d.ts
+declare const subscriptionStatsSchema: _$typebox.TObject<{
+  total: _$typebox.TInteger;
+  trialing: _$typebox.TInteger;
+  active: _$typebox.TInteger;
+  pastDue: _$typebox.TInteger;
+  suspended: _$typebox.TInteger;
+  cancelled: _$typebox.TInteger;
+  expired: _$typebox.TInteger;
+  trialConversionRate: _$typebox.TNumber;
+  churnRate: _$typebox.TNumber;
+  byPlan: _$typebox.TRecord<"^.*$", _$typebox.TObject<{
+    active: _$typebox.TInteger;
+    trialing: _$typebox.TInteger;
+    total: _$typebox.TInteger;
+  }>>;
+}>;
+type SubscriptionStats = Static<typeof subscriptionStatsSchema>;
+//#endregion
+//#region ../../src/api/subscriptions/services/SubscriptionService.d.ts
+interface SubscribeOptions {
+  /**
+   * Override plan/global trial days.
+   */
+  trialDays?: number;
+  /**
+   * Go straight to active (requires payment).
+   */
+  skipTrial?: boolean;
+  /**
+   * Metadata to attach to the subscription.
+   */
+  metadata?: Record<string, unknown>;
+}
+interface CancelOptions {
+  /**
+   * Cancellation reason.
+   */
+  reason?: string;
+  /**
+   * Cancel immediately instead of at period end.
+   */
+  immediate?: boolean;
+  /**
+   * User who initiated the cancellation.
+   */
+  cancelledBy?: string;
+}
+interface ChangePlanOptions {
+  /**
+   * Apply now (with proration) or at period end.
+   */
+  immediate?: boolean;
+  /**
+   * Override settings.prorateOnChange.
+   */
+  prorate?: boolean;
+}
+interface EventContext$2 {
+  previousStatus?: string;
+  newStatus?: string;
+  previousPlanId?: string;
+  newPlanId?: string;
+  paymentIntentId?: string;
+  amount?: number;
+  currency?: string;
+  triggeredBy?: string;
+  userId?: string;
+  note?: string;
+}
+declare class SubscriptionService {
+  protected readonly alepha: Alepha;
+  protected readonly log: _$alepha_logger0.Logger;
+  protected readonly dateTime: DateTimeProvider;
+  protected readonly subscriptionRepo: _$alepha_orm0.Repository<_$typebox.TObject<{
+    id: _$alepha_orm0.PgAttr<_$alepha_orm0.PgAttr<_$typebox.TString, typeof _$alepha_orm0.PG_PRIMARY_KEY>, typeof _$alepha_orm0.PG_DEFAULT>;
+    version: _$alepha_orm0.PgAttr<_$alepha_orm0.PgAttr<_$typebox.TInteger, typeof _$alepha_orm0.PG_VERSION>, typeof _$alepha_orm0.PG_DEFAULT>;
+    createdAt: _$alepha_orm0.PgAttr<_$alepha_orm0.PgAttr<_$typebox.TString, typeof _$alepha_orm0.PG_CREATED_AT>, typeof _$alepha_orm0.PG_DEFAULT>;
+    updatedAt: _$alepha_orm0.PgAttr<_$alepha_orm0.PgAttr<_$typebox.TString, typeof _$alepha_orm0.PG_UPDATED_AT>, typeof _$alepha_orm0.PG_DEFAULT>;
+    organizationId: _$alepha_orm0.PgAttr<_$typebox.TString, typeof _$alepha_orm0.PG_ORGANIZATION>;
+    planId: _$typebox.TString;
+    interval: _$typebox.TUnsafe<"monthly" | "yearly">;
+    status: _$typebox.TUnsafe<"trialing" | "active" | "past_due" | "suspended" | "cancelled" | "expired">;
+    currentPeriodStart: _$typebox.TString;
+    currentPeriodEnd: _$typebox.TString;
+    trialStart: _$typebox.TOptional<_$typebox.TString>;
+    trialEnd: _$typebox.TOptional<_$typebox.TString>;
+    cancelledAt: _$typebox.TOptional<_$typebox.TString>;
+    cancelReason: _$typebox.TOptional<_$typebox.TString>;
+    cancelAtPeriodEnd: _$typebox.TBoolean;
+    lastPaymentIntentId: _$typebox.TOptional<_$typebox.TString>;
+    lastPaymentAt: _$typebox.TOptional<_$typebox.TString>;
+    nextBillingAt: _$typebox.TOptional<_$typebox.TString>;
+    dunningStartedAt: _$typebox.TOptional<_$typebox.TString>;
+    dunningAttempt: _$typebox.TInteger;
+    dunningNextRetryAt: _$typebox.TOptional<_$typebox.TString>;
+    pendingPlanId: _$typebox.TOptional<_$typebox.TString>;
+    pendingInterval: _$typebox.TOptional<_$typebox.TUnsafe<"monthly" | "yearly">>;
+    metadata: _$typebox.TOptional<_$typebox.TRecord<"^.*$", _$typebox.TAny>>;
+  }>>;
+  protected readonly eventRepo: _$alepha_orm0.Repository<_$typebox.TObject<{
+    id: _$alepha_orm0.PgAttr<_$alepha_orm0.PgAttr<_$typebox.TString, typeof _$alepha_orm0.PG_PRIMARY_KEY>, typeof _$alepha_orm0.PG_DEFAULT>;
+    createdAt: _$alepha_orm0.PgAttr<_$alepha_orm0.PgAttr<_$typebox.TString, typeof _$alepha_orm0.PG_CREATED_AT>, typeof _$alepha_orm0.PG_DEFAULT>;
+    subscriptionId: _$alepha_orm0.PgAttr<_$typebox.TString, typeof _$alepha_orm0.PG_REF>;
+    organizationId: _$alepha_orm0.PgAttr<_$typebox.TString, typeof _$alepha_orm0.PG_ORGANIZATION>;
+    type: _$typebox.TUnsafe<"past_due" | "suspended" | "cancelled" | "expired" | "created" | "trial_started" | "trial_ended" | "activated" | "renewed" | "payment_failed" | "payment_retried" | "reactivated" | "plan_changed" | "plan_change_scheduled" | "resumed">;
+    previousStatus: _$typebox.TOptional<_$typebox.TString>;
+    newStatus: _$typebox.TOptional<_$typebox.TString>;
+    previousPlanId: _$typebox.TOptional<_$typebox.TString>;
+    newPlanId: _$typebox.TOptional<_$typebox.TString>;
+    paymentIntentId: _$typebox.TOptional<_$typebox.TString>;
+    amount: _$typebox.TOptional<_$typebox.TInteger>;
+    currency: _$typebox.TOptional<_$typebox.TString>;
+    triggeredBy: _$typebox.TOptional<_$typebox.TString>;
+    userId: _$typebox.TOptional<_$typebox.TString>;
+    note: _$typebox.TOptional<_$typebox.TString>;
+  }>>;
+  protected readonly config: SubscriptionConfig;
+  /**
+   * Find a subscription by organization ID.
+   * Returns null if no subscription exists.
+   */
+  getByOrganization(organizationId: string): Promise<SubscriptionEntity | null>;
+  /**
+   * Get a subscription by ID. Throws NotFoundError if not found.
+   */
+  getSubscription(id: string): Promise<SubscriptionEntity>;
+  /**
+   * Returns true if the subscription currently grants access.
+   * Accessible statuses: trialing, active, past_due (grace period),
+   * or cancelled with cancelAtPeriodEnd before period end.
+   */
+  isAccessible(sub: SubscriptionEntity): boolean;
+  /**
+   * Record a subscription event in the event log.
+   */
+  recordEvent(subscriptionId: string, organizationId: string, type: SubscriptionEventEntity["type"], context?: EventContext$2): Promise<void>;
+  /**
+   * Compute the end of a billing interval from a start date.
+   */
+  computeIntervalEnd(start: string, interval: "monthly" | "yearly"): string;
+  /**
+   * Create a new subscription for an organization.
+   */
+  subscribe(organizationId: string, planId: string, interval: "monthly" | "yearly", options?: SubscribeOptions): Promise<SubscriptionEntity>;
+  /**
+   * Cancel a subscription.
+   * If immediate, the subscription expires right away.
+   * If at period end, the subscription remains accessible until the period ends.
+   */
+  cancel(subscriptionId: string, options?: CancelOptions): Promise<void>;
+  /**
+   * Resume a cancelled subscription before its period ends.
+   * Only valid for subscriptions cancelled with cancelAtPeriodEnd.
+   */
+  resume(subscriptionId: string): Promise<void>;
+  /**
+   * Change the plan of a subscription.
+   * If immediate, proration is calculated and the plan changes now.
+   * If at period end, the change is scheduled for the next renewal.
+   * Returns the net proration amount (positive = charge, negative = credit).
+   */
+  changePlan(subscriptionId: string, newPlanId: string, newInterval?: "monthly" | "yearly", options?: ChangePlanOptions): Promise<number>;
+  /**
+   * Reactivate a suspended subscription (admin action).
+   * Resets dunning state and starts a new billing period.
+   */
+  reactivate(subscriptionId: string): Promise<void>;
+  /**
+   * Extend the trial period of a trialing subscription.
+   */
+  extendTrial(subscriptionId: string, days: number): Promise<void>;
+  /**
+   * Check if an organization has access to a specific feature.
+   */
+  can(organizationId: string, feature: string): Promise<boolean>;
+  /**
+   * Get the usage limit for a resource.
+   * Returns -1 for unlimited, 0 for no access.
+   */
+  limit(organizationId: string, resource: string): Promise<number>;
+  /**
+   * Get the full entitlements snapshot for an organization.
+   */
+  getEntitlements(organizationId: string): Promise<Entitlements>;
+  /**
+   * Find subscriptions with pagination and filtering.
+   */
+  findSubscriptions(query?: SubscriptionQuery): Promise<Page<SubscriptionEntity>>;
+  /**
+   * Get the event history for a subscription, ordered by most recent first.
+   */
+  getHistory(subscriptionId: string): Promise<SubscriptionEventEntity[]>;
+  /**
+   * Get aggregated subscription statistics.
+   */
+  getStats(): Promise<SubscriptionStats>;
+  /**
+   * Get revenue data from recent subscription events.
+   * Sums amounts from renewed and activated events within the specified window.
+   */
+  getRevenue(days?: number): Promise<{
+    total: number;
+    count: number;
+  }>;
+  /**
+   * Calculate proration for a mid-cycle plan change.
+   * Returns the net amount: positive = charge, negative = credit.
+   */
+  protected calculateProration(sub: SubscriptionEntity, newPlanId: string, newInterval: "monthly" | "yearly"): Promise<number>;
+}
+//#endregion
+//#region ../../src/api/subscriptions/controllers/AdminSubscriptionController.d.ts
+declare class AdminSubscriptionController {
+  protected readonly url = "/subscriptions";
+  protected readonly group = "admin:subscriptions";
+  protected readonly service: SubscriptionService;
+  protected readonly config: SubscriptionConfig;
+  /**
+   * Find subscriptions with pagination and filtering.
+   */
+  readonly findSubscriptions: _$alepha_server0.ActionPrimitiveFn<{
+    query: _$typebox.TObject<{
+      page: _$typebox.TOptional<_$typebox.TInteger>;
+      size: _$typebox.TOptional<_$typebox.TInteger>;
+      sort: _$typebox.TOptional<_$typebox.TString>;
+      status: _$typebox.TOptional<_$typebox.TUnsafe<"trialing" | "active" | "past_due" | "suspended" | "cancelled" | "expired">>;
+      planId: _$typebox.TOptional<_$typebox.TString>;
+      organizationId: _$typebox.TOptional<_$typebox.TString>;
+    }>;
+    response: _$alepha.TPage<_$typebox.TObject<{
+      id: PgAttr<PgAttr<_$typebox.TString, typeof PG_PRIMARY_KEY>, typeof PG_DEFAULT>;
+      version: PgAttr<PgAttr<_$typebox.TInteger, typeof PG_VERSION>, typeof PG_DEFAULT>;
+      createdAt: PgAttr<PgAttr<_$typebox.TString, typeof PG_CREATED_AT>, typeof PG_DEFAULT>;
+      updatedAt: PgAttr<PgAttr<_$typebox.TString, typeof PG_UPDATED_AT>, typeof PG_DEFAULT>;
+      organizationId: PgAttr<_$typebox.TString, typeof PG_ORGANIZATION>;
+      planId: _$typebox.TString;
+      interval: _$typebox.TUnsafe<"monthly" | "yearly">;
+      status: _$typebox.TUnsafe<"trialing" | "active" | "past_due" | "suspended" | "cancelled" | "expired">;
+      currentPeriodStart: _$typebox.TString;
+      currentPeriodEnd: _$typebox.TString;
+      trialStart: _$typebox.TOptional<_$typebox.TString>;
+      trialEnd: _$typebox.TOptional<_$typebox.TString>;
+      cancelledAt: _$typebox.TOptional<_$typebox.TString>;
+      cancelReason: _$typebox.TOptional<_$typebox.TString>;
+      cancelAtPeriodEnd: _$typebox.TBoolean;
+      lastPaymentIntentId: _$typebox.TOptional<_$typebox.TString>;
+      lastPaymentAt: _$typebox.TOptional<_$typebox.TString>;
+      nextBillingAt: _$typebox.TOptional<_$typebox.TString>;
+      dunningStartedAt: _$typebox.TOptional<_$typebox.TString>;
+      dunningAttempt: _$typebox.TInteger;
+      dunningNextRetryAt: _$typebox.TOptional<_$typebox.TString>;
+      pendingPlanId: _$typebox.TOptional<_$typebox.TString>;
+      pendingInterval: _$typebox.TOptional<_$typebox.TUnsafe<"monthly" | "yearly">>;
+      metadata: _$typebox.TOptional<_$typebox.TRecord<"^.*$", _$typebox.TAny>>;
+    }>>;
+  }>;
+  /**
+   * Get a subscription by ID.
+   */
+  readonly getSubscription: _$alepha_server0.ActionPrimitiveFn<{
+    params: _$typebox.TObject<{
+      id: _$typebox.TString;
+    }>;
+    response: _$typebox.TObject<{
+      id: PgAttr<PgAttr<_$typebox.TString, typeof PG_PRIMARY_KEY>, typeof PG_DEFAULT>;
+      version: PgAttr<PgAttr<_$typebox.TInteger, typeof PG_VERSION>, typeof PG_DEFAULT>;
+      createdAt: PgAttr<PgAttr<_$typebox.TString, typeof PG_CREATED_AT>, typeof PG_DEFAULT>;
+      updatedAt: PgAttr<PgAttr<_$typebox.TString, typeof PG_UPDATED_AT>, typeof PG_DEFAULT>;
+      organizationId: PgAttr<_$typebox.TString, typeof PG_ORGANIZATION>;
+      planId: _$typebox.TString;
+      interval: _$typebox.TUnsafe<"monthly" | "yearly">;
+      status: _$typebox.TUnsafe<"trialing" | "active" | "past_due" | "suspended" | "cancelled" | "expired">;
+      currentPeriodStart: _$typebox.TString;
+      currentPeriodEnd: _$typebox.TString;
+      trialStart: _$typebox.TOptional<_$typebox.TString>;
+      trialEnd: _$typebox.TOptional<_$typebox.TString>;
+      cancelledAt: _$typebox.TOptional<_$typebox.TString>;
+      cancelReason: _$typebox.TOptional<_$typebox.TString>;
+      cancelAtPeriodEnd: _$typebox.TBoolean;
+      lastPaymentIntentId: _$typebox.TOptional<_$typebox.TString>;
+      lastPaymentAt: _$typebox.TOptional<_$typebox.TString>;
+      nextBillingAt: _$typebox.TOptional<_$typebox.TString>;
+      dunningStartedAt: _$typebox.TOptional<_$typebox.TString>;
+      dunningAttempt: _$typebox.TInteger;
+      dunningNextRetryAt: _$typebox.TOptional<_$typebox.TString>;
+      pendingPlanId: _$typebox.TOptional<_$typebox.TString>;
+      pendingInterval: _$typebox.TOptional<_$typebox.TUnsafe<"monthly" | "yearly">>;
+      metadata: _$typebox.TOptional<_$typebox.TRecord<"^.*$", _$typebox.TAny>>;
+    }>;
+  }>;
+  /**
+   * Get aggregated subscription statistics.
+   */
+  readonly getStats: _$alepha_server0.ActionPrimitiveFn<{
+    response: _$typebox.TObject<{
+      total: _$typebox.TInteger;
+      trialing: _$typebox.TInteger;
+      active: _$typebox.TInteger;
+      pastDue: _$typebox.TInteger;
+      suspended: _$typebox.TInteger;
+      cancelled: _$typebox.TInteger;
+      expired: _$typebox.TInteger;
+      trialConversionRate: _$typebox.TNumber;
+      churnRate: _$typebox.TNumber;
+      byPlan: _$typebox.TRecord<"^.*$", _$typebox.TObject<{
+        active: _$typebox.TInteger;
+        trialing: _$typebox.TInteger;
+        total: _$typebox.TInteger;
+      }>>;
+    }>;
+  }>;
+  /**
+   * Get revenue data from recent subscription events.
+   */
+  readonly getRevenue: _$alepha_server0.ActionPrimitiveFn<{
+    query: _$typebox.TObject<{
+      days: _$typebox.TOptional<_$typebox.TInteger>;
+    }>;
+    response: _$typebox.TObject<{
+      total: _$typebox.TInteger;
+      count: _$typebox.TInteger;
+    }>;
+  }>;
+  /**
+   * Get Monthly Recurring Revenue breakdown.
+   */
+  readonly getMrr: _$alepha_server0.ActionPrimitiveFn<{
+    response: _$typebox.TObject<{
+      total: _$typebox.TInteger;
+      byPlan: _$typebox.TRecord<"^.*$", _$typebox.TInteger>;
+      growth: _$typebox.TInteger;
+      newMrr: _$typebox.TInteger;
+      expansionMrr: _$typebox.TInteger;
+      contractionMrr: _$typebox.TInteger;
+      churnMrr: _$typebox.TInteger;
+    }>;
+  }>;
+  /**
+   * Force a plan change for a subscription (admin action).
+   */
+  readonly adminChangePlan: _$alepha_server0.ActionPrimitiveFn<{
+    params: _$typebox.TObject<{
+      id: _$typebox.TString;
+    }>;
+    body: _$typebox.TObject<{
+      planId: _$typebox.TString;
+      interval: _$typebox.TOptional<_$typebox.TUnsafe<"monthly" | "yearly">>;
+      immediate: _$typebox.TOptional<_$typebox.TBoolean>;
+    }>;
+    response: _$typebox.TObject<{
+      id: PgAttr<PgAttr<_$typebox.TString, typeof PG_PRIMARY_KEY>, typeof PG_DEFAULT>;
+      version: PgAttr<PgAttr<_$typebox.TInteger, typeof PG_VERSION>, typeof PG_DEFAULT>;
+      createdAt: PgAttr<PgAttr<_$typebox.TString, typeof PG_CREATED_AT>, typeof PG_DEFAULT>;
+      updatedAt: PgAttr<PgAttr<_$typebox.TString, typeof PG_UPDATED_AT>, typeof PG_DEFAULT>;
+      organizationId: PgAttr<_$typebox.TString, typeof PG_ORGANIZATION>;
+      planId: _$typebox.TString;
+      interval: _$typebox.TUnsafe<"monthly" | "yearly">;
+      status: _$typebox.TUnsafe<"trialing" | "active" | "past_due" | "suspended" | "cancelled" | "expired">;
+      currentPeriodStart: _$typebox.TString;
+      currentPeriodEnd: _$typebox.TString;
+      trialStart: _$typebox.TOptional<_$typebox.TString>;
+      trialEnd: _$typebox.TOptional<_$typebox.TString>;
+      cancelledAt: _$typebox.TOptional<_$typebox.TString>;
+      cancelReason: _$typebox.TOptional<_$typebox.TString>;
+      cancelAtPeriodEnd: _$typebox.TBoolean;
+      lastPaymentIntentId: _$typebox.TOptional<_$typebox.TString>;
+      lastPaymentAt: _$typebox.TOptional<_$typebox.TString>;
+      nextBillingAt: _$typebox.TOptional<_$typebox.TString>;
+      dunningStartedAt: _$typebox.TOptional<_$typebox.TString>;
+      dunningAttempt: _$typebox.TInteger;
+      dunningNextRetryAt: _$typebox.TOptional<_$typebox.TString>;
+      pendingPlanId: _$typebox.TOptional<_$typebox.TString>;
+      pendingInterval: _$typebox.TOptional<_$typebox.TUnsafe<"monthly" | "yearly">>;
+      metadata: _$typebox.TOptional<_$typebox.TRecord<"^.*$", _$typebox.TAny>>;
+    }>;
+  }>;
+  /**
+   * Force cancel a subscription (admin action).
+   */
+  readonly adminCancel: _$alepha_server0.ActionPrimitiveFn<{
+    params: _$typebox.TObject<{
+      id: _$typebox.TString;
+    }>;
+    body: _$typebox.TObject<{
+      reason: _$typebox.TOptional<_$typebox.TString>;
+      immediate: _$typebox.TOptional<_$typebox.TBoolean>;
+    }>;
+    response: _$typebox.TObject<{
+      ok: _$typebox.TBoolean;
+      id: _$typebox.TOptional<_$typebox.TUnion<[_$typebox.TString, _$typebox.TInteger]>>;
+      count: _$typebox.TOptional<_$typebox.TNumber>;
+    }>;
+  }>;
+  /**
+   * Reactivate a suspended subscription (admin action).
+   */
+  readonly adminReactivate: _$alepha_server0.ActionPrimitiveFn<{
+    params: _$typebox.TObject<{
+      id: _$typebox.TString;
+    }>;
+    response: _$typebox.TObject<{
+      ok: _$typebox.TBoolean;
+      id: _$typebox.TOptional<_$typebox.TUnion<[_$typebox.TString, _$typebox.TInteger]>>;
+      count: _$typebox.TOptional<_$typebox.TNumber>;
+    }>;
+  }>;
+  /**
+   * Extend the trial period for a trialing subscription (admin action).
+   */
+  readonly adminExtendTrial: _$alepha_server0.ActionPrimitiveFn<{
+    params: _$typebox.TObject<{
+      id: _$typebox.TString;
+    }>;
+    body: _$typebox.TObject<{
+      days: _$typebox.TInteger;
+    }>;
+    response: _$typebox.TObject<{
+      ok: _$typebox.TBoolean;
+      id: _$typebox.TOptional<_$typebox.TUnion<[_$typebox.TString, _$typebox.TInteger]>>;
+      count: _$typebox.TOptional<_$typebox.TNumber>;
+    }>;
+  }>;
+}
+//#endregion
+//#region ../../src/api/subscriptions/controllers/SubscriptionController.d.ts
+declare class SubscriptionController {
+  protected readonly url = "/subscriptions";
+  protected readonly group = "subscriptions";
+  protected readonly service: SubscriptionService;
+  protected readonly config: SubscriptionConfig;
+  /**
+   * List available subscription plans with pricing.
+   */
+  readonly getPlans: _$alepha_server0.ActionPrimitiveFn<{
+    response: _$typebox.TArray<_$typebox.TObject<{
+      id: _$typebox.TString;
+      name: _$typebox.TString;
+      description: _$typebox.TOptional<_$typebox.TString>;
+      pricing: _$typebox.TArray<_$typebox.TObject<{
+        interval: _$typebox.TUnsafe<"monthly" | "yearly">;
+        amount: _$typebox.TInteger;
+        currency: _$typebox.TString;
+      }>>;
+      features: _$typebox.TArray<_$typebox.TString>;
+      limits: _$typebox.TRecord<"^.*$", _$typebox.TInteger>;
+      trial: _$typebox.TOptional<_$typebox.TObject<{
+        days: _$typebox.TInteger;
+        requirePaymentMethod: _$typebox.TBoolean;
+      }>>;
+      order: _$typebox.TInteger;
+    }>>;
+  }>;
+  /**
+   * Get the current organization's subscription.
+   */
+  readonly getMySubscription: _$alepha_server0.ActionPrimitiveFn<{
+    response: _$typebox.TObject<{
+      id: PgAttr<PgAttr<_$typebox.TString, typeof PG_PRIMARY_KEY>, typeof PG_DEFAULT>;
+      version: PgAttr<PgAttr<_$typebox.TInteger, typeof PG_VERSION>, typeof PG_DEFAULT>;
+      createdAt: PgAttr<PgAttr<_$typebox.TString, typeof PG_CREATED_AT>, typeof PG_DEFAULT>;
+      updatedAt: PgAttr<PgAttr<_$typebox.TString, typeof PG_UPDATED_AT>, typeof PG_DEFAULT>;
+      organizationId: PgAttr<_$typebox.TString, typeof PG_ORGANIZATION>;
+      planId: _$typebox.TString;
+      interval: _$typebox.TUnsafe<"monthly" | "yearly">;
+      status: _$typebox.TUnsafe<"trialing" | "active" | "past_due" | "suspended" | "cancelled" | "expired">;
+      currentPeriodStart: _$typebox.TString;
+      currentPeriodEnd: _$typebox.TString;
+      trialStart: _$typebox.TOptional<_$typebox.TString>;
+      trialEnd: _$typebox.TOptional<_$typebox.TString>;
+      cancelledAt: _$typebox.TOptional<_$typebox.TString>;
+      cancelReason: _$typebox.TOptional<_$typebox.TString>;
+      cancelAtPeriodEnd: _$typebox.TBoolean;
+      lastPaymentIntentId: _$typebox.TOptional<_$typebox.TString>;
+      lastPaymentAt: _$typebox.TOptional<_$typebox.TString>;
+      nextBillingAt: _$typebox.TOptional<_$typebox.TString>;
+      dunningStartedAt: _$typebox.TOptional<_$typebox.TString>;
+      dunningAttempt: _$typebox.TInteger;
+      dunningNextRetryAt: _$typebox.TOptional<_$typebox.TString>;
+      pendingPlanId: _$typebox.TOptional<_$typebox.TString>;
+      pendingInterval: _$typebox.TOptional<_$typebox.TUnsafe<"monthly" | "yearly">>;
+      metadata: _$typebox.TOptional<_$typebox.TRecord<"^.*$", _$typebox.TAny>>;
+    }>;
+  }>;
+  /**
+   * Create a new subscription for the current organization.
+   */
+  readonly subscribe: _$alepha_server0.ActionPrimitiveFn<{
+    body: _$typebox.TObject<{
+      planId: _$typebox.TString;
+      interval: _$typebox.TUnsafe<"monthly" | "yearly">;
+      paymentMethodId: _$typebox.TOptional<_$typebox.TString>;
+      skipTrial: _$typebox.TOptional<_$typebox.TBoolean>;
+      metadata: _$typebox.TOptional<_$typebox.TRecord<"^.*$", _$typebox.TAny>>;
+    }>;
+    response: _$typebox.TObject<{
+      id: PgAttr<PgAttr<_$typebox.TString, typeof PG_PRIMARY_KEY>, typeof PG_DEFAULT>;
+      version: PgAttr<PgAttr<_$typebox.TInteger, typeof PG_VERSION>, typeof PG_DEFAULT>;
+      createdAt: PgAttr<PgAttr<_$typebox.TString, typeof PG_CREATED_AT>, typeof PG_DEFAULT>;
+      updatedAt: PgAttr<PgAttr<_$typebox.TString, typeof PG_UPDATED_AT>, typeof PG_DEFAULT>;
+      organizationId: PgAttr<_$typebox.TString, typeof PG_ORGANIZATION>;
+      planId: _$typebox.TString;
+      interval: _$typebox.TUnsafe<"monthly" | "yearly">;
+      status: _$typebox.TUnsafe<"trialing" | "active" | "past_due" | "suspended" | "cancelled" | "expired">;
+      currentPeriodStart: _$typebox.TString;
+      currentPeriodEnd: _$typebox.TString;
+      trialStart: _$typebox.TOptional<_$typebox.TString>;
+      trialEnd: _$typebox.TOptional<_$typebox.TString>;
+      cancelledAt: _$typebox.TOptional<_$typebox.TString>;
+      cancelReason: _$typebox.TOptional<_$typebox.TString>;
+      cancelAtPeriodEnd: _$typebox.TBoolean;
+      lastPaymentIntentId: _$typebox.TOptional<_$typebox.TString>;
+      lastPaymentAt: _$typebox.TOptional<_$typebox.TString>;
+      nextBillingAt: _$typebox.TOptional<_$typebox.TString>;
+      dunningStartedAt: _$typebox.TOptional<_$typebox.TString>;
+      dunningAttempt: _$typebox.TInteger;
+      dunningNextRetryAt: _$typebox.TOptional<_$typebox.TString>;
+      pendingPlanId: _$typebox.TOptional<_$typebox.TString>;
+      pendingInterval: _$typebox.TOptional<_$typebox.TUnsafe<"monthly" | "yearly">>;
+      metadata: _$typebox.TOptional<_$typebox.TRecord<"^.*$", _$typebox.TAny>>;
+    }>;
+  }>;
+  /**
+   * Change the plan for the current organization's subscription.
+   */
+  readonly changePlan: _$alepha_server0.ActionPrimitiveFn<{
+    body: _$typebox.TObject<{
+      planId: _$typebox.TString;
+      interval: _$typebox.TOptional<_$typebox.TUnsafe<"monthly" | "yearly">>;
+      immediate: _$typebox.TOptional<_$typebox.TBoolean>;
+    }>;
+    response: _$typebox.TObject<{
+      id: PgAttr<PgAttr<_$typebox.TString, typeof PG_PRIMARY_KEY>, typeof PG_DEFAULT>;
+      version: PgAttr<PgAttr<_$typebox.TInteger, typeof PG_VERSION>, typeof PG_DEFAULT>;
+      createdAt: PgAttr<PgAttr<_$typebox.TString, typeof PG_CREATED_AT>, typeof PG_DEFAULT>;
+      updatedAt: PgAttr<PgAttr<_$typebox.TString, typeof PG_UPDATED_AT>, typeof PG_DEFAULT>;
+      organizationId: PgAttr<_$typebox.TString, typeof PG_ORGANIZATION>;
+      planId: _$typebox.TString;
+      interval: _$typebox.TUnsafe<"monthly" | "yearly">;
+      status: _$typebox.TUnsafe<"trialing" | "active" | "past_due" | "suspended" | "cancelled" | "expired">;
+      currentPeriodStart: _$typebox.TString;
+      currentPeriodEnd: _$typebox.TString;
+      trialStart: _$typebox.TOptional<_$typebox.TString>;
+      trialEnd: _$typebox.TOptional<_$typebox.TString>;
+      cancelledAt: _$typebox.TOptional<_$typebox.TString>;
+      cancelReason: _$typebox.TOptional<_$typebox.TString>;
+      cancelAtPeriodEnd: _$typebox.TBoolean;
+      lastPaymentIntentId: _$typebox.TOptional<_$typebox.TString>;
+      lastPaymentAt: _$typebox.TOptional<_$typebox.TString>;
+      nextBillingAt: _$typebox.TOptional<_$typebox.TString>;
+      dunningStartedAt: _$typebox.TOptional<_$typebox.TString>;
+      dunningAttempt: _$typebox.TInteger;
+      dunningNextRetryAt: _$typebox.TOptional<_$typebox.TString>;
+      pendingPlanId: _$typebox.TOptional<_$typebox.TString>;
+      pendingInterval: _$typebox.TOptional<_$typebox.TUnsafe<"monthly" | "yearly">>;
+      metadata: _$typebox.TOptional<_$typebox.TRecord<"^.*$", _$typebox.TAny>>;
+    }>;
+  }>;
+  /**
+   * Cancel the current organization's subscription.
+   */
+  readonly cancel: _$alepha_server0.ActionPrimitiveFn<{
+    body: _$typebox.TObject<{
+      reason: _$typebox.TOptional<_$typebox.TString>;
+      immediate: _$typebox.TOptional<_$typebox.TBoolean>;
+    }>;
+    response: _$typebox.TObject<{
+      ok: _$typebox.TBoolean;
+      id: _$typebox.TOptional<_$typebox.TUnion<[_$typebox.TString, _$typebox.TInteger]>>;
+      count: _$typebox.TOptional<_$typebox.TNumber>;
+    }>;
+  }>;
+  /**
+   * Resume a cancelled subscription before the period ends.
+   */
+  readonly resume: _$alepha_server0.ActionPrimitiveFn<{
+    response: _$typebox.TObject<{
+      ok: _$typebox.TBoolean;
+      id: _$typebox.TOptional<_$typebox.TUnion<[_$typebox.TString, _$typebox.TInteger]>>;
+      count: _$typebox.TOptional<_$typebox.TNumber>;
+    }>;
+  }>;
+  /**
+   * Get the billing event history for the current organization's subscription.
+   */
+  readonly getSubscriptionHistory: _$alepha_server0.ActionPrimitiveFn<{
+    response: _$typebox.TArray<_$typebox.TObject<{
+      id: PgAttr<PgAttr<_$typebox.TString, typeof PG_PRIMARY_KEY>, typeof PG_DEFAULT>;
+      createdAt: PgAttr<PgAttr<_$typebox.TString, typeof PG_CREATED_AT>, typeof PG_DEFAULT>;
+      subscriptionId: PgAttr<_$typebox.TString, typeof PG_REF>;
+      organizationId: PgAttr<_$typebox.TString, typeof PG_ORGANIZATION>;
+      type: _$typebox.TUnsafe<"past_due" | "suspended" | "cancelled" | "expired" | "created" | "trial_started" | "trial_ended" | "activated" | "renewed" | "payment_failed" | "payment_retried" | "reactivated" | "plan_changed" | "plan_change_scheduled" | "resumed">;
+      previousStatus: _$typebox.TOptional<_$typebox.TString>;
+      newStatus: _$typebox.TOptional<_$typebox.TString>;
+      previousPlanId: _$typebox.TOptional<_$typebox.TString>;
+      newPlanId: _$typebox.TOptional<_$typebox.TString>;
+      paymentIntentId: _$typebox.TOptional<_$typebox.TString>;
+      amount: _$typebox.TOptional<_$typebox.TInteger>;
+      currency: _$typebox.TOptional<_$typebox.TString>;
+      triggeredBy: _$typebox.TOptional<_$typebox.TString>;
+      userId: _$typebox.TOptional<_$typebox.TString>;
+      note: _$typebox.TOptional<_$typebox.TString>;
+    }>>;
+  }>;
+  /**
+   * Get the feature and usage limit entitlements for the current organization.
+   */
+  readonly getEntitlements: _$alepha_server0.ActionPrimitiveFn<{
+    response: _$typebox.TObject<{
+      planId: _$typebox.TString;
+      planName: _$typebox.TString;
+      status: _$typebox.TUnsafe<"trialing" | "active" | "past_due" | "suspended" | "cancelled" | "expired">;
+      features: _$typebox.TArray<_$typebox.TString>;
+      limits: _$typebox.TRecord<"^.*$", _$typebox.TInteger>;
+      trialEndsAt: _$typebox.TOptional<_$typebox.TString>;
+      periodEndsAt: _$typebox.TString;
+      cancelledAt: _$typebox.TOptional<_$typebox.TString>;
+    }>;
+  }>;
+}
+//#endregion
+//#region ../../src/api/subscriptions/jobs/SubscriptionJobs.d.ts
+interface EventContext$1 {
+  previousStatus?: string;
+  newStatus?: string;
+  paymentIntentId?: string;
+  amount?: number;
+  currency?: string;
+  triggeredBy?: string;
+  note?: string;
+}
+declare class SubscriptionJobs {
+  protected readonly log: _$alepha_logger0.Logger;
+  protected readonly dateTime: DateTimeProvider;
+  protected readonly paymentService: PaymentService;
+  protected readonly config: SubscriptionConfig;
+  protected readonly subscriptionRepo: _$alepha_orm0.Repository<_$typebox.TObject<{
+    id: _$alepha_orm0.PgAttr<_$alepha_orm0.PgAttr<_$typebox.TString, typeof _$alepha_orm0.PG_PRIMARY_KEY>, typeof _$alepha_orm0.PG_DEFAULT>;
+    version: _$alepha_orm0.PgAttr<_$alepha_orm0.PgAttr<_$typebox.TInteger, typeof _$alepha_orm0.PG_VERSION>, typeof _$alepha_orm0.PG_DEFAULT>;
+    createdAt: _$alepha_orm0.PgAttr<_$alepha_orm0.PgAttr<_$typebox.TString, typeof _$alepha_orm0.PG_CREATED_AT>, typeof _$alepha_orm0.PG_DEFAULT>;
+    updatedAt: _$alepha_orm0.PgAttr<_$alepha_orm0.PgAttr<_$typebox.TString, typeof _$alepha_orm0.PG_UPDATED_AT>, typeof _$alepha_orm0.PG_DEFAULT>;
+    organizationId: _$alepha_orm0.PgAttr<_$typebox.TString, typeof _$alepha_orm0.PG_ORGANIZATION>;
+    planId: _$typebox.TString;
+    interval: _$typebox.TUnsafe<"monthly" | "yearly">;
+    status: _$typebox.TUnsafe<"trialing" | "active" | "past_due" | "suspended" | "cancelled" | "expired">;
+    currentPeriodStart: _$typebox.TString;
+    currentPeriodEnd: _$typebox.TString;
+    trialStart: _$typebox.TOptional<_$typebox.TString>;
+    trialEnd: _$typebox.TOptional<_$typebox.TString>;
+    cancelledAt: _$typebox.TOptional<_$typebox.TString>;
+    cancelReason: _$typebox.TOptional<_$typebox.TString>;
+    cancelAtPeriodEnd: _$typebox.TBoolean;
+    lastPaymentIntentId: _$typebox.TOptional<_$typebox.TString>;
+    lastPaymentAt: _$typebox.TOptional<_$typebox.TString>;
+    nextBillingAt: _$typebox.TOptional<_$typebox.TString>;
+    dunningStartedAt: _$typebox.TOptional<_$typebox.TString>;
+    dunningAttempt: _$typebox.TInteger;
+    dunningNextRetryAt: _$typebox.TOptional<_$typebox.TString>;
+    pendingPlanId: _$typebox.TOptional<_$typebox.TString>;
+    pendingInterval: _$typebox.TOptional<_$typebox.TUnsafe<"monthly" | "yearly">>;
+    metadata: _$typebox.TOptional<_$typebox.TRecord<"^.*$", _$typebox.TAny>>;
+  }>>;
+  protected readonly eventRepo: _$alepha_orm0.Repository<_$typebox.TObject<{
+    id: _$alepha_orm0.PgAttr<_$alepha_orm0.PgAttr<_$typebox.TString, typeof _$alepha_orm0.PG_PRIMARY_KEY>, typeof _$alepha_orm0.PG_DEFAULT>;
+    createdAt: _$alepha_orm0.PgAttr<_$alepha_orm0.PgAttr<_$typebox.TString, typeof _$alepha_orm0.PG_CREATED_AT>, typeof _$alepha_orm0.PG_DEFAULT>;
+    subscriptionId: _$alepha_orm0.PgAttr<_$typebox.TString, typeof _$alepha_orm0.PG_REF>;
+    organizationId: _$alepha_orm0.PgAttr<_$typebox.TString, typeof _$alepha_orm0.PG_ORGANIZATION>;
+    type: _$typebox.TUnsafe<"past_due" | "suspended" | "cancelled" | "expired" | "created" | "trial_started" | "trial_ended" | "activated" | "renewed" | "payment_failed" | "payment_retried" | "reactivated" | "plan_changed" | "plan_change_scheduled" | "resumed">;
+    previousStatus: _$typebox.TOptional<_$typebox.TString>;
+    newStatus: _$typebox.TOptional<_$typebox.TString>;
+    previousPlanId: _$typebox.TOptional<_$typebox.TString>;
+    newPlanId: _$typebox.TOptional<_$typebox.TString>;
+    paymentIntentId: _$typebox.TOptional<_$typebox.TString>;
+    amount: _$typebox.TOptional<_$typebox.TInteger>;
+    currency: _$typebox.TOptional<_$typebox.TString>;
+    triggeredBy: _$typebox.TOptional<_$typebox.TString>;
+    userId: _$typebox.TOptional<_$typebox.TString>;
+    note: _$typebox.TOptional<_$typebox.TString>;
+  }>>;
+  /**
+   * Record a subscription event in the event log.
+   */
+  protected recordEvent(subscriptionId: string, organizationId: string, type: SubscriptionEventEntity["type"], context?: EventContext$1): Promise<void>;
+  /**
+   * Creates payment intents for subscriptions due for renewal.
+   * Runs hourly.
+   */
+  readonly billingCycle: _$alepha_api_jobs0.JobPrimitive<_$typebox.TSchema>;
+  /**
+   * Retries failed payments on the dunning schedule.
+   * Runs hourly.
+   */
+  readonly dunningRetry: _$alepha_api_jobs0.JobPrimitive<_$typebox.TSchema>;
+  /**
+   * Handles trial expirations.
+   * Runs hourly.
+   */
+  readonly trialExpiry: _$alepha_api_jobs0.JobPrimitive<_$typebox.TSchema>;
+  /**
+   * Expires cancelled subscriptions that reached period end.
+   * Runs hourly.
+   */
+  readonly expirationSweep: _$alepha_api_jobs0.JobPrimitive<_$typebox.TSchema>;
+  /**
+   * Suspends past_due subscriptions where grace period has elapsed.
+   * Runs daily at 2 AM.
+   */
+  readonly gracePeriodSweep: _$alepha_api_jobs0.JobPrimitive<_$typebox.TSchema>;
+  /**
+   * Purges old subscription events older than 365 days.
+   * Runs daily at 3 AM.
+   */
+  readonly purgeEvents: _$alepha_api_jobs0.JobPrimitive<_$typebox.TSchema>;
+}
+//#endregion
+//#region ../../src/api/subscriptions/middleware/$requireLimit.d.ts
+/**
+ * Middleware that enforces a per-organization usage limit for a resource.
+ *
+ * Resolves the organization from `args[0].user.organization`, increments the
+ * usage counter for the given resource, and throws `ForbiddenError` if the
+ * plan limit has been reached.
+ * Throws `ForbiddenError` if no organization is present or the limit is exceeded.
+ *
+ * ```typescript
+ * class ApiController {
+ *   search = $action({
+ *     use: [$requireLimit("api_calls")],
+ *     handler: async ({ query }) => { ... },
+ *   });
+ * }
+ * ```
+ *
+ * @param resource The resource identifier to track (e.g., "api_calls", "exports").
+ */
+declare const $requireLimit: (resource: string) => Middleware;
+//#endregion
+//#region ../../src/api/subscriptions/middleware/$requirePlan.d.ts
+/**
+ * Middleware that gates access to a handler behind a subscription feature flag.
+ *
+ * Resolves the organization from `args[0].user.organization` and checks whether
+ * the organization's current plan includes the given feature.
+ * Throws `ForbiddenError` if no organization is present or the feature is not available.
+ *
+ * ```typescript
+ * class ReportController {
+ *   generate = $action({
+ *     use: [$requirePlan("advanced_reports")],
+ *     handler: async ({ user }) => { ... },
+ *   });
+ * }
+ * ```
+ *
+ * @param feature The feature identifier to check against the plan's feature list.
+ */
+declare const $requirePlan: (feature: string) => Middleware;
+//#endregion
+//#region ../../src/api/subscriptions/notifications/SubscriptionNotifications.d.ts
+declare class SubscriptionNotifications {
+  /**
+   * Sent when a trial is ending soon.
+   */
+  protected readonly trialEnding: _$alepha_api_notifications0.NotificationPrimitive<_$typebox.TObject<{
+    planName: _$typebox.TString;
+    trialEndDate: _$typebox.TString;
+    amount: _$typebox.TString;
+    interval: _$typebox.TString;
+  }>>;
+  /**
+   * Sent when a payment fails. Critical notification.
+   */
+  protected readonly paymentFailed: _$alepha_api_notifications0.NotificationPrimitive<_$typebox.TObject<{
+    planName: _$typebox.TString;
+    amount: _$typebox.TString;
+    retryDate: _$typebox.TOptional<_$typebox.TString>;
+  }>>;
+  /**
+   * Sent when a subscription is suspended due to failed payments. Critical notification.
+   */
+  protected readonly subscriptionSuspended: _$alepha_api_notifications0.NotificationPrimitive<_$typebox.TObject<{
+    planName: _$typebox.TString;
+  }>>;
+  /**
+   * Sent when a subscription is successfully renewed.
+   */
+  protected readonly subscriptionRenewed: _$alepha_api_notifications0.NotificationPrimitive<_$typebox.TObject<{
+    planName: _$typebox.TString;
+    amount: _$typebox.TString;
+    nextBillingDate: _$typebox.TString;
+  }>>;
+  /**
+   * Sent when a subscription plan is changed.
+   */
+  protected readonly planChanged: _$alepha_api_notifications0.NotificationPrimitive<_$typebox.TObject<{
+    oldPlanName: _$typebox.TString;
+    newPlanName: _$typebox.TString;
+    effectiveDate: _$typebox.TString;
+  }>>;
+  /**
+   * Sent when a subscription is cancelled.
+   */
+  protected readonly cancellationConfirmed: _$alepha_api_notifications0.NotificationPrimitive<_$typebox.TObject<{
+    planName: _$typebox.TString;
+    accessUntil: _$typebox.TOptional<_$typebox.TString>;
+  }>>;
+}
+//#endregion
+//#region ../../src/api/subscriptions/schemas/cancelSubscriptionSchema.d.ts
+declare const cancelSubscriptionSchema: _$typebox.TObject<{
+  reason: _$typebox.TOptional<_$typebox.TString>;
+  immediate: _$typebox.TOptional<_$typebox.TBoolean>;
+}>;
+type CancelSubscription = Static<typeof cancelSubscriptionSchema>;
+//#endregion
+//#region ../../src/api/subscriptions/schemas/changePlanSchema.d.ts
+declare const changePlanSchema: _$typebox.TObject<{
+  planId: _$typebox.TString;
+  interval: _$typebox.TOptional<_$typebox.TUnsafe<"monthly" | "yearly">>;
+  immediate: _$typebox.TOptional<_$typebox.TBoolean>;
+}>;
+type ChangePlan = Static<typeof changePlanSchema>;
+//#endregion
+//#region ../../src/api/subscriptions/schemas/createSubscriptionSchema.d.ts
+declare const createSubscriptionSchema: _$typebox.TObject<{
+  planId: _$typebox.TString;
+  interval: _$typebox.TUnsafe<"monthly" | "yearly">;
+  paymentMethodId: _$typebox.TOptional<_$typebox.TString>;
+  skipTrial: _$typebox.TOptional<_$typebox.TBoolean>;
+  metadata: _$typebox.TOptional<_$typebox.TRecord<"^.*$", _$typebox.TAny>>;
+}>;
+type CreateSubscription = Static<typeof createSubscriptionSchema>;
+//#endregion
+//#region ../../src/api/subscriptions/schemas/mrrSchema.d.ts
+declare const mrrSchema: _$typebox.TObject<{
+  total: _$typebox.TInteger;
+  byPlan: _$typebox.TRecord<"^.*$", _$typebox.TInteger>;
+  growth: _$typebox.TInteger;
+  newMrr: _$typebox.TInteger;
+  expansionMrr: _$typebox.TInteger;
+  contractionMrr: _$typebox.TInteger;
+  churnMrr: _$typebox.TInteger;
+}>;
+type MrrData = Static<typeof mrrSchema>;
+//#endregion
+//#region ../../src/api/subscriptions/schemas/planResourceSchema.d.ts
+declare const planResourceSchema: _$typebox.TObject<{
+  id: _$typebox.TString;
+  name: _$typebox.TString;
+  description: _$typebox.TOptional<_$typebox.TString>;
+  pricing: _$typebox.TArray<_$typebox.TObject<{
+    interval: _$typebox.TUnsafe<"monthly" | "yearly">;
+    amount: _$typebox.TInteger;
+    currency: _$typebox.TString;
+  }>>;
+  features: _$typebox.TArray<_$typebox.TString>;
+  limits: _$typebox.TRecord<"^.*$", _$typebox.TInteger>;
+  trial: _$typebox.TOptional<_$typebox.TObject<{
+    days: _$typebox.TInteger;
+    requirePaymentMethod: _$typebox.TBoolean;
+  }>>;
+  order: _$typebox.TInteger;
+}>;
+type PlanResource = Static<typeof planResourceSchema>;
+//#endregion
+//#region ../../src/api/subscriptions/schemas/subscriptionEventResourceSchema.d.ts
+declare const subscriptionEventResourceSchema: _$typebox.TObject<{
+  id: PgAttr<PgAttr<_$typebox.TString, typeof PG_PRIMARY_KEY>, typeof PG_DEFAULT>;
+  createdAt: PgAttr<PgAttr<_$typebox.TString, typeof PG_CREATED_AT>, typeof PG_DEFAULT>;
+  subscriptionId: PgAttr<_$typebox.TString, typeof PG_REF>;
+  organizationId: PgAttr<_$typebox.TString, typeof PG_ORGANIZATION>;
+  type: _$typebox.TUnsafe<"past_due" | "suspended" | "cancelled" | "expired" | "created" | "trial_started" | "trial_ended" | "activated" | "renewed" | "payment_failed" | "payment_retried" | "reactivated" | "plan_changed" | "plan_change_scheduled" | "resumed">;
+  previousStatus: _$typebox.TOptional<_$typebox.TString>;
+  newStatus: _$typebox.TOptional<_$typebox.TString>;
+  previousPlanId: _$typebox.TOptional<_$typebox.TString>;
+  newPlanId: _$typebox.TOptional<_$typebox.TString>;
+  paymentIntentId: _$typebox.TOptional<_$typebox.TString>;
+  amount: _$typebox.TOptional<_$typebox.TInteger>;
+  currency: _$typebox.TOptional<_$typebox.TString>;
+  triggeredBy: _$typebox.TOptional<_$typebox.TString>;
+  userId: _$typebox.TOptional<_$typebox.TString>;
+  note: _$typebox.TOptional<_$typebox.TString>;
+}>;
+type SubscriptionEventResource = Static<typeof subscriptionEventResourceSchema>;
+//#endregion
+//#region ../../src/api/subscriptions/schemas/subscriptionResourceSchema.d.ts
+declare const subscriptionResourceSchema: _$typebox.TObject<{
+  id: PgAttr<PgAttr<_$typebox.TString, typeof PG_PRIMARY_KEY>, typeof PG_DEFAULT>;
+  version: PgAttr<PgAttr<_$typebox.TInteger, typeof PG_VERSION>, typeof PG_DEFAULT>;
+  createdAt: PgAttr<PgAttr<_$typebox.TString, typeof PG_CREATED_AT>, typeof PG_DEFAULT>;
+  updatedAt: PgAttr<PgAttr<_$typebox.TString, typeof PG_UPDATED_AT>, typeof PG_DEFAULT>;
+  organizationId: PgAttr<_$typebox.TString, typeof PG_ORGANIZATION>;
+  planId: _$typebox.TString;
+  interval: _$typebox.TUnsafe<"monthly" | "yearly">;
+  status: _$typebox.TUnsafe<"trialing" | "active" | "past_due" | "suspended" | "cancelled" | "expired">;
+  currentPeriodStart: _$typebox.TString;
+  currentPeriodEnd: _$typebox.TString;
+  trialStart: _$typebox.TOptional<_$typebox.TString>;
+  trialEnd: _$typebox.TOptional<_$typebox.TString>;
+  cancelledAt: _$typebox.TOptional<_$typebox.TString>;
+  cancelReason: _$typebox.TOptional<_$typebox.TString>;
+  cancelAtPeriodEnd: _$typebox.TBoolean;
+  lastPaymentIntentId: _$typebox.TOptional<_$typebox.TString>;
+  lastPaymentAt: _$typebox.TOptional<_$typebox.TString>;
+  nextBillingAt: _$typebox.TOptional<_$typebox.TString>;
+  dunningStartedAt: _$typebox.TOptional<_$typebox.TString>;
+  dunningAttempt: _$typebox.TInteger;
+  dunningNextRetryAt: _$typebox.TOptional<_$typebox.TString>;
+  pendingPlanId: _$typebox.TOptional<_$typebox.TString>;
+  pendingInterval: _$typebox.TOptional<_$typebox.TUnsafe<"monthly" | "yearly">>;
+  metadata: _$typebox.TOptional<_$typebox.TRecord<"^.*$", _$typebox.TAny>>;
+}>;
+type SubscriptionResource = Static<typeof subscriptionResourceSchema>;
+//#endregion
+//#region ../../src/api/subscriptions/services/BillingService.d.ts
+interface PaymentEvent {
+  intentId: string;
+  amount: number;
+  currency: string;
+  metadata?: unknown;
+}
+interface EventContext {
+  previousStatus?: string;
+  newStatus?: string;
+  previousPlanId?: string;
+  newPlanId?: string;
+  paymentIntentId?: string;
+  amount?: number;
+  currency?: string;
+  triggeredBy?: string;
+  userId?: string;
+  note?: string;
+}
+declare class BillingService {
+  protected readonly alepha: Alepha;
+  protected readonly log: _$alepha_logger0.Logger;
+  protected readonly dateTime: DateTimeProvider;
+  protected readonly subscriptionRepo: _$alepha_orm0.Repository<_$typebox.TObject<{
+    id: _$alepha_orm0.PgAttr<_$alepha_orm0.PgAttr<_$typebox.TString, typeof _$alepha_orm0.PG_PRIMARY_KEY>, typeof _$alepha_orm0.PG_DEFAULT>;
+    version: _$alepha_orm0.PgAttr<_$alepha_orm0.PgAttr<_$typebox.TInteger, typeof _$alepha_orm0.PG_VERSION>, typeof _$alepha_orm0.PG_DEFAULT>;
+    createdAt: _$alepha_orm0.PgAttr<_$alepha_orm0.PgAttr<_$typebox.TString, typeof _$alepha_orm0.PG_CREATED_AT>, typeof _$alepha_orm0.PG_DEFAULT>;
+    updatedAt: _$alepha_orm0.PgAttr<_$alepha_orm0.PgAttr<_$typebox.TString, typeof _$alepha_orm0.PG_UPDATED_AT>, typeof _$alepha_orm0.PG_DEFAULT>;
+    organizationId: _$alepha_orm0.PgAttr<_$typebox.TString, typeof _$alepha_orm0.PG_ORGANIZATION>;
+    planId: _$typebox.TString;
+    interval: _$typebox.TUnsafe<"monthly" | "yearly">;
+    status: _$typebox.TUnsafe<"trialing" | "active" | "past_due" | "suspended" | "cancelled" | "expired">;
+    currentPeriodStart: _$typebox.TString;
+    currentPeriodEnd: _$typebox.TString;
+    trialStart: _$typebox.TOptional<_$typebox.TString>;
+    trialEnd: _$typebox.TOptional<_$typebox.TString>;
+    cancelledAt: _$typebox.TOptional<_$typebox.TString>;
+    cancelReason: _$typebox.TOptional<_$typebox.TString>;
+    cancelAtPeriodEnd: _$typebox.TBoolean;
+    lastPaymentIntentId: _$typebox.TOptional<_$typebox.TString>;
+    lastPaymentAt: _$typebox.TOptional<_$typebox.TString>;
+    nextBillingAt: _$typebox.TOptional<_$typebox.TString>;
+    dunningStartedAt: _$typebox.TOptional<_$typebox.TString>;
+    dunningAttempt: _$typebox.TInteger;
+    dunningNextRetryAt: _$typebox.TOptional<_$typebox.TString>;
+    pendingPlanId: _$typebox.TOptional<_$typebox.TString>;
+    pendingInterval: _$typebox.TOptional<_$typebox.TUnsafe<"monthly" | "yearly">>;
+    metadata: _$typebox.TOptional<_$typebox.TRecord<"^.*$", _$typebox.TAny>>;
+  }>>;
+  protected readonly eventRepo: _$alepha_orm0.Repository<_$typebox.TObject<{
+    id: _$alepha_orm0.PgAttr<_$alepha_orm0.PgAttr<_$typebox.TString, typeof _$alepha_orm0.PG_PRIMARY_KEY>, typeof _$alepha_orm0.PG_DEFAULT>;
+    createdAt: _$alepha_orm0.PgAttr<_$alepha_orm0.PgAttr<_$typebox.TString, typeof _$alepha_orm0.PG_CREATED_AT>, typeof _$alepha_orm0.PG_DEFAULT>;
+    subscriptionId: _$alepha_orm0.PgAttr<_$typebox.TString, typeof _$alepha_orm0.PG_REF>;
+    organizationId: _$alepha_orm0.PgAttr<_$typebox.TString, typeof _$alepha_orm0.PG_ORGANIZATION>;
+    type: _$typebox.TUnsafe<"past_due" | "suspended" | "cancelled" | "expired" | "created" | "trial_started" | "trial_ended" | "activated" | "renewed" | "payment_failed" | "payment_retried" | "reactivated" | "plan_changed" | "plan_change_scheduled" | "resumed">;
+    previousStatus: _$typebox.TOptional<_$typebox.TString>;
+    newStatus: _$typebox.TOptional<_$typebox.TString>;
+    previousPlanId: _$typebox.TOptional<_$typebox.TString>;
+    newPlanId: _$typebox.TOptional<_$typebox.TString>;
+    paymentIntentId: _$typebox.TOptional<_$typebox.TString>;
+    amount: _$typebox.TOptional<_$typebox.TInteger>;
+    currency: _$typebox.TOptional<_$typebox.TString>;
+    triggeredBy: _$typebox.TOptional<_$typebox.TString>;
+    userId: _$typebox.TOptional<_$typebox.TString>;
+    note: _$typebox.TOptional<_$typebox.TString>;
+  }>>;
+  protected readonly paymentService: PaymentService;
+  protected readonly config: SubscriptionConfig;
+  /**
+   * React to successful payment capture.
+   * Routes to the appropriate handler based on subscription status.
+   */
+  protected readonly onPaymentCaptured: _$alepha.HookPrimitive<"payments:captured">;
+  /**
+   * React to failed payment.
+   * Starts or advances the dunning flow.
+   */
+  protected readonly onPaymentFailed: _$alepha.HookPrimitive<"payments:failed">;
+  /**
+   * Find a subscription by its last payment intent ID.
+   * Returns null if no subscription matches.
+   */
+  protected findByPaymentIntent(intentId: string): Promise<SubscriptionEntity | null>;
+  /**
+   * Trial to active transition.
+   * Sets the first paid billing period and records activation events.
+   */
+  protected activate(sub: SubscriptionEntity, event: PaymentEvent): Promise<void>;
+  /**
+   * Active to active cycle renewal.
+   * Applies any pending plan change, then advances the billing period.
+   */
+  protected renew(sub: SubscriptionEntity, event: PaymentEvent): Promise<void>;
+  /**
+   * Recover from dunning: past_due to active.
+   * Resets all dunning state and records reactivation.
+   */
+  protected recoverFromDunning(sub: SubscriptionEntity, event: PaymentEvent): Promise<void>;
+  /**
+   * Reactivate from suspended state after a successful payment.
+   * Resets dunning, sets a fresh billing period, and records reactivation.
+   */
+  protected reactivateFromPayment(sub: SubscriptionEntity, event: PaymentEvent): Promise<void>;
+  /**
+   * Handle a failed payment: start or advance dunning.
+   * Updates dunning state and transitions to past_due if needed.
+   */
+  protected handlePaymentFailure(sub: SubscriptionEntity, event: PaymentEvent): Promise<void>;
+  /**
+   * Compute the end of a billing interval from a start date.
+   */
+  protected computeIntervalEnd(start: string, interval: "monthly" | "yearly"): string;
+  /**
+   * Record a subscription event in the event log.
+   */
+  protected recordEvent(subscriptionId: string, organizationId: string, type: SubscriptionEventEntity["type"], context?: EventContext): Promise<void>;
+}
+//#endregion
+//#region ../../src/api/subscriptions/services/UsageService.d.ts
+/**
+ * The result of a usage check or increment operation.
+ */
+interface UsageResult {
+  /**
+   * Whether the operation is allowed given the current usage and limit.
+   */
+  allowed: boolean;
+  /**
+   * Current usage count for the period.
+   */
+  current: number;
+  /**
+   * The plan limit for the resource. -1 means unlimited.
+   */
+  limit: number;
+  /**
+   * Remaining capacity. -1 means unlimited.
+   */
+  remaining: number;
+}
+/**
+ * Tracks and enforces per-organization resource usage limits.
+ *
+ * Usage counters are keyed by `organizationId:resource:YYYY-MM` and stored in the cache.
+ * Limits are resolved from the organization's current subscription plan.
+ */
+declare class UsageService {
+  protected readonly cache: CacheProvider;
+  protected readonly dateTime: DateTimeProvider;
+  protected readonly subscriptionService: SubscriptionService;
+  /**
+   * Increment a resource counter for the current period and return the usage result.
+   *
+   * @param organizationId The organization to track usage for.
+   * @param resource The resource identifier (e.g., "api_calls", "seats").
+   * @param amount Amount to increment by (default: 1).
+   */
+  increment(organizationId: string, resource: string, amount?: number): Promise<UsageResult>;
+  /**
+   * Get the current usage for a resource without incrementing.
+   *
+   * @param organizationId The organization to query usage for.
+   * @param resource The resource identifier.
+   */
+  getUsage(organizationId: string, resource: string): Promise<UsageResult>;
+  /**
+   * Reset all usage counters for an organization.
+   *
+   * Used at the start of a new billing period.
+   *
+   * @param organizationId The organization whose counters to reset.
+   */
+  resetForPeriod(organizationId: string): Promise<void>;
+  /**
+   * Build the cache key for a usage counter.
+   *
+   * Format: `organizationId:resource:YYYY-MM`
+   */
+  protected buildKey(organizationId: string, resource: string): string;
+}
+//#endregion
+//#region ../../src/api/subscriptions/index.d.ts
+declare module "alepha" {
+  interface Hooks {
+    "subscription:created": {
+      subscriptionId: string;
+      organizationId: string;
+      planId: string;
+      trial: boolean;
+    };
+    "subscription:activated": {
+      subscriptionId: string;
+      organizationId: string;
+      planId: string;
+    };
+    "subscription:renewed": {
+      subscriptionId: string;
+      organizationId: string;
+      planId: string;
+      amount: number;
+      currency: string;
+    };
+    "subscription:cancelled": {
+      subscriptionId: string;
+      organizationId: string;
+      planId: string;
+      reason?: string;
+      immediate: boolean;
+    };
+    "subscription:expired": {
+      subscriptionId: string;
+      organizationId: string;
+      planId: string;
+    };
+    "subscription:resumed": {
+      subscriptionId: string;
+      organizationId: string;
+      planId: string;
+    };
+    "subscription:plan_changed": {
+      subscriptionId: string;
+      organizationId: string;
+      oldPlanId: string;
+      newPlanId: string;
+      immediate: boolean;
+    };
+    "subscription:payment_failed": {
+      subscriptionId: string;
+      organizationId: string;
+      planId: string;
+      attempt: number;
+    };
+    "subscription:suspended": {
+      subscriptionId: string;
+      organizationId: string;
+      planId: string;
+    };
+    "subscription:reactivated": {
+      subscriptionId: string;
+      organizationId: string;
+      planId: string;
+    };
+    "subscription:trial_ending": {
+      subscriptionId: string;
+      organizationId: string;
+      planId: string;
+      endsAt: string;
+    };
+  }
+}
+/**
+ * Subscription management module — plan-based access control, billing integration,
+ * usage limits, and lifecycle events (trial, renewal, cancellation, suspension).
+ *
+ * Depends on `AlephaPayments` for payment processing — register it in your app
+ * alongside this module. Use `SubscriptionConfig` to declare your plans and limits.
+ *
+ * @module alepha.api.subscriptions
+ */
+declare const AlephaApiSubscriptions: _$alepha.Service<_$alepha.Module>;
+//#endregion
+export { $requireLimit, $requirePlan, AdminSubscriptionController, AlephaApiSubscriptions, BillingService, CancelSubscription, ChangePlan, CreateSubscription, Entitlements, MrrData, PlanDefinition, PlanResource, SubscriptionConfig, SubscriptionController, SubscriptionEntity, SubscriptionEventEntity, SubscriptionEventResource, SubscriptionJobs, SubscriptionNotifications, SubscriptionQuery, SubscriptionResource, SubscriptionService, SubscriptionSettings, SubscriptionStats, UsageResult, UsageService, cancelSubscriptionSchema, changePlanSchema, createSubscriptionSchema, entitlementsSchema, mrrSchema, planDefinitionSchema, planResourceSchema, subscriptionEventResourceSchema, subscriptionEvents, subscriptionQuerySchema, subscriptionResourceSchema, subscriptionSettingsSchema, subscriptionStatsSchema, subscriptions };
+//# sourceMappingURL=index.d.ts.map