@pithy-sh/payments 0.1.5 → 0.2.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.
@@ -1 +1 @@
1
- {"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,KAAK,UAAU,EAGhB,MAAM,0CAA0C,CAAC;AAClD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAEzE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAI3E,OAAO,EAAE,cAAc,EAAE,KAAK,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAG3E,OAAO,KAAK,EAAE,uBAAuB,EAAuB,MAAM,2BAA2B,CAAC;AAQ9F,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAK7C;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,eAAe,GAAG,mBAAmB,GAAG;IAClD;;;;OAIG;IACH,cAAc,CAAC,EAAE,uBAAuB,CAAC;CAC1C,CAAC;AA4LF,6FAA6F;AAC7F,MAAM,WAAW,kBACf,SAAQ,UAAU,CAAC,eAAe,EAAE,kBAAkB,EAAE,UAAU,EAAE,OAAO,iBAAiB,CAAC;IAC7F,4BAA4B;IAC5B,cAAc,EAAE,cAAc,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,kBAAkB,CAwFrE;AAED,sFAAsF;AACtF,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,IAAI,kBAAkB,CAE7F"}
1
+ {"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,KAAK,UAAU,EAGhB,MAAM,0CAA0C,CAAC;AAClD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAEzE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAI3E,OAAO,EAAE,cAAc,EAAE,KAAK,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAG3E,OAAO,KAAK,EAAE,uBAAuB,EAAuB,MAAM,2BAA2B,CAAC;AAS9F,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAK7C;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,eAAe,GAAG,mBAAmB,GAAG;IAClD;;;;OAIG;IACH,cAAc,CAAC,EAAE,uBAAuB,CAAC;CAC1C,CAAC;AAsMF,6FAA6F;AAC7F,MAAM,WAAW,kBACf,SAAQ,UAAU,CAAC,eAAe,EAAE,kBAAkB,EAAE,UAAU,EAAE,OAAO,iBAAiB,CAAC;IAC7F,4BAA4B;IAC5B,cAAc,EAAE,cAAc,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,kBAAkB,CA6FrE;AAED,sFAAsF;AACtF,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,IAAI,kBAAkB,CAE7F"}
@@ -3,6 +3,7 @@
3
3
  import { PaymentsConfig } from "./config/config.js";
4
4
  import { paymentsTables } from "./data/tables.js";
5
5
  import { installEntitlementResolver } from "./entitlement/resolver.js";
6
+ import { requireImplementedSubject } from "./entitlement/unimplementedSubject.js";
6
7
  import { paymentsManifestConfig } from "./http/manifestConfig.js";
7
8
  import { paymentsSecretsRegistry } from "./secret/registry.js";
8
9
  import { paymentsWorkflows } from "./workflows/specs.js";
