pguerrerox
94b8c357b4
- add workspace-scoped billing storage, usage tracking, and add-on catalog - enforce plan entitlements for search and deep research routes - expand pricing and account UI around billing state, usage, and upgrades
328 lines
18 KiB
Markdown
328 lines
18 KiB
Markdown
# TODO: LocaleScope Pricing & Packaging Design
|
|
|
|
## Goals
|
|
- [ ] Position LocaleScope as a local market intelligence platform, not a scraper/export commodity.
|
|
- [ ] Align pricing, packaging, product capabilities, and billing enforcement to a single plan model.
|
|
- [ ] Protect infrastructure with quotas, credits, throttling, and priority processing.
|
|
- [ ] Preserve room for future AI, enrichment, API, collaboration, and enterprise expansion.
|
|
|
|
## 1) Product & Marketing Alignment
|
|
- [x] Update product messaging to emphasize:
|
|
- local market intelligence
|
|
- geographic prospecting
|
|
- territory discovery
|
|
- operational prospecting workflows
|
|
- [x] Remove or reduce copy that frames the product as lead scraping or raw export tooling.
|
|
- [x] Define a concise plan-comparison narrative for Starter, Growth, Pro, and Enterprise.
|
|
- [x] Make Growth the obvious value anchor in pricing page design and copy.
|
|
- [ ] Decide whether to update historical/internal naming artifacts separately:
|
|
- `CHANGELOG.md` historical branding references
|
|
- `package.json` package name
|
|
|
|
## 2) Canonical Plan Definitions
|
|
- [x] Create a single source of truth for canonical plan definitions in code.
|
|
- [x] Keep the canonical catalog separate from presentation metadata:
|
|
- catalog = entitlements/commercial packaging data
|
|
- presentation = pricing-card copy, marketing bullets, comparison-table labels
|
|
- [x] Keep step `#2` scoped to catalog/type design and pricing-page integration only.
|
|
- [x] Define these initial SKUs:
|
|
- `starter_monthly`
|
|
- `growth_monthly`
|
|
- `pro_monthly`
|
|
- `enterprise_custom`
|
|
- [x] Add annual counterparts with 20% discount support.
|
|
- [x] Reserve type support for future founder/LTD SKUs without adding them to the active catalog yet.
|
|
- [x] Add explicit catalog identity fields for each plan:
|
|
- `tier`
|
|
- `billingInterval`
|
|
- `isSelfServe`
|
|
- `contactSalesRequired`
|
|
- [x] Include in each plan definition:
|
|
- pricing
|
|
- monthly usage limits
|
|
- workspace/user limits
|
|
- feature flags
|
|
- queue priority / processing tier
|
|
- add-on eligibility
|
|
- [x] Treat workspace/user limits as commercial allowances first, not guaranteed enforceable constraints yet.
|
|
- [x] Use customer-facing `researchRunsPerMonth` in the initial catalog and defer internal credit-ledger semantics to step `#3`.
|
|
- [x] Add lightweight helper accessors around the catalog, for example:
|
|
- `getPlanByCode`
|
|
- `getSelfServePlans`
|
|
- `isAnnualPlan`
|
|
- `getPlanDisplayMeta`
|
|
- [x] Expand shared billing/account types only enough to support future plan display:
|
|
- current plan code nullable
|
|
- billing interval nullable
|
|
- billing status/message
|
|
- no real subscription persistence yet
|
|
- [x] Add explicit listing semantics so public pricing visibility does not depend on billing interval.
|
|
- [x] Add plan family / sibling linkage to support future annual toggles, plan switching, and analytics rollups.
|
|
- [x] Reduce quantitative pricing bullet duplication by deriving core plan facts from structured catalog limits.
|
|
- [x] Encode internal feature readiness notes for marketed-but-not-yet-enforced capabilities.
|
|
- [ ] Follow-up recommendation: clarify whether `getPlanByCode` should stay active-catalog-only or be renamed to make reserved-code behavior explicit.
|
|
- [ ] Follow-up recommendation: revisit whether `planFamily` should remain separate from `tier` or be consolidated later.
|
|
- [ ] Follow-up recommendation: consider moving shared plan price/period formatting helpers into the billing domain once account and pricing UI expand.
|
|
- [ ] Follow-up recommendation: extend readiness modeling beyond feature flags if later steps need readiness for support, processing, or add-on availability.
|
|
|
|
## 3) Packaging & Entitlement Model
|
|
- [x] Decide the internal usage model:
|
|
- plan-based research runs, or
|
|
- credit ledger with variable credit consumption per action
|
|
- [x] Recommended default: use a credit system internally and simpler plan language externally.
|
|
- [x] Keep the public catalog and pricing page centered on plan allowances, not internal billing mechanics.
|
|
- [x] Define the research credit schedule, for example:
|
|
- small local search = 1 credit
|
|
- multi-radius query = 3-5 credits
|
|
- enriched search = 10 credits
|
|
- [x] Define export limits by plan:
|
|
- Starter = 2,500/month
|
|
- Growth = 15,000/month
|
|
- Pro = 75,000/month
|
|
- [x] Define what happens at limit exhaustion:
|
|
- block
|
|
- upgrade prompt
|
|
- add-on purchase path
|
|
- enterprise/contact sales path
|
|
- [x] Implement a shared entitlement policy layer with:
|
|
- usage resources/actions
|
|
- plan-to-allowance translation helpers
|
|
- action cost estimation helpers
|
|
- pure entitlement decision helpers
|
|
- [x] Separate capability gating from allowance checks in the entitlement layer.
|
|
- [x] Add explicit allowance semantics so `null` does not silently mean allowed/unlimited.
|
|
- [x] Add canonical action policy definitions for:
|
|
- `basic_search_run`
|
|
- `deep_research_preview`
|
|
- `deep_research_batch_run`
|
|
- `csv_export`
|
|
- future `enrichment_run`
|
|
- future `api_request`
|
|
- [x] Keep step `#3` policy-only:
|
|
- no DB persistence yet
|
|
- no route enforcement yet
|
|
- no billing-provider integration yet
|
|
- [ ] Future note: `evaluateActionEntitlement()` is policy-only and later steps must provide real remaining-usage inputs from subscription/account state.
|
|
- [ ] Future note: missing readiness metadata currently implies `launch_ready`; keep readiness annotations current as new gated features are added.
|
|
- [ ] Future note: `api_requests` and `enrichments` are modeled ahead of full product implementation; do not treat them as launch-ready by default.
|
|
- [ ] Future note: deep research costing should stay aligned with preview-derived estimates and should not diverge into a second billing algorithm.
|
|
- [ ] Future note: export policy is defined, but reliable export enforcement requires a future backend export endpoint.
|
|
- [ ] Future note: usage subject remains `user` until workspace-scoped ownership and pooled usage are ready.
|
|
- [ ] Future note: `territoryMapping` currently carries deep-research capability semantics and may need a dedicated capability later if gating becomes more granular.
|
|
|
|
## 4) Feature Gates by Plan
|
|
- [x] Implement a shared feature-gate interpreter layer that resolves feature state by plan using:
|
|
- plan feature flags
|
|
- feature readiness metadata
|
|
- self-serve vs enterprise upgrade paths
|
|
- [x] Starter
|
|
- [x] CSV export
|
|
- [x] map search
|
|
- [x] radius search
|
|
- [x] basic filters
|
|
- [x] exclude automations
|
|
- [x] exclude API access
|
|
- [x] exclude enrichments
|
|
- [x] exclude CRM integrations
|
|
- [x] exclude collaboration
|
|
- [x] Growth
|
|
- [x] saved searches
|
|
- [x] territory mapping
|
|
- [x] advanced filtering
|
|
- [x] deduplication
|
|
- [x] export history
|
|
- [x] tagging & notes
|
|
- [x] faster processing
|
|
- [x] priority support
|
|
- [x] Pro
|
|
- [x] shared lists
|
|
- [x] scheduled research
|
|
- [x] bulk exports
|
|
- [x] CRM integrations
|
|
- [x] webhooks/API
|
|
- [x] enrichment credits
|
|
- [x] collaboration features
|
|
- [x] Enterprise
|
|
- [x] pooled or custom usage
|
|
- [x] SSO
|
|
- [x] SLA
|
|
- [x] white-labeling
|
|
- [x] onboarding / account management
|
|
- [x] dedicated infrastructure options
|
|
- [x] custom integrations
|
|
- [x] Align feature-gate interpretation with entitlement action mappings in shared code.
|
|
- [x] Keep step `#4` shared-policy only:
|
|
- no broad UI rollout yet
|
|
- no backend route enforcement yet
|
|
- no usage-ledger coupling yet
|
|
- [ ] Future note: make upgrade recommendations readiness-aware so users are not prompted to upgrade into tiers where the target feature is still `coming_soon`.
|
|
- [ ] Future note: consolidate action ↔ feature mapping into one canonical source shared by `entitlements.ts` and `feature-gates.ts` to avoid drift between UI gating and backend action policy.
|
|
- [ ] Future note: for Enterprise plans, included-but-not-ready features should usually resolve to `coming_soon` instead of `contact_sales`.
|
|
- [ ] Future note: revisit the fallback `coming_soon` state for unavailable or unmapped features before broad UI rollout so hidden vs upgrade vs future behavior stays intentional.
|
|
|
|
## 5) Billing & Data Model Design
|
|
- [x] Design subscription/account state separately from the canonical plan catalog.
|
|
- [x] Keep billing-provider identifiers out of the canonical catalog until payments integration work begins.
|
|
- [x] Design subscription state storage for current plan, billing interval, and status.
|
|
- [x] Design a monthly usage ledger for:
|
|
- research credits/runs
|
|
- exports
|
|
- enrichments
|
|
- API usage (future)
|
|
- [x] Design add-on purchases and remaining balances.
|
|
- [x] Define renewal/reset behavior for monthly quotas.
|
|
- [x] Define annual billing behavior and renewal terms.
|
|
- [x] Define LTD handling with monthly quotas and non-unlimited usage.
|
|
- [x] Implement workspace-scoped billing foundation storage for:
|
|
- billing accounts
|
|
- usage periods
|
|
- usage counters
|
|
- add-on purchases
|
|
- add-on balances
|
|
- [x] Add billing repository/service layers and minimal account-data integration.
|
|
- [x] Keep step `#5` foundation-only:
|
|
- no Stripe/webhook integration yet
|
|
- no route enforcement yet
|
|
- no full billing UI rollout yet
|
|
- [ ] Future note: `remaining = 0` for `not_available` resources is intentional and should stay aligned with entitlement semantics.
|
|
- [ ] Future note: expired billing periods should fail closed for current usage-window resolution until subscription lifecycle automation can advance billing periods reliably.
|
|
- [ ] Future note: consider exposing `usagePeriodId` later if enforcement, debugging, or admin tooling needs period-level traceability.
|
|
- [ ] Future note: add transactional workflows around billing-account updates, usage updates, and add-on purchase/balance mutations once real payment flows are introduced.
|
|
- [ ] Future note: `plan_code` is currently unconstrained text in the database; keep application-side validation strict unless a later migration adds stronger DB validation.
|
|
- [ ] Future note: usage ownership is workspace-scoped in storage, but current operational enforcement is still catching up to that model.
|
|
|
|
## 6) Enforcement Architecture
|
|
- [x] Create a centralized entitlement/usage policy service on the backend.
|
|
- [x] Ensure all high-cost actions check entitlements before execution.
|
|
- [x] Start with enforcement on:
|
|
- [x] research routes
|
|
- [x] Bootstrap new and existing workspaces into a usable pre-payments Starter billing state so enforcement does not hard-block all chargeable actions before subscriptions exist.
|
|
- [x] Reuse a shared deep-research estimate path so entitlement cost estimation and batch creation use the same preview-derived basis.
|
|
- [x] Add clear API responses for quota exhaustion and upgrade flows.
|
|
- [ ] Future note: the current enforcement slice should be treated as the core entitlement/runtime gate, not the full operational control layer.
|
|
- [ ] Future note: the default Starter bootstrap is a pre-payments usability policy and should be revisited when real subscription lifecycle automation is implemented.
|
|
|
|
## 7) Workspace, User, and Collaboration Readiness
|
|
- [x] Review whether current data ownership is sufficiently workspace-scoped for plan promises.
|
|
- [x] Identify gaps between current user-scoped data model and promised team/workspace packaging.
|
|
- [x] Document which catalog limits can be enforced immediately versus only represented commercially at launch.
|
|
- [x] Define how to enforce:
|
|
- [x] users included
|
|
- [x] workspace limits
|
|
- [x] shared assets/lists
|
|
- [x] collaboration permissions
|
|
- [x] Decide whether some collaboration features need phased rollout rather than immediate sale.
|
|
- [x] Add a shared workspace-readiness matrix covering:
|
|
- current ownership scope
|
|
- target ownership scope
|
|
- enforceability state
|
|
- collaboration phase definitions
|
|
- [x] Document the current collaboration phase as workspace billing with mostly personal data ownership.
|
|
- [x] Define the migration target for workspace ownership of:
|
|
- `search_jobs`
|
|
- `deep_research_batches`
|
|
- `businesses`
|
|
- `search_job_results`
|
|
- [ ] Future note: before true collaboration is sold as real runtime behavior, core domain entities need `workspace_id` ownership and repository/query updates.
|
|
- [ ] Future note: users included and workspace limits should remain soft-gated until multi-workspace UX and shared data ownership mature.
|
|
- [ ] Future note: shared lists, tagging/notes, and collaboration permissions should not be treated as hard-enforceable features until the workspace migration is complete.
|
|
|
|
## 8) Pricing Page & Account UX
|
|
- [x] Build pricing page from canonical plan definitions instead of hardcoded copy.
|
|
- [x] Derive pricing-card and comparison-table content from presentation metadata layered on top of the canonical catalog.
|
|
- [x] Add plan comparison table.
|
|
- [x] Add annual/monthly toggle.
|
|
- [x] Add upgrade CTAs and contact-sales CTA.
|
|
- [x] Add account/billing page showing:
|
|
- [x] current plan
|
|
- [x] billing interval
|
|
- [x] usage this month
|
|
- [x] remaining quota
|
|
- [x] available add-ons
|
|
- [x] upgrade options
|
|
- [x] Add quota warning UX before hard exhaustion.
|
|
- [x] Keep migration-dependent collaboration messaging honest by surfacing included-but-not-ready capabilities as `Coming soon` instead of pretending they are fully live.
|
|
- [ ] Future note: the pricing comparison table should stay aligned with workspace-readiness decisions as collaboration and shared asset features move toward workspace ownership.
|
|
- [ ] Future note: upgrade CTAs are present, but actual checkout/subscription management should remain tied to the future payments integration step.
|
|
- [ ] Future note: pricing and account UX should keep users included, workspace limits, and collaboration-adjacent promises explicitly soft-gated until workspace-owned shared data and hard enforcement are ready.
|
|
- [ ] Future note: replace placeholder upgrade CTAs in the account billing UI with a real upgrade path, pricing-page jump, contact-sales flow, or explicit `coming soon` behavior before broader rollout.
|
|
|
|
## 9) Add-On Strategy
|
|
- [x] Define export add-ons:
|
|
- +10k exports = $29
|
|
- +50k exports = $99
|
|
- [x] Define enrichment packs:
|
|
- 1,000 enrichments = $49
|
|
- [x] Reserve future add-ons for:
|
|
- AI prospecting assistant
|
|
- white-label / agency tools
|
|
- higher API capacity
|
|
- [x] Decide whether add-ons are one-time, monthly recurring, or both.
|
|
- [ ] Future note: launch active add-ons should stay limited to one-time export packs until enrichment delivery and payments lifecycle handling are live.
|
|
- [ ] Future note: recurring feature add-ons should not be sold until the underlying capabilities and subscription management flows exist end-to-end.
|
|
|
|
## 10) Payments Integration
|
|
- [ ] Choose billing provider (likely Stripe).
|
|
- [ ] Map internal SKUs to external billing products/prices.
|
|
- [ ] Support subscriptions, annual billing, add-ons, and enterprise/manual invoicing.
|
|
- [ ] Define webhook handling for subscription state changes.
|
|
- [ ] Define downgrade, cancellation, retry, and grace-period behavior.
|
|
- [ ] Add internal admin visibility for billing state.
|
|
|
|
## 11) Founder / LTD Strategy
|
|
- [ ] Decide whether to launch founder LTD at all.
|
|
- [ ] If yes, define strict quantity cap (e.g. first 100-250 customers).
|
|
- [ ] Define founder SKUs:
|
|
- Founder Plan = $249 one-time
|
|
- Founder Pro = $499 one-time
|
|
- [ ] Ensure founder plans have monthly quotas and exclude unlimited compute/API.
|
|
- [ ] Define which future features are excluded from LTD plans.
|
|
|
|
## 12) Analytics, Ops, and Revenue Instrumentation
|
|
- [ ] Track pricing-page conversion by plan.
|
|
- [ ] Track quota exhaustion events.
|
|
- [ ] Track upgrade triggers:
|
|
- export limit hit
|
|
- research limit hit
|
|
- feature-gate encounter
|
|
- [ ] Track add-on attach rate.
|
|
- [ ] Track plan mix, churn, expansion revenue, and annual conversion.
|
|
- [ ] Add internal dashboards for billing and usage health.
|
|
|
|
## 13) Operational Enforcement Follow-Up
|
|
- [ ] Add queue prioritization by plan tier.
|
|
- [ ] Add throttling/fair-usage controls.
|
|
- [ ] Add export-route enforcement once CSV/export generation moves to a backend endpoint.
|
|
- [ ] Add enrichment-route enforcement once enrichment actions/routes are implemented.
|
|
- [ ] Future note: queue prioritization is deferred until async worker routing or higher-volume queued execution becomes an active runtime path.
|
|
- [ ] Future note: throttling/fair-usage controls are deferred until higher-volume execution patterns require operational protection.
|
|
- [ ] Future note: export enforcement remains deferred until CSV/export generation moves to a backend endpoint.
|
|
- [ ] Future note: enrichment-route enforcement remains deferred until enrichment actions/routes are implemented.
|
|
|
|
## 14) Rollout Plan
|
|
- [ ] Phase 1: finalize canonical plan definitions, presentation metadata boundaries, and entitlement model.
|
|
- [ ] Phase 2: implement usage ledger and backend enforcement.
|
|
- [ ] Phase 3: review workspace, user, and collaboration readiness before expanding team/workspace promises.
|
|
- [ ] Phase 4: update pricing page and account/billing UI based on the workspace/collaboration readiness decisions.
|
|
- [ ] Phase 5: finalize add-on strategy before wiring payment products.
|
|
- [ ] Phase 6: integrate payments and subscription lifecycle handling.
|
|
- [ ] Phase 7: decide and implement founder/LTD strategy only after the core subscription path is stable.
|
|
- [ ] Phase 8: expand analytics, ops, and revenue instrumentation around the live billing and upgrade flows.
|
|
- [ ] Phase 9: launch collaboration, API, enrichment, and enterprise features as architecture matures.
|
|
- [ ] Phase 10: complete deferred operational enforcement work such as queue prioritization, throttling, and backend export enforcement when runtime scale justifies it.
|
|
|
|
## Recommended Execution Order
|
|
- [ ] Next: `#10 Payments Integration`
|
|
- [ ] Then: `#11 Founder / LTD Strategy`
|
|
- [ ] Then: `#12 Analytics, Ops, and Revenue Instrumentation`
|
|
- [ ] Keep `#13 Operational Enforcement Follow-Up` deferred until async worker routing, backend exports, or higher-volume execution patterns make it necessary.
|
|
|
|
## Open Questions
|
|
- [ ] Will research capacity be marketed as runs, credits, or both?
|
|
- [ ] Which collaboration/team features are truly launch-ready?
|
|
- [ ] Should workspace limits be hard-enforced at launch or soft-gated initially?
|
|
- [ ] Which add-ons launch on day one vs later?
|
|
- [ ] Is founder/LTD part of launch or a separate campaign?
|
|
- [ ] What exact enterprise triggers require custom sales instead of self-serve?
|
|
- [ ] Which plan data belongs in the canonical catalog versus presentation metadata?
|