@fantastic.dev/better-stripe 0.86.0 → 0.88.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +12 -0
- package/README.md +1 -1
- package/dist/client/billing/renewalObservation/active-scheduled.d.ts +6 -0
- package/dist/client/billing/renewalObservation/active-scheduled.d.ts.map +1 -0
- package/dist/client/billing/renewalObservation/active-scheduled.js +37 -0
- package/dist/client/billing/renewalObservation/active-scheduled.js.map +1 -0
- package/dist/client/billing/renewalObservation/common.d.ts +47 -0
- package/dist/client/billing/renewalObservation/common.d.ts.map +1 -0
- package/dist/client/billing/renewalObservation/common.js +39 -0
- package/dist/client/billing/renewalObservation/common.js.map +1 -0
- package/dist/client/billing/renewalObservation/configured-baseline.d.ts +76 -0
- package/dist/client/billing/renewalObservation/configured-baseline.d.ts.map +1 -0
- package/dist/client/billing/renewalObservation/configured-baseline.js +26 -0
- package/dist/client/billing/renewalObservation/configured-baseline.js.map +1 -0
- package/dist/client/billing/renewalObservation/coupon-discount-joins.d.ts +53 -0
- package/dist/client/billing/renewalObservation/coupon-discount-joins.d.ts.map +1 -0
- package/dist/client/billing/renewalObservation/coupon-discount-joins.js +103 -0
- package/dist/client/billing/renewalObservation/coupon-discount-joins.js.map +1 -0
- package/dist/client/billing/renewalObservation/invoice-tax-identity.d.ts +52 -0
- package/dist/client/billing/renewalObservation/invoice-tax-identity.d.ts.map +1 -0
- package/dist/client/billing/renewalObservation/invoice-tax-identity.js +49 -0
- package/dist/client/billing/renewalObservation/invoice-tax-identity.js.map +1 -0
- package/dist/client/billing/renewalObservation/pending-and-stage.d.ts +76 -0
- package/dist/client/billing/renewalObservation/pending-and-stage.d.ts.map +1 -0
- package/dist/client/billing/renewalObservation/pending-and-stage.js +36 -0
- package/dist/client/billing/renewalObservation/pending-and-stage.js.map +1 -0
- package/dist/client/billing/renewalObservation/phase-price-normalization.d.ts +57 -0
- package/dist/client/billing/renewalObservation/phase-price-normalization.d.ts.map +1 -0
- package/dist/client/billing/renewalObservation/phase-price-normalization.js +70 -0
- package/dist/client/billing/renewalObservation/phase-price-normalization.js.map +1 -0
- package/dist/client/billing/renewalObservation/planProjection.d.ts +8 -0
- package/dist/client/billing/renewalObservation/planProjection.d.ts.map +1 -0
- package/dist/client/billing/renewalObservation/planProjection.js +150 -0
- package/dist/client/billing/renewalObservation/planProjection.js.map +1 -0
- package/dist/client/billing/renewalObservation/reference-catalog.d.ts +37 -0
- package/dist/client/billing/renewalObservation/reference-catalog.d.ts.map +1 -0
- package/dist/client/billing/renewalObservation/reference-catalog.js +109 -0
- package/dist/client/billing/renewalObservation/reference-catalog.js.map +1 -0
- package/dist/client/billing/renewalObservation/schedule-templates.d.ts +74 -0
- package/dist/client/billing/renewalObservation/schedule-templates.d.ts.map +1 -0
- package/dist/client/billing/renewalObservation/schedule-templates.js +72 -0
- package/dist/client/billing/renewalObservation/schedule-templates.js.map +1 -0
- package/dist/client/billing/renewalObservation/scheduled-context.d.ts +44 -0
- package/dist/client/billing/renewalObservation/scheduled-context.d.ts.map +1 -0
- package/dist/client/billing/renewalObservation/scheduled-context.js +64 -0
- package/dist/client/billing/renewalObservation/scheduled-context.js.map +1 -0
- package/dist/client/billing/renewalObservation/scheduled-identity.d.ts +53 -0
- package/dist/client/billing/renewalObservation/scheduled-identity.d.ts.map +1 -0
- package/dist/client/billing/renewalObservation/scheduled-identity.js +95 -0
- package/dist/client/billing/renewalObservation/scheduled-identity.js.map +1 -0
- package/dist/client/billing/renewalObservation/scheduled-normalization.d.ts +59 -0
- package/dist/client/billing/renewalObservation/scheduled-normalization.d.ts.map +1 -0
- package/dist/client/billing/renewalObservation/scheduled-normalization.js +29 -0
- package/dist/client/billing/renewalObservation/scheduled-normalization.js.map +1 -0
- package/dist/client/billing/renewalObservation/settings-normalization.d.ts +54 -0
- package/dist/client/billing/renewalObservation/settings-normalization.d.ts.map +1 -0
- package/dist/client/billing/renewalObservation/settings-normalization.js +53 -0
- package/dist/client/billing/renewalObservation/settings-normalization.js.map +1 -0
- package/dist/client/billing/renewalObservation/stage-runner.d.ts +4 -0
- package/dist/client/billing/renewalObservation/stage-runner.d.ts.map +1 -0
- package/dist/client/billing/renewalObservation/stage-runner.js +34 -0
- package/dist/client/billing/renewalObservation/stage-runner.js.map +1 -0
- package/dist/client/billing/renewalObservation/weeklyPending.d.ts +13 -0
- package/dist/client/billing/renewalObservation/weeklyPending.d.ts.map +1 -0
- package/dist/client/billing/renewalObservation/weeklyPending.js +55 -0
- package/dist/client/billing/renewalObservation/weeklyPending.js.map +1 -0
- package/dist/client/billing/renewalV2/binding.d.ts +1 -1
- package/dist/client/billing/renewalV2/binding.d.ts.map +1 -1
- package/dist/client/billing/renewalV2/binding.js.map +1 -1
- package/dist/client/billing/renewalV2/configureInput.d.ts +1 -0
- package/dist/client/billing/renewalV2/configureInput.d.ts.map +1 -1
- package/dist/client/billing/renewalV2/configureInput.js +3 -3
- package/dist/client/billing/renewalV2/configureInput.js.map +1 -1
- package/dist/client/billing/renewalV2/configureReceipt.d.ts +19 -0
- package/dist/client/billing/renewalV2/configureReceipt.d.ts.map +1 -0
- package/dist/client/billing/renewalV2/configureReceipt.js +91 -0
- package/dist/client/billing/renewalV2/configureReceipt.js.map +1 -0
- package/dist/client/billing/renewalV2/index.d.ts +417 -0
- package/dist/client/billing/renewalV2/index.d.ts.map +1 -1
- package/dist/client/billing/renewalV2/index.js +73 -3
- package/dist/client/billing/renewalV2/index.js.map +1 -1
- package/dist/client/billing/renewalV2/observation.d.ts +19 -0
- package/dist/client/billing/renewalV2/observation.d.ts.map +1 -0
- package/dist/client/billing/renewalV2/observation.js +95 -0
- package/dist/client/billing/renewalV2/observation.js.map +1 -0
- package/dist/client/billing/renewalV2/observationInput.d.ts +77 -0
- package/dist/client/billing/renewalV2/observationInput.d.ts.map +1 -0
- package/dist/client/billing/renewalV2/observationInput.js +140 -0
- package/dist/client/billing/renewalV2/observationInput.js.map +1 -0
- package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +32 -32
- package/dist/client/connect/payoutExecutionTestHelpers.d.ts +16 -16
- package/dist/client/renewal.d.ts +4 -2
- package/dist/client/renewal.d.ts.map +1 -1
- package/dist/client/renewal.js +2 -1
- package/dist/client/renewal.js.map +1 -1
- package/dist/client/usage/observationClient.d.ts +2 -2
- package/dist/client/usage/observationClient.d.ts.map +1 -1
- package/dist/component/balanceFunding/internal/actions.d.ts +11 -11
- package/dist/component/balanceFunding/mutations.d.ts +16 -16
- package/dist/component/balanceFunding/preparationHandlers.d.ts +8 -8
- package/dist/component/usage/allowance.fixtures.d.ts +16 -16
- package/docs/client-api.md +26 -0
- package/docs/renewal-context-reads.md +5 -1
- package/docs/renewal-material-observation.md +124 -0
- package/docs/renewal-phase-assembly.md +68 -0
- package/docs/renewal-price-replacements.md +3 -0
- package/package.json +1 -1
- package/src/client/billing/renewalObservation/active-scheduled.ts +67 -0
- package/src/client/billing/renewalObservation/common.ts +83 -0
- package/src/client/billing/renewalObservation/configured-baseline.ts +55 -0
- package/src/client/billing/renewalObservation/coupon-discount-joins.ts +163 -0
- package/src/client/billing/renewalObservation/invoice-tax-identity.ts +65 -0
- package/src/client/billing/renewalObservation/pending-and-stage.ts +89 -0
- package/src/client/billing/renewalObservation/phase-price-normalization.ts +106 -0
- package/src/client/billing/renewalObservation/planProjection.ts +177 -0
- package/src/client/billing/renewalObservation/reference-catalog.ts +150 -0
- package/src/client/billing/renewalObservation/schedule-templates.ts +118 -0
- package/src/client/billing/renewalObservation/scheduled-context.ts +98 -0
- package/src/client/billing/renewalObservation/scheduled-identity.ts +175 -0
- package/src/client/billing/renewalObservation/scheduled-normalization.ts +49 -0
- package/src/client/billing/renewalObservation/settings-normalization.ts +60 -0
- package/src/client/billing/renewalObservation/stage-runner.ts +30 -0
- package/src/client/billing/renewalObservation/weeklyPending.ts +81 -0
- package/src/client/billing/renewalV2/binding.ts +4 -1
- package/src/client/billing/renewalV2/configureInput.ts +3 -3
- package/src/client/billing/renewalV2/configureReceipt.test.ts +558 -0
- package/src/client/billing/renewalV2/configureReceipt.ts +96 -0
- package/src/client/billing/renewalV2/index.ts +131 -6
- package/src/client/billing/renewalV2/observation.boundary-review.test.ts +49 -0
- package/src/client/billing/renewalV2/observation.test.ts +334 -0
- package/src/client/billing/renewalV2/observation.ts +149 -0
- package/src/client/billing/renewalV2/observationInput.ts +167 -0
- package/src/client/renewal.ts +10 -0
|
@@ -22,14 +22,6 @@ export declare const begin: import("convex/server").RegisteredMutation<"public",
|
|
|
22
22
|
requestKey: string;
|
|
23
23
|
scopeKey: string;
|
|
24
24
|
}, Promise<{
|
|
25
|
-
reason: "identity_changed" | "revision_changed" | "scope_busy";
|
|
26
|
-
retryable: false;
|
|
27
|
-
status: "conflict";
|
|
28
|
-
} | {
|
|
29
|
-
reason: "policy_invalid";
|
|
30
|
-
retryable: false;
|
|
31
|
-
status: "rejected";
|
|
32
|
-
} | {
|
|
33
25
|
operation: {
|
|
34
26
|
accountId: string;
|
|
35
27
|
operationId: import("convex/values").GenericId<"balanceFundingOperations">;
|
|
@@ -40,6 +32,14 @@ export declare const begin: import("convex/server").RegisteredMutation<"public",
|
|
|
40
32
|
} | {
|
|
41
33
|
enabled: boolean;
|
|
42
34
|
status: "unchanged";
|
|
35
|
+
} | {
|
|
36
|
+
reason: "identity_changed" | "revision_changed" | "scope_busy";
|
|
37
|
+
retryable: false;
|
|
38
|
+
status: "conflict";
|
|
39
|
+
} | {
|
|
40
|
+
reason: "policy_invalid";
|
|
41
|
+
retryable: false;
|
|
42
|
+
status: "rejected";
|
|
43
43
|
} | {
|
|
44
44
|
reason: "provider_pending";
|
|
45
45
|
retryable: true;
|
|
@@ -395,14 +395,6 @@ export declare const prepare: import("convex/server").RegisteredMutation<"public
|
|
|
395
395
|
requestKey: string;
|
|
396
396
|
scopeKey: string;
|
|
397
397
|
}, Promise<{
|
|
398
|
-
reason: "identity_changed" | "revision_changed" | "scope_busy";
|
|
399
|
-
retryable: false;
|
|
400
|
-
status: "conflict";
|
|
401
|
-
} | {
|
|
402
|
-
reason: "policy_invalid";
|
|
403
|
-
retryable: false;
|
|
404
|
-
status: "rejected";
|
|
405
|
-
} | {
|
|
406
398
|
operation: {
|
|
407
399
|
accountId: string;
|
|
408
400
|
operationId: import("convex/values").GenericId<"balanceFundingOperations">;
|
|
@@ -413,6 +405,14 @@ export declare const prepare: import("convex/server").RegisteredMutation<"public
|
|
|
413
405
|
} | {
|
|
414
406
|
enabled: boolean;
|
|
415
407
|
status: "unchanged";
|
|
408
|
+
} | {
|
|
409
|
+
reason: "identity_changed" | "revision_changed" | "scope_busy";
|
|
410
|
+
retryable: false;
|
|
411
|
+
status: "conflict";
|
|
412
|
+
} | {
|
|
413
|
+
reason: "policy_invalid";
|
|
414
|
+
retryable: false;
|
|
415
|
+
status: "rejected";
|
|
416
416
|
} | {
|
|
417
417
|
reason: "provider_pending";
|
|
418
418
|
retryable: true;
|
|
@@ -2,14 +2,6 @@ import type { Infer } from "convex/values";
|
|
|
2
2
|
import type { MutationCtx } from "../_generated/server.js";
|
|
3
3
|
import { prepareArgs, finishPreparationArgs } from "./mutationValidators.js";
|
|
4
4
|
export declare function prepareHandler(ctx: MutationCtx, args: Infer<typeof prepareArgs>): Promise<{
|
|
5
|
-
reason: "identity_changed" | "revision_changed" | "scope_busy";
|
|
6
|
-
retryable: false;
|
|
7
|
-
status: "conflict";
|
|
8
|
-
} | {
|
|
9
|
-
reason: "policy_invalid";
|
|
10
|
-
retryable: false;
|
|
11
|
-
status: "rejected";
|
|
12
|
-
} | {
|
|
13
5
|
operation: {
|
|
14
6
|
accountId: string;
|
|
15
7
|
operationId: import("convex/values").GenericId<"balanceFundingOperations">;
|
|
@@ -20,6 +12,14 @@ export declare function prepareHandler(ctx: MutationCtx, args: Infer<typeof prep
|
|
|
20
12
|
} | {
|
|
21
13
|
enabled: boolean;
|
|
22
14
|
status: "unchanged";
|
|
15
|
+
} | {
|
|
16
|
+
reason: "identity_changed" | "revision_changed" | "scope_busy";
|
|
17
|
+
retryable: false;
|
|
18
|
+
status: "conflict";
|
|
19
|
+
} | {
|
|
20
|
+
reason: "policy_invalid";
|
|
21
|
+
retryable: false;
|
|
22
|
+
status: "rejected";
|
|
23
23
|
} | {
|
|
24
24
|
reason: "provider_pending";
|
|
25
25
|
retryable: true;
|
|
@@ -2351,6 +2351,14 @@ export declare function setupAllowance(): Promise<{
|
|
|
2351
2351
|
preparationId: import("convex/values").GenericId<"balanceFundingPreparations">;
|
|
2352
2352
|
requestKey: string;
|
|
2353
2353
|
result?: {
|
|
2354
|
+
reason: "identity_changed" | "revision_changed" | "scope_busy";
|
|
2355
|
+
retryable: false;
|
|
2356
|
+
status: "conflict";
|
|
2357
|
+
} | {
|
|
2358
|
+
reason: "policy_invalid";
|
|
2359
|
+
retryable: false;
|
|
2360
|
+
status: "rejected";
|
|
2361
|
+
} | {
|
|
2354
2362
|
operation: {
|
|
2355
2363
|
accountId: string;
|
|
2356
2364
|
operationId: import("convex/values").GenericId<"balanceFundingOperations">;
|
|
@@ -2361,14 +2369,6 @@ export declare function setupAllowance(): Promise<{
|
|
|
2361
2369
|
} | {
|
|
2362
2370
|
enabled: boolean;
|
|
2363
2371
|
status: "unchanged";
|
|
2364
|
-
} | {
|
|
2365
|
-
reason: "identity_changed" | "revision_changed" | "scope_busy";
|
|
2366
|
-
retryable: false;
|
|
2367
|
-
status: "conflict";
|
|
2368
|
-
} | {
|
|
2369
|
-
reason: "policy_invalid";
|
|
2370
|
-
retryable: false;
|
|
2371
|
-
status: "rejected";
|
|
2372
2372
|
} | {
|
|
2373
2373
|
reason: "provider_pending";
|
|
2374
2374
|
retryable: true;
|
|
@@ -2379,6 +2379,14 @@ export declare function setupAllowance(): Promise<{
|
|
|
2379
2379
|
payload: import("convex/values").VString<string, "required">;
|
|
2380
2380
|
preparationId: import("convex/values").VId<import("convex/values").GenericId<"balanceFundingPreparations">, "required">;
|
|
2381
2381
|
result: import("convex/values").VUnion<{
|
|
2382
|
+
reason: "identity_changed" | "revision_changed" | "scope_busy";
|
|
2383
|
+
retryable: false;
|
|
2384
|
+
status: "conflict";
|
|
2385
|
+
} | {
|
|
2386
|
+
reason: "policy_invalid";
|
|
2387
|
+
retryable: false;
|
|
2388
|
+
status: "rejected";
|
|
2389
|
+
} | {
|
|
2382
2390
|
operation: {
|
|
2383
2391
|
accountId: string;
|
|
2384
2392
|
operationId: import("convex/values").GenericId<"balanceFundingOperations">;
|
|
@@ -2389,14 +2397,6 @@ export declare function setupAllowance(): Promise<{
|
|
|
2389
2397
|
} | {
|
|
2390
2398
|
enabled: boolean;
|
|
2391
2399
|
status: "unchanged";
|
|
2392
|
-
} | {
|
|
2393
|
-
reason: "identity_changed" | "revision_changed" | "scope_busy";
|
|
2394
|
-
retryable: false;
|
|
2395
|
-
status: "conflict";
|
|
2396
|
-
} | {
|
|
2397
|
-
reason: "policy_invalid";
|
|
2398
|
-
retryable: false;
|
|
2399
|
-
status: "rejected";
|
|
2400
2400
|
} | {
|
|
2401
2401
|
reason: "provider_pending";
|
|
2402
2402
|
retryable: true;
|
package/docs/client-api.md
CHANGED
|
@@ -7,6 +7,32 @@ snapshots for an exact cross-product renewal request. It performs no provider I/
|
|
|
7
7
|
and supplies no schedule writer. See the [renewal replacement contract](./renewal-price-replacements.md)
|
|
8
8
|
for its selectors, private binding, required staged protocol and preservation gate.
|
|
9
9
|
|
|
10
|
+
### Pure renewal material observation
|
|
11
|
+
|
|
12
|
+
```ts
|
|
13
|
+
inspectRenewalScheduleMaterialV2(
|
|
14
|
+
options: InspectRenewalScheduleMaterialV2Options,
|
|
15
|
+
): Promise<RenewalScheduleMaterialObservationV2>
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
This standalone package export accepts complete raw `configuration`, five current
|
|
19
|
+
`reads` categories and optional raw `configureReceipt`. It rebuilds V2 bindings
|
|
20
|
+
and compares full material without provider I/O or trusted-store verification.
|
|
21
|
+
Its relations are `attached_unconfigured_match`, `pending_material_match`,
|
|
22
|
+
`current_target_material_match`, `terminal_facts_only`, `unknown` and `conflict`.
|
|
23
|
+
Acknowledgement and authentication remain unestablished. It is not a method on
|
|
24
|
+
`BetterStripe` or a schedule writer.
|
|
25
|
+
|
|
26
|
+
Both original and current `latest_invoice` fields are required. An `I0` to `I1`
|
|
27
|
+
change remains `conflict` with `effective_full_material_drift`; the five-read API
|
|
28
|
+
has no owned invoice-history proof. Pending without a raw configure response is
|
|
29
|
+
limited to the classic, changed-cadence, explicit-phase-start, one-week consistency
|
|
30
|
+
rule. Other unproved future durations remain unknown. See the
|
|
31
|
+
[material observation guide](renewal-material-observation.md) for complete input
|
|
32
|
+
fields, result limits, capture errors and the 500000-byte/10000-node/depth-40 bounds.
|
|
33
|
+
|
|
34
|
+
### Component-backed methods
|
|
35
|
+
|
|
10
36
|
All methods are available on the `BetterStripe` class instance. Methods that call the Stripe API are actions; methods that only read Convex data are queries.
|
|
11
37
|
|
|
12
38
|
Methods named `get<Entity>` take the component document ID (exception: `getInvoice`, which takes the Stripe invoice ID); methods named `get<Entity>ByStripeId` take the Stripe ID (`acct_...`, `prod_...`, `price_...`, `cs_...`, `sub_...`).
|
|
@@ -182,7 +182,8 @@ there is no automatic migration or fallback. Existing V1 projection, receipt
|
|
|
182
182
|
and configure consumers do not accept V2 records. V2 adds pure preparation,
|
|
183
183
|
request and attachment-receipt construction, plus
|
|
184
184
|
[raw configuration projection](renewal-phase-assembly.md#raw-v2-configuration-projection).
|
|
185
|
-
It
|
|
185
|
+
It also adds [configured-response receipt consistency](renewal-phase-assembly.md#raw-v2-configuration-receipts).
|
|
186
|
+
These constructors do not add a provider writer.
|
|
186
187
|
|
|
187
188
|
V2 retains the same raw preparation semantic checks and bounded JSON policy as
|
|
188
189
|
V1. It adds a limit of 500,000 UTF-8 bytes on each exact encoded hash preimage,
|
|
@@ -204,6 +205,9 @@ complete attachment receipt.
|
|
|
204
205
|
Configuration projection also selects `renewal-baseline`, `renewal-defaults`
|
|
205
206
|
and `renewal-configure` internally for its complete baseline, defaults and
|
|
206
207
|
unsigned request. No caller-supplied family selector is exposed.
|
|
208
|
+
Configured-response receipts select `renewal-configured-baseline` for the full
|
|
209
|
+
response body, `renewal-configured-defaults` when that body owns default settings,
|
|
210
|
+
and `renewal-configure-receipt` for the complete unsigned receipt.
|
|
207
211
|
|
|
208
212
|
The preparation preimage contains version, platform scope, expected selectors,
|
|
209
213
|
quantity and complete provider snapshot. Its logical key is separately retained
|
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
# Compare renewal schedule material
|
|
2
|
+
|
|
3
|
+
`inspectRenewalScheduleMaterialV2` compares supplied, complete subscription and
|
|
4
|
+
schedule reads against a raw V2 renewal configuration. It performs no provider
|
|
5
|
+
calls, writes, scheduling, authorization or trusted-store verification. Its result
|
|
6
|
+
is an unsigned material relation, not proof of a configure POST, payment,
|
|
7
|
+
entitlement, consent, exclusive causality or an atomic exclusion of other writers.
|
|
8
|
+
|
|
9
|
+
```ts
|
|
10
|
+
import {
|
|
11
|
+
inspectRenewalScheduleMaterialV2,
|
|
12
|
+
type InspectRenewalScheduleMaterialV2Options,
|
|
13
|
+
} from "@fantastic.dev/better-stripe";
|
|
14
|
+
|
|
15
|
+
const input: InspectRenewalScheduleMaterialV2Options = {
|
|
16
|
+
configuration: retainedRawConfiguration,
|
|
17
|
+
reads: {
|
|
18
|
+
schedule: currentOwnedSchedule,
|
|
19
|
+
subscription: currentOriginalSubscription,
|
|
20
|
+
targetPrice: currentTargetPrice,
|
|
21
|
+
billingCustomer: currentBillingCustomer,
|
|
22
|
+
coupons: completeCurrentCoupons,
|
|
23
|
+
},
|
|
24
|
+
// Optional complete raw input to constructRenewalConfigurationReceiptV2.
|
|
25
|
+
configureReceipt: retainedRawConfigurationResponse,
|
|
26
|
+
};
|
|
27
|
+
const relation = await inspectRenewalScheduleMaterialV2(input);
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
`configuration` is the full raw input accepted by
|
|
31
|
+
[`projectRenewalConfigurationV2`](renewal-phase-assembly.md), including the original
|
|
32
|
+
preparation, raw attachment receipt input, fresh preconfigure reads, observed time,
|
|
33
|
+
retained dispatch time and caller-owned key. The observer rebuilds the preparation,
|
|
34
|
+
attachment and desired request internally. It does not accept a caller-validated
|
|
35
|
+
context, desired-request handle or an authenticated-receipt flag.
|
|
36
|
+
|
|
37
|
+
The optional `configureReceipt` is the complete raw input to
|
|
38
|
+
`constructRenewalConfigurationReceiptV2`. Its nested `configuration` must equal the
|
|
39
|
+
root configuration, including optional-field presence. The observer rebuilds the
|
|
40
|
+
receipt and classifies its complete historical response before comparing current
|
|
41
|
+
reads. This binds supplied data consistently; it does not authenticate who returned
|
|
42
|
+
or stored that response. Supplying it never changes
|
|
43
|
+
`acknowledgementEstablished: false` or `authenticationEstablished: false`.
|
|
44
|
+
|
|
45
|
+
## Results and complete material
|
|
46
|
+
|
|
47
|
+
Every result has `providerQualificationRequired: true`. The `predicate` is one of:
|
|
48
|
+
|
|
49
|
+
| Predicate | Meaning |
|
|
50
|
+
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
|
|
51
|
+
| `attached_unconfigured_match` | The complete attached single-phase material still matches. |
|
|
52
|
+
| `pending_material_match` | Current paid material and the exact future phase match, with a supported independently bound future end. |
|
|
53
|
+
| `current_target_material_match` | The target phase is current and the uniquely identified target item, native period and complete retained material match. |
|
|
54
|
+
| `terminal_facts_only` | A terminal status was supplied; effectiveness remains `unknown`. |
|
|
55
|
+
| `unknown` | Required evidence or a supported mapping is missing. |
|
|
56
|
+
| `conflict` | Supplied material contradicts the retained operation. |
|
|
57
|
+
|
|
58
|
+
A current target match can identify a successor subscription item. It does not
|
|
59
|
+
require the original `si_` ID to survive the schedule transition. It requires the
|
|
60
|
+
linked original subscription and buyer, exact phase and native item period,
|
|
61
|
+
price/product, quantity, currency, full Price/Plan mapping, settings, discounts,
|
|
62
|
+
taxes, customer material and supported expanded-reference counterparts. Matching
|
|
63
|
+
only a price or future phase is insufficient. Unknown retained fields and counters
|
|
64
|
+
remain comparison material; they are not silently dropped or incremented.
|
|
65
|
+
|
|
66
|
+
### Invoice-pointer limitation
|
|
67
|
+
|
|
68
|
+
This API accepts five current-read categories. It has no invoice inventory, full
|
|
69
|
+
invoice/line history or owned successor-invoice proof. Both the original and current
|
|
70
|
+
subscription must contain their own `latest_invoice` field. An original `I0` and
|
|
71
|
+
current `I1` produce `conflict` with `effective_full_material_drift` when the other
|
|
72
|
+
active-material checks pass. This can describe a normal renewal that this limited
|
|
73
|
+
comparison cannot prove. Omitting the field does not make it supported; missing
|
|
74
|
+
fields produce `unknown` with `missing_latest_invoice`.
|
|
75
|
+
|
|
76
|
+
A positive active-material example therefore requires coherent invoice pointers
|
|
77
|
+
under the existing complete comparison. It does not prove that real renewals keep
|
|
78
|
+
that pointer unchanged. An optional raw configure receipt does not authorize an
|
|
79
|
+
`I0` to `I1` change. Admitting such changes requires separately defined owned
|
|
80
|
+
invoice-history evidence. This helper is not the complete renewal-observation or
|
|
81
|
+
renewal-replacement workflow.
|
|
82
|
+
|
|
83
|
+
### Pending without a configure response
|
|
84
|
+
|
|
85
|
+
A complete current-target match can be established from supplied reads without a
|
|
86
|
+
configure response. A pending match without that response has a narrower supported
|
|
87
|
+
class: classic billing, changed cadence, an ordinary anchor, a one-week licensed
|
|
88
|
+
target with explicit `phase_start`, and no trial, threshold, cancellation, pause or
|
|
89
|
+
other supported period-resetting condition. Every complete current-paid and future
|
|
90
|
+
settings guard must still pass.
|
|
91
|
+
|
|
92
|
+
For this class the observer infers the future end as the retained boundary plus
|
|
93
|
+
604800 UTC seconds, with safe-integer checks, then compares the actual future end.
|
|
94
|
+
This is a bounded consistency inference from Stripe's
|
|
95
|
+
[phase duration](https://docs.stripe.com/billing/subscriptions/subscription-schedules)
|
|
96
|
+
and [UTC billing-anchor](https://docs.stripe.com/billing/subscriptions/billing-cycle)
|
|
97
|
+
contracts. It is not a provider-qualified observation of the exact calculation.
|
|
98
|
+
No host calendar, invoice calculation or caller-supplied expected end is used.
|
|
99
|
+
|
|
100
|
+
Monthly/yearly, multi-week, flexible, automatic-anchor, calendar-edge and other
|
|
101
|
+
unproved future durations remain `unknown` with `future_duration_not_bound` unless
|
|
102
|
+
the complete historical raw configuration response binds the end under the
|
|
103
|
+
supported comparison rules. Reads never become a configure POST acknowledgement.
|
|
104
|
+
Released, canceled and completed facts do not establish terminal effectiveness.
|
|
105
|
+
A supplied schedule status must be a string. Arrays, objects, null and numeric
|
|
106
|
+
statuses return `unknown` with `invalid_schedule_status`; an unrecognized string
|
|
107
|
+
keeps `unknown` with `unsupported_schedule_status`. Values are never coerced into
|
|
108
|
+
a known terminal status.
|
|
109
|
+
|
|
110
|
+
## Capture and limits
|
|
111
|
+
|
|
112
|
+
The entire input is captured synchronously before asynchronous binding work.
|
|
113
|
+
Later caller mutations do not change that invocation. Roots must be plain or
|
|
114
|
+
null-prototype objects with closed own data fields. Getters, symbols, hidden
|
|
115
|
+
properties, sparse arrays, non-finite values and non-JSON objects are rejected;
|
|
116
|
+
SDK `lastResponse` metadata is not stripped from untrusted bare response inputs.
|
|
117
|
+
|
|
118
|
+
The whole submitted input, including repeated raw configuration material, is
|
|
119
|
+
limited to 500000 string/key characters, serialized characters and UTF-8 bytes,
|
|
120
|
+
10000 nodes and depth 40. These are this API's actual input bounds, not a claim
|
|
121
|
+
about whole-process memory or other SDK methods. Invalid raw capture rejects with
|
|
122
|
+
a fixed error; safe but insufficient material returns `unknown` or `conflict`
|
|
123
|
+
with a fixed reason. No raw provider error is logged or returned. The host remains
|
|
124
|
+
responsible for retaining its immutable request and response data when reads fail.
|
|
@@ -84,6 +84,74 @@ effectiveness. Protect original records and enforce host authorization and all
|
|
|
84
84
|
provider qualification gates before dispatch. Existing V1 APIs and record
|
|
85
85
|
formats are unchanged.
|
|
86
86
|
|
|
87
|
+
## Raw V2 configuration receipts
|
|
88
|
+
|
|
89
|
+
`constructRenewalConfigurationReceiptV2` records unsigned operation consistency
|
|
90
|
+
from raw configuration inputs and a retained response:
|
|
91
|
+
|
|
92
|
+
```ts
|
|
93
|
+
import { constructRenewalConfigurationReceiptV2 } from "@fantastic.dev/better-stripe";
|
|
94
|
+
|
|
95
|
+
const receipt = await constructRenewalConfigurationReceiptV2({
|
|
96
|
+
configuration: originalRawConfigurationInputs,
|
|
97
|
+
actualDispatch: {
|
|
98
|
+
scope: "platform",
|
|
99
|
+
apiVersion,
|
|
100
|
+
method: "POST",
|
|
101
|
+
path: projectedRequest.path,
|
|
102
|
+
payload: projectedRequest.payload,
|
|
103
|
+
key: projectedRequest.key,
|
|
104
|
+
firstDispatchedAt: projectedRequest.firstDispatchedAt,
|
|
105
|
+
},
|
|
106
|
+
providerSnapshot: retainedConfiguredScheduleBody,
|
|
107
|
+
transport: {
|
|
108
|
+
status: retainedStatus,
|
|
109
|
+
...(retainedRequestId === undefined
|
|
110
|
+
? {}
|
|
111
|
+
: { requestId: retainedRequestId }),
|
|
112
|
+
},
|
|
113
|
+
});
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
`configuration` is the complete raw input to `projectRenewalConfigurationV2`,
|
|
117
|
+
including its repeated original preparation and raw attachment receipt inputs.
|
|
118
|
+
Do not supply a projected request, stored receipt or verification handle in its
|
|
119
|
+
place. The constructor captures the entire input before its first await and
|
|
120
|
+
rebuilds C6 internally. Any returned C6 Failure rejects C9 with a fixed error;
|
|
121
|
+
C6's own Failure union remains unchanged. All seven actual dispatch fields,
|
|
122
|
+
including the complete payload, key and first-dispatch time, must equal C6.
|
|
123
|
+
|
|
124
|
+
Transport is closed `{ status, requestId? }`. Status must be an integer from
|
|
125
|
+
200 through 299. A present request ID must contain 1–255 characters; omit it
|
|
126
|
+
when absent. Null, empty or explicitly undefined IDs reject. Supply the complete
|
|
127
|
+
plain JSON Schedule body rather than an SDK wrapper: any own `lastResponse`
|
|
128
|
+
property, including hidden metadata, rejects. The public bounded JSON limits and
|
|
129
|
+
own-data constructor checks remain; captured required fields are checked again
|
|
130
|
+
before hashing.
|
|
131
|
+
|
|
132
|
+
Available response identity relations must agree with C6's Schedule,
|
|
133
|
+
Subscription, Customer, account and mode. The complete response body, including
|
|
134
|
+
unknown safe JSON keys, remains in C7 (`renewal-configured-baseline`). C8
|
|
135
|
+
(`renewal-configured-defaults`) is present only when the response owns
|
|
136
|
+
`default_settings`: absent stays absent, own null is hashed as null, and a present
|
|
137
|
+
object is hashed in full. C9 (`renewal-configure-receipt`) binds the complete
|
|
138
|
+
unsigned receipt, including the full C6 request, response, exact transport and
|
|
139
|
+
C7/optional C8. Each exact UTF-8 preimage retains the 500,000-byte limit; the
|
|
140
|
+
whole input and result retain the existing JSON traversal and size limits.
|
|
141
|
+
|
|
142
|
+
The result uses version `2`, stage `configure_acknowledged` and verification
|
|
143
|
+
`owned_response_only`. These are unsigned data-format literals. They do not
|
|
144
|
+
authenticate acknowledgement or ownership. A caller can manufacture coherent
|
|
145
|
+
data that passes. This operation-only constructor does not require response
|
|
146
|
+
phases or defaults to match the requested configuration and cannot certify that
|
|
147
|
+
they were applied. Full phase/material comparison, response acquisition and
|
|
148
|
+
same-call provenance, authorization, custody, provider qualification and renewal
|
|
149
|
+
effectiveness remain separate requirements.
|
|
150
|
+
|
|
151
|
+
No provider call, retry, key rotation, storage write, V1 conversion or native
|
|
152
|
+
qualification occurs. Keep the original operation records protected, and do not
|
|
153
|
+
treat the receipt or a matching digest as permission to write or grant service.
|
|
154
|
+
|
|
87
155
|
A candidate always has `providerQualification: "required"`. This describes a
|
|
88
156
|
remaining requirement, not authorization to dispatch. Host-supplied flags cannot
|
|
89
157
|
prove provider behavior, ownership, original configuration or historical intent.
|
|
@@ -48,6 +48,9 @@ The internal [preservation mappings](renewal-preservation-mappings.md) document
|
|
|
48
48
|
field projection boundaries separately from complete schedule eligibility.
|
|
49
49
|
The internal [phase assembly contract](renewal-phase-assembly.md) describes
|
|
50
50
|
preflight, acknowledged baselines and non-dispatchable configuration candidates.
|
|
51
|
+
The public [material observer](renewal-material-observation.md) compares supplied
|
|
52
|
+
V2 material without provider calls. Its invoice-pointer and no-response duration
|
|
53
|
+
limits leave the complete renewal workflow outside that pure helper.
|
|
51
54
|
|
|
52
55
|
The subscription's actual `currency` must match both prices' default `currency`.
|
|
53
56
|
This helper does not select `currency_options` or infer an alternative amount.
|
package/package.json
CHANGED
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
import {
|
|
2
|
+
object,
|
|
3
|
+
array,
|
|
4
|
+
need,
|
|
5
|
+
clone,
|
|
6
|
+
get,
|
|
7
|
+
equal,
|
|
8
|
+
timestamp,
|
|
9
|
+
planTemplateForPrice,
|
|
10
|
+
type ObserverCandidateResult,
|
|
11
|
+
} from "./common.js";
|
|
12
|
+
import type { pending } from "./pending-and-stage.js";
|
|
13
|
+
export function active(
|
|
14
|
+
state: Extract<ReturnType<typeof pending>, { kind: "continue" }>["state"],
|
|
15
|
+
): ObserverCandidateResult {
|
|
16
|
+
const {
|
|
17
|
+
rawReads,
|
|
18
|
+
base,
|
|
19
|
+
originalItem,
|
|
20
|
+
sub,
|
|
21
|
+
target,
|
|
22
|
+
context,
|
|
23
|
+
actualItem,
|
|
24
|
+
current,
|
|
25
|
+
actualItemDiscounts,
|
|
26
|
+
normalizeSub,
|
|
27
|
+
sourceWithAssociation,
|
|
28
|
+
targetTemplate,
|
|
29
|
+
} = state;
|
|
30
|
+
// BEGIN original 927-961
|
|
31
|
+
const effectiveTemplate = clone(sourceWithAssociation),
|
|
32
|
+
expectedItem = clone(originalItem);
|
|
33
|
+
expectedItem.id = actualItem.id;
|
|
34
|
+
expectedItem.price = clone(target);
|
|
35
|
+
const targetPlanTemplate = planTemplateForPrice(target, context);
|
|
36
|
+
need(targetPlanTemplate, "unproven_target_plan_price_mapping", "unknown");
|
|
37
|
+
// Expected comparison view from explicit field mapping; raw actual Plan stays in rawReads.
|
|
38
|
+
expectedItem.plan = targetPlanTemplate;
|
|
39
|
+
expectedItem.current_period_start = current.start_date;
|
|
40
|
+
expectedItem.current_period_end = current.end_date;
|
|
41
|
+
get(effectiveTemplate, "items").data = [expectedItem];
|
|
42
|
+
if (targetTemplate.billing_cycle_anchor === "phase_start")
|
|
43
|
+
effectiveTemplate.billing_cycle_anchor = current.start_date;
|
|
44
|
+
const normalizedActual = normalizeSub(sub, "target", target),
|
|
45
|
+
normalizedExpected = normalizeSub(effectiveTemplate, "original", target);
|
|
46
|
+
get(normalizedExpected, "items").data = [
|
|
47
|
+
{
|
|
48
|
+
...object(array(get(normalizedExpected, "items").data)[0]),
|
|
49
|
+
discounts: actualItemDiscounts,
|
|
50
|
+
},
|
|
51
|
+
];
|
|
52
|
+
need(
|
|
53
|
+
equal(normalizedActual, normalizedExpected),
|
|
54
|
+
"effective_full_material_drift",
|
|
55
|
+
);
|
|
56
|
+
return {
|
|
57
|
+
...base,
|
|
58
|
+
predicate: "active_effective_match",
|
|
59
|
+
observedItemId: String(actualItem.id),
|
|
60
|
+
nativePeriod: {
|
|
61
|
+
start: timestamp.parse(current.start_date),
|
|
62
|
+
end: timestamp.parse(current.end_date),
|
|
63
|
+
},
|
|
64
|
+
rawReads,
|
|
65
|
+
};
|
|
66
|
+
// END original 927-961
|
|
67
|
+
}
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
import { renewalSnapshot } from "../renewalReplacementSnapshot.js";
|
|
2
|
+
import {
|
|
3
|
+
equal,
|
|
4
|
+
referenceId,
|
|
5
|
+
productId,
|
|
6
|
+
timestamp,
|
|
7
|
+
} from "../renewalAggregate/shared.js";
|
|
8
|
+
import { planMatchesPrice, planTemplateForPrice } from "./planProjection.js";
|
|
9
|
+
export type O = Record<string, unknown>;
|
|
10
|
+
export class Stop extends Error {
|
|
11
|
+
constructor(
|
|
12
|
+
readonly reason: string,
|
|
13
|
+
readonly kind: "unknown" | "conflict" = "conflict",
|
|
14
|
+
) {
|
|
15
|
+
super(reason);
|
|
16
|
+
}
|
|
17
|
+
}
|
|
18
|
+
export const object = (v: unknown): O => {
|
|
19
|
+
if (!v || typeof v !== "object" || Array.isArray(v))
|
|
20
|
+
throw new Stop("incomplete_object", "unknown");
|
|
21
|
+
return v as O;
|
|
22
|
+
};
|
|
23
|
+
export const array = (v: unknown): unknown[] => {
|
|
24
|
+
if (!Array.isArray(v)) throw new Stop("incomplete_array", "unknown");
|
|
25
|
+
return v;
|
|
26
|
+
};
|
|
27
|
+
export function need(
|
|
28
|
+
value: unknown,
|
|
29
|
+
reason: string,
|
|
30
|
+
kind: "unknown" | "conflict" = "conflict",
|
|
31
|
+
): asserts value {
|
|
32
|
+
if (!value) throw new Stop(reason, kind);
|
|
33
|
+
}
|
|
34
|
+
export const clone = <T>(v: T): T => renewalSnapshot(v);
|
|
35
|
+
export const get = (v: O, key: string) => object(v[key]);
|
|
36
|
+
export function compareFullBaseline(left: unknown, right: unknown) {
|
|
37
|
+
let same = false;
|
|
38
|
+
try {
|
|
39
|
+
same = equal(left, right);
|
|
40
|
+
} catch {}
|
|
41
|
+
return { equal: same, acknowledgementEstablished: false as const };
|
|
42
|
+
}
|
|
43
|
+
export type ObserverCandidateResult = {
|
|
44
|
+
candidateOnly: true;
|
|
45
|
+
providerQualification: "required";
|
|
46
|
+
configureAcknowledged: false;
|
|
47
|
+
configureDispatchOutcome: "unknown";
|
|
48
|
+
providerCallsRequested: false;
|
|
49
|
+
predicate:
|
|
50
|
+
| "terminal_facts_only"
|
|
51
|
+
| "attached_unconfigured_match"
|
|
52
|
+
| "active_effective_match"
|
|
53
|
+
| "configured_baseline_material_match"
|
|
54
|
+
| "confirmed_pending"
|
|
55
|
+
| "unknown"
|
|
56
|
+
| "conflict";
|
|
57
|
+
reason?: string;
|
|
58
|
+
observedItemId?: string;
|
|
59
|
+
nativePeriod?: { start: number; end: number };
|
|
60
|
+
providerStatus?: unknown;
|
|
61
|
+
effectiveness?: "unknown";
|
|
62
|
+
rawReads?: unknown;
|
|
63
|
+
comparableSchedule?: unknown;
|
|
64
|
+
proofTargetEnd?: number;
|
|
65
|
+
proofStage?: "original" | "target";
|
|
66
|
+
};
|
|
67
|
+
/** Private SOURCE candidate only; no transport, public integration or ack adapter. */
|
|
68
|
+
|
|
69
|
+
export {
|
|
70
|
+
renewalSnapshot,
|
|
71
|
+
equal,
|
|
72
|
+
referenceId,
|
|
73
|
+
productId,
|
|
74
|
+
timestamp,
|
|
75
|
+
planMatchesPrice,
|
|
76
|
+
planTemplateForPrice,
|
|
77
|
+
};
|
|
78
|
+
export type Purpose = "baseline" | "live";
|
|
79
|
+
export type Evidence = {
|
|
80
|
+
targetEnd: number;
|
|
81
|
+
comparable: unknown;
|
|
82
|
+
stage: "original" | "target";
|
|
83
|
+
};
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
import { need, get, equal, type ObserverCandidateResult } from "./common.js";
|
|
2
|
+
import type { templates } from "./schedule-templates.js";
|
|
3
|
+
export function baseline(
|
|
4
|
+
state: Extract<ReturnType<typeof templates>, { kind: "continue" }>["state"],
|
|
5
|
+
) {
|
|
6
|
+
const {
|
|
7
|
+
rawReads,
|
|
8
|
+
base,
|
|
9
|
+
purpose,
|
|
10
|
+
originalItem,
|
|
11
|
+
sub,
|
|
12
|
+
current,
|
|
13
|
+
currentOriginal,
|
|
14
|
+
activeTarget,
|
|
15
|
+
normalizeSub,
|
|
16
|
+
sourceWithAssociation,
|
|
17
|
+
targetPhase,
|
|
18
|
+
comparableSchedule,
|
|
19
|
+
} = state;
|
|
20
|
+
// BEGIN original 851-879
|
|
21
|
+
if (purpose === "baseline") {
|
|
22
|
+
need(
|
|
23
|
+
currentOriginal ||
|
|
24
|
+
(activeTarget &&
|
|
25
|
+
current.start_date === targetPhase.start_date &&
|
|
26
|
+
current.end_date === targetPhase.end_date),
|
|
27
|
+
"configured_ack_phase_relation_unproven",
|
|
28
|
+
"unknown",
|
|
29
|
+
);
|
|
30
|
+
need(
|
|
31
|
+
equal(
|
|
32
|
+
normalizeSub(sub, "original", get(originalItem, "price")),
|
|
33
|
+
normalizeSub(
|
|
34
|
+
sourceWithAssociation,
|
|
35
|
+
"original",
|
|
36
|
+
get(originalItem, "price"),
|
|
37
|
+
),
|
|
38
|
+
),
|
|
39
|
+
"historical_original_material_drift",
|
|
40
|
+
);
|
|
41
|
+
return {
|
|
42
|
+
kind: "result" as const,
|
|
43
|
+
result: {
|
|
44
|
+
...base,
|
|
45
|
+
predicate: "configured_baseline_material_match",
|
|
46
|
+
rawReads,
|
|
47
|
+
comparableSchedule,
|
|
48
|
+
proofTargetEnd: Number(targetPhase.end_date),
|
|
49
|
+
proofStage: currentOriginal ? "original" : "target",
|
|
50
|
+
} as ObserverCandidateResult,
|
|
51
|
+
};
|
|
52
|
+
}
|
|
53
|
+
// END original 851-879
|
|
54
|
+
return { kind: "continue" as const, state: { ...state } };
|
|
55
|
+
}
|