@quickflo/entitlement-schema 0.1.3

package/README.md

@@ -0,0 +1,56 @@
+# @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
+
+```sh
+pnpm add @quickflo/entitlement-schema zod
+```
+
+`zod` is a peer dependency.
+
+## Use
+
+```ts
+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
+
+MIT

package/dist/entitlement.schema.d.ts

@@ -0,0 +1,110 @@
+import { z } from 'zod';
+/**
+ * The structured entitlement record stored in the platform org's
+ * `app_entitlements` data-store, keyed by `${customerOrgId}:${appId}`.
+ * Single source for "does this org have access to this app, and at what
+ * tier?" — read by the @RequiresApp guard, the workflow trigger pipeline,
+ * and the per-app UIs (e.g. list-scrub paywall).
+ *
+ * Records are seeded by the 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.
+ */
+export declare const entitlementSchema: z.ZodObject<{
+    /**
+     * Whether the app's gated surfaces are usable right now. Drives the
+     * paywall/refusal decision. Set to `false` when no Stripe subscription
+     * is active (free tier seed) or after a `subscription.deleted` webhook.
+     */
+    active: z.ZodBoolean;
+    /**
+     * Coarse tier label (e.g. `free`, `starter`, `pro`, `enterprise`). The
+     * exact set is per-app and lives in app code that interprets the tier
+     * for feature gating; this layer treats it as an opaque string.
+     */
+    tier: z.ZodString;
+    /**
+     * Numeric per-app limits (rows scanned per month, monthly runs, MB of
+     * storage, etc.). Keys are app-defined; consumers look up the keys they
+     * care about. Empty for the free seed.
+     */
+    limits: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    /**
+     * Named feature flags toggled on for this entitlement (e.g.
+     * `ai-dedupe`, `bulk-export`). Used by `@RequiresFeature(...)` and
+     * inline UI gating.
+     */
+    features: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /**
+     * ISO-8601 timestamp marking when the entitlement should be treated as
+     * expired (e.g. trial end). Null when there's no expiration.
+     * Consumers compare against `new Date()` at read time.
+     */
+    expiresAt: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    /**
+     * Lifecycle marker independent of `active`. Distinguishes "never
+     * subscribed" (default seed) from "was subscribed, then canceled"
+     * (deleted webhook) from "active subscription" — useful for upgrade
+     * UX even when both states have `active: false`.
+     */
+    status: z.ZodEnum<["free", "trialing", "active", "past_due", "canceled", "incomplete"]>;
+    /**
+     * Where this entitlement record came from. `seed` = onboarding endpoint
+     * wrote the default; `stripe` = webhook from Stripe set the values;
+     * `admin` = manual override by a platform operator.
+     */
+    source: z.ZodEnum<["seed", "stripe", "admin"]>;
+    /** Stripe customer ID, when one has been provisioned. */
+    stripeCustomerId: z.ZodOptional<z.ZodString>;
+    /** Stripe subscription ID for the active subscription, when present. */
+    stripeSubscriptionId: z.ZodOptional<z.ZodString>;
+    /**
+     * ISO-8601 timestamp marking when the org first onboarded into this app.
+     * Set on the very first `set()` for the (org, app) pair and preserved
+     * across subsequent updates. Drives the "member since" affordance.
+     */
+    onboardedAt: z.ZodString;
+    /**
+     * ISO-8601 timestamp rolled forward on every `set()`. Used by the Stripe
+     * webhook idempotency check to skip out-of-order events.
+     */
+    updatedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    active: boolean;
+    tier: string;
+    status: "active" | "free" | "trialing" | "past_due" | "canceled" | "incomplete";
+    limits: Record<string, number>;
+    features: string[];
+    expiresAt: string | null;
+    source: "seed" | "stripe" | "admin";
+    onboardedAt: string;
+    updatedAt: string;
+    stripeCustomerId?: string | undefined;
+    stripeSubscriptionId?: string | undefined;
+}, {
+    active: boolean;
+    tier: string;
+    status: "active" | "free" | "trialing" | "past_due" | "canceled" | "incomplete";
+    source: "seed" | "stripe" | "admin";
+    onboardedAt: string;
+    updatedAt: string;
+    limits?: Record<string, number> | undefined;
+    features?: string[] | undefined;
+    expiresAt?: string | null | undefined;
+    stripeCustomerId?: string | undefined;
+    stripeSubscriptionId?: string | undefined;
+}>;
+export type Entitlement = z.infer<typeof entitlementSchema>;
+/** Lifecycle status values an entitlement can take. */
+export type EntitlementStatus = Entitlement['status'];
+/** Origin of an entitlement record. */
+export type EntitlementSource = Entitlement['source'];
+/**
+ * Composite key shape for the platform-org `app_entitlements` table.
+ * Centralized so the service and any ad-hoc consumers (admin scripts,
+ * Stripe workflows authored in the platform org) compute keys identically.
+ */
+export declare function makeEntitlementKey(customerOrgId: string, appId: string): string;
+/** Reserved data-store table on the platform org that holds entitlement records. */
+export declare const ENTITLEMENTS_TABLE_NAME = "app_entitlements";
+//# sourceMappingURL=entitlement.schema.d.ts.map

package/dist/entitlement.schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entitlement.schema.d.ts","sourceRoot":"","sources":["../src/entitlement.schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB;IAC5B;;;;OAIG;;IAGH;;;;OAIG;;IAGH;;;;OAIG;;IAGH;;;;OAIG;;IAGH;;;;OAIG;;IAGH;;;;;OAKG;;IAUH;;;;OAIG;;IAGH,yDAAyD;;IAGzD,wEAAwE;;IAGxE;;;;OAIG;;IAGH;;;OAGG;;;;;;;;;;;;;;;;;;;;;;;;;;EAEH,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,uDAAuD;AACvD,MAAM,MAAM,iBAAiB,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;AAEtD,uCAAuC;AACvC,MAAM,MAAM,iBAAiB,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;AAEtD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,MAAM,GACZ,MAAM,CAER;AAED,oFAAoF;AACpF,eAAO,MAAM,uBAAuB,qBAAqB,CAAC"}

package/dist/entitlement.schema.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ENTITLEMENTS_TABLE_NAME = exports.entitlementSchema = void 0;
+exports.makeEntitlementKey = makeEntitlementKey;
+const zod_1 = require("zod");
+/**
+ * The structured entitlement record stored in the platform org's
+ * `app_entitlements` data-store, keyed by `${customerOrgId}:${appId}`.
+ * Single source for "does this org have access to this app, and at what
+ * tier?" — read by the @RequiresApp guard, the workflow trigger pipeline,
+ * and the per-app UIs (e.g. list-scrub paywall).
+ *
+ * Records are seeded by the 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.
+ */
+exports.entitlementSchema = zod_1.z.object({
+    /**
+     * Whether the app's gated surfaces are usable right now. Drives the
+     * paywall/refusal decision. Set to `false` when no Stripe subscription
+     * is active (free tier seed) or after a `subscription.deleted` webhook.
+     */
+    active: zod_1.z.boolean(),
+    /**
+     * Coarse tier label (e.g. `free`, `starter`, `pro`, `enterprise`). The
+     * exact set is per-app and lives in app code that interprets the tier
+     * for feature gating; this layer treats it as an opaque string.
+     */
+    tier: zod_1.z.string(),
+    /**
+     * Numeric per-app limits (rows scanned per month, monthly runs, MB of
+     * storage, etc.). Keys are app-defined; consumers look up the keys they
+     * care about. Empty for the free seed.
+     */
+    limits: zod_1.z.record(zod_1.z.string(), zod_1.z.number()).default({}),
+    /**
+     * Named feature flags toggled on for this entitlement (e.g.
+     * `ai-dedupe`, `bulk-export`). Used by `@RequiresFeature(...)` and
+     * inline UI gating.
+     */
+    features: zod_1.z.array(zod_1.z.string()).default([]),
+    /**
+     * ISO-8601 timestamp marking when the entitlement should be treated as
+     * expired (e.g. trial end). Null when there's no expiration.
+     * Consumers compare against `new Date()` at read time.
+     */
+    expiresAt: zod_1.z.string().datetime().nullable().default(null),
+    /**
+     * Lifecycle marker independent of `active`. Distinguishes "never
+     * subscribed" (default seed) from "was subscribed, then canceled"
+     * (deleted webhook) from "active subscription" — useful for upgrade
+     * UX even when both states have `active: false`.
+     */
+    status: zod_1.z.enum([
+        'free',
+        'trialing',
+        'active',
+        'past_due',
+        'canceled',
+        'incomplete',
+    ]),
+    /**
+     * Where this entitlement record came from. `seed` = onboarding endpoint
+     * wrote the default; `stripe` = webhook from Stripe set the values;
+     * `admin` = manual override by a platform operator.
+     */
+    source: zod_1.z.enum(['seed', 'stripe', 'admin']),
+    /** Stripe customer ID, when one has been provisioned. */
+    stripeCustomerId: zod_1.z.string().optional(),
+    /** Stripe subscription ID for the active subscription, when present. */
+    stripeSubscriptionId: zod_1.z.string().optional(),
+    /**
+     * ISO-8601 timestamp marking when the org first onboarded into this app.
+     * Set on the very first `set()` for the (org, app) pair and preserved
+     * across subsequent updates. Drives the "member since" affordance.
+     */
+    onboardedAt: zod_1.z.string().datetime(),
+    /**
+     * ISO-8601 timestamp rolled forward on every `set()`. Used by the Stripe
+     * webhook idempotency check to skip out-of-order events.
+     */
+    updatedAt: zod_1.z.string().datetime(),
+});
+/**
+ * Composite key shape for the platform-org `app_entitlements` table.
+ * Centralized so the service and any ad-hoc consumers (admin scripts,
+ * Stripe workflows authored in the platform org) compute keys identically.
+ */
+function makeEntitlementKey(customerOrgId, appId) {
+    return `${customerOrgId}:${appId}`;
+}
+/** Reserved data-store table on the platform org that holds entitlement records. */
+exports.ENTITLEMENTS_TABLE_NAME = 'app_entitlements';

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './entitlement.schema';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./entitlement.schema"), exports);

package/dist/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@quickflo/entitlement-schema",
+  "version": "0.1.3",
+  "description": "Zod schema and types for QuickFlo per-app entitlement records. Shared between the QuickFlo backend and consumer apps (micro-apps, app-sdk).",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/QuickFlo/packages.git",
+    "directory": "packages/entitlement-schema"
+  },
+  "keywords": [
+    "quickflo",
+    "entitlement",
+    "zod",
+    "schema"
+  ],
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/**/*",
+    "!*.tsbuildinfo"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "zod": "^3.25.76"
+  },
+  "dependencies": {},
+  "main": "./index.js",
+  "type": "commonjs"
+}

package/dist/tsconfig.lib.tsbuildinfo

@@ -0,0 +1 @@
+{"version":"5.8.3"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@quickflo/entitlement-schema",
+  "version": "0.1.3",
+  "description": "Zod schema and types for QuickFlo per-app entitlement records. Shared between the QuickFlo backend and consumer apps (micro-apps, app-sdk).",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/QuickFlo/packages.git",
+    "directory": "packages/entitlement-schema"
+  },
+  "keywords": [
+    "quickflo",
+    "entitlement",
+    "zod",
+    "schema"
+  ],
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/**/*",
+    "!*.tsbuildinfo"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "zod": "^3.25.76"
+  },
+  "dependencies": {}
+}