@quickflo/entitlement-schema

Zod schema + TypeScript types for the per-app entitlement record QuickFlo uses to gate access to apps it ships (list-scrub, zoom-sms, future verticals).

Install

pnpm add @quickflo/entitlement-schema zod

zod is a peer dependency.

Use

import {
  entitlementSchema,
  type Entitlement,
  type EntitlementStatus,
  type EntitlementSource,
  makeEntitlementKey,
  ENTITLEMENTS_TABLE_NAME,
} from '@quickflo/entitlement-schema';

const parsed: Entitlement = entitlementSchema.parse(someValue);

// Composite key for the platform-org `app_entitlements` table
const key = makeEntitlementKey('org_123', 'list-scrub');
// → "org_123:list-scrub"

What an entitlement represents

Each record answers: "does this customer org have access to this app, and at what tier?"

• active — drives the paywall/refusal decision
• tier — opaque per-app string (free, pro, etc.)
• limits — numeric per-app limits (rows/month, runs/month, storage)
• features — named feature flags
• expiresAt — ISO-8601 expiration, null when no expiration
• status — lifecycle marker (free / trialing / active / past_due / canceled / incomplete)
• source — origin of the record (seed / stripe / admin)
• stripeCustomerId, stripeSubscriptionId — Stripe IDs when present
• onboardedAt, updatedAt — ISO-8601 timestamps

Records are seeded by the QuickFlo onboarding endpoint and updated by the Stripe webhook workflows. Records are never deleted; presence of a record means the org has onboarded into the app at some point.

License

Apache-2.0