@@ -83,6 +84,16 @@ function checkLedgerGrants({ capabilities }, config) {
83
84
  * request that ever works, so there is nothing to lose by refusing to boot, and a Worker that boots into
84
85
  * that state is one whose first symptom is a support ticket from a paying company.
85
86
  */
87
+ /**
88
+ * **An unimplemented resolver is not an absent one, and this check is deliberately blind to the
89
+ * difference.** `pithy add payments --set billingSubject=organization` scaffolds
90
+ * `src/billing/subject.ts` exporting a placeholder branded unimplemented, and passes it here. It is a
91
+ * resolver, so this returns — which it must, because `payments()` runs every time a Worker's
92
+ * `pithy.config.ts` is evaluated and the CLI evaluates it on nearly every command. Refusing the
93
+ * placeholder here would leave the adopter with no `pithy` at all in the project the scaffold just landed
94
+ * in. `requireImplementedSubject`, on the capability's `boot` hook, is where the placeholder is refused —
95
+ * `createEntrypoint` runs it and nothing else does, so the Worker still will not serve (#500).
96
+ */
86
97
  function requireResolvableSubject(config, resolveSubject) {
87
98
  if (config.billingSubject !== "organization" || resolveSubject !== void 0) return;
88
99
  throw new ValidationError({
@@ -202,6 +213,7 @@ function payments(options) {
202
213
  secretRegistry: paymentsSecretsRegistry,
203
214
  workflows: paymentsWorkflows,
204
215
  compose: (context) => checkLedgerGrants(context, resolved),
216
+ boot: () => requireImplementedSubject(resolveSubject),
205
217
  client: ({ environment }) => clientProjection(resolved, environment),
206
218
  requiredBindings,
207
219
  config: PaymentsConfig,
@@ -0,0 +1,25 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import type { PaymentsSubjectResolver } from "./subjectSeam";
4
+ /**
5
+ * The scaffolded resolver: branded unimplemented, and a throw if anything ever calls it.
6
+ *
7
+ * A throw rather than `undefined`, and it is belt and braces rather than the mechanism — {@link
8
+ * requireImplementedSubject} means a deployed Worker never gets here. What it covers is every other way
9
+ * this function could be reached: a test composing the capability directly, a tool that assembles a
10
+ * backend without an entrypoint (`pithy ui` reads the composed route tree that way), an adopter who
11
+ * imported the placeholder somewhere of their own. In all of them a loud failure is the right answer and a
12
+ * quiet `undefined` is the failure mode of the stub this replaces.
13
+ */
14
+ export declare const unimplementedSubject: PaymentsSubjectResolver;
15
+ /** Whether this resolver is the scaffolded placeholder rather than something the adopter wrote. */
16
+ export declare function isUnimplementedSubject(resolver: PaymentsSubjectResolver | undefined): boolean;
17
+ /**
18
+ * Refuse a Worker whose subject resolver is still the scaffolded placeholder.
19
+ *
20
+ * Called from the capability's `boot` hook, which `createEntrypoint` runs and nothing else does. The
21
+ * message is the adopter's next action and nothing else: the file is named, the question it has to answer
22
+ * is stated, and the alternative is the other billing mode.
23
+ */
24
+ export declare function requireImplementedSubject(resolver: PaymentsSubjectResolver | undefined): void;
25
+ //# sourceMappingURL=unimplementedSubject.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"unimplementedSubject.d.ts","sourceRoot":"","sources":["../../src/entitlement/unimplementedSubject.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAwC7D;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,EAAE,uBAWP,CAAC;AAE7B,mGAAmG;AACnG,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,uBAAuB,GAAG,SAAS,GAAG,OAAO,CAE7F;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,uBAAuB,GAAG,SAAS,GAAG,IAAI,CAS7F"}
@@ -0,0 +1,78 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import { InternalError, ValidationError } from "@pithy-sh/core/src/error/pithyError";
4
+ //#region src/entitlement/unimplementedSubject.ts
5
+ /**
6
+ * The placeholder `pithy add payments --set billingSubject=organization` scaffolds, and the brand that
7
+ * makes it recognizably unfinished.
8
+ *
9
+ * ## Why a placeholder is safe here and a stub never is
10
+ *
11
+ * A stub is a resolver that *answers*. Returning `undefined` composes cleanly, satisfies every check the
12
+ * capability can make, and then denies every entitlement gate and raises `payments/subject_unresolved` on
13
+ * every write — which is indistinguishable from a customer who has not paid, and whose first symptom is a
14
+ * support ticket from a paying company. That is strictly worse than refusing to write the config at all,
15
+ * and it is why `pithy add` refused `organization` outright for as long as a stub was the only thing it
16
+ * could have written (#483).
17
+ *
18
+ * This answers nothing. It is a **marked absence**: a function carrying {@link UNIMPLEMENTED_SUBJECT},
19
+ * which `payments()` reads at the Worker's entrypoint and refuses to boot on. So the two facts that used
20
+ * to be in tension both hold — the adopter states `organization`, which is what they mean, and the Worker
21
+ * still will not serve a request until somebody has written the resolver (#500).
22
+ *
23
+ * ## Why the check is at the entrypoint and not at composition
24
+ *
25
+ * `payments()` runs whenever a Worker's `pithy.config.ts` is *evaluated*, and the CLI evaluates that
26
+ * module on nearly every command — `loadWorkerConfig` is how `migrate`, `deploy`, `doctor`, `upgrade` and
27
+ * `add` itself learn what a Worker composes. A refusal at composition would therefore brick the whole CLI
28
+ * in the adopter's project the moment the scaffold landed, which is exactly the #483 regression turned
29
+ * inside out. `createEntrypoint` is the one seam the CLI never crosses: only the Worker's own
30
+ * `src/index.ts` calls it. So the composition check stays what it was — an **absent** resolver is refused,
31
+ * unchanged — and the unimplemented one is refused one seam later, where the audience is a request.
32
+ */
33
+ /**
34
+ * The brand. `Symbol.for` rather than a module-local symbol or function identity: a project that ends up
35
+ * with two copies of `@pithy-sh/payments` resolved (a transitive range that did not dedupe) would compare
36
+ * a placeholder from one copy against the marker from the other, and identity would answer no — booting a
37
+ * Worker that denies every gate, which is the one outcome this file exists to prevent. A registered symbol
38
+ * is the same symbol in both copies.
39
+ */
40
+ const UNIMPLEMENTED_SUBJECT = Symbol.for("@pithy-sh/payments/unimplemented-subject");
41
+ /**
42
+ * The scaffolded resolver: branded unimplemented, and a throw if anything ever calls it.
43
+ *
44
+ * A throw rather than `undefined`, and it is belt and braces rather than the mechanism — {@link
45
+ * requireImplementedSubject} means a deployed Worker never gets here. What it covers is every other way
46
+ * this function could be reached: a test composing the capability directly, a tool that assembles a
47
+ * backend without an entrypoint (`pithy ui` reads the composed route tree that way), an adopter who
48
+ * imported the placeholder somewhere of their own. In all of them a loud failure is the right answer and a
49
+ * quiet `undefined` is the failure mode of the stub this replaces.
50
+ */
51
+ const unimplementedSubject = Object.defineProperty(async () => {
52
+ throw new InternalError({
53
+ message: "The subject resolver for this project has not been written.",
54
+ action: "Implement resolveSubject in this Worker's src/billing/subject.ts.",
55
+ detail: "pithy add scaffolded an unimplemented resolveSubject and it is still the one composed. Under billingSubject: \"organization\" only the application can say which organization a caller is acting for."
56
+ });
57
+ }, UNIMPLEMENTED_SUBJECT, { value: true });
58
+ /** Whether this resolver is the scaffolded placeholder rather than something the adopter wrote. */
59
+ function isUnimplementedSubject(resolver) {
60
+ return resolver !== void 0 && resolver[UNIMPLEMENTED_SUBJECT] === true;
61
+ }
62
+ /**
63
+ * Refuse a Worker whose subject resolver is still the scaffolded placeholder.
64
+ *
65
+ * Called from the capability's `boot` hook, which `createEntrypoint` runs and nothing else does. The
66
+ * message is the adopter's next action and nothing else: the file is named, the question it has to answer
67
+ * is stated, and the alternative is the other billing mode.
68
+ */
69
+ function requireImplementedSubject(resolver) {
70
+ if (!isUnimplementedSubject(resolver)) return;
71
+ throw new ValidationError({
72
+ message: "This project bills organizations, and its subject resolver is still the scaffolded placeholder.",
73
+ action: "Implement resolveSubject in this Worker's src/billing/subject.ts, or set `billingSubject: \"user\"` in pithy.config.ts.",
74
+ detail: "pithy add wrote src/billing/subject.ts exporting an unimplemented resolveSubject, and it is unchanged. Payments has no members table and never guesses a holder, so booting on it would deny every entitlement gate and raise payments/subject_unresolved on every write, for every caller, forever."
75
+ });
76
+ }
77
+ //#endregion
78
+ export { isUnimplementedSubject, requireImplementedSubject, unimplementedSubject };
package/dist/index.d.ts CHANGED
@@ -35,6 +35,7 @@ export { PaymentsWebhookEvent, WEBHOOK_EVENT_ORPHANED, webhookEventAwaitsOwner }
35
35
  export { grantEntitlement, type ManualEntitlementInput, type ManualEntitlementOptions, revokeEntitlement, } from "./entitlement/manual";
36
36
  export { createPaymentsEntitlementResolver, installEntitlementResolver, PAYMENTS_ENTITLEMENT_PROVIDER, } from "./entitlement/resolver";
37
37
  export { authenticatedUserSubject, type PaymentsSubjectResolver, type PaymentsSubjectSeam, requirePaymentsSubject, resolvePaymentsSubject, } from "./entitlement/subjectSeam";
38
+ export { isUnimplementedSubject, requireImplementedSubject, unimplementedSubject, } from "./entitlement/unimplementedSubject";
38
39
  export { type AppliedGrant, applyGrants, type FulfillmentReport, type FulfillPurchaseOptions, fulfillPurchase, type GrantOptions, grantRef, ledgerGrantFor, purchaseIsPaid, } from "./grants/apply";
39
40
  export { type ClawbackOutcome, clawbackGrants, clawbackRef } from "./grants/clawback";
40
41
  export { type OpenPaymentsLedgerOptions, openPaymentsLedger, type PaymentsLedger, type PaymentsLedgerLoader, } from "./grants/ledgerSeam";
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
package/dist/index.js CHANGED
@@ -13,6 +13,7 @@ import { PAYMENTS_ENTITLEMENTS_TABLE, PAYMENTS_PROVIDER_ACCOUNTS_TABLE, PAYMENTS
13
13
  import { resolveEntitlements } from "./projection/resolve.js";
14
14
  import { authenticatedUserSubject, requirePaymentsSubject, resolvePaymentsSubject } from "./entitlement/subjectSeam.js";
15
15
  import { PAYMENTS_ENTITLEMENT_PROVIDER, createPaymentsEntitlementResolver, installEntitlementResolver } from "./entitlement/resolver.js";
16
+ import { isUnimplementedSubject, requireImplementedSubject, unimplementedSubject } from "./entitlement/unimplementedSubject.js";
16
17
  import { PaymentsAuditActions } from "./audit/actions.js";
17
18
  import { grantEntitlement, revokeEntitlement } from "./entitlement/manual.js";
18
19
  import { openPaymentsLedger } from "./grants/ledgerSeam.js";
@@ -42,4 +43,4 @@ import { PAYMENTS_RECONCILE_KEY, triggerPaymentsReconcile } from "./http/dispatc
42
43
  import { paymentsWorkerName, resolvePaymentsConfig } from "./provision/resolvePaymentsConfig.js";
43
44
  import { batchedRailAccess } from "./workflows/railAccess.js";
44
45
  import { reconcilePayments } from "./workflows/reconcile.js";
45
- export { ACCESS_GRANTING_STATUSES, APPLE_API_AUDIENCE, APPLE_API_BASES, APPLE_ROOT_CERTIFICATES, AppleSubscriptionStatuses, AppleWebhookNotification, CheckoutRequest, DEFAULT_EXPIRING_WITHIN_SECONDS, DEFAULT_STALE_AFTER_SECONDS, EntitlementGrantRequest, EntitlementRevokeRequest, GOOGLE_JWKS_URL, GOOGLE_OIDC_ISSUERS, GoogleJwk, GoogleJwks, GoogleWebhookNotification, ORPHAN_REPAIR_LIMIT, PAYMENTS_CAPABILITY, PAYMENTS_CATALOG_READ_SCOPE, PAYMENTS_CONTROL_PLANE_SCOPES, PAYMENTS_ENTITLEMENTS_TABLE, PAYMENTS_ENTITLEMENT_GRANT_SCOPE, PAYMENTS_ENTITLEMENT_PROVIDER, PAYMENTS_ENTITLEMENT_REVOKE_SCOPE, PAYMENTS_MIGRATION_ORDER, PAYMENTS_PROVIDER_ACCOUNTS_TABLE, PAYMENTS_PROVIDER_SECRET, PAYMENTS_PURCHASES_TABLE, PAYMENTS_RAILS, PAYMENTS_RECONCILE_KEY, PAYMENTS_RECONCILE_RUNS_TABLE, PAYMENTS_WEBHOOK_EVENTS_TABLE, PaymentsAppleCredentials, PaymentsAppleProduct, PaymentsAuditActions, PaymentsConfig, PaymentsEntitlement, PaymentsGoogleCredentials, PaymentsGoogleProduct, PaymentsGrants, PaymentsLedgerGrant, PaymentsLemonSqueezyProduct, PaymentsLemonSqueezySettings, PaymentsPaddleProduct, PaymentsPaddleSettings, PaymentsProduct, PaymentsProductType, PaymentsProviderAccount, PaymentsProviderCredentials, PaymentsPurchase, PaymentsRail, PaymentsRailToggles, PaymentsReconcileParams, PaymentsReconcileRun, PaymentsStripeCredentials, PaymentsStripeProduct, PaymentsStripeSettings, PaymentsSubject, PaymentsSubjectType, PaymentsWebhookEvent, ProviderEvent, PurchaseEnvironment, PurchaseStatus, PurchaseSubmission, RECONCILE_RUN_RETENTION_DAYS, RestoreRequest, STRIPE_API_VERSION, STRIPE_METADATA_ACCOUNT_REFERENCE, STRIPE_METADATA_PRICE, StripeWebhookNotification, WEBHOOK_EVENT_ORPHANED, appleSubscriptionStatus, applyGrants, authenticatedUserSubject, batchedRailAccess, clawbackGrants, clawbackRef, createPaymentsEntitlementResolver, decodeSubjectReference, encodeSubjectReference, entitlementsForProduct, fulfillPurchase, grantEntitlement, grantRef, grantableEntitlements, grantingStatuses, implementedRails, installEntitlementResolver, isCheckoutRail, isPaymentsCapability, ledgerGrantFor, linkProviderAccount, minorUnitDigits, minorUnitsFromScaled, mintAppleApiToken, noteIsRepairable, noteText, openPaymentsLedger, payments, paymentsDatabase, paymentsExampleSeed, paymentsSecretsRegistry, paymentsTables, paymentsWorkerName, paymentsWorkflowRegistry, paymentsWorkflows, productForProviderSku, projectPurchase, providerAccountForSubject, providerProductId, purchaseIsPaid, railCredentials, railEnabled, reconcilePayments, recordReconcileRun, registerPaymentsRoutes, repairOrphanedEvents, requireAuth, requirePaymentsSubject, resolveEntitlements, resolveNotificationOwner, resolvePaymentsConfig, resolvePaymentsSubject, resolveProduct, resolveRailProvider, revokeEntitlement, sameSubject, statusGrantsAccess, triggerPaymentsReconcile, webhookEventAwaitsOwner };
46
+ export { ACCESS_GRANTING_STATUSES, APPLE_API_AUDIENCE, APPLE_API_BASES, APPLE_ROOT_CERTIFICATES, AppleSubscriptionStatuses, AppleWebhookNotification, CheckoutRequest, DEFAULT_EXPIRING_WITHIN_SECONDS, DEFAULT_STALE_AFTER_SECONDS, EntitlementGrantRequest, EntitlementRevokeRequest, GOOGLE_JWKS_URL, GOOGLE_OIDC_ISSUERS, GoogleJwk, GoogleJwks, GoogleWebhookNotification, ORPHAN_REPAIR_LIMIT, PAYMENTS_CAPABILITY, PAYMENTS_CATALOG_READ_SCOPE, PAYMENTS_CONTROL_PLANE_SCOPES, PAYMENTS_ENTITLEMENTS_TABLE, PAYMENTS_ENTITLEMENT_GRANT_SCOPE, PAYMENTS_ENTITLEMENT_PROVIDER, PAYMENTS_ENTITLEMENT_REVOKE_SCOPE, PAYMENTS_MIGRATION_ORDER, PAYMENTS_PROVIDER_ACCOUNTS_TABLE, PAYMENTS_PROVIDER_SECRET, PAYMENTS_PURCHASES_TABLE, PAYMENTS_RAILS, PAYMENTS_RECONCILE_KEY, PAYMENTS_RECONCILE_RUNS_TABLE, PAYMENTS_WEBHOOK_EVENTS_TABLE, PaymentsAppleCredentials, PaymentsAppleProduct, PaymentsAuditActions, PaymentsConfig, PaymentsEntitlement, PaymentsGoogleCredentials, PaymentsGoogleProduct, PaymentsGrants, PaymentsLedgerGrant, PaymentsLemonSqueezyProduct, PaymentsLemonSqueezySettings, PaymentsPaddleProduct, PaymentsPaddleSettings, PaymentsProduct, PaymentsProductType, PaymentsProviderAccount, PaymentsProviderCredentials, PaymentsPurchase, PaymentsRail, PaymentsRailToggles, PaymentsReconcileParams, PaymentsReconcileRun, PaymentsStripeCredentials, PaymentsStripeProduct, PaymentsStripeSettings, PaymentsSubject, PaymentsSubjectType, PaymentsWebhookEvent, ProviderEvent, PurchaseEnvironment, PurchaseStatus, PurchaseSubmission, RECONCILE_RUN_RETENTION_DAYS, RestoreRequest, STRIPE_API_VERSION, STRIPE_METADATA_ACCOUNT_REFERENCE, STRIPE_METADATA_PRICE, StripeWebhookNotification, WEBHOOK_EVENT_ORPHANED, appleSubscriptionStatus, applyGrants, authenticatedUserSubject, batchedRailAccess, clawbackGrants, clawbackRef, createPaymentsEntitlementResolver, decodeSubjectReference, encodeSubjectReference, entitlementsForProduct, fulfillPurchase, grantEntitlement, grantRef, grantableEntitlements, grantingStatuses, implementedRails, installEntitlementResolver, isCheckoutRail, isPaymentsCapability, isUnimplementedSubject, ledgerGrantFor, linkProviderAccount, minorUnitDigits, minorUnitsFromScaled, mintAppleApiToken, noteIsRepairable, noteText, openPaymentsLedger, payments, paymentsDatabase, paymentsExampleSeed, paymentsSecretsRegistry, paymentsTables, paymentsWorkerName, paymentsWorkflowRegistry, paymentsWorkflows, productForProviderSku, projectPurchase, providerAccountForSubject, providerProductId, purchaseIsPaid, railCredentials, railEnabled, reconcilePayments, recordReconcileRun, registerPaymentsRoutes, repairOrphanedEvents, requireAuth, requireImplementedSubject, requirePaymentsSubject, resolveEntitlements, resolveNotificationOwner, resolvePaymentsConfig, resolvePaymentsSubject, resolveProduct, resolveRailProvider, revokeEntitlement, sameSubject, statusGrantsAccess, triggerPaymentsReconcile, unimplementedSubject, webhookEventAwaitsOwner };
@@ -3,5 +3,5 @@
3
3
  /** This package's npm name — the join key against a release feed. */
4
4
  export declare const PACKAGE_NAME = "@pithy-sh/payments";
5
5
  /** This package's version, stamped from its own package.json at generation time. */
6
- export declare const PACKAGE_VERSION = "0.1.5";
6
+ export declare const PACKAGE_VERSION = "0.2.0";
7
7
  //# sourceMappingURL=version.generated.d.ts.map
@@ -4,6 +4,6 @@
4
4
  /** This package's npm name — the join key against a release feed. */
5
5
  const PACKAGE_NAME = "@pithy-sh/payments";
6
6
  /** This package's version, stamped from its own package.json at generation time. */
7
- const PACKAGE_VERSION = "0.1.5";
7
+ const PACKAGE_VERSION = "0.2.0";
8
8
  //#endregion
9
9
  export { PACKAGE_NAME, PACKAGE_VERSION };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pithy-sh/payments",
3
- "version": "0.1.5",
3
+ "version": "0.2.0",
4
4
  "license": "MIT",
5
5
  "repository": {
6
6
  "type": "git",
@@ -37,7 +37,7 @@
37
37
  "reset": "bun run clean && rm -rf node_modules"
38
38
  },
39
39
  "peerDependencies": {
40
- "@pithy-sh/ledger": "^0.1.4",
40
+ "@pithy-sh/ledger": "^0.1.5",
41
41
  "hono": "^4.13.2",
42
42
  "kysely": "^0.29.0",
43
43
  "react": "^19.0.0",
@@ -55,8 +55,8 @@
55
55
  "@cloudflare/workers-types": "^5.20260729.1",
56
56
  "@hono/zod-validator": "^0.9.0",
57
57
  "@paddle/paddle-js": "^1.6.4",
58
- "@pithy-sh/core": "^0.1.5",
59
- "@pithy-sh/secrets": "^0.1.4"
58
+ "@pithy-sh/core": "^0.2.0",
59
+ "@pithy-sh/secrets": "^0.1.5"
60
60
  },
61
61
  "devDependencies": {
62
62
  "@cloudflare/vitest-plugin": "^1.0.0",
@@ -56,8 +56,8 @@
56
56
  "key": "billingSubject",
57
57
  "choices": ["user", "organization"],
58
58
  "describe": "Who holds a subscription in this project. user \u2014 one person buys, one person is entitled. organization \u2014 a company buys, and everybody in it is entitled. It keys the entitlement column and its UNIQUE index, so changing it once anybody has subscribed is a migration, not an edit.",
59
- "choicesNeedingCode": {
60
- "organization": "It needs a `resolveSubject` seam saying which organization a caller is acting for, and `pithy add` writes JSON, not functions. Add payments with --set billingSubject=user, then in this Worker's pithy.config.ts change it to \"organization\" and pass `resolveSubject` \u2014 see @pithy-sh/payments' README."
59
+ "choicesNeedingSeam": {
60
+ "organization": "paymentsSubject"
61
61
  }
62
62
  },
63
63
  {
package/src/capability.ts CHANGED
@@ -17,6 +17,7 @@ import { PaymentsConfig, type PaymentsConfigInput } from "./config/config";
17
17
  import { paymentsTables } from "./data/tables";
18
18
  import { installEntitlementResolver } from "./entitlement/resolver";
19
19
  import type { PaymentsSubjectResolver, PaymentsSubjectSeam } from "./entitlement/subjectSeam";
20
+ import { requireImplementedSubject } from "./entitlement/unimplementedSubject";
20
21
  import { paymentsManifestConfig } from "./http/manifestConfig";
21
22
  import { registerPaymentsRoutes } from "./http/routes";
22
23
  import { paymentsAdminRoutes } from "./http/scopes";
@@ -156,6 +157,16 @@ function checkLedgerGrants({ capabilities }: CapabilityComposeContext, config: P
156
157
  * request that ever works, so there is nothing to lose by refusing to boot, and a Worker that boots into
157
158
  * that state is one whose first symptom is a support ticket from a paying company.
158
159
  */
160
+ /**
161
+ * **An unimplemented resolver is not an absent one, and this check is deliberately blind to the
162
+ * difference.** `pithy add payments --set billingSubject=organization` scaffolds
163
+ * `src/billing/subject.ts` exporting a placeholder branded unimplemented, and passes it here. It is a
164
+ * resolver, so this returns — which it must, because `payments()` runs every time a Worker's
165
+ * `pithy.config.ts` is evaluated and the CLI evaluates it on nearly every command. Refusing the
166
+ * placeholder here would leave the adopter with no `pithy` at all in the project the scaffold just landed
167
+ * in. `requireImplementedSubject`, on the capability's `boot` hook, is where the placeholder is refused —
168
+ * `createEntrypoint` runs it and nothing else does, so the Worker still will not serve (#500).
169
+ */
159
170
  function requireResolvableSubject(config: PaymentsConfig, resolveSubject: PaymentsSubjectResolver | undefined): void {
160
171
  if (config.billingSubject !== "organization" || resolveSubject !== undefined) return;
161
172
  throw new ValidationError({
@@ -338,6 +349,11 @@ export function payments(options: PaymentsOptions): PaymentsCapability {
338
349
  // The one thing this capability cannot check on its own: whether the ledger it credits agrees the
339
350
  // currency exists. See `checkLedgerGrants` for why the failure is otherwise invisible.
340
351
  compose: (context) => checkLedgerGrants(context, resolved),
352
+ // The other half of {@link requireResolvableSubject}, and it is at the entrypoint rather than at
353
+ // composition on purpose: `pithy add` scaffolds an unimplemented `resolveSubject`, and every `pithy`
354
+ // command evaluates this config to learn what the Worker composes. Refusing here refuses the Worker
355
+ // and leaves the toolchain that fixes it working. See `entitlement/unimplementedSubject.ts`.
356
+ boot: () => requireImplementedSubject(resolveSubject),
341
357
  // What a browser may know. See `clientProjection` for why the list is what it is.
342
358
  client: ({ environment }): PaymentsClientProjection => clientProjection(resolved, environment),
343
359
  requiredBindings,
@@ -0,0 +1,89 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+
4
+ import { InternalError, ValidationError } from "@pithy-sh/core/src/error/pithyError";
5
+ import type { PaymentsSubjectResolver } from "./subjectSeam";
6
+
7
+ /**
8
+ * The placeholder `pithy add payments --set billingSubject=organization` scaffolds, and the brand that
9
+ * makes it recognizably unfinished.
10
+ *
11
+ * ## Why a placeholder is safe here and a stub never is
12
+ *
13
+ * A stub is a resolver that *answers*. Returning `undefined` composes cleanly, satisfies every check the
14
+ * capability can make, and then denies every entitlement gate and raises `payments/subject_unresolved` on
15
+ * every write — which is indistinguishable from a customer who has not paid, and whose first symptom is a
16
+ * support ticket from a paying company. That is strictly worse than refusing to write the config at all,
17
+ * and it is why `pithy add` refused `organization` outright for as long as a stub was the only thing it
18
+ * could have written (#483).
19
+ *
20
+ * This answers nothing. It is a **marked absence**: a function carrying {@link UNIMPLEMENTED_SUBJECT},
21
+ * which `payments()` reads at the Worker's entrypoint and refuses to boot on. So the two facts that used
22
+ * to be in tension both hold — the adopter states `organization`, which is what they mean, and the Worker
23
+ * still will not serve a request until somebody has written the resolver (#500).
24
+ *
25
+ * ## Why the check is at the entrypoint and not at composition
26
+ *
27
+ * `payments()` runs whenever a Worker's `pithy.config.ts` is *evaluated*, and the CLI evaluates that
28
+ * module on nearly every command — `loadWorkerConfig` is how `migrate`, `deploy`, `doctor`, `upgrade` and
29
+ * `add` itself learn what a Worker composes. A refusal at composition would therefore brick the whole CLI
30
+ * in the adopter's project the moment the scaffold landed, which is exactly the #483 regression turned
31
+ * inside out. `createEntrypoint` is the one seam the CLI never crosses: only the Worker's own
32
+ * `src/index.ts` calls it. So the composition check stays what it was — an **absent** resolver is refused,
33
+ * unchanged — and the unimplemented one is refused one seam later, where the audience is a request.
34
+ */
35
+
36
+ /**
37
+ * The brand. `Symbol.for` rather than a module-local symbol or function identity: a project that ends up
38
+ * with two copies of `@pithy-sh/payments` resolved (a transitive range that did not dedupe) would compare
39
+ * a placeholder from one copy against the marker from the other, and identity would answer no — booting a
40
+ * Worker that denies every gate, which is the one outcome this file exists to prevent. A registered symbol
41
+ * is the same symbol in both copies.
42
+ */
43
+ const UNIMPLEMENTED_SUBJECT = Symbol.for("@pithy-sh/payments/unimplemented-subject");
44
+
45
+ /**
46
+ * The scaffolded resolver: branded unimplemented, and a throw if anything ever calls it.
47
+ *
48
+ * A throw rather than `undefined`, and it is belt and braces rather than the mechanism — {@link
49
+ * requireImplementedSubject} means a deployed Worker never gets here. What it covers is every other way
50
+ * this function could be reached: a test composing the capability directly, a tool that assembles a
51
+ * backend without an entrypoint (`pithy ui` reads the composed route tree that way), an adopter who
52
+ * imported the placeholder somewhere of their own. In all of them a loud failure is the right answer and a
53
+ * quiet `undefined` is the failure mode of the stub this replaces.
54
+ */
55
+ export const unimplementedSubject: PaymentsSubjectResolver = Object.defineProperty(
56
+ async () => {
57
+ throw new InternalError({
58
+ message: "The subject resolver for this project has not been written.",
59
+ action: "Implement resolveSubject in this Worker's src/billing/subject.ts.",
60
+ detail:
61
+ 'pithy add scaffolded an unimplemented resolveSubject and it is still the one composed. Under billingSubject: "organization" only the application can say which organization a caller is acting for.',
62
+ });
63
+ },
64
+ UNIMPLEMENTED_SUBJECT,
65
+ { value: true },
66
+ ) as PaymentsSubjectResolver;
67
+
68
+ /** Whether this resolver is the scaffolded placeholder rather than something the adopter wrote. */
69
+ export function isUnimplementedSubject(resolver: PaymentsSubjectResolver | undefined): boolean {
70
+ return resolver !== undefined && (resolver as unknown as Record<symbol, unknown>)[UNIMPLEMENTED_SUBJECT] === true;
71
+ }
72
+
73
+ /**
74
+ * Refuse a Worker whose subject resolver is still the scaffolded placeholder.
75
+ *
76
+ * Called from the capability's `boot` hook, which `createEntrypoint` runs and nothing else does. The
77
+ * message is the adopter's next action and nothing else: the file is named, the question it has to answer
78
+ * is stated, and the alternative is the other billing mode.
79
+ */
80
+ export function requireImplementedSubject(resolver: PaymentsSubjectResolver | undefined): void {
81
+ if (!isUnimplementedSubject(resolver)) return;
82
+ throw new ValidationError({
83
+ message: "This project bills organizations, and its subject resolver is still the scaffolded placeholder.",
84
+ action:
85
+ 'Implement resolveSubject in this Worker\'s src/billing/subject.ts, or set `billingSubject: "user"` in pithy.config.ts.',
86
+ detail:
87
+ "pithy add wrote src/billing/subject.ts exporting an unimplemented resolveSubject, and it is unchanged. Payments has no members table and never guesses a holder, so booting on it would deny every entitlement gate and raise payments/subject_unresolved on every write, for every caller, forever.",
88
+ });
89
+ }
package/src/index.ts CHANGED
@@ -105,6 +105,14 @@ export {
105
105
  requirePaymentsSubject,
106
106
  resolvePaymentsSubject,
107
107
  } from "./entitlement/subjectSeam";
108
+ // The scaffolded placeholder, here beside the resolver type for the same reason that type is: the module
109
+ // `pithy add` writes into `apps/<worker>/src/billing/subject.ts` imports both, and a file the adopter is
110
+ // meant to edit should not reach past the package's documented entrypoint to do it.
111
+ export {
112
+ isUnimplementedSubject,
113
+ requireImplementedSubject,
114
+ unimplementedSubject,
115
+ } from "./entitlement/unimplementedSubject";
108
116
  export {
109
117
  type AppliedGrant,
110
118
  applyGrants,
@@ -13,4 +13,4 @@
13
13
  export const PACKAGE_NAME = "@pithy-sh/payments";
14
14
 
15
15
  /** This package's version, stamped from its own package.json at generation time. */
16
- export const PACKAGE_VERSION = "0.1.5";
16
+ export const PACKAGE_VERSION = "0.2.0";