@shware/purchase 7.5.0 → 8.0.0

package/dist/google-play/mapper.cjs

@@ -53,6 +53,17 @@ function mapCancellationDetails(context) {
 	return null;
 }
 /**
+* What a paid Play subscription order was for, by its order id. Play numbers a subscription's
+* orders from the first purchase: the initial order is `GPA.1234-5678-9012-34567`, each renewal
+* the same id with `..0`, `..1`, ... appended. A plan change through the Play Store is a new
+* purchase with an order id of its own, so it reads as a start, like any first purchase.
+*
+* ref: [Order ID](https://developer.android.com/google/play/billing/subscriptions#renewals)
+*/
+function mapPaymentType(orderId) {
+	return orderId.includes("..") ? "SUBSCRIPTION_RENEWAL" : "SUBSCRIPTION_START";
+}
+/**
 * When the subscription was cancelled. Only a user cancellation carries the time; for the others
 * the caller falls back to when it learnt of it.
 */
@@ -62,6 +73,7 @@ function mapCanceledAt(context) {
 //#endregion
 exports.mapCanceledAt = mapCanceledAt;
 exports.mapCancellationDetails = mapCancellationDetails;
+exports.mapPaymentType = mapPaymentType;
 exports.mapSubscriptionStatus = mapSubscriptionStatus;
 
 //# sourceMappingURL=mapper.cjs.map

package/dist/google-play/mapper.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"mapper.cjs","names":[],"sources":["../../src/google-play/mapper.ts"],"sourcesContent":["import type { CancellationDetails, SubscriptionStatus } from '../subscription/index';\nimport type { GooglePlaySubscriptionState } from './real-time-developer-notification';\n\nexport function mapSubscriptionStatus(state: GooglePlaySubscriptionState): SubscriptionStatus {\n  switch (state) {\n    case 'SUBSCRIPTION_STATE_PENDING':\n      return 'PENDING';\n    case 'SUBSCRIPTION_STATE_ACTIVE':\n      return 'ACTIVE';\n    case 'SUBSCRIPTION_STATE_PAUSED':\n      return 'PAUSED';\n    case 'SUBSCRIPTION_STATE_IN_GRACE_PERIOD':\n      return 'IN_GRACE_PERIOD';\n    case 'SUBSCRIPTION_STATE_ON_HOLD':\n      return 'ON_HOLD';\n    case 'SUBSCRIPTION_STATE_CANCELED':\n      return 'CANCELED';\n    case 'SUBSCRIPTION_STATE_EXPIRED':\n      return 'EXPIRED';\n    case 'SUBSCRIPTION_STATE_PENDING_PURCHASE_CANCELED':\n      return 'PENDING_PURCHASE_CANCELED';\n    default:\n      throw new Error(`Unknown Google Play subscription state: ${state}`);\n  }\n}\n\n/** Play's cancel-survey answers in the shared vocabulary. */\nconst SURVEY_FEEDBACK: Record<string, CancellationDetails['feedback']> = {\n  CANCEL_SURVEY_REASON_NOT_ENOUGH_USAGE: 'unused',\n  CANCEL_SURVEY_REASON_TECHNICAL_ISSUES: 'low_quality',\n  CANCEL_SURVEY_REASON_COST_RELATED: 'too_expensive',\n  CANCEL_SURVEY_REASON_FOUND_BETTER_APP: 'switched_service',\n  CANCEL_SURVEY_REASON_OTHERS: 'other',\n};\n\n/**\n * `canceledStateContext` of `purchases.subscriptionsv2.get`, declared structurally so this\n * module does not depend on the Play Developer API client.\n */\nexport interface CanceledStateContext {\n  userInitiatedCancellation?: {\n    cancelTime?: string | null;\n    cancelSurveyResult?: { reason?: string | null; reasonUserInput?: string | null } | null;\n  } | null;\n  systemInitiatedCancellation?: object | null;\n  developerInitiatedCancellation?: object | null;\n  replacementCancellation?: object | null;\n}\n\n/**\n * Why a Play subscription stopped renewing. The Play Store asks the user for a reason on cancel\n * (and for free text when it is \"Other\"), which comes back in `cancelSurveyResult`. Null while\n * the subscription renews, and for a replacement: that is the linked purchase taking over, not a\n * cancellation to report.\n */\nexport function mapCancellationDetails(\n  context: CanceledStateContext | null | undefined\n): CancellationDetails | null {\n  if (!context) return null;\n  if (context.userInitiatedCancellation) {\n    const survey = context.userInitiatedCancellation.cancelSurveyResult;\n    return {\n      initiator: 'user',\n      reason: survey?.reason ?? null,\n      feedback: (survey?.reason && SURVEY_FEEDBACK[survey.reason]) || null,\n      comment: survey?.reasonUserInput ?? null,\n    };\n  }\n  if (context.systemInitiatedCancellation) {\n    return { initiator: 'system', reason: 'SYSTEM_INITIATED', feedback: null, comment: null };\n  }\n  if (context.developerInitiatedCancellation) {\n    return { initiator: 'developer', reason: 'DEVELOPER_INITIATED', feedback: null, comment: null };\n  }\n  return null;\n}\n\n/**\n * When the subscription was cancelled. Only a user cancellation carries the time; for the others\n * the caller falls back to when it learnt of it.\n */\nexport function mapCanceledAt(context: CanceledStateContext | null | undefined): string | null {\n  return context?.userInitiatedCancellation?.cancelTime ?? null;\n}\n"],"mappings":";;AAGA,SAAgB,sBAAsB,OAAwD;CAC5F,QAAQ,OAAR;EACE,KAAK,8BACH,OAAO;EACT,KAAK,6BACH,OAAO;EACT,KAAK,6BACH,OAAO;EACT,KAAK,sCACH,OAAO;EACT,KAAK,8BACH,OAAO;EACT,KAAK,+BACH,OAAO;EACT,KAAK,8BACH,OAAO;EACT,KAAK,gDACH,OAAO;EACT,SACE,MAAM,IAAI,MAAM,2CAA2C,OAAO;CACtE;AACF;;AAGA,MAAM,kBAAmE;CACvE,uCAAuC;CACvC,uCAAuC;CACvC,mCAAmC;CACnC,uCAAuC;CACvC,6BAA6B;AAC/B;;;;;;;AAsBA,SAAgB,uBACd,SAC4B;CAC5B,IAAI,CAAC,SAAS,OAAO;CACrB,IAAI,QAAQ,2BAA2B;EACrC,MAAM,SAAS,QAAQ,0BAA0B;EACjD,OAAO;GACL,WAAW;GACX,QAAQ,QAAQ,UAAU;GAC1B,UAAW,QAAQ,UAAU,gBAAgB,OAAO,WAAY;GAChE,SAAS,QAAQ,mBAAmB;EACtC;CACF;CACA,IAAI,QAAQ,6BACV,OAAO;EAAE,WAAW;EAAU,QAAQ;EAAoB,UAAU;EAAM,SAAS;CAAK;CAE1F,IAAI,QAAQ,gCACV,OAAO;EAAE,WAAW;EAAa,QAAQ;EAAuB,UAAU;EAAM,SAAS;CAAK;CAEhG,OAAO;AACT;;;;;AAMA,SAAgB,cAAc,SAAiE;CAC7F,OAAO,SAAS,2BAA2B,cAAc;AAC3D"}
+{"version":3,"file":"mapper.cjs","names":[],"sources":["../../src/google-play/mapper.ts"],"sourcesContent":["import type { CancellationDetails, PaymentType, SubscriptionStatus } from '../subscription/index';\nimport type { GooglePlaySubscriptionState } from './real-time-developer-notification';\n\nexport function mapSubscriptionStatus(state: GooglePlaySubscriptionState): SubscriptionStatus {\n  switch (state) {\n    case 'SUBSCRIPTION_STATE_PENDING':\n      return 'PENDING';\n    case 'SUBSCRIPTION_STATE_ACTIVE':\n      return 'ACTIVE';\n    case 'SUBSCRIPTION_STATE_PAUSED':\n      return 'PAUSED';\n    case 'SUBSCRIPTION_STATE_IN_GRACE_PERIOD':\n      return 'IN_GRACE_PERIOD';\n    case 'SUBSCRIPTION_STATE_ON_HOLD':\n      return 'ON_HOLD';\n    case 'SUBSCRIPTION_STATE_CANCELED':\n      return 'CANCELED';\n    case 'SUBSCRIPTION_STATE_EXPIRED':\n      return 'EXPIRED';\n    case 'SUBSCRIPTION_STATE_PENDING_PURCHASE_CANCELED':\n      return 'PENDING_PURCHASE_CANCELED';\n    default:\n      throw new Error(`Unknown Google Play subscription state: ${state}`);\n  }\n}\n\n/** Play's cancel-survey answers in the shared vocabulary. */\nconst SURVEY_FEEDBACK: Record<string, CancellationDetails['feedback']> = {\n  CANCEL_SURVEY_REASON_NOT_ENOUGH_USAGE: 'unused',\n  CANCEL_SURVEY_REASON_TECHNICAL_ISSUES: 'low_quality',\n  CANCEL_SURVEY_REASON_COST_RELATED: 'too_expensive',\n  CANCEL_SURVEY_REASON_FOUND_BETTER_APP: 'switched_service',\n  CANCEL_SURVEY_REASON_OTHERS: 'other',\n};\n\n/**\n * `canceledStateContext` of `purchases.subscriptionsv2.get`, declared structurally so this\n * module does not depend on the Play Developer API client.\n */\nexport interface CanceledStateContext {\n  userInitiatedCancellation?: {\n    cancelTime?: string | null;\n    cancelSurveyResult?: { reason?: string | null; reasonUserInput?: string | null } | null;\n  } | null;\n  systemInitiatedCancellation?: object | null;\n  developerInitiatedCancellation?: object | null;\n  replacementCancellation?: object | null;\n}\n\n/**\n * Why a Play subscription stopped renewing. The Play Store asks the user for a reason on cancel\n * (and for free text when it is \"Other\"), which comes back in `cancelSurveyResult`. Null while\n * the subscription renews, and for a replacement: that is the linked purchase taking over, not a\n * cancellation to report.\n */\nexport function mapCancellationDetails(\n  context: CanceledStateContext | null | undefined\n): CancellationDetails | null {\n  if (!context) return null;\n  if (context.userInitiatedCancellation) {\n    const survey = context.userInitiatedCancellation.cancelSurveyResult;\n    return {\n      initiator: 'user',\n      reason: survey?.reason ?? null,\n      feedback: (survey?.reason && SURVEY_FEEDBACK[survey.reason]) || null,\n      comment: survey?.reasonUserInput ?? null,\n    };\n  }\n  if (context.systemInitiatedCancellation) {\n    return { initiator: 'system', reason: 'SYSTEM_INITIATED', feedback: null, comment: null };\n  }\n  if (context.developerInitiatedCancellation) {\n    return { initiator: 'developer', reason: 'DEVELOPER_INITIATED', feedback: null, comment: null };\n  }\n  return null;\n}\n\n/**\n * What a paid Play subscription order was for, by its order id. Play numbers a subscription's\n * orders from the first purchase: the initial order is `GPA.1234-5678-9012-34567`, each renewal\n * the same id with `..0`, `..1`, ... appended. A plan change through the Play Store is a new\n * purchase with an order id of its own, so it reads as a start, like any first purchase.\n *\n * ref: [Order ID](https://developer.android.com/google/play/billing/subscriptions#renewals)\n */\nexport function mapPaymentType(orderId: string): Exclude<PaymentType, 'ONE_TIME'> {\n  return orderId.includes('..') ? 'SUBSCRIPTION_RENEWAL' : 'SUBSCRIPTION_START';\n}\n\n/**\n * When the subscription was cancelled. Only a user cancellation carries the time; for the others\n * the caller falls back to when it learnt of it.\n */\nexport function mapCanceledAt(context: CanceledStateContext | null | undefined): string | null {\n  return context?.userInitiatedCancellation?.cancelTime ?? null;\n}\n"],"mappings":";;AAGA,SAAgB,sBAAsB,OAAwD;CAC5F,QAAQ,OAAR;EACE,KAAK,8BACH,OAAO;EACT,KAAK,6BACH,OAAO;EACT,KAAK,6BACH,OAAO;EACT,KAAK,sCACH,OAAO;EACT,KAAK,8BACH,OAAO;EACT,KAAK,+BACH,OAAO;EACT,KAAK,8BACH,OAAO;EACT,KAAK,gDACH,OAAO;EACT,SACE,MAAM,IAAI,MAAM,2CAA2C,OAAO;CACtE;AACF;;AAGA,MAAM,kBAAmE;CACvE,uCAAuC;CACvC,uCAAuC;CACvC,mCAAmC;CACnC,uCAAuC;CACvC,6BAA6B;AAC/B;;;;;;;AAsBA,SAAgB,uBACd,SAC4B;CAC5B,IAAI,CAAC,SAAS,OAAO;CACrB,IAAI,QAAQ,2BAA2B;EACrC,MAAM,SAAS,QAAQ,0BAA0B;EACjD,OAAO;GACL,WAAW;GACX,QAAQ,QAAQ,UAAU;GAC1B,UAAW,QAAQ,UAAU,gBAAgB,OAAO,WAAY;GAChE,SAAS,QAAQ,mBAAmB;EACtC;CACF;CACA,IAAI,QAAQ,6BACV,OAAO;EAAE,WAAW;EAAU,QAAQ;EAAoB,UAAU;EAAM,SAAS;CAAK;CAE1F,IAAI,QAAQ,gCACV,OAAO;EAAE,WAAW;EAAa,QAAQ;EAAuB,UAAU;EAAM,SAAS;CAAK;CAEhG,OAAO;AACT;;;;;;;;;AAUA,SAAgB,eAAe,SAAmD;CAChF,OAAO,QAAQ,SAAS,IAAI,IAAI,yBAAyB;AAC3D;;;;;AAMA,SAAgB,cAAc,SAAiE;CAC7F,OAAO,SAAS,2BAA2B,cAAc;AAC3D"}

