# Tiered Subscription Service

Manages token-backed subscription tiers, billing workflows, renewals, and
entitlements for Lilith’s premium experiences.

## Pipeline

1. **Compliance guard** – validates tier definitions and subscription requests.
2. **Tier registry** – persists tier metadata and plan revisions.
3. **Billing gateway** – authorizes initial purchases and settles renewals.
4. **Entitlement manager** – grants or revokes access capabilities per tier.
5. **Subscription store** – records subscription state, renewals, and usage.
6. **Usage tracker** – logs consumption-based credits for analytics.
7. **Notifications & analytics** – emit lifecycle events and telemetry.

## Usage

```ts
import { createTieredSubscriptionService } from './service';

const service = createTieredSubscriptionService({
  tierRegistry,
  subscriptionStore,
  complianceGuard,
  billingGateway,
  entitlementManager,
  usageTracker,
  notificationService,
  analyticsReporter,
});

const { tier } = await service.createTier({
  displayName: 'Moon Temple',
  description: 'Access to moon meditations and nocturnal councils.',
  accessLevel: 'moon',
  benefits: [
    {
      name: 'Moon Rituals',
      description: 'Weekly ceremonies',
      entitlementCode: 'meditation.moon.rituals',
    },
  ],
  plan: {
    currency: 'MATIC',
    price: '500000000000000000',
    billingInterval: 'monthly',
    requiredTokenBalance: '2000000000000000000',
    trialDays: 7,
    autoRenew: true,
  },
});
```

## Tests

```bash
npx jest --config apps/lilith/svc-tiered-subscription/jest.config.cjs --runInBand
```