@stacksjs/payments 0.75.187 → 0.75.188

package/dist/drivers/stripe.d.ts

@@ -1,6 +1,52 @@
 import type Stripe from 'stripe';
-/** Whether this process has the credential required to make Stripe calls. */
+/**
+ * Whether the two things Stripe needs are actually present.
+ *
+ * Reported separately because an app that is missing both should be told
+ * both, and because the two are fixed in different places: one in the
+ * environment, one in the app's package.json (stacksjs/stacks#2911).
+ */
+export declare function stripeAvailability(): StripeAvailability;
+/**
+ * Whether Stripe is usable in this process.
+ *
+ * This used to check only the secret key, so it answered `true` on a tree
+ * where every Stripe call would throw - which is the one answer that makes
+ * the function useless, since the reason to ask is to find that out.
+ */
 export declare function isStripeConfigured(): boolean;
+/**
+ * Why Stripe cannot be used, or null when it can.
+ *
+ * Names everything that is missing rather than the first thing, so an app
+ * missing both the key and the SDK is not told to fix one, redeploy, and
+ * discover the other. Pure, so a caller can report on an availability it
+ * gathered earlier - a boot check, a health endpoint, `doctor`.
+ */
+export declare function describeStripeAvailability(available: StripeAvailability): string | null;
+/**
+ * Say so, once, when this process is set up for Stripe but cannot use it.
+ *
+ * Returns the message it reported, or null when there was nothing to say.
+ *
+ * Called from the API entry points so a tree with no SDK is one line at boot
+ * rather than a 500 inside the first webhook (stacksjs/stacks#2911). It warns
+ * rather than refusing to start: a missing SDK breaks billing, but unlike an
+ * unresolvable middleware alias it cannot serve anything it should not, and
+ * refusing would take down an app carrying a `STRIPE_SECRET_KEY` it no longer
+ * uses.
+ *
+ * Only fires when a key is configured and the SDK is not. A key is what says
+ * the app means to use Stripe; the driver name does not, since `stripe` is
+ * the default for every app that never chose one. A missing key alone is
+ * ordinary in development and says nothing.
+ */
+export declare function reportStripeAvailability(options?: {
+   
+  warn?: (message: string) => void
+   
+  available?: StripeAvailability
+}): string | null;
 /**
  * Lazy-initialized Stripe instance.
  * Only throws when you actually try to use Stripe, not at module load time.
@@ -8,4 +54,9 @@ export declare function isStripeConfigured(): boolean;
  * (e.g., in tests, CLI, or environments that don't use Stripe).
  */
 export declare const stripe: Stripe;
+/** What Stripe needs in order to work, reported separately. */
+export declare interface StripeAvailability {
+  key: boolean
+  sdk: boolean
+}
 declare type StripeConstructor = typeof Stripe;

package/dist/drivers/stripe.js

@@ -1 +1 @@
-import{createRequire}from"node:module";import{services}from"@stacksjs/config";const require=createRequire(import.meta.url);function StripeCtor(){try{return require("stripe")}catch{throw Error("Stripe payments are being used but the `stripe` package is not installed. It is an opt-in dependency - run `bun add stripe` to enable server-side Stripe payments.")}}let _stripe=null;export function isStripeConfigured(){return Boolean(String(services?.stripe?.secretKey||"").trim())}export const stripe=new Proxy({},{get(_target,prop){if(!_stripe){const apiKey=services?.stripe?.secretKey;if(!apiKey)throw Error("Stripe secret key is not configured. Set STRIPE_SECRET_KEY in your .env file.");const Stripe=StripeCtor(),apiVersion=Stripe.API_VERSION,configuredVersion=services?.stripe?.apiVersion;if(configuredVersion&&configuredVersion!==apiVersion)throw Error(`Stripe API version ${configuredVersion} does not match the installed SDK version ${apiVersion}`);_stripe=new Stripe(apiKey,{apiVersion})}return _stripe[prop]}});
+import{createRequire}from"node:module";import{services}from"@stacksjs/config";const require=createRequire(import.meta.url);function StripeCtor(){try{return require("stripe")}catch{throw Error(describeStripeAvailability({key:!0,sdk:!1}))}}let _stripe=null;export function stripeAvailability(){return{key:Boolean(String(services?.stripe?.secretKey||"").trim()),sdk:isStripeSdkInstalled()}}function isStripeSdkInstalled(){try{require.resolve("stripe");return!0}catch{return!1}}export function isStripeConfigured(){const{key,sdk}=stripeAvailability();return key&&sdk}export function describeStripeAvailability(available){if(available.key&&available.sdk)return null;const reasons=[];if(!available.sdk)reasons.push("the `stripe` package is not installed (it is an optional peer, which Bun does not install for you - run `bun add stripe` in your app, pinned to an exact version)");if(!available.key)reasons.push("no Stripe secret key is configured (set STRIPE_SECRET_KEY in your .env)");return`Stripe is being used but is not usable here: ${reasons.join("; and ")}.`}export function reportStripeAvailability(options={}){const available=options.available??stripeAvailability();if(!available.key||available.sdk)return null;const message=describeStripeAvailability(available);(options.warn??console.warn)(`[stacks] ${message}`);return message}export const stripe=new Proxy({},{get(_target,prop){if(!_stripe){const unusable=describeStripeAvailability(stripeAvailability());if(unusable)throw Error(unusable);const apiKey=String(services?.stripe?.secretKey||"").trim(),Stripe=StripeCtor(),apiVersion=Stripe.API_VERSION,configuredVersion=services?.stripe?.apiVersion;if(configuredVersion&&configuredVersion!==apiVersion)throw Error(`Stripe API version ${configuredVersion} does not match the installed SDK version ${apiVersion}`);_stripe=new Stripe(apiKey,{apiVersion})}return _stripe[prop]}});

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/payments",
   "type": "module",
   "sideEffects": false,
-  "version": "0.75.187",
+  "version": "0.75.188",
   "description": "The Stacks payments package. Currently supporting Stripe.",
   "author": "Chris Breuer",
   "contributors": [
@@ -60,12 +60,12 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@stacksjs/config": "0.75.187",
-    "@stacksjs/database": "0.75.187",
-    "@stacksjs/error-handling": "0.75.187",
-    "@stacksjs/logging": "0.75.187",
-    "@stacksjs/orm": "0.75.187",
-    "@stacksjs/types": "0.75.187"
+    "@stacksjs/config": "0.75.188",
+    "@stacksjs/database": "0.75.188",
+    "@stacksjs/error-handling": "0.75.188",
+    "@stacksjs/logging": "0.75.188",
+    "@stacksjs/orm": "0.75.188",
+    "@stacksjs/types": "0.75.188"
   },
   "peerDependencies": {
     "@stripe/stripe-js": "^10.0.0",
@@ -80,7 +80,7 @@
     }
   },
   "devDependencies": {
-    "@stacksjs/utils": "0.75.187",
+    "@stacksjs/utils": "0.75.188",
     "@stripe/stripe-js": "^10.0.0",
     "better-dx": "^0.2.24",
     "stripe": "23.0.0"