package/dist/google-play/mapper.d.cts

@@ -1,4 +1,4 @@
-import { CancellationDetails, SubscriptionStatus } from "../subscription/index.cjs";
+import { CancellationDetails, PaymentType, SubscriptionStatus } from "../subscription/index.cjs";
 import { GooglePlaySubscriptionState } from "./real-time-developer-notification.cjs";
 //#region src/google-play/mapper.d.ts
 export declare function mapSubscriptionStatus(state: GooglePlaySubscriptionState): SubscriptionStatus;
@@ -25,6 +25,15 @@ export interface CanceledStateContext {
  * cancellation to report.
  */
 export declare function mapCancellationDetails(context: CanceledStateContext | null | undefined): CancellationDetails | null;
+/**
+ * What a paid Play subscription order was for, by its order id. Play numbers a subscription's
+ * orders from the first purchase: the initial order is `GPA.1234-5678-9012-34567`, each renewal
+ * the same id with `..0`, `..1`, ... appended. A plan change through the Play Store is a new
+ * purchase with an order id of its own, so it reads as a start, like any first purchase.
+ *
+ * ref: [Order ID](https://developer.android.com/google/play/billing/subscriptions#renewals)
+ */
+export declare function mapPaymentType(orderId: string): Exclude<PaymentType, 'ONE_TIME'>;
 /**
  * When the subscription was cancelled. Only a user cancellation carries the time; for the others
  * the caller falls back to when it learnt of it.

package/dist/google-play/mapper.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"mapper.d.cts","names":[],"sources":["../../src/google-play/mapper.ts"],"mappings":";;;wBAGgB,sBAAsB,OAAO,8BAA8B;;;;;iBAoC1D;EACf;IACE;IACA;MAAuB;MAAwB;;;EAEjD;EACA;EACA;;;;;;;;wBASc,uBACd,SAAS,0CACR;;;;;wBAwBa,cAAc,SAAS"}
+{"version":3,"file":"mapper.d.cts","names":[],"sources":["../../src/google-play/mapper.ts"],"mappings":";;;wBAGgB,sBAAsB,OAAO,8BAA8B;;;;;iBAoC1D;EACf;IACE;IACA;MAAuB;MAAwB;;;EAEjD;EACA;EACA;;;;;;;;wBASc,uBACd,SAAS,0CACR;;;;;;;;;wBA4Ba,eAAe,kBAAkB,QAAQ;;;;;wBAQzC,cAAc,SAAS"}

package/dist/google-play/mapper.d.mts

@@ -1,4 +1,4 @@
-import { CancellationDetails, SubscriptionStatus } from "../subscription/index.mjs";
+import { CancellationDetails, PaymentType, SubscriptionStatus } from "../subscription/index.mjs";
 import { GooglePlaySubscriptionState } from "./real-time-developer-notification.mjs";
 //#region src/google-play/mapper.d.ts
 export declare function mapSubscriptionStatus(state: GooglePlaySubscriptionState): SubscriptionStatus;
@@ -25,6 +25,15 @@ export interface CanceledStateContext {
  * cancellation to report.
  */
 export declare function mapCancellationDetails(context: CanceledStateContext | null | undefined): CancellationDetails | null;
+/**
+ * What a paid Play subscription order was for, by its order id. Play numbers a subscription's
+ * orders from the first purchase: the initial order is `GPA.1234-5678-9012-34567`, each renewal
+ * the same id with `..0`, `..1`, ... appended. A plan change through the Play Store is a new
+ * purchase with an order id of its own, so it reads as a start, like any first purchase.
+ *
+ * ref: [Order ID](https://developer.android.com/google/play/billing/subscriptions#renewals)
+ */
+export declare function mapPaymentType(orderId: string): Exclude<PaymentType, 'ONE_TIME'>;
 /**
  * When the subscription was cancelled. Only a user cancellation carries the time; for the others
  * the caller falls back to when it learnt of it.

package/dist/google-play/mapper.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"mapper.d.mts","names":[],"sources":["../../src/google-play/mapper.ts"],"mappings":";;;wBAGgB,sBAAsB,OAAO,8BAA8B;;;;;iBAoC1D;EACf;IACE;IACA;MAAuB;MAAwB;;;EAEjD;EACA;EACA;;;;;;;;wBASc,uBACd,SAAS,0CACR;;;;;wBAwBa,cAAc,SAAS"}
+{"version":3,"file":"mapper.d.mts","names":[],"sources":["../../src/google-play/mapper.ts"],"mappings":";;;wBAGgB,sBAAsB,OAAO,8BAA8B;;;;;iBAoC1D;EACf;IACE;IACA;MAAuB;MAAwB;;;EAEjD;EACA;EACA;;;;;;;;wBASc,uBACd,SAAS,0CACR;;;;;;;;;wBA4Ba,eAAe,kBAAkB,QAAQ;;;;;wBAQzC,cAAc,SAAS"}

package/dist/google-play/mapper.mjs

@@ -52,6 +52,17 @@ function mapCancellationDetails(context) {
 	return null;
 }
 /**
+* What a paid Play subscription order was for, by its order id. Play numbers a subscription's
+* orders from the first purchase: the initial order is `GPA.1234-5678-9012-34567`, each renewal
+* the same id with `..0`, `..1`, ... appended. A plan change through the Play Store is a new
+* purchase with an order id of its own, so it reads as a start, like any first purchase.
+*
+* ref: [Order ID](https://developer.android.com/google/play/billing/subscriptions#renewals)
+*/
+function mapPaymentType(orderId) {
+	return orderId.includes("..") ? "SUBSCRIPTION_RENEWAL" : "SUBSCRIPTION_START";
+}
+/**
 * When the subscription was cancelled. Only a user cancellation carries the time; for the others
 * the caller falls back to when it learnt of it.
 */
@@ -59,6 +70,6 @@ function mapCanceledAt(context) {
 	return context?.userInitiatedCancellation?.cancelTime ?? null;
 }
 //#endregion
-export { mapCanceledAt, mapCancellationDetails, mapSubscriptionStatus };
+export { mapCanceledAt, mapCancellationDetails, mapPaymentType, mapSubscriptionStatus };
 
 //# sourceMappingURL=mapper.mjs.map

package/dist/google-play/mapper.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"mapper.mjs","names":[],"sources":["../../src/google-play/mapper.ts"],"sourcesContent":["import type { CancellationDetails, SubscriptionStatus } from '../subscription/index';\nimport type { GooglePlaySubscriptionState } from './real-time-developer-notification';\n\nexport function mapSubscriptionStatus(state: GooglePlaySubscriptionState): SubscriptionStatus {\n  switch (state) {\n    case 'SUBSCRIPTION_STATE_PENDING':\n      return 'PENDING';\n    case 'SUBSCRIPTION_STATE_ACTIVE':\n      return 'ACTIVE';\n    case 'SUBSCRIPTION_STATE_PAUSED':\n      return 'PAUSED';\n    case 'SUBSCRIPTION_STATE_IN_GRACE_PERIOD':\n      return 'IN_GRACE_PERIOD';\n    case 'SUBSCRIPTION_STATE_ON_HOLD':\n      return 'ON_HOLD';\n    case 'SUBSCRIPTION_STATE_CANCELED':\n      return 'CANCELED';\n    case 'SUBSCRIPTION_STATE_EXPIRED':\n      return 'EXPIRED';\n    case 'SUBSCRIPTION_STATE_PENDING_PURCHASE_CANCELED':\n      return 'PENDING_PURCHASE_CANCELED';\n    default:\n      throw new Error(`Unknown Google Play subscription state: ${state}`);\n  }\n}\n\n/** Play's cancel-survey answers in the shared vocabulary. */\nconst SURVEY_FEEDBACK: Record<string, CancellationDetails['feedback']> = {\n  CANCEL_SURVEY_REASON_NOT_ENOUGH_USAGE: 'unused',\n  CANCEL_SURVEY_REASON_TECHNICAL_ISSUES: 'low_quality',\n  CANCEL_SURVEY_REASON_COST_RELATED: 'too_expensive',\n  CANCEL_SURVEY_REASON_FOUND_BETTER_APP: 'switched_service',\n  CANCEL_SURVEY_REASON_OTHERS: 'other',\n};\n\n/**\n * `canceledStateContext` of `purchases.subscriptionsv2.get`, declared structurally so this\n * module does not depend on the Play Developer API client.\n */\nexport interface CanceledStateContext {\n  userInitiatedCancellation?: {\n    cancelTime?: string | null;\n    cancelSurveyResult?: { reason?: string | null; reasonUserInput?: string | null } | null;\n  } | null;\n  systemInitiatedCancellation?: object | null;\n  developerInitiatedCancellation?: object | null;\n  replacementCancellation?: object | null;\n}\n\n/**\n * Why a Play subscription stopped renewing. The Play Store asks the user for a reason on cancel\n * (and for free text when it is \"Other\"), which comes back in `cancelSurveyResult`. Null while\n * the subscription renews, and for a replacement: that is the linked purchase taking over, not a\n * cancellation to report.\n */\nexport function mapCancellationDetails(\n  context: CanceledStateContext | null | undefined\n): CancellationDetails | null {\n  if (!context) return null;\n  if (context.userInitiatedCancellation) {\n    const survey = context.userInitiatedCancellation.cancelSurveyResult;\n    return {\n      initiator: 'user',\n      reason: survey?.reason ?? null,\n      feedback: (survey?.reason && SURVEY_FEEDBACK[survey.reason]) || null,\n      comment: survey?.reasonUserInput ?? null,\n    };\n  }\n  if (context.systemInitiatedCancellation) {\n    return { initiator: 'system', reason: 'SYSTEM_INITIATED', feedback: null, comment: null };\n  }\n  if (context.developerInitiatedCancellation) {\n    return { initiator: 'developer', reason: 'DEVELOPER_INITIATED', feedback: null, comment: null };\n  }\n  return null;\n}\n\n/**\n * When the subscription was cancelled. Only a user cancellation carries the time; for the others\n * the caller falls back to when it learnt of it.\n */\nexport function mapCanceledAt(context: CanceledStateContext | null | undefined): string | null {\n  return context?.userInitiatedCancellation?.cancelTime ?? null;\n}\n"],"mappings":";AAGA,SAAgB,sBAAsB,OAAwD;CAC5F,QAAQ,OAAR;EACE,KAAK,8BACH,OAAO;EACT,KAAK,6BACH,OAAO;EACT,KAAK,6BACH,OAAO;EACT,KAAK,sCACH,OAAO;EACT,KAAK,8BACH,OAAO;EACT,KAAK,+BACH,OAAO;EACT,KAAK,8BACH,OAAO;EACT,KAAK,gDACH,OAAO;EACT,SACE,MAAM,IAAI,MAAM,2CAA2C,OAAO;CACtE;AACF;;AAGA,MAAM,kBAAmE;CACvE,uCAAuC;CACvC,uCAAuC;CACvC,mCAAmC;CACnC,uCAAuC;CACvC,6BAA6B;AAC/B;;;;;;;AAsBA,SAAgB,uBACd,SAC4B;CAC5B,IAAI,CAAC,SAAS,OAAO;CACrB,IAAI,QAAQ,2BAA2B;EACrC,MAAM,SAAS,QAAQ,0BAA0B;EACjD,OAAO;GACL,WAAW;GACX,QAAQ,QAAQ,UAAU;GAC1B,UAAW,QAAQ,UAAU,gBAAgB,OAAO,WAAY;GAChE,SAAS,QAAQ,mBAAmB;EACtC;CACF;CACA,IAAI,QAAQ,6BACV,OAAO;EAAE,WAAW;EAAU,QAAQ;EAAoB,UAAU;EAAM,SAAS;CAAK;CAE1F,IAAI,QAAQ,gCACV,OAAO;EAAE,WAAW;EAAa,QAAQ;EAAuB,UAAU;EAAM,SAAS;CAAK;CAEhG,OAAO;AACT;;;;;AAMA,SAAgB,cAAc,SAAiE;CAC7F,OAAO,SAAS,2BAA2B,cAAc;AAC3D"}
+{"version":3,"file":"mapper.mjs","names":[],"sources":["../../src/google-play/mapper.ts"],"sourcesContent":["import type { CancellationDetails, PaymentType, SubscriptionStatus } from '../subscription/index';\nimport type { GooglePlaySubscriptionState } from './real-time-developer-notification';\n\nexport function mapSubscriptionStatus(state: GooglePlaySubscriptionState): SubscriptionStatus {\n  switch (state) {\n    case 'SUBSCRIPTION_STATE_PENDING':\n      return 'PENDING';\n    case 'SUBSCRIPTION_STATE_ACTIVE':\n      return 'ACTIVE';\n    case 'SUBSCRIPTION_STATE_PAUSED':\n      return 'PAUSED';\n    case 'SUBSCRIPTION_STATE_IN_GRACE_PERIOD':\n      return 'IN_GRACE_PERIOD';\n    case 'SUBSCRIPTION_STATE_ON_HOLD':\n      return 'ON_HOLD';\n    case 'SUBSCRIPTION_STATE_CANCELED':\n      return 'CANCELED';\n    case 'SUBSCRIPTION_STATE_EXPIRED':\n      return 'EXPIRED';\n    case 'SUBSCRIPTION_STATE_PENDING_PURCHASE_CANCELED':\n      return 'PENDING_PURCHASE_CANCELED';\n    default:\n      throw new Error(`Unknown Google Play subscription state: ${state}`);\n  }\n}\n\n/** Play's cancel-survey answers in the shared vocabulary. */\nconst SURVEY_FEEDBACK: Record<string, CancellationDetails['feedback']> = {\n  CANCEL_SURVEY_REASON_NOT_ENOUGH_USAGE: 'unused',\n  CANCEL_SURVEY_REASON_TECHNICAL_ISSUES: 'low_quality',\n  CANCEL_SURVEY_REASON_COST_RELATED: 'too_expensive',\n  CANCEL_SURVEY_REASON_FOUND_BETTER_APP: 'switched_service',\n  CANCEL_SURVEY_REASON_OTHERS: 'other',\n};\n\n/**\n * `canceledStateContext` of `purchases.subscriptionsv2.get`, declared structurally so this\n * module does not depend on the Play Developer API client.\n */\nexport interface CanceledStateContext {\n  userInitiatedCancellation?: {\n    cancelTime?: string | null;\n    cancelSurveyResult?: { reason?: string | null; reasonUserInput?: string | null } | null;\n  } | null;\n  systemInitiatedCancellation?: object | null;\n  developerInitiatedCancellation?: object | null;\n  replacementCancellation?: object | null;\n}\n\n/**\n * Why a Play subscription stopped renewing. The Play Store asks the user for a reason on cancel\n * (and for free text when it is \"Other\"), which comes back in `cancelSurveyResult`. Null while\n * the subscription renews, and for a replacement: that is the linked purchase taking over, not a\n * cancellation to report.\n */\nexport function mapCancellationDetails(\n  context: CanceledStateContext | null | undefined\n): CancellationDetails | null {\n  if (!context) return null;\n  if (context.userInitiatedCancellation) {\n    const survey = context.userInitiatedCancellation.cancelSurveyResult;\n    return {\n      initiator: 'user',\n      reason: survey?.reason ?? null,\n      feedback: (survey?.reason && SURVEY_FEEDBACK[survey.reason]) || null,\n      comment: survey?.reasonUserInput ?? null,\n    };\n  }\n  if (context.systemInitiatedCancellation) {\n    return { initiator: 'system', reason: 'SYSTEM_INITIATED', feedback: null, comment: null };\n  }\n  if (context.developerInitiatedCancellation) {\n    return { initiator: 'developer', reason: 'DEVELOPER_INITIATED', feedback: null, comment: null };\n  }\n  return null;\n}\n\n/**\n * What a paid Play subscription order was for, by its order id. Play numbers a subscription's\n * orders from the first purchase: the initial order is `GPA.1234-5678-9012-34567`, each renewal\n * the same id with `..0`, `..1`, ... appended. A plan change through the Play Store is a new\n * purchase with an order id of its own, so it reads as a start, like any first purchase.\n *\n * ref: [Order ID](https://developer.android.com/google/play/billing/subscriptions#renewals)\n */\nexport function mapPaymentType(orderId: string): Exclude<PaymentType, 'ONE_TIME'> {\n  return orderId.includes('..') ? 'SUBSCRIPTION_RENEWAL' : 'SUBSCRIPTION_START';\n}\n\n/**\n * When the subscription was cancelled. Only a user cancellation carries the time; for the others\n * the caller falls back to when it learnt of it.\n */\nexport function mapCanceledAt(context: CanceledStateContext | null | undefined): string | null {\n  return context?.userInitiatedCancellation?.cancelTime ?? null;\n}\n"],"mappings":";AAGA,SAAgB,sBAAsB,OAAwD;CAC5F,QAAQ,OAAR;EACE,KAAK,8BACH,OAAO;EACT,KAAK,6BACH,OAAO;EACT,KAAK,6BACH,OAAO;EACT,KAAK,sCACH,OAAO;EACT,KAAK,8BACH,OAAO;EACT,KAAK,+BACH,OAAO;EACT,KAAK,8BACH,OAAO;EACT,KAAK,gDACH,OAAO;EACT,SACE,MAAM,IAAI,MAAM,2CAA2C,OAAO;CACtE;AACF;;AAGA,MAAM,kBAAmE;CACvE,uCAAuC;CACvC,uCAAuC;CACvC,mCAAmC;CACnC,uCAAuC;CACvC,6BAA6B;AAC/B;;;;;;;AAsBA,SAAgB,uBACd,SAC4B;CAC5B,IAAI,CAAC,SAAS,OAAO;CACrB,IAAI,QAAQ,2BAA2B;EACrC,MAAM,SAAS,QAAQ,0BAA0B;EACjD,OAAO;GACL,WAAW;GACX,QAAQ,QAAQ,UAAU;GAC1B,UAAW,QAAQ,UAAU,gBAAgB,OAAO,WAAY;GAChE,SAAS,QAAQ,mBAAmB;EACtC;CACF;CACA,IAAI,QAAQ,6BACV,OAAO;EAAE,WAAW;EAAU,QAAQ;EAAoB,UAAU;EAAM,SAAS;CAAK;CAE1F,IAAI,QAAQ,gCACV,OAAO;EAAE,WAAW;EAAa,QAAQ;EAAuB,UAAU;EAAM,SAAS;CAAK;CAEhG,OAAO;AACT;;;;;;;;;AAUA,SAAgB,eAAe,SAAmD;CAChF,OAAO,QAAQ,SAAS,IAAI,IAAI,yBAAyB;AAC3D;;;;;AAMA,SAAgB,cAAc,SAAiE;CAC7F,OAAO,SAAS,2BAA2B,cAAc;AAC3D"}

