@agnostack/next-shopify 4.0.0-canary.8 → 4.0.0

package/CHANGELOG.md

@@ -1,3 +1,101 @@
+# [4.0.0](https://github.com/agnostack/next-shopify/compare/v3.3.0...v4.0.0) (2026-10-09)
+
+
+* feat!: require a storage implementation rather than bundling one ([a13f021](https://github.com/agnostack/next-shopify/commit/a13f02143b0836a35e0506443ec9fdbf674518db))
+
+
+### Bug Fixes
+
+* add dev copies of the required peers so checkJs can resolve them ([6c7fdd2](https://github.com/agnostack/next-shopify/commit/6c7fdd2ce0f6094bc0477b48cea39be189bc1329))
+* add pnpm-lock.yaml ([bfc803a](https://github.com/agnostack/next-shopify/commit/bfc803a3e758d72e13a1f201cff266f43a28665d))
+* address the review notes on the checkjs stack ([52dca8d](https://github.com/agnostack/next-shopify/commit/52dca8d006f6d7f192982d5a91c5b814041127ec))
+* align .gitignore with the shared template ([5968bf1](https://github.com/agnostack/next-shopify/commit/5968bf193a32cd0c4f3f45f6d71694b8f872961c))
+* build and test against firebase-admin 14.4.0 ([cf75069](https://github.com/agnostack/next-shopify/commit/cf75069fab599ab29d8e2d95068c91044c7ae191))
+* bump cookies to 0.9.1 ([6e7554c](https://github.com/agnostack/next-shopify/commit/6e7554c3bd85bc57f9bffcafecd7c65564d06160))
+* bump isbot to 5.2.2 and import it by name ([30c1228](https://github.com/agnostack/next-shopify/commit/30c12288f1754809d25a4c9db2334d09c487db08))
+* bump js-base64 to 3.9.3 ([7543e32](https://github.com/agnostack/next-shopify/commit/7543e3220f5b9d265a1ee205caff08d0ef0cf1ae))
+* bump jwt-decode to 4.0.0 ([bc5df03](https://github.com/agnostack/next-shopify/commit/bc5df03761dc691566833ea9fa5e1e93622befb1))
+* bump minimatch to 10.2.6 ([8aa0dc6](https://github.com/agnostack/next-shopify/commit/8aa0dc61678a778522409e2659baa490728d8e2b))
+* bump nextjs-cors to 2.2.1 ([173860d](https://github.com/agnostack/next-shopify/commit/173860dd166f8e7eaade280f5480dcd207f637a6))
+* bump uuid to 11.1.1 and drop its stub typings ([fa02d50](https://github.com/agnostack/next-shopify/commit/fa02d50b52540577a7191fb9b5e02dcba63213c9))
+* cap the firebase-admin peer below 14 ([42b2b32](https://github.com/agnostack/next-shopify/commit/42b2b3259184e623418209704bfd82c86a56481a)), closes [firebase/firebase-admin-node#3164](https://github.com/firebase/firebase-admin-node/issues/3164)
+* compare ArrayBuffer hashes by their byte length ([1b08a62](https://github.com/agnostack/next-shopify/commit/1b08a623fceea251b1721c39fa9907c77b22bb7f))
+* compile the CommonJS sources for the node that can require esm ([f30407a](https://github.com/agnostack/next-shopify/commit/f30407a77e4344d9d6a410b921a9b17edfc891c5))
+* declare typescript as 5.x like the rest of the toolchain ([a1e7ee3](https://github.com/agnostack/next-shopify/commit/a1e7ee38f8bd189265f1590811236ddb29b839af))
+* decode zstd in the proxy response adapter and fail closed on unknown encodings ([cdcd8a5](https://github.com/agnostack/next-shopify/commit/cdcd8a559e9ff772bdcd4e42ce46a3ebf6fca92c))
+* drop jsonwebtoken ([5abb88c](https://github.com/agnostack/next-shopify/commit/5abb88c466e967134ca785c005067566150d4965))
+* fail clearly when the shopify api is bypassed instead of with a TypeError ([d7e647e](https://github.com/agnostack/next-shopify/commit/d7e647e0fd75ffb4e5a09b203768720f6460b153))
+* float firebase-admin to 14.x ([5784493](https://github.com/agnostack/next-shopify/commit/5784493cdbcb3130f54299b364d61f29b0179bdb))
+* float the http-proxy devDependency to 1.18.x ([825819b](https://github.com/agnostack/next-shopify/commit/825819b0e39e8d3b4ef62fec9dfc8ff8a90a924b))
+* give the dual export subpaths a default condition ([10c2c90](https://github.com/agnostack/next-shopify/commit/10c2c9024ccab238444249551d32aeda9520be21))
+* give the test workflow read-only permissions and cancel superseded runs ([2b26326](https://github.com/agnostack/next-shopify/commit/2b26326d78b6bc7c02eac948009e24191dd6274f))
+* hand isbot a string for the User-Agent lookup ([2b42b4c](https://github.com/agnostack/next-shopify/commit/2b42b4c588af3ed0358904e3fffeed2e8401a010))
+* import jsonwebtoken as a default so the esm build links under native node ([3db30d9](https://github.com/agnostack/next-shopify/commit/3db30d9b9d8a6882de7ff714e93b2fc3df3eece2))
+* inflate proxied responses in the adapter so corrupt bodies fail closed ([3056b5d](https://github.com/agnostack/next-shopify/commit/3056b5df9a351368725111feeed7d7371e652e56))
+* keep the storage contract and its implementations in one tree ([2b380e7](https://github.com/agnostack/next-shopify/commit/2b380e789d41385d56f2c4464917db32e888beb1))
+* keep the storage contract in shared and the storage folder for implementations ([e862a11](https://github.com/agnostack/next-shopify/commit/e862a1129b71668fcae431b164ba66e1e51906e7))
+* mark the version-signalling peers optional ([87b2c6d](https://github.com/agnostack/next-shopify/commit/87b2c6de6d7cdd89b9a9b60be56c7955fa85e3df))
+* move both workflows to checkout v6, pnpm/action-setup v6 and setup-node v5 ([46669e7](https://github.com/agnostack/next-shopify/commit/46669e73fd17862726970d622c232486df5eaac5))
+* move the session handler to the modular firebase-admin imports ([0ef15fc](https://github.com/agnostack/next-shopify/commit/0ef15fc7a26a8a6989ca0ec5831d762504e5a89f))
+* move vitest to 4.x ([2b0b7de](https://github.com/agnostack/next-shopify/commit/2b0b7de7b70120cda4b1051a89a1848137e1e377))
+* name getShopifyHelpers' return type so its declaration is emitted ([e871d98](https://github.com/agnostack/next-shopify/commit/e871d987d0ad93d8c8e9442a512067e2ba531bb3))
+* notes and a GitHub release on every publishing branch, changelog only on stable releases ([2c9ad23](https://github.com/agnostack/next-shopify/commit/2c9ad2356a0c3f834bac8423d900078513d0eca0))
+* queue overlapping release runs instead of cancelling them ([d75f9dc](https://github.com/agnostack/next-shopify/commit/d75f9dc0c246e3388b28ef4c4a1429140e8248dd))
+* raise the next and react peer floors to the versions the app runs ([1efb9c9](https://github.com/agnostack/next-shopify/commit/1efb9c95a2c41e6b97a89e1c76610de4a3df7039))
+* read the proxied content-encoding case-insensitively and treat identity as none ([d2e0351](https://github.com/agnostack/next-shopify/commit/d2e03513e93212a95f2cb1c0b6d3173285f5dd0a))
+* reflow the checkJs JSDoc into multi-line blocks and drop the inline parameter casts ([73e855e](https://github.com/agnostack/next-shopify/commit/73e855ea290b13b6eccee5afbd066269f077dcff))
+* replace node-http-proxy-json with a typed responseInterceptor adapter ([45bd502](https://github.com/agnostack/next-shopify/commit/45bd502bf98fb1ddfe057d05e35f6deae123143c))
+* reset the proxied response immediately when the upstream aborts mid-body ([c14225e](https://github.com/agnostack/next-shopify/commit/c14225e10767c1781617d8e4e7d499b2e63d8ab7))
+* resolve modules with node16 and split the tsconfigs ([9b87dd2](https://github.com/agnostack/next-shopify/commit/9b87dd2316c16f0c3272f4b1b57e72233b599e52))
+* run semantic-release through pnpm exec so package keywords are not masked ([39cd371](https://github.com/agnostack/next-shopify/commit/39cd371007223b2bb1bda10c99a907f8ad91b486))
+* satisfy the typecheck and pin the stored document paths ([83b2691](https://github.com/agnostack/next-shopify/commit/83b2691ddaf0b2e5f6b4fe0309a12bd6c56115ee))
+* sign extension session tokens with jose ([0c3b0c0](https://github.com/agnostack/next-shopify/commit/0c3b0c00e017a42d25867032a78c18ada7881d15))
+* skip CI on the release commit ([c277847](https://github.com/agnostack/next-shopify/commit/c277847f20d97eef849a9438945727e898d964e1))
+* standardize version ([6fe44c5](https://github.com/agnostack/next-shopify/commit/6fe44c5ead19be5740ecd6ca58ddad82426f8ed3))
+* standardize version ([4218665](https://github.com/agnostack/next-shopify/commit/42186651b7604a8438a4a01fedb940f5efae4f73))
+* suffix relative imports so the esm build links under native node ([c73827e](https://github.com/agnostack/next-shopify/commit/c73827eea42044c980d11330abe3a5ee6a3a9893))
+* take unknown in ensureStorage, since that is what it is deciding ([5a8a3f8](https://github.com/agnostack/next-shopify/commit/5a8a3f88fd18c5654e0928ab9c69626cd7ec2356))
+* throw a clear error when CryptoHandler is used before it is initialized ([db17f06](https://github.com/agnostack/next-shopify/commit/db17f06ccc489feaa0af7cd5347f2f96cd09d078))
+* type state as the consumer's own data rather than as opaque ([ca13e28](https://github.com/agnostack/next-shopify/commit/ca13e28f1e7f91a8c39c74f516e998c7848f8d0f))
+* type the public helpers surface so it stops discarding the contract ([77088dd](https://github.com/agnostack/next-shopify/commit/77088dd4718a7de119c9446ba52df8648f47a388))
+* type the storage contract so an implementation cannot read what it stores ([06c05bf](https://github.com/agnostack/next-shopify/commit/06c05bf80af1d5b1c2cc3fa8c4d0195e533daf33))
+* type-check the js sources ([61f0783](https://github.com/agnostack/next-shopify/commit/61f0783e7e0108af8304b80a9d6391856afa40c3))
+* verify extension session tokens with jose ([b436d11](https://github.com/agnostack/next-shopify/commit/b436d11b75f09470a98667130937a69753531ed4))
+
+
+### chore
+
+* modernize the toolchain to node 22, pnpm, eslint 9 and vitest ([0cc5cd4](https://github.com/agnostack/next-shopify/commit/0cc5cd4648ae2d173d192018ae204836b064bac8))
+
+
+### Features
+
+* add ESM output and /esm + /shared subpath exports ([52c7c15](https://github.com/agnostack/next-shopify/commit/52c7c1530eaee759c3a02adb663f3d68d6bffe47))
+* declare a session-storage contract and accept an implementation ([9f22481](https://github.com/agnostack/next-shopify/commit/9f22481f4cc65e6edfe908a0505a7daecab75ea3))
+* enable npm trusted publishing with the token as fallback ([e72f5d2](https://github.com/agnostack/next-shopify/commit/e72f5d241e38569814b870c10fb0e499ff82baac))
+* preview the release a labelled PR would cut ([746674c](https://github.com/agnostack/next-shopify/commit/746674c46d52136e706d7559c6daa5334eb6d88b)), closes [#67](https://github.com/agnostack/next-shopify/issues/67)
+* replaced getAPIConfig with API_CONFIG page config literal ([d452ee9](https://github.com/agnostack/next-shopify/commit/d452ee90232a392fc4056ca11451a49a35736e00))
+* thread the storage contract through every handler factory ([e3dfa32](https://github.com/agnostack/next-shopify/commit/e3dfa32a00358bb5bb78236f0d96dec1acebcd0a)), closes [#204](https://github.com/agnostack/next-shopify/issues/204)
+
+
+### BREAKING CHANGES
+
+* getShopifyHelpers no longer falls back to a bundled firestore
+store. Every consumer must pass `storage`; omitting it now throws at composition
+instead of silently writing sessions to a store this package chose. The
+./storage/firestore export and the firebase-admin peer are removed with it.
+
+Also recorded here because 4.0.0-canary.9 shipped it under a `fix:` type: the
+./storage export was retired in favour of ./shared, which carries the contract,
+its types and ensureStorage.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+* requires node >=22.
+
+Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
+* getAPIConfig has been removed — calling it in `export const config` is a fatal build error under next 15's static analyzer. Use the named re-export:
+`export { API_CONFIG as config } from '@agnostack/next-shopify/lib'`
+
 # [3.3.0](https://github.com/agnostack/next-shopify/compare/v3.2.2...v3.3.0) (2025-08-20)
 
 

package/dist/esm/lib/handlers/api/billing.js

@@ -21,8 +21,9 @@ const TERMINAL_STATUSES = [
 /**
  * @param {any} [serverRuntimeConfig]
  * @param {any} [data]
+ * @param {import('../../../shared/index.js').StorageOptions} [options]
  */
-export const handleAppBilling = (serverRuntimeConfig, data) => {
+export const handleAppBilling = (serverRuntimeConfig, data, options) => {
     const { returnResponse = true } = data !== null && data !== void 0 ? data : {};
     /**
      * @param {any} req
@@ -45,7 +46,7 @@ export const handleAppBilling = (serverRuntimeConfig, data) => {
             if (stringEmpty(shop)) {
                 return handleResponse({ handler: 'billing', error: 'Missing shop' });
             }
-            const helpers = await getShopifyHelpers(serverRuntimeConfig, { shop });
+            const helpers = await getShopifyHelpers(serverRuntimeConfig, { shop }, options);
             if (!helpers.shopify) {
                 throw new Error('Shopify API is not initialized');
             }

package/dist/esm/lib/handlers/api/callback.js

@@ -11,8 +11,9 @@ import { isTrue, appendQuery, stringEmpty, ensureArray, ensureString, stringNotE
 /**
  * @param {any} [serverRuntimeConfig]
  * @param {any} [data]
+ * @param {import('../../../shared/index.js').StorageOptions} [options]
  */
-export const handleCallback = (serverRuntimeConfig, data) => {
+export const handleCallback = (serverRuntimeConfig, data, options) => {
     const { API_PATHS, PAGE_PATHS, PAYMENT_CONFIG, } = serverRuntimeConfig;
     const { returnResponse = true } = data !== null && data !== void 0 ? data : {};
     const prepareWebhookHandlers = getPrepareWebhookHandlers(serverRuntimeConfig);
@@ -44,7 +45,7 @@ export const handleCallback = (serverRuntimeConfig, data) => {
         let redirectUrl = `${errorPath}?code=invalid_callback_response`;
         let shopify;
         try {
-            const helpers = await getShopifyHelpers(serverRuntimeConfig, { shop });
+            const helpers = await getShopifyHelpers(serverRuntimeConfig, { shop }, options);
             if (!helpers.shopify) {
                 throw new Error('Shopify API is not initialized');
             }
@@ -88,7 +89,7 @@ export const handleCallback = (serverRuntimeConfig, data) => {
                 // NOTE: handleEnsureBilling handles calling encryptStoreSession for offline session when shouldCheckBilling
                 const confirmationUrl = await handleEnsureBilling(session, { reAuth });
                 if (stringNotEmpty(confirmationUrl)) {
-                    redirectUrl = confirmationUrl;
+                    redirectUrl = `${confirmationUrl}`;
                 }
             }
             // NOTE confirm that state can be appended to the confirmationUrl,

package/dist/esm/lib/handlers/api/uninstall.js

@@ -16,8 +16,9 @@ import { stringEmpty, arrayNotEmpty, } from '../../../shared/index.js';
 /**
  * @param {any} [serverRuntimeConfig]
  * @param {any} [data]
+ * @param {import('../../../shared/index.js').StorageOptions} [options]
  */
-export const handleAppUninstalled = (serverRuntimeConfig, data) => {
+export const handleAppUninstalled = (serverRuntimeConfig, data, options) => {
     const { returnResponse = true } = data !== null && data !== void 0 ? data : {};
     /**
      * @param {any} req
@@ -40,7 +41,7 @@ export const handleAppUninstalled = (serverRuntimeConfig, data) => {
             if (stringEmpty(shop)) {
                 return handleResponse({ handler: 'uninstall', error: 'Missing shop' });
             }
-            const { shopify, findSessionIds, deleteSessions } = await getShopifyHelpers(serverRuntimeConfig, { shop });
+            const { shopify, findSessionIds, deleteSessions } = await getShopifyHelpers(serverRuntimeConfig, { shop }, options);
             if (!shopify) {
                 throw new Error('Shopify API is not initialized');
             }

package/dist/esm/lib/handlers/api/verifiable/appInstallation.js

@@ -4,9 +4,10 @@ import { handleGraph } from './graph.js';
 /**
  * @param {any} [serverRuntimeConfig]
  * @param {any} [data]
+ * @param {import('../../../../shared/index.js').StorageOptions} [options]
  */
-export const handleLoadAppInstallation = (serverRuntimeConfig, data) => {
-    const _handleGraph = handleGraph(serverRuntimeConfig, data);
+export const handleLoadAppInstallation = (serverRuntimeConfig, data, options) => {
+    const _handleGraph = handleGraph(serverRuntimeConfig, data, options);
     const { returnResponse = true } = data !== null && data !== void 0 ? data : {};
     /**
      * @param {any} req

package/dist/esm/lib/handlers/api/verifiable/graph.js

@@ -16,8 +16,9 @@ import { isType, safeParse, stringEmpty, ensureString, ensureObject, ensureArray
 /**
  * @param {any} [serverRuntimeConfig]
  * @param {any} [data]
+ * @param {import('../../../../shared/index.js').StorageOptions} [options]
  */
-export const handleGraph = (serverRuntimeConfig, data) => {
+export const handleGraph = (serverRuntimeConfig, data, options) => {
     const _getVerificationHelpers = getVerificationHelpers(serverRuntimeConfig);
     const { returnResponse = true } = data !== null && data !== void 0 ? data : {};
     /**
@@ -62,7 +63,7 @@ export const handleGraph = (serverRuntimeConfig, data) => {
         let headers;
         let message = 'Error handling query call';
         try {
-            const helpers = await getShopifyHelpers(serverRuntimeConfig, { shop });
+            const helpers = await getShopifyHelpers(serverRuntimeConfig, { shop }, options);
             if (!helpers.shopify) {
                 throw new Error('Shopify API is not initialized');
             }

package/dist/esm/lib/handlers/api/verifiable/proxy.js

@@ -28,11 +28,12 @@ const verifyAppProxySignature = (signature, verifiable, hmacSecret) => {
 /**
  * @param {any} [serverRuntimeConfig]
  * @param {any} [data]
+ * @param {import('../../../../shared/index.js').StorageOptions} [options]
  */
-export const handleProxy = (serverRuntimeConfig, data) => {
+export const handleProxy = (serverRuntimeConfig, data, options) => {
     const { generateReplacements, returnResponse = true } = data !== null && data !== void 0 ? data : {};
     const { API_BASE_PATH, API_URLS, API_PATHS, APP_CONFIG, APP_BASE_URL, TARGET_SAFELIST, ORIGIN_SAFELIST, } = serverRuntimeConfig;
-    const _prepareHeaders = prepareHeaders(serverRuntimeConfig);
+    const _prepareHeaders = prepareHeaders(serverRuntimeConfig, options);
     const _getVerificationHelpers = getVerificationHelpers(serverRuntimeConfig);
     const _getVerifiedSessionData = getVerifiedSessionData(serverRuntimeConfig);
     /**

package/dist/esm/lib/handlers/api/webhook.js

@@ -16,8 +16,9 @@ import { matchHostname, ensureArray, splitCommas, safeParse, stringEmpty, conver
 /**
  * @param {any} [serverRuntimeConfig]
  * @param {any} [data]
+ * @param {import('../../../shared/index.js').StorageOptions} [options]
  */
-export const handleWebhookEvent = (serverRuntimeConfig, data) => {
+export const handleWebhookEvent = (serverRuntimeConfig, data, options) => {
     const { ORIGIN_SAFELIST, WEBHOOK_TOPIC_BLOCKLIST } = serverRuntimeConfig;
     const _a = data !== null && data !== void 0 ? data : {}, { returnResponse = true } = _a, config = __rest(_a, ["returnResponse"]);
     /**
@@ -45,7 +46,7 @@ export const handleWebhookEvent = (serverRuntimeConfig, data) => {
             if (!matchHostname(shop, ORIGIN_SAFELIST)) {
                 return handleResponse({ handler: 'webhook', error: 'Shop is not safelisted' });
             }
-            const { shopify } = await getShopifyHelpers(serverRuntimeConfig, { shop });
+            const { shopify } = await getShopifyHelpers(serverRuntimeConfig, { shop }, options);
             if (!shopify) {
                 throw new Error('Shopify API is not initialized');
             }

package/dist/esm/lib/handlers/ssr/protect.js

@@ -26,8 +26,9 @@ const processRedirect = (url, params, permanent = false) => ({
 /**
  * @param {any} [serverRuntimeConfig]
  * @param {any} [_props]
+ * @param {import('../../../shared/index.js').StorageOptions} [options]
  */
-export const protectRoute = (serverRuntimeConfig, _props) => {
+export const protectRoute = (serverRuntimeConfig, _props, options) => {
     const { PAGE_PATHS, API_PATHS, APP_CONFIG, PAYMENT_CONFIG } = serverRuntimeConfig;
     const { isSessionTokenEnabled } = APP_CONFIG;
     const exitPath = PAGE_PATHS[PAGE_ROUTE_NAMES.EXIT];
@@ -47,7 +48,7 @@ export const protectRoute = (serverRuntimeConfig, _props) => {
             console.info(`${chalk.yellowBright('next-shopify')} - [${chalk.bold('protectRoute')}]: ${`Bypassing local protect - should ONLY happen when running in next to test non-shopify functionality!`}`);
             return { props };
         }
-        const helpers = await getShopifyHelpers(serverRuntimeConfig, { shop });
+        const helpers = await getShopifyHelpers(serverRuntimeConfig, { shop }, options);
         // NOTE: unreachable — allowLocalBypass returned above, and getInitializedShopify makes the same call
         if (!helpers.shopify) {
             throw new Error('Shopify API is not initialized');

package/dist/esm/lib/index.js

@@ -1,4 +1,3 @@
 export * from '../shared/index.js';
 export * from './handlers/index.js';
-export * from '../storage/index.js';
 export { getShopifyHelpers, prepareHeaders } from './utils/index.js';

package/dist/esm/lib/utils/session.js

@@ -12,7 +12,7 @@ var __rest = (this && this.__rest) || function (s, e) {
 import { Base64 } from 'js-base64';
 import { HttpResponseError, RequestedTokenType } from '@shopify/shopify-api';
 import { isTrue, isString, isNumericOnly, ensureString, ensureArray, cleanObject, objectEmpty, stringEmpty, ensureObject, isTokenExpired, stringNotEmpty, objectNotEmpty, stringEmptyOnly, removeLeadingSlash, ShopifyAuthenticationError, ShopifySessionAuthenticationError, ShopifySessionMissingError, ShopifySessionInvalidError, SESSION_TOKEN_PARAM, APP_QUERY, TRANSFORM, } from '../../shared/index.js';
-import { ensureStorage } from '../../storage/index.js';
+import { ensureStorage } from '../../shared/index.js';
 import { ensureBilling } from './billing.js';
 import { replaceHeaders } from './headers.js';
 import { getInitializedShopify } from './shopify.js';
@@ -74,39 +74,26 @@ const prepareSessionPayload = (session) => {
     const _b = _onlineAccessInfo !== null && _onlineAccessInfo !== void 0 ? _onlineAccessInfo : {}, { associated_user } = _b, onlineAccessInfo = __rest(_b, ["associated_user"]);
     return Object.assign({ onlineAccessInfo }, sessionData);
 };
-// NOTE: imported lazily so an app that supplies its own storage never loads firebase-admin,
-// even though it is still the default. PR 4 removes this branch and the peer with it.
-/**
- * @param {any} firebaseConfig
- * @param {any} options
- */
-const createDefaultStorage = async (firebaseConfig, options) => {
-    const { createFirestoreStorage } = await import('../../storage/firestore/index.js');
-    return createFirestoreStorage(firebaseConfig, options);
-};
 // TODO: move to curry??
 /**
  * @param {any} [serverRuntimeConfig]
  * @param {any} [config]
- * @param {{ storage?: import('../../storage/index.js').SessionStorage }} [options]
- *   `storage` defaults to the Firestore implementation, which is the only reason this package
- *   still declares firebase-admin.
+ * @param {import('../../shared/index.js').StorageOptions} options
+ *   ⚠️ `storage` is REQUIRED. There is no bundled implementation to fall back to, so omitting it
+ *   throws here rather than quietly writing sessions somewhere this app does not own.
  * @returns {Promise<import('./types.js').ShopifyHelpers>}
  */
 export const getShopifyHelpers = async (serverRuntimeConfig, config, { storage: _storage } = {}) => {
     var _a, _b;
     const shopify = getInitializedShopify(serverRuntimeConfig);
-    const { APP_ID, FB_CONFIG, FB_ROOT_COLLECTION, SHOPIFY_RUN_MODE, SESSION_CONFIG, PAYMENT_CONFIG, } = serverRuntimeConfig;
+    const { SHOPIFY_RUN_MODE, SESSION_CONFIG, PAYMENT_CONFIG, } = serverRuntimeConfig;
     const { shop } = config !== null && config !== void 0 ? config : {};
     const isReviewMode = isTrue((SHOPIFY_RUN_MODE === 'review') &&
         (PAYMENT_CONFIG === null || PAYMENT_CONFIG === void 0 ? void 0 : PAYMENT_CONFIG.required));
     // TODO: should this use our helper instead (and/or as a fallback)??
     const shopId = (_b = (_a = shopify === null || shopify === void 0 ? void 0 : shopify.utils) === null || _a === void 0 ? void 0 : _a.sanitizeShop) === null || _b === void 0 ? void 0 : _b.call(_a, shop);
     const cryptoHandler = CryptoHandler.getInstance(SESSION_CONFIG);
-    const storage = ensureStorage(_storage !== null && _storage !== void 0 ? _storage : await createDefaultStorage(FB_CONFIG, {
-        collection: FB_ROOT_COLLECTION,
-        configurationId: APP_ID,
-    }));
+    const storage = ensureStorage(_storage);
     // NOTE: this should handle running in next to test non-shopify functionality
     if (!shopify) {
         return {
@@ -232,6 +219,9 @@ export const getShopifyHelpers = async (serverRuntimeConfig, config, { storage:
             rawRequest: req,
             rawResponse: res,
         });
+        // NOTE: the core is the only thing allowed to interpret a stored session. The contract types
+        // these payloads as `unknown` so an implementation cannot read them, which makes this the one
+        // deliberate exception rather than a hole left open for everyone.
         // eslint-disable-next-line @typescript-eslint/no-unused-vars
         const _c = (_b = (await storage.loadSession(shopId, sessionId))) !== null && _b !== void 0 ? _b : {}, { accessToken: encryptedOnlineAccessToken } = _c, storedOnlineSession = __rest(_c, ["accessToken"]);
         let session = storedOnlineSession;
@@ -259,6 +249,9 @@ export const getShopifyHelpers = async (serverRuntimeConfig, config, { storage:
     const verifyOfflineSession = async () => {
         var _a;
         const sessionId = shopify.session.getOfflineId(shop);
+        // NOTE: the core is the only thing allowed to interpret a stored session. The contract types
+        // these payloads as `unknown` so an implementation cannot read them, which makes this the one
+        // deliberate exception rather than a hole left open for everyone.
         const _b = (_a = (await storage.loadSession(shopId, sessionId))) !== null && _a !== void 0 ? _a : {}, { accessToken: encryptedOfflineAccessToken } = _b, offlineSession = __rest(_b, ["accessToken"]);
         return {
             sessionId,
@@ -443,14 +436,17 @@ const extendAppHeaders = (headers, appData) => {
         [`x-shopify-app-metafield-${metafieldKey}`]: value,
     })), headers);
 };
-/** @param {any} [serverRuntimeConfig] */
-export const prepareHeaders = (serverRuntimeConfig) => async ({ generateReplacements, appData, shop, appId, headers: _headers, } = /** @type {any} */ ({})) => {
+/**
+ * @param {any} [serverRuntimeConfig]
+ * @param {import('../../shared/index.js').StorageOptions} [options]
+ */
+export const prepareHeaders = (serverRuntimeConfig, options) => async ({ generateReplacements, appData, shop, appId, headers: _headers, } = /** @type {any} */ ({})) => {
     const headers = cleanObject(_headers, false, stringEmptyOnly);
     if (objectEmpty(headers) || !generateReplacements) {
         return headers;
     }
     if (!appData) {
-        const { loadAppData } = await getShopifyHelpers(serverRuntimeConfig, { shop });
+        const { loadAppData } = await getShopifyHelpers(serverRuntimeConfig, { shop }, options);
         appData = await loadAppData({ appId }); // NOTE: this handles even if no appId
     }
     if (!appData) {

package/dist/esm/shared/index.js

@@ -5,5 +5,7 @@ export * from './errors.js';
 export * from './graph.js';
 export * from './match.js';
 export * from './shopify.js';
+export * from './storage.js';
+export * from './types.js';
 export * from './theme.js';
 export * from './uuid.js';

package/dist/esm/shared/storage.js

@@ -0,0 +1,35 @@
+import { ensureArray } from './display.js';
+export const STORAGE_METHODS = [
+    'loadState',
+    'storeState',
+    'deleteState',
+    'loadSession',
+    'updateSession',
+    'deleteSessions',
+    'findSessionIds'
+];
+/**
+ * Fails at composition rather than at the first OAuth round-trip. Nothing automated covers the
+ * Shopify auth flow, so a missing method would otherwise surface as a runtime TypeError in a
+ * callback that needs a real dev store to reach.
+ *
+ * ⚠️ Takes `unknown` on purpose. Whether this is a SessionStorage is what the function decides,
+ * so the argument cannot be typed as one, and `any` would let the body use it before checking.
+ *
+ * @param {unknown} storage
+ * @returns {import('./types.js').SessionStorage}
+ */
+export const ensureStorage = (storage) => {
+    const candidate = /** @type {Record<string, unknown> | null | undefined} */ (storage);
+    // ⚠️ the upgrade path, called out separately: this package used to bundle a firestore store and
+    // fall back to it. Listing all seven methods as missing would be true and would not explain why.
+    if (!candidate) {
+        throw new Error('No session storage supplied. Pass one as `storage` - this package no longer bundles a default.');
+    }
+    const missing = ensureArray(STORAGE_METHODS).filter((method) => (typeof (candidate === null || candidate === void 0 ? void 0 : candidate[method]) !== 'function'));
+    if (missing.length) {
+        throw new Error(`Invalid session storage, missing: ${missing.join(', ')}`);
+    }
+    // the one place the assertion is earned: every method is present, so it is a SessionStorage
+    return /** @type {import('./types.js').SessionStorage} */ (storage);
+};

package/dist/esm/shared/types.js

@@ -0,0 +1,3 @@
+// The session-storage contract. Types rather than JSDoc typedefs because that is nearly all this
+// is, and because tsc preserves JSDoc into the emitted JavaScript, where none of it belongs.
+export {};

package/dist/lib/handlers/api/billing.d.ts

@@ -1 +1 @@
-export function handleAppBilling(serverRuntimeConfig?: any, data?: any): (req: any, res: any) => Promise<any>;
+export function handleAppBilling(serverRuntimeConfig?: any, data?: any, options?: import("../../../shared/index.js").StorageOptions): (req: any, res: any) => Promise<any>;

package/dist/lib/handlers/api/billing.js

@@ -24,8 +24,9 @@ const TERMINAL_STATUSES = [
 /**
  * @param {any} [serverRuntimeConfig]
  * @param {any} [data]
+ * @param {import('../../../shared/index.js').StorageOptions} [options]
  */
-const handleAppBilling = (serverRuntimeConfig, data) => {
+const handleAppBilling = (serverRuntimeConfig, data, options) => {
     const { returnResponse = true } = data !== null && data !== void 0 ? data : {};
     /**
      * @param {any} req
@@ -48,7 +49,7 @@ const handleAppBilling = (serverRuntimeConfig, data) => {
             if ((0, index_js_2.stringEmpty)(shop)) {
                 return handleResponse({ handler: 'billing', error: 'Missing shop' });
             }
-            const helpers = await (0, index_js_1.getShopifyHelpers)(serverRuntimeConfig, { shop });
+            const helpers = await (0, index_js_1.getShopifyHelpers)(serverRuntimeConfig, { shop }, options);
             if (!helpers.shopify) {
                 throw new Error('Shopify API is not initialized');
             }

package/dist/lib/handlers/api/callback.d.ts

@@ -1 +1 @@
-export function handleCallback(serverRuntimeConfig?: any, data?: any): (req: any, res: any, params: any) => Promise<any>;
+export function handleCallback(serverRuntimeConfig?: any, data?: any, options?: import("../../../shared/index.js").StorageOptions): (req: any, res: any, params: any) => Promise<any>;

package/dist/lib/handlers/api/callback.js

@@ -14,8 +14,9 @@ const index_js_2 = require("../../../shared/index.js");
 /**
  * @param {any} [serverRuntimeConfig]
  * @param {any} [data]
+ * @param {import('../../../shared/index.js').StorageOptions} [options]
  */
-const handleCallback = (serverRuntimeConfig, data) => {
+const handleCallback = (serverRuntimeConfig, data, options) => {
     const { API_PATHS, PAGE_PATHS, PAYMENT_CONFIG, } = serverRuntimeConfig;
     const { returnResponse = true } = data !== null && data !== void 0 ? data : {};
     const prepareWebhookHandlers = (0, index_js_1.getPrepareWebhookHandlers)(serverRuntimeConfig);
@@ -47,7 +48,7 @@ const handleCallback = (serverRuntimeConfig, data) => {
         let redirectUrl = `${errorPath}?code=invalid_callback_response`;
         let shopify;
         try {
-            const helpers = await (0, index_js_1.getShopifyHelpers)(serverRuntimeConfig, { shop });
+            const helpers = await (0, index_js_1.getShopifyHelpers)(serverRuntimeConfig, { shop }, options);
             if (!helpers.shopify) {
                 throw new Error('Shopify API is not initialized');
             }
@@ -91,7 +92,7 @@ const handleCallback = (serverRuntimeConfig, data) => {
                 // NOTE: handleEnsureBilling handles calling encryptStoreSession for offline session when shouldCheckBilling
                 const confirmationUrl = await handleEnsureBilling(session, { reAuth });
                 if ((0, index_js_2.stringNotEmpty)(confirmationUrl)) {
-                    redirectUrl = confirmationUrl;
+                    redirectUrl = `${confirmationUrl}`;
                 }
             }
             // NOTE confirm that state can be appended to the confirmationUrl,

package/dist/lib/handlers/api/uninstall.d.ts

@@ -1 +1 @@
-export function handleAppUninstalled(serverRuntimeConfig?: any, data?: any): (req: any, res: any) => Promise<any>;
+export function handleAppUninstalled(serverRuntimeConfig?: any, data?: any, options?: import("../../../shared/index.js").StorageOptions): (req: any, res: any) => Promise<any>;

package/dist/lib/handlers/api/uninstall.js

@@ -19,8 +19,9 @@ const index_js_2 = require("../../../shared/index.js");
 /**
  * @param {any} [serverRuntimeConfig]
  * @param {any} [data]
+ * @param {import('../../../shared/index.js').StorageOptions} [options]
  */
-const handleAppUninstalled = (serverRuntimeConfig, data) => {
+const handleAppUninstalled = (serverRuntimeConfig, data, options) => {
     const { returnResponse = true } = data !== null && data !== void 0 ? data : {};
     /**
      * @param {any} req
@@ -43,7 +44,7 @@ const handleAppUninstalled = (serverRuntimeConfig, data) => {
             if ((0, index_js_2.stringEmpty)(shop)) {
                 return handleResponse({ handler: 'uninstall', error: 'Missing shop' });
             }
-            const { shopify, findSessionIds, deleteSessions } = await (0, index_js_1.getShopifyHelpers)(serverRuntimeConfig, { shop });
+            const { shopify, findSessionIds, deleteSessions } = await (0, index_js_1.getShopifyHelpers)(serverRuntimeConfig, { shop }, options);
             if (!shopify) {
                 throw new Error('Shopify API is not initialized');
             }

package/dist/lib/handlers/api/verifiable/appInstallation.d.ts

@@ -1 +1 @@
-export function handleLoadAppInstallation(serverRuntimeConfig?: any, data?: any): (req: any, res: any, params: any) => Promise<any>;
+export function handleLoadAppInstallation(serverRuntimeConfig?: any, data?: any, options?: import("../../../../shared/index.js").StorageOptions): (req: any, res: any, params: any) => Promise<any>;

package/dist/lib/handlers/api/verifiable/appInstallation.js

@@ -7,9 +7,10 @@ const graph_js_1 = require("./graph.js");
 /**
  * @param {any} [serverRuntimeConfig]
  * @param {any} [data]
+ * @param {import('../../../../shared/index.js').StorageOptions} [options]
  */
-const handleLoadAppInstallation = (serverRuntimeConfig, data) => {
-    const _handleGraph = (0, graph_js_1.handleGraph)(serverRuntimeConfig, data);
+const handleLoadAppInstallation = (serverRuntimeConfig, data, options) => {
+    const _handleGraph = (0, graph_js_1.handleGraph)(serverRuntimeConfig, data, options);
     const { returnResponse = true } = data !== null && data !== void 0 ? data : {};
     /**
      * @param {any} req

package/dist/lib/handlers/api/verifiable/graph.d.ts

@@ -1 +1 @@
-export function handleGraph(serverRuntimeConfig?: any, data?: any): (req: any, res: any, params: any) => Promise<any>;
+export function handleGraph(serverRuntimeConfig?: any, data?: any, options?: import("../../../../shared/index.js").StorageOptions): (req: any, res: any, params: any) => Promise<any>;

package/dist/lib/handlers/api/verifiable/graph.js

@@ -19,8 +19,9 @@ const index_js_2 = require("../../../../shared/index.js");
 /**
  * @param {any} [serverRuntimeConfig]
  * @param {any} [data]
+ * @param {import('../../../../shared/index.js').StorageOptions} [options]
  */
-const handleGraph = (serverRuntimeConfig, data) => {
+const handleGraph = (serverRuntimeConfig, data, options) => {
     const _getVerificationHelpers = (0, verifyd_1.getVerificationHelpers)(serverRuntimeConfig);
     const { returnResponse = true } = data !== null && data !== void 0 ? data : {};
     /**
@@ -65,7 +66,7 @@ const handleGraph = (serverRuntimeConfig, data) => {
         let headers;
         let message = 'Error handling query call';
         try {
-            const helpers = await (0, index_js_1.getShopifyHelpers)(serverRuntimeConfig, { shop });
+            const helpers = await (0, index_js_1.getShopifyHelpers)(serverRuntimeConfig, { shop }, options);
             if (!helpers.shopify) {
                 throw new Error('Shopify API is not initialized');
             }

package/dist/lib/handlers/api/verifiable/proxy.d.ts

@@ -1 +1 @@
-export function handleProxy(serverRuntimeConfig?: any, data?: any): (req: any, res: any, params: any) => Promise<any>;
+export function handleProxy(serverRuntimeConfig?: any, data?: any, options?: import("../../../../shared/index.js").StorageOptions): (req: any, res: any, params: any) => Promise<any>;

package/dist/lib/handlers/api/verifiable/proxy.js

@@ -34,11 +34,12 @@ const verifyAppProxySignature = (signature, verifiable, hmacSecret) => {
 /**
  * @param {any} [serverRuntimeConfig]
  * @param {any} [data]
+ * @param {import('../../../../shared/index.js').StorageOptions} [options]
  */
-const handleProxy = (serverRuntimeConfig, data) => {
+const handleProxy = (serverRuntimeConfig, data, options) => {
     const { generateReplacements, returnResponse = true } = data !== null && data !== void 0 ? data : {};
     const { API_BASE_PATH, API_URLS, API_PATHS, APP_CONFIG, APP_BASE_URL, TARGET_SAFELIST, ORIGIN_SAFELIST, } = serverRuntimeConfig;
-    const _prepareHeaders = (0, index_js_1.prepareHeaders)(serverRuntimeConfig);
+    const _prepareHeaders = (0, index_js_1.prepareHeaders)(serverRuntimeConfig, options);
     const _getVerificationHelpers = (0, verifyd_1.getVerificationHelpers)(serverRuntimeConfig);
     const _getVerifiedSessionData = (0, index_js_1.getVerifiedSessionData)(serverRuntimeConfig);
     /**

package/dist/lib/handlers/api/webhook.d.ts

@@ -1 +1 @@
-export function handleWebhookEvent(serverRuntimeConfig?: any, data?: any): (req: any, res: any, data: any) => Promise<any>;
+export function handleWebhookEvent(serverRuntimeConfig?: any, data?: any, options?: import("../../../shared/index.js").StorageOptions): (req: any, res: any, data: any) => Promise<any>;

package/dist/lib/handlers/api/webhook.js

@@ -19,8 +19,9 @@ const index_js_2 = require("../../../shared/index.js");
 /**
  * @param {any} [serverRuntimeConfig]
  * @param {any} [data]
+ * @param {import('../../../shared/index.js').StorageOptions} [options]
  */
-const handleWebhookEvent = (serverRuntimeConfig, data) => {
+const handleWebhookEvent = (serverRuntimeConfig, data, options) => {
     const { ORIGIN_SAFELIST, WEBHOOK_TOPIC_BLOCKLIST } = serverRuntimeConfig;
     const _a = data !== null && data !== void 0 ? data : {}, { returnResponse = true } = _a, config = __rest(_a, ["returnResponse"]);
     /**
@@ -48,7 +49,7 @@ const handleWebhookEvent = (serverRuntimeConfig, data) => {
             if (!(0, index_js_2.matchHostname)(shop, ORIGIN_SAFELIST)) {
                 return handleResponse({ handler: 'webhook', error: 'Shop is not safelisted' });
             }
-            const { shopify } = await (0, index_js_1.getShopifyHelpers)(serverRuntimeConfig, { shop });
+            const { shopify } = await (0, index_js_1.getShopifyHelpers)(serverRuntimeConfig, { shop }, options);
             if (!shopify) {
                 throw new Error('Shopify API is not initialized');
             }

package/dist/lib/handlers/ssr/protect.d.ts

@@ -1,4 +1,4 @@
-export function protectRoute(serverRuntimeConfig?: any, _props?: any): ({ req, res, query, locale, resolvedUrl, }: any | undefined, data: any) => Promise<{
+export function protectRoute(serverRuntimeConfig?: any, _props?: any, options?: import("../../../shared/index.js").StorageOptions): ({ req, res, query, locale, resolvedUrl, }: any | undefined, data: any) => Promise<{
     redirect: {
         destination: string;
         permanent: any;