saasfunnels 0.4.2 → 0.5.0

package/README.md

@@ -106,7 +106,11 @@ The scanner reads supported application files one at a time without the old 500-
 
 Static pricing supports literal spreads, capability/quota maps, unlimited limits, and exact Stripe lookup-key matching. It never executes customer code. Pricing definitions are inspected beyond the first ten filename matches; unrelated helpers do not count as plans.
 
-If extraction is unsupported, `.saasfunnels/setup-review.json` lists the files and reasons. Correct those declarations or review a `.saasfunnels/setup-pricing.json` file with `{ "plans": [{ "key": "pro", "name": "Pro", "features": { "export": true }, "prices": [{ "key": "price_ACTUAL_ID" }] }] }`, then resume. Use real identifiers from the connected merchant. Raw source files are never uploaded by guided setup or the pricing handoff.
+If extraction is unsupported, `.saasfunnels/setup-review.json` lists the files and reasons. Correct those declarations or prepare a targeted `.saasfunnels/setup-pricing.json` patch such as `{ "plans": [{ "key": "pro", "features": { "export": true } }] }`, then start a fresh `setup run` (changed inputs cannot resume an older run). The CLI fetches the existing normalized evidence as its baseline, including in a fresh worktree. Omitted plans, features, quotas, components, and prices are retained. Source content and credentials are never uploaded.
+
+Patch mode is the default. Components replace only their matching component key; prices change only when explicitly supplied. Use `removals: [{ "planKey": "pro", "componentKey": "extra_seats" }]` for an exact removal. A full replacement must explicitly use `"mode": "snapshot"`. Removed commercial evidence is held for administrator review, preserving the current review until selected. `withdrawDeveloperAnswers` takes question IDs; `withdrawLifecycle` takes `{family, subjectKey}` identities for explicit withdrawals. Submission and selection do not publish configuration.
+
+CLI 0.5.0 requires Setup contract 4 and stops before creating a run against an older application. Deploy the compatible server and preservation migration before releasing this CLI. Supported 0.4.x installers retain their v3 contract, with server-side completeness and removal guards.
 
 Discovery follows Git ignore rules (including custom build folders) while keeping tracked application sources and new, non-ignored source files. Standalone folders without Git use the standard source filters.
 
@@ -146,3 +150,84 @@ file. No source files or credentials belong in either upload.
 Changes to those files or application source require a fresh run. Use `--resume`
 only for unchanged interrupted work. The scan identity includes reviewed inputs
 and scanner contract version, so accepted old submissions cannot hide corrections.
+
+### Lifecycle findings for Funnel preparation
+
+The plans stage can also submit `.saasfunnels/setup-lifecycle.json`, a JSON array
+of reviewed application findings. The coding agent should inspect the actual
+billing and entitlement code and include only established facts with relative
+source paths and line numbers. This file is a structured discovery input, not an
+authorization to change subscriptions or publish Funnels. It is sent only through
+the existing approved setup upload.
+
+Each finding has `family`, `subjectKey`, `state` (`supported`, `not_applicable`, or
+`unknown`), `provenance`, `reason`, nullable `entry`/`action`, and family-specific
+`terms`. For example:
+
+```json
+[
+  {
+    "family": "trial_conversion",
+    "subjectKey": null,
+    "state": "supported",
+    "provenance": [{ "file": "src/billing.ts", "line": 42 }],
+    "reason": "Subscription creation configures a trial.",
+    "entry": null,
+    "action": null,
+    "terms": {
+      "durationDays": 14,
+      "endBehavior": "paid_conversion",
+      "paymentRequirement": "required",
+      "paidPlanKey": "pro"
+    }
+  }
+]
+```
+
+These example terms are not defaults. Use `null`/`unknown` for unresolved terms
+and real discovered keys for references. Supported families and their terms are:
+
+- `trial_conversion`: durationDays, endBehavior, paymentRequirement, paidPlanKey.
+- `feature_trial`: durationDays, endBehavior, paymentRequirement, trialKey; subjectKey identifies the feature.
+- `cancellation_save`: cancellationTiming.
+- `failed_payment_recovery`: recoveryAction, providerRecovery.
+- `reactivation`: restoration, paidPlanKey.
+- `seat_expansion` and `add_on_expansion`: quantitySourceKey, quantityBasis, includedQuantity, billingTiming; subjectKey identifies the quantity dimension or add-on.
+
+See `src/setup-lifecycle-contract.ts` for the exact enum values and bounds. Missing
+findings do not establish that a journey is unsupported. A supported or
+not-applicable finding requires source evidence. Do not infer cancellation,
+recovery, restoration or seat semantics from a plan name. Runtime connection
+verification always remains a separate application check; submitted connections
+are classified as discovered even when a local declaration says tested.
+
+Changes to this file require a fresh scan; `--resume` rejects changed input.
+Files larger than 200 KB, invalid or duplicate findings, and sensitive source
+paths are rejected. No raw source or credentials belong in the findings. This
+structured input path does not itself automatically infer lifecycle behavior
+from arbitrary application code.
+
+During the ordinary source scan, Setup also discovers a bounded set of billing
+patterns automatically. It recognizes a locally imported Stripe client, literal
+subscription/Checkout `trial_period_days`, trial-end settings needing review,
+subscription cancellation calls and `cancel_at_period_end`. An invoice-payment
+call is surfaced as an unknown recovery capability, because ordinary invoice
+payment does not establish failed-payment recovery.
+
+Findings contain only structured terms and source locations. Payment collection,
+application access after expiry, destination plans, entry/action bindings and
+provider recovery policies remain unknown unless reviewed evidence establishes
+them. Conflicting durations or cancellation timings remain unknown rather than
+being resolved by file order. Source declarations do not prove installation.
+Tests, demos, ignored/sensitive files, shadowed clients and ambiguous expressions
+are excluded. This first recognizer handles direct JavaScript/TypeScript client
+calls; imported client factories, other languages, new item-level Trial Offer
+APIs and custom lifecycle implementations still need reviewed evidence. Explicit
+reviewed declarations take precedence per family/subject, as with reviewed
+pricing declarations; they are still presented for workspace approval.
+
+Provider references: [subscription cancellation](https://docs.stripe.com/billing/subscriptions/cancel),
+[Checkout free trials](https://docs.stripe.com/payments/checkout/free-trials), and
+[invoice payment](https://docs.stripe.com/api/invoices/pay). New
+[Trial Offers](https://docs.stripe.com/billing/subscriptions/trials) are a different
+contract; this recognizer does not infer their terms from older trial parameters.

package/dist/library.js

@@ -235858,7 +235858,7 @@ function validateFeatureCatalogManifest(value) {
 
 // src/identity.ts
 var SAASFUNNELS_CLI_NAME = "saasfunnels";
-var SAASFUNNELS_CLI_VERSION = "0.4.2";
+var SAASFUNNELS_CLI_VERSION = "0.5.0";
 var SAASFUNNELS_PRODUCT_NAME = "SaaSFunnels";
 var SAASFUNNELS_DEFAULT_API_BASE_URL = "https://app.saasfunnels.ai";
 var SAASFUNNELS_ENV = Object.freeze({