package/dist/index.cjs

@@ -17,3 +17,6 @@ exports.REFUND_STATUS_TRANSITIONS = require_subscription_index.REFUND_STATUS_TRA
 exports.RESUBSCRIBE_INTENTS = require_subscription_index.RESUBSCRIBE_INTENTS;
 exports.SUBSCRIPTION_STATUSES = require_subscription_index.SUBSCRIPTION_STATUSES;
 exports.StripeConfig = require_stripe_config.StripeConfig;
+exports.defineAppStoreConfig = require_app_store_config.defineAppStoreConfig;
+exports.defineGooglePlayConfig = require_google_play_config.defineGooglePlayConfig;
+exports.defineStripeConfig = require_stripe_config.defineStripeConfig;

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { AppStoreConfig } from "./app-store/config.cjs";
+import { AppStoreConfig, defineAppStoreConfig } from "./app-store/config.cjs";
 import { AVAILABLE_STATUSES, CANCELLATION_FEEDBACKS, CANCELLATION_INITIATORS, CLOSED_DISPUTE_STATUSES, CancellationDetails, CancellationFeedback, CancellationInitiator, DISPUTE_STATUSES, DisputeStatus, PAYMENT_TYPES, PLATFORMS, PaymentType, Platform, REFUND_STATUSES, REFUND_STATUS_TRANSITIONS, RESUBSCRIBE_INTENTS, RefundStatus, ResubscribeIntent, SUBSCRIPTION_STATUSES, SubscriptionStatus } from "./subscription/index.cjs";
-import { GooglePlayConfig } from "./google-play/config.cjs";
-import { StripeConfig } from "./stripe/config.cjs";
-export { AVAILABLE_STATUSES, AppStoreConfig, CANCELLATION_FEEDBACKS, CANCELLATION_INITIATORS, CLOSED_DISPUTE_STATUSES, type CancellationDetails, type CancellationFeedback, type CancellationInitiator, DISPUTE_STATUSES, type DisputeStatus, GooglePlayConfig, PAYMENT_TYPES, PLATFORMS, type PaymentType, type Platform, REFUND_STATUSES, REFUND_STATUS_TRANSITIONS, RESUBSCRIBE_INTENTS, type RefundStatus, type ResubscribeIntent, SUBSCRIPTION_STATUSES, StripeConfig, type SubscriptionStatus };
+import { GooglePlayConfig, defineGooglePlayConfig } from "./google-play/config.cjs";
+import { StripeConfig, defineStripeConfig } from "./stripe/config.cjs";
+export { AVAILABLE_STATUSES, AppStoreConfig, CANCELLATION_FEEDBACKS, CANCELLATION_INITIATORS, CLOSED_DISPUTE_STATUSES, type CancellationDetails, type CancellationFeedback, type CancellationInitiator, DISPUTE_STATUSES, type DisputeStatus, GooglePlayConfig, PAYMENT_TYPES, PLATFORMS, type PaymentType, type Platform, REFUND_STATUSES, REFUND_STATUS_TRANSITIONS, RESUBSCRIBE_INTENTS, type RefundStatus, type ResubscribeIntent, SUBSCRIPTION_STATUSES, StripeConfig, type SubscriptionStatus, defineAppStoreConfig, defineGooglePlayConfig, defineStripeConfig };

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { AppStoreConfig } from "./app-store/config.mjs";
+import { AppStoreConfig, defineAppStoreConfig } from "./app-store/config.mjs";
 import { AVAILABLE_STATUSES, CANCELLATION_FEEDBACKS, CANCELLATION_INITIATORS, CLOSED_DISPUTE_STATUSES, CancellationDetails, CancellationFeedback, CancellationInitiator, DISPUTE_STATUSES, DisputeStatus, PAYMENT_TYPES, PLATFORMS, PaymentType, Platform, REFUND_STATUSES, REFUND_STATUS_TRANSITIONS, RESUBSCRIBE_INTENTS, RefundStatus, ResubscribeIntent, SUBSCRIPTION_STATUSES, SubscriptionStatus } from "./subscription/index.mjs";
-import { GooglePlayConfig } from "./google-play/config.mjs";
-import { StripeConfig } from "./stripe/config.mjs";
-export { AVAILABLE_STATUSES, AppStoreConfig, CANCELLATION_FEEDBACKS, CANCELLATION_INITIATORS, CLOSED_DISPUTE_STATUSES, type CancellationDetails, type CancellationFeedback, type CancellationInitiator, DISPUTE_STATUSES, type DisputeStatus, GooglePlayConfig, PAYMENT_TYPES, PLATFORMS, type PaymentType, type Platform, REFUND_STATUSES, REFUND_STATUS_TRANSITIONS, RESUBSCRIBE_INTENTS, type RefundStatus, type ResubscribeIntent, SUBSCRIPTION_STATUSES, StripeConfig, type SubscriptionStatus };
+import { GooglePlayConfig, defineGooglePlayConfig } from "./google-play/config.mjs";
+import { StripeConfig, defineStripeConfig } from "./stripe/config.mjs";
+export { AVAILABLE_STATUSES, AppStoreConfig, CANCELLATION_FEEDBACKS, CANCELLATION_INITIATORS, CLOSED_DISPUTE_STATUSES, type CancellationDetails, type CancellationFeedback, type CancellationInitiator, DISPUTE_STATUSES, type DisputeStatus, GooglePlayConfig, PAYMENT_TYPES, PLATFORMS, type PaymentType, type Platform, REFUND_STATUSES, REFUND_STATUS_TRANSITIONS, RESUBSCRIBE_INTENTS, type RefundStatus, type ResubscribeIntent, SUBSCRIPTION_STATUSES, StripeConfig, type SubscriptionStatus, defineAppStoreConfig, defineGooglePlayConfig, defineStripeConfig };

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { AVAILABLE_STATUSES, CANCELLATION_FEEDBACKS, CANCELLATION_INITIATORS, CLOSED_DISPUTE_STATUSES, DISPUTE_STATUSES, PAYMENT_TYPES, PLATFORMS, REFUND_STATUSES, REFUND_STATUS_TRANSITIONS, RESUBSCRIBE_INTENTS, SUBSCRIPTION_STATUSES } from "./subscription/index.mjs";
-import { AppStoreConfig } from "./app-store/config.mjs";
-import { GooglePlayConfig } from "./google-play/config.mjs";
-import { StripeConfig } from "./stripe/config.mjs";
-export { AVAILABLE_STATUSES, AppStoreConfig, CANCELLATION_FEEDBACKS, CANCELLATION_INITIATORS, CLOSED_DISPUTE_STATUSES, DISPUTE_STATUSES, GooglePlayConfig, PAYMENT_TYPES, PLATFORMS, REFUND_STATUSES, REFUND_STATUS_TRANSITIONS, RESUBSCRIBE_INTENTS, SUBSCRIPTION_STATUSES, StripeConfig };
+import { AppStoreConfig, defineAppStoreConfig } from "./app-store/config.mjs";
+import { GooglePlayConfig, defineGooglePlayConfig } from "./google-play/config.mjs";
+import { StripeConfig, defineStripeConfig } from "./stripe/config.mjs";
+export { AVAILABLE_STATUSES, AppStoreConfig, CANCELLATION_FEEDBACKS, CANCELLATION_INITIATORS, CLOSED_DISPUTE_STATUSES, DISPUTE_STATUSES, GooglePlayConfig, PAYMENT_TYPES, PLATFORMS, REFUND_STATUSES, REFUND_STATUS_TRANSITIONS, RESUBSCRIBE_INTENTS, SUBSCRIPTION_STATUSES, StripeConfig, defineAppStoreConfig, defineGooglePlayConfig, defineStripeConfig };

package/dist/stripe/config.cjs

@@ -1,10 +1,13 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_runtime = require("../_virtual/_rolldown/runtime.cjs");
+const require_catalog = require("../catalog.cjs");
 let _shware_utils = require("@shware/utils");
 let ms = require("ms");
 ms = require_runtime.__toESM(ms, 1);
 //#region src/stripe/config.ts
 const addMethod = Symbol("addMethod");
+/** The private constructor's one door, for this module's `define` function only. */
+const construct = Symbol("construct");
 var Product = class {
 	id;
 	config;
@@ -62,6 +65,9 @@ var StripeConfig = class StripeConfig {
 	successUrl;
 	cancellationCouponId;
 	allowPromotionCodes;
+	namespace;
+	plans;
+	billingPeriods;
 	get productIds() {
 		return Array.from(this.products.keys());
 	}
@@ -73,6 +79,10 @@ var StripeConfig = class StripeConfig {
 		return this;
 	};
 	constructor(options) {
+		require_catalog.assertCatalog(options);
+		this.namespace = options.namespace;
+		this.plans = options.plans;
+		this.billingPeriods = options.billingPeriods;
 		this.mode = options.mode;
 		this.returnUrl = options.returnUrl;
 		this.cancelUrl = options.cancelUrl;
@@ -80,14 +90,16 @@ var StripeConfig = class StripeConfig {
 		this.cancellationCouponId = options.cancellationCouponId;
 		this.allowPromotionCodes = options.allowPromotionCodes;
 	}
-	static create = (options) => {
-		return new StripeConfig(options);
-	};
+	static [construct] = (options) => new StripeConfig(options);
 	/**
 	* One-time products take no extra args; subscriptions require both plan and billingPeriod.
 	* A plan+period pair may be declared on only one product — version its prices in that chain.
 	*/
-	product = (productId, plan = null, billingPeriod = null) => new Product(this, productId, plan, billingPeriod);
+	product = (productId, plan = null, billingPeriod = null) => {
+		require_catalog.assertInNamespace(this.namespace, productId);
+		require_catalog.assertDeclared(this, plan, billingPeriod);
+		return new Product(this, productId, plan, billingPeriod);
+	};
 	getPlan = (productId) => {
 		const product = this.products.get(productId);
 		(0, _shware_utils.invariant)(product, `Product not found for ${productId}`);
@@ -105,6 +117,15 @@ var StripeConfig = class StripeConfig {
 		(0, _shware_utils.invariant)(product, `Product not found for ${productId}`);
 		return product.plan === null ? "payment" : "subscription";
 	};
+	/**
+	* Whether the config declares `productId` and sells it as a subscription, so `getPlan` and
+	* `getBillingPeriod` hold for it. False, not a throw, for an id it does not know: a product that
+	* left the config (renamed, retired) or one named by metadata set outside the app.
+	*/
+	isSubscription = (productId) => {
+		const product = this.products.get(productId);
+		return product !== void 0 && product.plan !== null;
+	};
 	/** The price new checkouts are created with: the default, or its test twin in test mode. */
 	getPriceId = (productId) => {
 		const product = this.products.get(productId);
@@ -122,6 +143,22 @@ var StripeConfig = class StripeConfig {
 		for (const product of this.products.values()) if (product.prices.has(priceId)) return product.id;
 		return null;
 	};
+	/**
+	* How switching from one subscription product to another relates them (see
+	* {@link PlanComparison}), by the order `plans` and `billingPeriods` were declared in. Throws for
+	* a product that is not a subscription.
+	*/
+	comparePlans = (fromProductId, toProductId) => {
+		const level = (productId) => ({
+			plan: this.plans.indexOf(this.getPlan(productId)),
+			period: this.billingPeriods.indexOf(this.getBillingPeriod(productId))
+		});
+		const from = level(fromProductId);
+		const to = level(toProductId);
+		if (to.plan !== from.plan) return to.plan > from.plan ? "upgrade" : "downgrade";
+		if (to.period !== from.period) return to.period > from.period ? "longer" : "shorter";
+		return "same";
+	};
 	getCreditAmount = (productId, priceId) => {
 		const product = this.products.get(productId);
 		(0, _shware_utils.invariant)(product, `Product not found for ${productId}`);
@@ -149,7 +186,16 @@ var StripeConfig = class StripeConfig {
 		return new Date(Date.now() + expiresIn).toISOString();
 	};
 };
+/**
+* Declare the Stripe product catalog. Every type parameter is inferred from the options:
+* the namespace from `namespace`, the plans and billing periods from `plans` and `billingPeriods`
+* (`const`, so a literal array needs no `as const`). Products are then added with the fluent chain.
+*/
+function defineStripeConfig(options) {
+	return StripeConfig[construct](options);
+}
 //#endregion
 exports.StripeConfig = StripeConfig;
+exports.defineStripeConfig = defineStripeConfig;
 
 //# sourceMappingURL=config.cjs.map

package/dist/stripe/config.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"config.cjs","names":[],"sources":["../../src/stripe/config.ts"],"sourcesContent":["import { invariant } from '@shware/utils';\nimport ms from 'ms';\nimport type { Metadata } from '../types';\n\nexport type PriceId = `price_${string}`;\n\n/**\n * Which Stripe object space the config addresses. Test and live prices are\n * disjoint, so a config is built for exactly one of them. Derive it from the\n * secret key (`sk_test_` vs `sk_live_`) rather than from the deployment\n * environment: the key is what actually decides which space API calls hit.\n */\nexport type StripeMode = 'live' | 'test';\n\nconst addMethod = Symbol('addMethod');\n\nclass Product<\n  NS extends Lowercase<string> = Lowercase<string>,\n  PE extends string = string,\n  BP extends string = string,\n  PL extends string = never,\n  PI extends string = never,\n  I extends PriceId = never,\n> {\n  readonly id: string;\n  readonly config: StripeConfig<NS, PE, BP, PL, PI>;\n  readonly plan: PE | null;\n  readonly billingPeriod: BP | null;\n  readonly prices: Map<PriceId, Metadata>;\n\n  defaultPriceId: PriceId | null;\n\n  constructor(\n    config: StripeConfig<NS, PE, BP, PL, PI>,\n    id: string,\n    plan: PE | null = null,\n    billingPeriod: BP | null = null\n  ) {\n    this.id = id;\n    this.config = config;\n    this.plan = plan;\n    this.billingPeriod = billingPeriod;\n    this.prices = new Map();\n    this.defaultPriceId = null;\n  }\n\n  /**\n   * Non-default prices stay declared on purpose: they keep resolving for\n   * grandfathered subscribers and serve as price-experiment arms. Never\n   * create new checkouts with a legacy price unless that is intentional.\n   */\n  price = <K extends PriceId>(\n    priceId: K extends I ? never : K,\n    metadata: Metadata = { credits: 0, expiresIn: '0' }\n  ): Product<NS, PE, BP, PL, PI, I | K> => {\n    invariant(!this.prices.has(priceId), `Duplicate price ${priceId}`);\n    this.prices.set(priceId, metadata);\n    return this as Product<NS, PE, BP, PL, PI, I | K>;\n  };\n\n  /**\n   * `test` is the sandbox twin of the default price. In test mode it is what\n   * checkouts are created with, and it resolves to the default price's\n   * entitlement, so credits are declared once and cannot drift between the\n   * two modes. Legacy prices need no twin: a sandbox holds no grandfathered\n   * subscribers. Live mode ignores it, so a test price reaching a live config\n   * still fails as an unknown price instead of being granted an entitlement.\n   */\n  default = (defaultPriceId: I, twin?: { test: PriceId }) => {\n    const metadata = this.prices.get(defaultPriceId);\n    invariant(metadata, `Default price ${defaultPriceId} is not declared`);\n    if (this.config.mode === 'test') {\n      invariant(twin, `Test price not declared for default ${defaultPriceId} of ${this.id}`);\n      invariant(!this.prices.has(twin.test), `Duplicate price ${twin.test}`);\n      this.prices.set(twin.test, metadata);\n      this.defaultPriceId = twin.test;\n    } else {\n      this.defaultPriceId = defaultPriceId;\n    }\n    this.config[addMethod](this);\n    return this.config;\n  };\n}\n\ntype Options = {\n  mode: StripeMode;\n  returnUrl: string;\n  cancelUrl: string;\n  successUrl: `${string}session_id={CHECKOUT_SESSION_ID}${string}`;\n  cancellationCouponId: string;\n  allowPromotionCodes: boolean;\n};\n\nexport class StripeConfig<\n  NS extends Lowercase<string> = Lowercase<string>,\n  PE extends string = string,\n  BP extends string = string,\n  PL extends string = never,\n  PI extends string = never,\n> {\n  private readonly products: Map<string, Product<NS, PE, BP, PL, PI>> = new Map();\n\n  public readonly mode: StripeMode;\n  public returnUrl: string;\n  public cancelUrl: string;\n  public successUrl: `${string}session_id={CHECKOUT_SESSION_ID}${string}`;\n  public cancellationCouponId: string;\n  public allowPromotionCodes: boolean;\n\n  get productIds(): string[] {\n    return Array.from(this.products.keys());\n  }\n\n  // runtime mirror of the type-level guards: generic accumulation only\n  // protects a single fluent chain, not statement-style re-entry or casts\n  [addMethod] = (product: Product<NS, PE, BP, PL, PI>) => {\n    invariant(!this.products.has(product.id), `Duplicate product ${product.id}`);\n    // A Stripe price belongs to one Stripe product, and getProductId must have one answer.\n    for (const existing of this.products.values()) {\n      for (const priceId of product.prices.keys()) {\n        invariant(!existing.prices.has(priceId), `Duplicate price ${priceId} on ${existing.id}`);\n      }\n    }\n    if (product.plan !== null) {\n      for (const existing of this.products.values()) {\n        invariant(\n          existing.plan !== product.plan || existing.billingPeriod !== product.billingPeriod,\n          `Duplicate plan ${product.plan}:${product.billingPeriod}`\n        );\n      }\n    }\n    this.products.set(product.id, product);\n    return this;\n  };\n\n  private constructor(options: Options) {\n    this.mode = options.mode;\n    this.returnUrl = options.returnUrl;\n    this.cancelUrl = options.cancelUrl;\n    this.successUrl = options.successUrl;\n    this.cancellationCouponId = options.cancellationCouponId;\n    this.allowPromotionCodes = options.allowPromotionCodes;\n  }\n\n  static create = <NS extends Lowercase<string>, PE extends string, BP extends string = string>(\n    options: Options\n  ) => {\n    return new StripeConfig<NS, PE, BP>(options);\n  };\n\n  /**\n   * One-time products take no extra args; subscriptions require both plan and billingPeriod.\n   * A plan+period pair may be declared on only one product — version its prices in that chain.\n   */\n  product: {\n    <K extends `${NS}.${Lowercase<string>}`>(\n      productId: K extends PI ? never : K\n    ): Product<NS, PE, BP, PL, K | PI>;\n    <K extends `${NS}.${Lowercase<string>}`, L extends PE, P extends BP>(\n      productId: K extends PI ? never : K,\n      plan: L,\n      billingPeriod: `${L}:${P}` extends PL ? never : P\n    ): Product<NS, PE, BP, `${L}:${P}` | PL, K | PI>;\n  } = (productId: string, plan: PE | null = null, billingPeriod: BP | null = null) =>\n    // oxlint-disable-next-line typescript/no-unnecessary-type-assertion -- widens to the overloads' accumulated generics\n    new Product(this, productId, plan, billingPeriod) as never;\n\n  getPlan = (productId: string): PE => {\n    const product = this.products.get(productId);\n    invariant(product, `Product not found for ${productId}`);\n    invariant(product.plan, `Product ${productId} is not a subscription`);\n    return product.plan;\n  };\n\n  getBillingPeriod = (productId: string): BP => {\n    const product = this.products.get(productId);\n    invariant(product, `Product not found for ${productId}`);\n    invariant(product.billingPeriod, `Product ${productId} is not a subscription`);\n    return product.billingPeriod;\n  };\n\n  getMode = (productId: string): 'payment' | 'subscription' => {\n    const product = this.products.get(productId);\n    invariant(product, `Product not found for ${productId}`);\n    return product.plan === null ? 'payment' : 'subscription';\n  };\n\n  /** The price new checkouts are created with: the default, or its test twin in test mode. */\n  getPriceId = (productId: string): PriceId => {\n    const product = this.products.get(productId);\n    invariant(product, `Product not found for ${productId}`);\n    invariant(product.defaultPriceId, `Default price not found for product ${productId}`);\n    return product.defaultPriceId;\n  };\n\n  /**\n   * The product that declares `priceId` (a legacy price or the test twin included), or null for a\n   * price this config does not know: one set up by hand in the dashboard, or a test price reaching\n   * a live config. Reading the product from the price a Stripe object charged, rather than from\n   * metadata that may already name the next plan, is what an invoice should be credited by.\n   */\n  getProductId = (priceId: string): string | null => {\n    for (const product of this.products.values()) {\n      if (product.prices.has(priceId as PriceId)) return product.id;\n    }\n    return null;\n  };\n\n  getCreditAmount = (productId: string, priceId?: string): number => {\n    const product = this.products.get(productId);\n    invariant(product, `Product not found for ${productId}`);\n    if (priceId) {\n      const price = product.prices.get(priceId as PriceId);\n      invariant(price, `Price not found for ${priceId}`);\n      return price.credits;\n    }\n\n    invariant(product.defaultPriceId, `Default price not found for product ${productId}`);\n    return product.prices.get(product.defaultPriceId)?.credits ?? 0;\n  };\n\n  private readonly getCreditExpiresIn = (productId: string, priceId?: string): number => {\n    const product = this.products.get(productId);\n    invariant(product, `Product not found for ${productId}`);\n    if (priceId) {\n      const price = product.prices.get(priceId as PriceId);\n      invariant(price, `Price not found for ${priceId}`);\n      return ms(price.expiresIn);\n    }\n\n    invariant(product.defaultPriceId, `Default price not found for product ${productId}`);\n    return ms(product.prices.get(product.defaultPriceId)?.expiresIn ?? '0');\n  };\n\n  getCreditExpiresAt = (productId: string, priceId?: string): string => {\n    const expiresIn = this.getCreditExpiresIn(productId, priceId);\n    return new Date(Date.now() + expiresIn).toISOString();\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"config.cjs","names":[],"sources":["../../src/stripe/config.ts"],"sourcesContent":["import { invariant } from '@shware/utils';\nimport ms from 'ms';\nimport { type Catalog, assertCatalog, assertDeclared, assertInNamespace } from '../catalog';\nimport type { Metadata } from '../types';\n\nexport type PriceId = `price_${string}`;\n\n/**\n * Which Stripe object space the config addresses. Test and live prices are\n * disjoint, so a config is built for exactly one of them. Derive it from the\n * secret key (`sk_test_` vs `sk_live_`) rather than from the deployment\n * environment: the key is what actually decides which space API calls hit.\n */\nexport type StripeMode = 'live' | 'test';\n\nconst addMethod = Symbol('addMethod');\n/** The private constructor's one door, for this module's `define` function only. */\nconst construct = Symbol('construct');\n\nclass Product<\n  NS extends Lowercase<string> = Lowercase<string>,\n  PE extends string = string,\n  BP extends string = string,\n  PL extends string = never,\n  PI extends string = never,\n  I extends PriceId = never,\n> {\n  readonly id: string;\n  readonly config: StripeConfig<NS, PE, BP, PL, PI>;\n  readonly plan: PE | null;\n  readonly billingPeriod: BP | null;\n  readonly prices: Map<PriceId, Metadata>;\n\n  defaultPriceId: PriceId | null;\n\n  constructor(\n    config: StripeConfig<NS, PE, BP, PL, PI>,\n    id: string,\n    plan: PE | null = null,\n    billingPeriod: BP | null = null\n  ) {\n    this.id = id;\n    this.config = config;\n    this.plan = plan;\n    this.billingPeriod = billingPeriod;\n    this.prices = new Map();\n    this.defaultPriceId = null;\n  }\n\n  /**\n   * Non-default prices stay declared on purpose: they keep resolving for\n   * grandfathered subscribers and serve as price-experiment arms. Never\n   * create new checkouts with a legacy price unless that is intentional.\n   */\n  price = <K extends PriceId>(\n    priceId: K extends I ? never : K,\n    metadata: Metadata = { credits: 0, expiresIn: '0' }\n  ): Product<NS, PE, BP, PL, PI, I | K> => {\n    invariant(!this.prices.has(priceId), `Duplicate price ${priceId}`);\n    this.prices.set(priceId, metadata);\n    return this as Product<NS, PE, BP, PL, PI, I | K>;\n  };\n\n  /**\n   * `test` is the sandbox twin of the default price. In test mode it is what\n   * checkouts are created with, and it resolves to the default price's\n   * entitlement, so credits are declared once and cannot drift between the\n   * two modes. Legacy prices need no twin: a sandbox holds no grandfathered\n   * subscribers. Live mode ignores it, so a test price reaching a live config\n   * still fails as an unknown price instead of being granted an entitlement.\n   */\n  default = (defaultPriceId: I, twin?: { test: PriceId }) => {\n    const metadata = this.prices.get(defaultPriceId);\n    invariant(metadata, `Default price ${defaultPriceId} is not declared`);\n    if (this.config.mode === 'test') {\n      invariant(twin, `Test price not declared for default ${defaultPriceId} of ${this.id}`);\n      invariant(!this.prices.has(twin.test), `Duplicate price ${twin.test}`);\n      this.prices.set(twin.test, metadata);\n      this.defaultPriceId = twin.test;\n    } else {\n      this.defaultPriceId = defaultPriceId;\n    }\n    this.config[addMethod](this);\n    return this.config;\n  };\n}\n\n/** `plans` and `billingPeriods` are the order {@link StripeConfig.comparePlans} reads. */\ntype Options<NS extends Lowercase<string>, PE extends string, BP extends string> = Catalog<\n  NS,\n  PE,\n  BP\n> & {\n  mode: StripeMode;\n  returnUrl: string;\n  cancelUrl: string;\n  successUrl: `${string}session_id={CHECKOUT_SESSION_ID}${string}`;\n  cancellationCouponId: string;\n  allowPromotionCodes: boolean;\n};\n\n/**\n * How a switch between two subscription products relates them, by plan level first and billing\n * period second:\n * - `upgrade` / `downgrade`: a higher or lower plan, whatever the periods.\n * - `longer` / `shorter`: the same plan billed over a longer or shorter period (monthly → yearly\n *   is `longer`). Apple calls these crossgrades.\n * - `same`: the same plan and period.\n */\nexport type PlanComparison = 'upgrade' | 'downgrade' | 'longer' | 'shorter' | 'same';\n\nexport class StripeConfig<\n  NS extends Lowercase<string> = Lowercase<string>,\n  PE extends string = string,\n  BP extends string = string,\n  PL extends string = never,\n  PI extends string = never,\n> {\n  private readonly products: Map<string, Product<NS, PE, BP, PL, PI>> = new Map();\n\n  public readonly mode: StripeMode;\n  public returnUrl: string;\n  public cancelUrl: string;\n  public successUrl: `${string}session_id={CHECKOUT_SESSION_ID}${string}`;\n  public cancellationCouponId: string;\n  public allowPromotionCodes: boolean;\n  public readonly namespace: NS;\n  public readonly plans: readonly PE[];\n  public readonly billingPeriods: readonly BP[];\n\n  get productIds(): string[] {\n    return Array.from(this.products.keys());\n  }\n\n  // runtime mirror of the type-level guards: generic accumulation only\n  // protects a single fluent chain, not statement-style re-entry or casts\n  [addMethod] = (product: Product<NS, PE, BP, PL, PI>) => {\n    invariant(!this.products.has(product.id), `Duplicate product ${product.id}`);\n    // A Stripe price belongs to one Stripe product, and getProductId must have one answer.\n    for (const existing of this.products.values()) {\n      for (const priceId of product.prices.keys()) {\n        invariant(!existing.prices.has(priceId), `Duplicate price ${priceId} on ${existing.id}`);\n      }\n    }\n    if (product.plan !== null) {\n      for (const existing of this.products.values()) {\n        invariant(\n          existing.plan !== product.plan || existing.billingPeriod !== product.billingPeriod,\n          `Duplicate plan ${product.plan}:${product.billingPeriod}`\n        );\n      }\n    }\n    this.products.set(product.id, product);\n    return this;\n  };\n\n  private constructor(options: Options<NS, PE, BP>) {\n    assertCatalog(options);\n    this.namespace = options.namespace;\n    this.plans = options.plans;\n    this.billingPeriods = options.billingPeriods;\n    this.mode = options.mode;\n    this.returnUrl = options.returnUrl;\n    this.cancelUrl = options.cancelUrl;\n    this.successUrl = options.successUrl;\n    this.cancellationCouponId = options.cancellationCouponId;\n    this.allowPromotionCodes = options.allowPromotionCodes;\n  }\n\n  static [construct] = <NS extends Lowercase<string>, PE extends string, BP extends string>(\n    options: Options<NS, PE, BP>\n  ) => new StripeConfig<NS, PE, BP>(options);\n\n  /**\n   * One-time products take no extra args; subscriptions require both plan and billingPeriod.\n   * A plan+period pair may be declared on only one product — version its prices in that chain.\n   */\n  product: {\n    <K extends `${NS}.${Lowercase<string>}`>(\n      productId: K extends PI ? never : K\n    ): Product<NS, PE, BP, PL, K | PI>;\n    <K extends `${NS}.${Lowercase<string>}`, L extends PE, P extends BP>(\n      productId: K extends PI ? never : K,\n      plan: L,\n      billingPeriod: `${L}:${P}` extends PL ? never : P\n    ): Product<NS, PE, BP, `${L}:${P}` | PL, K | PI>;\n  } = (productId: string, plan: PE | null = null, billingPeriod: BP | null = null) => {\n    assertInNamespace(this.namespace, productId);\n    assertDeclared(this, plan, billingPeriod);\n    // oxlint-disable-next-line typescript/no-unnecessary-type-assertion -- widens to the overloads' accumulated generics\n    return new Product(this, productId, plan, billingPeriod) as never;\n  };\n\n  getPlan = (productId: string): PE => {\n    const product = this.products.get(productId);\n    invariant(product, `Product not found for ${productId}`);\n    invariant(product.plan, `Product ${productId} is not a subscription`);\n    return product.plan;\n  };\n\n  getBillingPeriod = (productId: string): BP => {\n    const product = this.products.get(productId);\n    invariant(product, `Product not found for ${productId}`);\n    invariant(product.billingPeriod, `Product ${productId} is not a subscription`);\n    return product.billingPeriod;\n  };\n\n  getMode = (productId: string): 'payment' | 'subscription' => {\n    const product = this.products.get(productId);\n    invariant(product, `Product not found for ${productId}`);\n    return product.plan === null ? 'payment' : 'subscription';\n  };\n\n  /**\n   * Whether the config declares `productId` and sells it as a subscription, so `getPlan` and\n   * `getBillingPeriod` hold for it. False, not a throw, for an id it does not know: a product that\n   * left the config (renamed, retired) or one named by metadata set outside the app.\n   */\n  isSubscription = (productId: string): boolean => {\n    const product = this.products.get(productId);\n    return product !== undefined && product.plan !== null;\n  };\n\n  /** The price new checkouts are created with: the default, or its test twin in test mode. */\n  getPriceId = (productId: string): PriceId => {\n    const product = this.products.get(productId);\n    invariant(product, `Product not found for ${productId}`);\n    invariant(product.defaultPriceId, `Default price not found for product ${productId}`);\n    return product.defaultPriceId;\n  };\n\n  /**\n   * The product that declares `priceId` (a legacy price or the test twin included), or null for a\n   * price this config does not know: one set up by hand in the dashboard, or a test price reaching\n   * a live config. Reading the product from the price a Stripe object charged, rather than from\n   * metadata that may already name the next plan, is what an invoice should be credited by.\n   */\n  getProductId = (priceId: string): string | null => {\n    for (const product of this.products.values()) {\n      if (product.prices.has(priceId as PriceId)) return product.id;\n    }\n    return null;\n  };\n\n  /**\n   * How switching from one subscription product to another relates them (see\n   * {@link PlanComparison}), by the order `plans` and `billingPeriods` were declared in. Throws for\n   * a product that is not a subscription.\n   */\n  comparePlans = (fromProductId: string, toProductId: string): PlanComparison => {\n    const level = (productId: string) => ({\n      plan: this.plans.indexOf(this.getPlan(productId)),\n      period: this.billingPeriods.indexOf(this.getBillingPeriod(productId)),\n    });\n    const from = level(fromProductId);\n    const to = level(toProductId);\n    if (to.plan !== from.plan) return to.plan > from.plan ? 'upgrade' : 'downgrade';\n    if (to.period !== from.period) return to.period > from.period ? 'longer' : 'shorter';\n    return 'same';\n  };\n\n  getCreditAmount = (productId: string, priceId?: string): number => {\n    const product = this.products.get(productId);\n    invariant(product, `Product not found for ${productId}`);\n    if (priceId) {\n      const price = product.prices.get(priceId as PriceId);\n      invariant(price, `Price not found for ${priceId}`);\n      return price.credits;\n    }\n\n    invariant(product.defaultPriceId, `Default price not found for product ${productId}`);\n    return product.prices.get(product.defaultPriceId)?.credits ?? 0;\n  };\n\n  private readonly getCreditExpiresIn = (productId: string, priceId?: string): number => {\n    const product = this.products.get(productId);\n    invariant(product, `Product not found for ${productId}`);\n    if (priceId) {\n      const price = product.prices.get(priceId as PriceId);\n      invariant(price, `Price not found for ${priceId}`);\n      return ms(price.expiresIn);\n    }\n\n    invariant(product.defaultPriceId, `Default price not found for product ${productId}`);\n    return ms(product.prices.get(product.defaultPriceId)?.expiresIn ?? '0');\n  };\n\n  getCreditExpiresAt = (productId: string, priceId?: string): string => {\n    const expiresIn = this.getCreditExpiresIn(productId, priceId);\n    return new Date(Date.now() + expiresIn).toISOString();\n  };\n}\n\n/**\n * Declare the Stripe product catalog. Every type parameter is inferred from the options:\n * the namespace from `namespace`, the plans and billing periods from `plans` and `billingPeriods`\n * (`const`, so a literal array needs no `as const`). Products are then added with the fluent chain.\n */\nexport function defineStripeConfig<\n  const NS extends Lowercase<string>,\n  const PE extends string,\n  const BP extends string,\n>(options: Options<NS, PE, BP>): StripeConfig<NS, PE, BP> {\n  return StripeConfig[construct](options);\n}\n"],"mappings":"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"}

package/dist/stripe/config.d.cts

@@ -1,3 +1,4 @@
+import { Catalog } from "../catalog.cjs";
 import { Metadata } from "../types.cjs";
 //#region src/stripe/config.d.ts
 export type PriceId = `price_${string}`;
@@ -9,6 +10,8 @@ export type PriceId = `price_${string}`;
  */
 export type StripeMode = 'live' | 'test';
 declare const addMethod: unique symbol;
+/** The private constructor's one door, for this module's `define` function only. */
+declare const construct: unique symbol;
 declare class Product<NS extends Lowercase<string> = Lowercase<string>, PE extends string = string, BP extends string = string, PL extends string = never, PI extends string = never, I extends PriceId = never> {
   readonly id: string;
   readonly config: StripeConfig<NS, PE, BP, PL, PI>;
@@ -35,7 +38,8 @@ declare class Product<NS extends Lowercase<string> = Lowercase<string>, PE exten
     test: PriceId;
   }) => StripeConfig<NS, PE, BP, PL, PI>;
 }
-type Options = {
+/** `plans` and `billingPeriods` are the order {@link StripeConfig.comparePlans} reads. */
+type Options<NS extends Lowercase<string>, PE extends string, BP extends string> = Catalog<NS, PE, BP> & {
   mode: StripeMode;
   returnUrl: string;
   cancelUrl: string;
@@ -43,6 +47,15 @@ type Options = {
   cancellationCouponId: string;
   allowPromotionCodes: boolean;
 };
+/**
+ * How a switch between two subscription products relates them, by plan level first and billing
+ * period second:
+ * - `upgrade` / `downgrade`: a higher or lower plan, whatever the periods.
+ * - `longer` / `shorter`: the same plan billed over a longer or shorter period (monthly → yearly
+ *   is `longer`). Apple calls these crossgrades.
+ * - `same`: the same plan and period.
+ */
+export type PlanComparison = 'upgrade' | 'downgrade' | 'longer' | 'shorter' | 'same';
 export declare class StripeConfig<NS extends Lowercase<string> = Lowercase<string>, PE extends string = string, BP extends string = string, PL extends string = never, PI extends string = never> {
   private readonly products;
   readonly mode: StripeMode;
@@ -51,10 +64,13 @@ export declare class StripeConfig<NS extends Lowercase<string> = Lowercase<strin
   successUrl: `${string}session_id={CHECKOUT_SESSION_ID}${string}`;
   cancellationCouponId: string;
   allowPromotionCodes: boolean;
+  readonly namespace: NS;
+  readonly plans: readonly PE[];
+  readonly billingPeriods: readonly BP[];
   get productIds(): string[];
   [addMethod]: (product: Product<NS, PE, BP, PL, PI>) => this;
   private constructor();
-  static create: <NS_1 extends Lowercase<string>, PE_1 extends string, BP_1 extends string = string>(options: Options) => StripeConfig<NS_1, PE_1, BP_1, never, never>;
+  static [construct]: <NS_1 extends Lowercase<string>, PE_1 extends string, BP_1 extends string>(options: Options<NS_1, PE_1, BP_1>) => StripeConfig<NS_1, PE_1, BP_1, never, never>;
   /**
    * One-time products take no extra args; subscriptions require both plan and billingPeriod.
    * A plan+period pair may be declared on only one product — version its prices in that chain.
@@ -66,6 +82,12 @@ export declare class StripeConfig<NS extends Lowercase<string> = Lowercase<strin
   getPlan: (productId: string) => PE;
   getBillingPeriod: (productId: string) => BP;
   getMode: (productId: string) => 'payment' | 'subscription';
+  /**
+   * Whether the config declares `productId` and sells it as a subscription, so `getPlan` and
+   * `getBillingPeriod` hold for it. False, not a throw, for an id it does not know: a product that
+   * left the config (renamed, retired) or one named by metadata set outside the app.
+   */
+  isSubscription: (productId: string) => boolean;
   /** The price new checkouts are created with: the default, or its test twin in test mode. */
   getPriceId: (productId: string) => PriceId;
   /**
@@ -75,10 +97,22 @@ export declare class StripeConfig<NS extends Lowercase<string> = Lowercase<strin
    * metadata that may already name the next plan, is what an invoice should be credited by.
    */
   getProductId: (priceId: string) => string | null;
+  /**
+   * How switching from one subscription product to another relates them (see
+   * {@link PlanComparison}), by the order `plans` and `billingPeriods` were declared in. Throws for
+   * a product that is not a subscription.
+   */
+  comparePlans: (fromProductId: string, toProductId: string) => PlanComparison;
   getCreditAmount: (productId: string, priceId?: string) => number;
   private readonly getCreditExpiresIn;
   getCreditExpiresAt: (productId: string, priceId?: string) => string;
 }
+/**
+ * Declare the Stripe product catalog. Every type parameter is inferred from the options:
+ * the namespace from `namespace`, the plans and billing periods from `plans` and `billingPeriods`
+ * (`const`, so a literal array needs no `as const`). Products are then added with the fluent chain.
+ */
+export declare function defineStripeConfig<const NS extends Lowercase<string>, const PE extends string, const BP extends string>(options: Options<NS, PE, BP>): StripeConfig<NS, PE, BP>;
 //#endregion
 export {};
 //# sourceMappingURL=config.d.cts.map

package/dist/stripe/config.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.cts","names":[],"sources":["../../src/stripe/config.ts"],"mappings":";;YAIY;;;;;;;YAQA;cAEN;cAEA,QACJ,WAAW,oBAAoB,mBAC/B,4BACA,4BACA,2BACA,2BACA,UAAU;WAED;WACA,QAAQ,aAAa,IAAI,IAAI,IAAI,IAAI;WACrC,MAAM;WACN,eAAe;WACf,QAAQ,IAAI,SAAS;EAE9B,gBAAgB;EAEhB,YACE,QAAQ,aAAa,IAAI,IAAI,IAAI,IAAI,KACrC,YACA,OAAM,WACN,gBAAe;;;;;;EAejB,QAAS,UAAU,SAAO,SACf,UAAU,YAAY,GAAC,WACtB,aACT,QAAQ,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI;;;;;;;;;EAcnC,UAAO,gBAAoB,GAAC;IAAW,MAAM;QAAS,aAAA,IAAA,IAAA,IAAA,IAAA;;KAgBnD;EACH,MAAM;EACN;EACA;EACA;EACA;EACA;;qBAGW,aACX,WAAW,oBAAoB,mBAC/B,4BACA,4BACA,2BACA;mBAEiB;WAED,MAAM;EACf;EACA;EACA;EACA;EACA;MAEH;GAMH,aAAU,SAAa,QAAQ,IAAI,IAAI,IAAI,IAAI;UAoBzC;SASA,SAAU,aAAW,mBAAmB,qBAAmB,8BAA0B,SACjF,YAAO,aAAA,MAAA,MAAA;;;;;EASlB;KACG,aAAa,MAAM,qBAClB,WAAW,UAAU,aAAa,IACjC,QAAQ,IAAI,IAAI,IAAI,IAAI,IAAI;KAC9B,aAAa,MAAM,qBAAqB,UAAU,IAAI,UAAU,IAC/D,WAAW,UAAU,aAAa,GAClC,MAAM,GACN,kBAAkB,KAAK,YAAY,aAAa,IAC/C,QAAQ,IAAI,IAAI,OAAO,KAAK,MAAM,IAAI,IAAI;;EAK/C,UAAO,sBAAwB;EAO/B,mBAAgB,sBAAwB;EAOxC,UAAO;;EAOP,aAAU,sBAAwB;;;;;;;EAalC,eAAY;EAOZ,kBAAe,mBAAqB;mBAanB;EAajB,qBAAkB,mBAAqB"}
+{"version":3,"file":"config.d.cts","names":[],"sources":["../../src/stripe/config.ts"],"mappings":";;;YAKY;;;;;;;YAQA;cAEN;;cAEA;cAEA,QACJ,WAAW,oBAAoB,mBAC/B,4BACA,4BACA,2BACA,2BACA,UAAU;WAED;WACA,QAAQ,aAAa,IAAI,IAAI,IAAI,IAAI;WACrC,MAAM;WACN,eAAe;WACf,QAAQ,IAAI,SAAS;EAE9B,gBAAgB;EAEhB,YACE,QAAQ,aAAa,IAAI,IAAI,IAAI,IAAI,KACrC,YACA,OAAM,WACN,gBAAe;;;;;;EAejB,QAAS,UAAU,SAAO,SACf,UAAU,YAAY,GAAC,WACtB,aACT,QAAQ,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI;;;;;;;;;EAcnC,UAAO,gBAAoB,GAAC;IAAW,MAAM;QAAS,aAAA,IAAA,IAAA,IAAA,IAAA;;;KAiBnD,QAAQ,WAAW,mBAAmB,mBAAmB,qBAAqB,QACjF,IACA,IACA;EAEA,MAAM;EACN;EACA;EACA;EACA;EACA;;;;;;;;;;YAWU;qBAEC,aACX,WAAW,oBAAoB,mBAC/B,4BACA,4BACA,2BACA;mBAEiB;WAED,MAAM;EACf;EACA;EACA;EACA;EACA;WACS,WAAW;WACX,gBAAgB;WAChB,yBAAyB;MAErC;GAMH,aAAU,SAAa,QAAQ,IAAI,IAAI,IAAI,IAAI;UAoBzC;UAaC,aAAc,aAAW,mBAAmB,qBAAmB,qBAAiB,SAC7E,QAAQ,MAAI,MAAI,UAAG,aAAA,MAAA,MAAA;;;;;EAO9B;KACG,aAAa,MAAM,qBAClB,WAAW,UAAU,aAAa,IACjC,QAAQ,IAAI,IAAI,IAAI,IAAI,IAAI;KAC9B,aAAa,MAAM,qBAAqB,UAAU,IAAI,UAAU,IAC/D,WAAW,UAAU,aAAa,GAClC,MAAM,GACN,kBAAkB,KAAK,YAAY,aAAa,IAC/C,QAAQ,IAAI,IAAI,OAAO,KAAK,MAAM,IAAI,IAAI;;EAQ/C,UAAO,sBAAwB;EAO/B,mBAAgB,sBAAwB;EAOxC,UAAO;;;;;;EAWP,iBAAc;;EAMd,aAAU,sBAAwB;;;;;;;EAalC,eAAY;;;;;;EAYZ,eAAY,uBAAyB,wBAAwB;EAY7D,kBAAe,mBAAqB;mBAanB;EAajB,qBAAkB,mBAAqB;;;;;;;wBAWzB,yBACR,WAAW,yBACX,yBACA,mBACN,SAAS,QAAQ,IAAI,IAAI,MAAM,aAAa,IAAI,IAAI"}

package/dist/stripe/config.d.mts

@@ -1,3 +1,4 @@
+import { Catalog } from "../catalog.mjs";
 import { Metadata } from "../types.mjs";
 //#region src/stripe/config.d.ts
 export type PriceId = `price_${string}`;
@@ -9,6 +10,8 @@ export type PriceId = `price_${string}`;
  */
 export type StripeMode = 'live' | 'test';
 declare const addMethod: unique symbol;
+/** The private constructor's one door, for this module's `define` function only. */
+declare const construct: unique symbol;
 declare class Product<NS extends Lowercase<string> = Lowercase<string>, PE extends string = string, BP extends string = string, PL extends string = never, PI extends string = never, I extends PriceId = never> {
   readonly id: string;
   readonly config: StripeConfig<NS, PE, BP, PL, PI>;
@@ -35,7 +38,8 @@ declare class Product<NS extends Lowercase<string> = Lowercase<string>, PE exten
     test: PriceId;
   }) => StripeConfig<NS, PE, BP, PL, PI>;
 }
-type Options = {
+/** `plans` and `billingPeriods` are the order {@link StripeConfig.comparePlans} reads. */
+type Options<NS extends Lowercase<string>, PE extends string, BP extends string> = Catalog<NS, PE, BP> & {
   mode: StripeMode;
   returnUrl: string;
   cancelUrl: string;
@@ -43,6 +47,15 @@ type Options = {
   cancellationCouponId: string;
   allowPromotionCodes: boolean;
 };
+/**
+ * How a switch between two subscription products relates them, by plan level first and billing
+ * period second:
+ * - `upgrade` / `downgrade`: a higher or lower plan, whatever the periods.
+ * - `longer` / `shorter`: the same plan billed over a longer or shorter period (monthly → yearly
+ *   is `longer`). Apple calls these crossgrades.
+ * - `same`: the same plan and period.
+ */
+export type PlanComparison = 'upgrade' | 'downgrade' | 'longer' | 'shorter' | 'same';
 export declare class StripeConfig<NS extends Lowercase<string> = Lowercase<string>, PE extends string = string, BP extends string = string, PL extends string = never, PI extends string = never> {
   private readonly products;
   readonly mode: StripeMode;
@@ -51,10 +64,13 @@ export declare class StripeConfig<NS extends Lowercase<string> = Lowercase<strin
   successUrl: `${string}session_id={CHECKOUT_SESSION_ID}${string}`;
   cancellationCouponId: string;
   allowPromotionCodes: boolean;
+  readonly namespace: NS;
+  readonly plans: readonly PE[];
+  readonly billingPeriods: readonly BP[];
   get productIds(): string[];
   [addMethod]: (product: Product<NS, PE, BP, PL, PI>) => this;
   private constructor();
-  static create: <NS_1 extends Lowercase<string>, PE_1 extends string, BP_1 extends string = string>(options: Options) => StripeConfig<NS_1, PE_1, BP_1, never, never>;
+  static [construct]: <NS_1 extends Lowercase<string>, PE_1 extends string, BP_1 extends string>(options: Options<NS_1, PE_1, BP_1>) => StripeConfig<NS_1, PE_1, BP_1, never, never>;
   /**
    * One-time products take no extra args; subscriptions require both plan and billingPeriod.
    * A plan+period pair may be declared on only one product — version its prices in that chain.
@@ -66,6 +82,12 @@ export declare class StripeConfig<NS extends Lowercase<string> = Lowercase<strin
   getPlan: (productId: string) => PE;
   getBillingPeriod: (productId: string) => BP;
   getMode: (productId: string) => 'payment' | 'subscription';
+  /**
+   * Whether the config declares `productId` and sells it as a subscription, so `getPlan` and
+   * `getBillingPeriod` hold for it. False, not a throw, for an id it does not know: a product that
+   * left the config (renamed, retired) or one named by metadata set outside the app.
+   */
+  isSubscription: (productId: string) => boolean;
   /** The price new checkouts are created with: the default, or its test twin in test mode. */
   getPriceId: (productId: string) => PriceId;
   /**
@@ -75,10 +97,22 @@ export declare class StripeConfig<NS extends Lowercase<string> = Lowercase<strin
    * metadata that may already name the next plan, is what an invoice should be credited by.
    */
   getProductId: (priceId: string) => string | null;
+  /**
+   * How switching from one subscription product to another relates them (see
+   * {@link PlanComparison}), by the order `plans` and `billingPeriods` were declared in. Throws for
+   * a product that is not a subscription.
+   */
+  comparePlans: (fromProductId: string, toProductId: string) => PlanComparison;
   getCreditAmount: (productId: string, priceId?: string) => number;
   private readonly getCreditExpiresIn;
   getCreditExpiresAt: (productId: string, priceId?: string) => string;
 }
+/**
+ * Declare the Stripe product catalog. Every type parameter is inferred from the options:
+ * the namespace from `namespace`, the plans and billing periods from `plans` and `billingPeriods`
+ * (`const`, so a literal array needs no `as const`). Products are then added with the fluent chain.
+ */
+export declare function defineStripeConfig<const NS extends Lowercase<string>, const PE extends string, const BP extends string>(options: Options<NS, PE, BP>): StripeConfig<NS, PE, BP>;
 //#endregion
 export {};
 //# sourceMappingURL=config.d.mts.map

package/dist/stripe/config.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.mts","names":[],"sources":["../../src/stripe/config.ts"],"mappings":";;YAIY;;;;;;;YAQA;cAEN;cAEA,QACJ,WAAW,oBAAoB,mBAC/B,4BACA,4BACA,2BACA,2BACA,UAAU;WAED;WACA,QAAQ,aAAa,IAAI,IAAI,IAAI,IAAI;WACrC,MAAM;WACN,eAAe;WACf,QAAQ,IAAI,SAAS;EAE9B,gBAAgB;EAEhB,YACE,QAAQ,aAAa,IAAI,IAAI,IAAI,IAAI,KACrC,YACA,OAAM,WACN,gBAAe;;;;;;EAejB,QAAS,UAAU,SAAO,SACf,UAAU,YAAY,GAAC,WACtB,aACT,QAAQ,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI;;;;;;;;;EAcnC,UAAO,gBAAoB,GAAC;IAAW,MAAM;QAAS,aAAA,IAAA,IAAA,IAAA,IAAA;;KAgBnD;EACH,MAAM;EACN;EACA;EACA;EACA;EACA;;qBAGW,aACX,WAAW,oBAAoB,mBAC/B,4BACA,4BACA,2BACA;mBAEiB;WAED,MAAM;EACf;EACA;EACA;EACA;EACA;MAEH;GAMH,aAAU,SAAa,QAAQ,IAAI,IAAI,IAAI,IAAI;UAoBzC;SASA,SAAU,aAAW,mBAAmB,qBAAmB,8BAA0B,SACjF,YAAO,aAAA,MAAA,MAAA;;;;;EASlB;KACG,aAAa,MAAM,qBAClB,WAAW,UAAU,aAAa,IACjC,QAAQ,IAAI,IAAI,IAAI,IAAI,IAAI;KAC9B,aAAa,MAAM,qBAAqB,UAAU,IAAI,UAAU,IAC/D,WAAW,UAAU,aAAa,GAClC,MAAM,GACN,kBAAkB,KAAK,YAAY,aAAa,IAC/C,QAAQ,IAAI,IAAI,OAAO,KAAK,MAAM,IAAI,IAAI;;EAK/C,UAAO,sBAAwB;EAO/B,mBAAgB,sBAAwB;EAOxC,UAAO;;EAOP,aAAU,sBAAwB;;;;;;;EAalC,eAAY;EAOZ,kBAAe,mBAAqB;mBAanB;EAajB,qBAAkB,mBAAqB"}
+{"version":3,"file":"config.d.mts","names":[],"sources":["../../src/stripe/config.ts"],"mappings":";;;YAKY;;;;;;;YAQA;cAEN;;cAEA;cAEA,QACJ,WAAW,oBAAoB,mBAC/B,4BACA,4BACA,2BACA,2BACA,UAAU;WAED;WACA,QAAQ,aAAa,IAAI,IAAI,IAAI,IAAI;WACrC,MAAM;WACN,eAAe;WACf,QAAQ,IAAI,SAAS;EAE9B,gBAAgB;EAEhB,YACE,QAAQ,aAAa,IAAI,IAAI,IAAI,IAAI,KACrC,YACA,OAAM,WACN,gBAAe;;;;;;EAejB,QAAS,UAAU,SAAO,SACf,UAAU,YAAY,GAAC,WACtB,aACT,QAAQ,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI;;;;;;;;;EAcnC,UAAO,gBAAoB,GAAC;IAAW,MAAM;QAAS,aAAA,IAAA,IAAA,IAAA,IAAA;;;KAiBnD,QAAQ,WAAW,mBAAmB,mBAAmB,qBAAqB,QACjF,IACA,IACA;EAEA,MAAM;EACN;EACA;EACA;EACA;EACA;;;;;;;;;;YAWU;qBAEC,aACX,WAAW,oBAAoB,mBAC/B,4BACA,4BACA,2BACA;mBAEiB;WAED,MAAM;EACf;EACA;EACA;EACA;EACA;WACS,WAAW;WACX,gBAAgB;WAChB,yBAAyB;MAErC;GAMH,aAAU,SAAa,QAAQ,IAAI,IAAI,IAAI,IAAI;UAoBzC;UAaC,aAAc,aAAW,mBAAmB,qBAAmB,qBAAiB,SAC7E,QAAQ,MAAI,MAAI,UAAG,aAAA,MAAA,MAAA;;;;;EAO9B;KACG,aAAa,MAAM,qBAClB,WAAW,UAAU,aAAa,IACjC,QAAQ,IAAI,IAAI,IAAI,IAAI,IAAI;KAC9B,aAAa,MAAM,qBAAqB,UAAU,IAAI,UAAU,IAC/D,WAAW,UAAU,aAAa,GAClC,MAAM,GACN,kBAAkB,KAAK,YAAY,aAAa,IAC/C,QAAQ,IAAI,IAAI,OAAO,KAAK,MAAM,IAAI,IAAI;;EAQ/C,UAAO,sBAAwB;EAO/B,mBAAgB,sBAAwB;EAOxC,UAAO;;;;;;EAWP,iBAAc;;EAMd,aAAU,sBAAwB;;;;;;;EAalC,eAAY;;;;;;EAYZ,eAAY,uBAAyB,wBAAwB;EAY7D,kBAAe,mBAAqB;mBAanB;EAajB,qBAAkB,mBAAqB;;;;;;;wBAWzB,yBACR,WAAW,yBACX,yBACA,mBACN,SAAS,QAAQ,IAAI,IAAI,MAAM,aAAa,IAAI,IAAI"}