@platform-x/shp-auth-client 0.0.1

package/README.md

@@ -0,0 +1,304 @@
+# @platform-x-shp/shp-auth-client
+
+Shared library for Platform-X's Shopify microservices — `shp-auth-service`,
+`shp-cart-service`, `shp-customer-service`, `shp-order-service`, `shp-product-service`. Given a
+tenant's site name (e.g. `KIWI`), it resolves that tenant's Shopify and Keycloak configuration
+from a secret store, and provides three ready-to-use pieces built on top of that config:
+
+1. A resilient, tenant-scoped **GraphQL client** for Shopify's Admin or Storefront API.
+2. An Express **middleware that verifies a Keycloak-issued bearer token**, so every consumer
+   verifies tokens the same way instead of each running its own `jwks-rsa` setup.
+3. A small set of **resilience helpers** (retry, timeout, circuit breaker) and **error classes**
+   shared across services.
+
+---
+
+## Install
+
+```bash
+npm install @platform-x-shp/shp-auth-client
+```
+
+Peer dependency: `express` `^4.18.0`.
+
+## Quick start
+
+```ts
+import { getTenantConfig, getGraphQLClient, gql } from '@platform-x-shp/shp-auth-client';
+
+// Tenant config (Shopify + Keycloak settings for one site)
+const config = await getTenantConfig('KIWI');
+console.log(config.shopify.storeDomain); // e.g. "knma-vofh9g70.myshopify.com"
+
+// A ready-to-use GraphQL client, pre-configured with the tenant's endpoint + auth header
+const admin = await getGraphQLClient('KIWI', 'admin');
+const data = await admin.request(gql`query { shop { name } }`);
+```
+
+---
+
+## Tenant config
+
+### How it's resolved
+
+Every secret is looked up under an id built as:
+
+```
+${SITENAME}_${PROVIDER}_${KEY}   (uppercased)
+```
+
+e.g. `buildSecretId('KIWI', 'SHOPIFY', 'STORE_DOMAIN')` → `KIWI_SHOPIFY_STORE_DOMAIN`.
+
+```ts
+getTenantConfig(siteName: string): Promise<TenantConfig>
+clearTenantCache(siteName?: string): void
+setConfigProvider(provider: ConfigProvider): void   // mainly for tests — see Testing below
+```
+
+`getTenantConfig(siteName)` fetches all 18 keys for that tenant — 9 Shopify + 9 Keycloak — in
+parallel, and caches the result for **5 minutes per site name** (`clearTenantCache()` to bust it
+early, e.g. after rotating a secret).
+
+**Shopify keys:** `ADMIN_API_ACCESS_TOKEN`, `IS_ENABLED`, `PLAN_NAME`, `CLIENT_ID`,
+`CLIENT_SECRET`, `STORE_DOMAIN`, `STOREFRONT_API_VERSION`, `STOREFRONT_PRIVATE_TOKEN`,
+`WEBHOOK_HMAC_SECRET`, `CALLBACK_URL`, `POST_LOGOUT_REDIRECT_URI`.
+
+**Keycloak keys:** `BASE_URL` (well, `KEYCLOCK_HOST` — see below), `REALM`, `CLIENT_ID`,
+`CLIENT_SECRET`, `DISCOVERY_URL`, `JWKS_URI`, `ISSUER`.
+
+`CALLBACK_URL`/`POST_LOGOUT_REDIRECT_URI` live under the `SHOPIFY` provider segment
+(`KIWI_SHOPIFY_CALLBACK_URL`, not `KIWI_KEYCLOAK_CALLBACK_URL`) even though they end up on
+`TenantConfig.keycloak` — they're Shopify's external-IdP redirect URLs for this store, not
+Keycloak realm data, so nothing about the realm can derive them.
+
+Fetches are always **per-key**, never a bulk "list everything in the project" call — a GCP
+project may hold hundreds of unrelated secrets, and this package only ever needs these 18 per
+tenant.
+
+### Where secrets actually come from: `SECRET_MODE`
+
+Each of those 18 lookups goes through [`hep-secret-access`](https://www.npmjs.com/package/hep-secret-access)'s
+`secretManager()`, which picks a backing provider based on the `SECRET_MODE` env var (the same
+convention `hep-delivery-service` uses):
+
+| `SECRET_MODE` | Source | Notes |
+|---|---|---|
+| `env` | `process.env[secretId]` | For local dev — no GCP dependency. |
+| `gsm` | GCP Secret Manager, `projects/{GOOGLE_PROJECT_ID}/secrets/{secretId}/versions/latest` | Needs `GOOGLE_PROJECT_ID` and valid GCP credentials (ADC or a service account). |
+| `csi` | A file per secret under `BASEPATH` (default `/var/secrets`), named after the secret id | For a Kubernetes CSI Secret Store volume mount. |
+
+If `SECRET_MODE` isn't set at all, `createConfigProvider('auto')` (used internally by
+`getTenantConfig`) falls back based on `NODE_ENV`:
+
+- `NODE_ENV=production` → `gsm` (throws if `GOOGLE_PROJECT_ID` is missing)
+- anything else → `env`
+
+Force a specific mode for one call without touching the ambient env:
+
+```ts
+import { createConfigProvider, setConfigProvider } from '@platform-x-shp/shp-auth-client';
+
+setConfigProvider(createConfigProvider('secret-manager')); // forces gsm just for this provider
+```
+
+> **Note:** unlike `hep-secret-access`'s own `EnvProvider` (which silently returns `''` for a
+> missing key), this package always throws `SecretNotFoundError` on a missing/empty secret,
+> regardless of mode — a misconfigured tenant should fail loudly, not propagate blank strings.
+
+**`GOOGLE_PROJECT_ID` vs `GCP_PROJECT_ID`:** GSM mode reads **`GOOGLE_PROJECT_ID`** — that's what
+`hep-secret-access`'s `GoogleSecretManagerProvider` actually uses. It is *not* the same as
+`GCP_PROJECT_ID`, which this package doesn't read at all. If `GOOGLE_PROJECT_ID` is missing while
+`SECRET_MODE=gsm` is explicitly set, nothing here will catch it — GSM lookups will silently
+target `hep-secret-access`'s own fallback project (`x-site-qa`) instead of yours, and fail with a
+confusing "not found or no permission" error.
+
+### Environment variables
+
+| Variable | Required when | Purpose |
+|---|---|---|
+| `SECRET_MODE` | optional | `env` \| `gsm` \| `csi` — overrides the `NODE_ENV`-based auto-selection. |
+| `NODE_ENV` | used by `auto` mode | `production` → defaults to `gsm`; anything else → `env`. |
+| `GOOGLE_PROJECT_ID` | `gsm` mode | GCP project id secrets are looked up in. |
+| `BASEPATH` | `csi` mode | Directory secret files are mounted under (default `/var/secrets`). |
+| `KIWI_SHOPIFY_*`, `KIWI_KEYCLOAK_*` | `env` mode | The 18 per-tenant values themselves (see table above), read directly from `process.env`. |
+
+(Swap `KIWI` for whatever site name you call `getTenantConfig`/`getGraphQLClient` with — the
+prefix is derived from that argument, not hardcoded.)
+
+---
+
+## GraphQL client
+
+```ts
+getGraphQLClient(siteName: string, type?: 'admin' | 'storefront'): Promise<GraphQLClient>
+clearGraphQLClientCache(siteName?: string): void
+```
+
+Returns a cached [`graphql-request`](https://github.com/jasonkuhrt/graphql-request) client,
+pre-configured per `type`:
+
+| `type` | Endpoint | Auth header |
+|---|---|---|
+| `admin` (default) | `https://{storeDomain}/admin/api/{storefrontApiVersion}/graphql.json` | `X-Shopify-Access-Token: {adminApiAccessToken}` |
+| `storefront` | `https://{storeDomain}/api/{storefrontApiVersion}/graphql.json` | `Shopify-Storefront-Private-Token: {storefrontPrivateToken}` |
+
+`storefrontPrivateToken` is a **private** (server-side) Storefront token — it must go through the
+`Shopify-Storefront-Private-Token` header, not the public-token header
+(`X-Shopify-Storefront-Access-Token`), which Shopify rejects it with a 401.
+
+Call `clearGraphQLClientCache(siteName?)` after rotating a token so the next call rebuilds the
+client with fresh config instead of reusing the cached one.
+
+This package also extends Node's default TLS trust store with the OS certificate store at import
+time (see `tls-trust.ts`), so `getGraphQLClient` calls succeed behind a TLS-intercepting corporate
+proxy without every consuming service needing its own `--use-system-ca` flag or CA bundle file.
+
+## Resilience helpers
+
+Building blocks for wrapping outbound calls — used internally by services that call
+`getGraphQLClient`, also exported for direct use:
+
+```ts
+withRetry(fn, retries = 3, baseMs = 200, shouldRetry?): Promise<T>   // exponential backoff
+withTimeout(fn, ms = 5000): Promise<T>                               // throws TimeoutError
+new CircuitBreaker(failureThreshold = 5, resetAfterMs = 30_000)       // .call(fn), .isOpen(), .reset()
+```
+
+Typical usage in a consuming service:
+
+```ts
+const breaker = new CircuitBreaker();
+
+async function adminGraphql<T>(query: string, variables?: Record<string, unknown>): Promise<T> {
+  return breaker.call(() =>
+    withTimeout(() =>
+      withRetry(async () => {
+        const client = await getGraphQLClient('KIWI', 'admin');
+        return client.request<T>(query, variables);
+      }, 3, 300, (err) => err instanceof ClientError && (err.response?.status === 429 || (err.response?.status ?? 0) >= 500)),
+      15000
+    )
+  );
+}
+```
+
+---
+
+## Keycloak token verification
+
+```ts
+extractBearer(authorization?: string): string
+verifyKeycloakToken(token: string, config: KeycloakVerifyConfig): Promise<KeycloakTokenPayload>
+keycloakConfigForTenant(siteName: string, audience?: string): Promise<KeycloakVerifyConfig>
+requireKeycloakAuth(config: KeycloakVerifyConfig | ((req) => KeycloakVerifyConfig | Promise<KeycloakVerifyConfig>))
+```
+
+- `extractBearer` strips the `Bearer ` prefix from an `Authorization` header, throwing
+  `UnauthorizedError` if it's missing or malformed.
+- `verifyKeycloakToken` checks a token's RS256 signature (via `config.jwksUri`), issuer, and — if
+  given — audience. One `jwks-rsa` client is created per distinct `jwksUri` and reused across
+  calls (it has its own internal signing-key cache + rate limiter), so calling this repeatedly for
+  the same tenant doesn't refetch keys.
+- `keycloakConfigForTenant(siteName, audience?)` builds a `KeycloakVerifyConfig` from
+  `getTenantConfig(siteName).keycloak` — the issuer/JWKS come from the tenant's resolved config,
+  not a locally duplicated env var. `audience` is passed through as-is since it's a per-caller
+  restriction, not a per-tenant secret.
+- `requireKeycloakAuth` is the Express middleware most services actually use. It takes either a
+  static `KeycloakVerifyConfig` (a service with its own fixed issuer/JWKS env vars — e.g.
+  `shp-auth-service`'s admin-facing Keycloak config) or a function that resolves one per request —
+  typically `() => keycloakConfigForTenant(SITE_NAME)`. On success it sets `req.user = { sub,
+  role }` and `req.keycloakUser` (the full decoded payload) before calling `next()`.
+
+```ts
+import { requireKeycloakAuth, keycloakConfigForTenant } from '@platform-x-shp/shp-auth-client';
+
+export const requireAuth = requireKeycloakAuth(() =>
+  keycloakConfigForTenant('KIWI', process.env.KEYCLOAK_AUDIENCE || undefined),
+);
+
+router.get('/orders/:id', requireAuth, ordersController.getOrder);
+```
+
+Failures reject with `TokenExpiredError`, `TokenInvalidError`, or `UnauthorizedError` (see Errors
+below) — `requireKeycloakAuth` forwards them to `next(err)`, so a service's own
+`globalErrorHandler` (or this package's) maps them to the right HTTP status.
+
+---
+
+## Errors
+
+All thrown as plain `Error` subclasses with a distinct `.name`:
+
+| Class | Meaning |
+|---|---|
+| `TenantNotFoundError` | Tenant config not found for a site name |
+| `SecretNotFoundError` | A specific secret was missing/empty |
+| `TokenExpiredError` / `TokenInvalidError` | Keycloak token verification failures |
+| `UnauthorizedError` / `ForbiddenError` / `CrossTenantAccessError` | Access control |
+| `ShopifyApiError` / `ShopifyUserError` | Shopify API / GraphQL user errors |
+| `TimeoutError` / `CircuitOpenError` | From `withTimeout` / `CircuitBreaker` |
+
+`globalErrorHandler(err, req, res, next)` is an optional Express error-handling middleware that
+maps each of the above to an HTTP status code and returns `{ error, code }` — use it directly, or
+as a reference for a service's own error handler.
+
+## Multi-tenancy from a request (optional)
+
+```ts
+extractSiteName(req): string | null   // 'sitehost'/'sitename' header, or hostname, uppercased
+```
+
+Not currently wired into any consuming service's request pipeline (each service today resolves a
+single fixed `SITE_NAME` from its own env at startup) — provided for a future per-request,
+multi-tenant routing scenario.
+
+---
+
+## Testing
+
+`setConfigProvider(provider)` swaps the module-level `ConfigProvider` `getTenantConfig` uses (and
+clears the tenant cache) — pass a mock implementing `{ get(secretId): Promise<string> }` in tests
+instead of hitting `env`/`gsm`/`csi` for real.
+
+```bash
+npm test         # cross-env NODE_ENV=test jest --runInBand
+npm run typecheck
+npm run lint
+```
+
+## Full API surface
+
+```ts
+export { getTenantConfig, clearTenantCache, setConfigProvider };
+export { extractSiteName, buildSecretId };
+export { createConfigProvider };
+export type { ProviderMode };
+export { HepSecretProvider };
+export { TTLCache };
+export { getGraphQLClient, clearGraphQLClientCache, gql, ClientError };
+export { withRetry, withTimeout, CircuitBreaker };
+export { extractBearer, verifyKeycloakToken, keycloakConfigForTenant, requireKeycloakAuth };
+export type { KeycloakTokenPayload, KeycloakVerifyConfig };
+export {
+  TenantNotFoundError, SecretNotFoundError,
+  TokenExpiredError, TokenInvalidError, UnauthorizedError,
+  CrossTenantAccessError, ForbiddenError,
+  ShopifyApiError, ShopifyUserError,
+  TimeoutError, CircuitOpenError,
+  globalErrorHandler,
+};
+export type { TenantConfig, ShopifyConfig, KeycloakConfig, ConfigProvider };
+```
+
+## Development
+
+```bash
+npm run build   # tsc -> dist/
+npm run dev     # tsc --watch
+npm run clean   # rm -rf dist
+```
+
+Bump `version` in `package.json` and `npm publish` (registry: `registry.npmjs.org`, scope
+`@platform-x` per `.npmrc`) to ship changes to consuming services — they pin
+`@platform-x-shp/shp-auth-client` by version, so a local change here has no effect on them until
+published and their dependency is bumped + reinstalled.

package/dist/cache.d.ts

@@ -0,0 +1,10 @@
+export declare class TTLCache<T> {
+    private store;
+    private ttlMs;
+    constructor(ttlMs?: number);
+    get(key: string): T | null;
+    set(key: string, value: T): void;
+    delete(key: string): void;
+    clear(): void;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAKA,qBAAa,QAAQ,CAAC,CAAC;IACrB,OAAO,CAAC,KAAK,CAAoC;IACjD,OAAO,CAAC,KAAK,CAAS;gBAEV,KAAK,SAAgB;IAIjC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI;IAS1B,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAIhC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIzB,KAAK,IAAI,IAAI;CAGd"}

package/dist/cache.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TTLCache = void 0;
+class TTLCache {
+    constructor(ttlMs = 5 * 60 * 1000) {
+        this.store = new Map();
+        this.ttlMs = ttlMs;
+    }
+    get(key) {
+        const entry = this.store.get(key);
+        if (!entry || Date.now() > entry.expiresAt) {
+            this.store.delete(key);
+            return null;
+        }
+        return entry.value;
+    }
+    set(key, value) {
+        this.store.set(key, { value, expiresAt: Date.now() + this.ttlMs });
+    }
+    delete(key) {
+        this.store.delete(key);
+    }
+    clear() {
+        this.store.clear();
+    }
+}
+exports.TTLCache = TTLCache;
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":";;;AAKA,MAAa,QAAQ;IAInB,YAAY,KAAK,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI;QAHzB,UAAK,GAAG,IAAI,GAAG,EAAyB,CAAC;QAI/C,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;IAED,GAAG,CAAC,GAAW;QACb,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS,EAAE,CAAC;YAC3C,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACvB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,KAAK,CAAC,KAAK,CAAC;IACrB,CAAC;IAED,GAAG,CAAC,GAAW,EAAE,KAAQ;QACvB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;IACrE,CAAC;IAED,MAAM,CAAC,GAAW;QAChB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IAED,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;CACF;AA5BD,4BA4BC"}

package/dist/config-provider.d.ts

@@ -0,0 +1,17 @@
+import type { ConfigProvider } from './types';
+export type ProviderMode = 'secret-manager' | 'env' | 'csi' | 'auto';
+/**
+ * Factory to create the appropriate config provider. Secrets are actually
+ * resolved by hep-secret-access's secretManager() (env | gsm | csi, chosen via
+ * SECRET_MODE — see hep-delivery-service's secret_key.services.ts for the
+ * reference usage this mirrors).
+ *
+ * An explicit mode forces that SECRET_MODE (set just before constructing the
+ * provider, then restored) regardless of the ambient value. 'auto' (the
+ * default) defers to whatever SECRET_MODE is already set; only when it isn't
+ * set at all does this fall back to NODE_ENV-based selection (gsm in
+ * production, env otherwise) so deployments that never set SECRET_MODE keep
+ * working unchanged.
+ */
+export declare function createConfigProvider(mode?: ProviderMode): ConfigProvider;
+//# sourceMappingURL=config-provider.d.ts.map

package/dist/config-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-provider.d.ts","sourceRoot":"","sources":["../src/config-provider.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,MAAM,MAAM,YAAY,GAAG,gBAAgB,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC;AASrE;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,GAAE,YAAqB,GAAG,cAAc,CAyBhF"}

package/dist/config-provider.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createConfigProvider = createConfigProvider;
+const hep_secret_provider_1 = require("./hep-secret-provider");
+/** Our mode names -> hep-secret-access's SECRET_MODE values. */
+const TO_HEP_MODE = {
+    env: 'env',
+    'secret-manager': 'gsm',
+    csi: 'csi',
+};
+/**
+ * Factory to create the appropriate config provider. Secrets are actually
+ * resolved by hep-secret-access's secretManager() (env | gsm | csi, chosen via
+ * SECRET_MODE — see hep-delivery-service's secret_key.services.ts for the
+ * reference usage this mirrors).
+ *
+ * An explicit mode forces that SECRET_MODE (set just before constructing the
+ * provider, then restored) regardless of the ambient value. 'auto' (the
+ * default) defers to whatever SECRET_MODE is already set; only when it isn't
+ * set at all does this fall back to NODE_ENV-based selection (gsm in
+ * production, env otherwise) so deployments that never set SECRET_MODE keep
+ * working unchanged.
+ */
+function createConfigProvider(mode = 'auto') {
+    if (mode !== 'auto') {
+        const previous = process.env.SECRET_MODE;
+        process.env.SECRET_MODE = TO_HEP_MODE[mode];
+        try {
+            return new hep_secret_provider_1.HepSecretProvider();
+        }
+        finally {
+            if (previous === undefined)
+                delete process.env.SECRET_MODE;
+            else
+                process.env.SECRET_MODE = previous;
+        }
+    }
+    if (!process.env.SECRET_MODE) {
+        if (process.env.NODE_ENV === 'production') {
+            // GOOGLE_PROJECT_ID (not GCP_PROJECT_ID) is what hep-secret-access's
+            // GoogleSecretManagerProvider actually reads — checking the wrong name
+            // here would let this pass while GSM silently falls back to its own
+            // default project.
+            if (!process.env.GOOGLE_PROJECT_ID)
+                throw new Error('GOOGLE_PROJECT_ID is required in production');
+            process.env.SECRET_MODE = 'gsm';
+        }
+        else {
+            process.env.SECRET_MODE = 'env';
+        }
+    }
+    return new hep_secret_provider_1.HepSecretProvider();
+}
+//# sourceMappingURL=config-provider.js.map

package/dist/config-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-provider.js","sourceRoot":"","sources":["../src/config-provider.ts"],"names":[],"mappings":";;AAyBA,oDAyBC;AAlDD,+DAA0D;AAK1D,gEAAgE;AAChE,MAAM,WAAW,GAAqD;IACpE,GAAG,EAAE,KAAK;IACV,gBAAgB,EAAE,KAAK;IACvB,GAAG,EAAE,KAAK;CACX,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,SAAgB,oBAAoB,CAAC,OAAqB,MAAM;IAC9D,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACpB,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC;QACzC,OAAO,CAAC,GAAG,CAAC,WAAW,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;QAC5C,IAAI,CAAC;YACH,OAAO,IAAI,uCAAiB,EAAE,CAAC;QACjC,CAAC;gBAAS,CAAC;YACT,IAAI,QAAQ,KAAK,SAAS;gBAAE,OAAO,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC;;gBACtD,OAAO,CAAC,GAAG,CAAC,WAAW,GAAG,QAAQ,CAAC;QAC1C,CAAC;IACH,CAAC;IAED,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC;QAC7B,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY,EAAE,CAAC;YAC1C,qEAAqE;YACrE,uEAAuE;YACvE,oEAAoE;YACpE,mBAAmB;YACnB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB;gBAAE,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;YACnG,OAAO,CAAC,GAAG,CAAC,WAAW,GAAG,KAAK,CAAC;QAClC,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,GAAG,CAAC,WAAW,GAAG,KAAK,CAAC;QAClC,CAAC;IACH,CAAC;IACD,OAAO,IAAI,uCAAiB,EAAE,CAAC;AACjC,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,53 @@
+export declare class TenantNotFoundError extends Error {
+    constructor(siteName: string);
+}
+export declare class SecretNotFoundError extends Error {
+    constructor(secretId: string);
+}
+export declare class TokenExpiredError extends Error {
+    constructor();
+}
+export declare class TokenInvalidError extends Error {
+    constructor(detail?: string);
+}
+export declare class UnauthorizedError extends Error {
+    constructor(message?: string);
+}
+export declare class CrossTenantAccessError extends Error {
+    constructor();
+}
+export declare class ForbiddenError extends Error {
+    constructor(message?: string);
+}
+export declare class ShopifyApiError extends Error {
+    readonly statusCode: number;
+    readonly body: unknown;
+    constructor(statusCode: number, body: unknown);
+}
+export declare class ShopifyUserError extends Error {
+    readonly errors: Array<{
+        field: string[];
+        message: string;
+    }>;
+    constructor(errors: Array<{
+        field: string[];
+        message: string;
+    }>);
+}
+export declare class TimeoutError extends Error {
+    constructor(message: string);
+}
+export declare class CircuitOpenError extends Error {
+    constructor(message: string);
+}
+export interface ErrorHandlerRequest {
+    headers: Record<string, string | string[] | undefined>;
+    tenantId?: string;
+}
+export interface ErrorHandlerResponse {
+    status(code: number): {
+        json(body: unknown): unknown;
+    };
+}
+export declare function globalErrorHandler(err: Error, req: ErrorHandlerRequest, res: ErrorHandlerResponse, _next: unknown): void;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAEA,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,QAAQ,EAAE,MAAM;CAI7B;AAED,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,QAAQ,EAAE,MAAM;CAI7B;AAID,qBAAa,iBAAkB,SAAQ,KAAK;;CAK3C;AAED,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,MAAM,CAAC,EAAE,MAAM;CAI5B;AAED,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,SAAiB;CAIrC;AAID,qBAAa,sBAAuB,SAAQ,KAAK;;CAKhD;AAED,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,SAAc;CAIlC;AAID,qBAAa,eAAgB,SAAQ,KAAK;aAEtB,UAAU,EAAE,MAAM;aAClB,IAAI,EAAE,OAAO;gBADb,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,OAAO;CAKhC;AAED,qBAAa,gBAAiB,SAAQ,KAAK;aACb,MAAM,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;gBAAnD,MAAM,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAIhF;AAID,qBAAa,YAAa,SAAQ,KAAK;gBACzB,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,OAAO,EAAE,MAAM;CAI5B;AAiBD,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAA;KAAE,CAAC;CACxD;AAED,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,KAAK,EACV,GAAG,EAAE,mBAAmB,EACxB,GAAG,EAAE,oBAAoB,EAIzB,KAAK,EAAE,OAAO,GACb,IAAI,CAaN"}

package/dist/errors.js

@@ -0,0 +1,117 @@
+"use strict";
+// ─── Tenant / Config errors ─────────────────────────────────────────────────
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CircuitOpenError = exports.TimeoutError = exports.ShopifyUserError = exports.ShopifyApiError = exports.ForbiddenError = exports.CrossTenantAccessError = exports.UnauthorizedError = exports.TokenInvalidError = exports.TokenExpiredError = exports.SecretNotFoundError = exports.TenantNotFoundError = void 0;
+exports.globalErrorHandler = globalErrorHandler;
+class TenantNotFoundError extends Error {
+    constructor(siteName) {
+        super(`Tenant config not found: ${siteName}`);
+        this.name = 'TenantNotFoundError';
+    }
+}
+exports.TenantNotFoundError = TenantNotFoundError;
+class SecretNotFoundError extends Error {
+    constructor(secretId) {
+        super(`Secret not found or empty: ${secretId}`);
+        this.name = 'SecretNotFoundError';
+    }
+}
+exports.SecretNotFoundError = SecretNotFoundError;
+// ─── Auth / Token errors ───────────────────────────────────────────────────
+class TokenExpiredError extends Error {
+    constructor() {
+        super('Access token has expired');
+        this.name = 'TokenExpiredError';
+    }
+}
+exports.TokenExpiredError = TokenExpiredError;
+class TokenInvalidError extends Error {
+    constructor(detail) {
+        super(detail ? `Invalid token: ${detail}` : 'Invalid token');
+        this.name = 'TokenInvalidError';
+    }
+}
+exports.TokenInvalidError = TokenInvalidError;
+class UnauthorizedError extends Error {
+    constructor(message = 'Unauthorized') {
+        super(message);
+        this.name = 'UnauthorizedError';
+    }
+}
+exports.UnauthorizedError = UnauthorizedError;
+// ─── Access control errors ─────────────────────────────────────────────────
+class CrossTenantAccessError extends Error {
+    constructor() {
+        super('Cross-tenant access denied');
+        this.name = 'CrossTenantAccessError';
+    }
+}
+exports.CrossTenantAccessError = CrossTenantAccessError;
+class ForbiddenError extends Error {
+    constructor(message = 'Forbidden') {
+        super(message);
+        this.name = 'ForbiddenError';
+    }
+}
+exports.ForbiddenError = ForbiddenError;
+// ─── Shopify API errors ────────────────────────────────────────────────────
+class ShopifyApiError extends Error {
+    constructor(statusCode, body) {
+        super(`Shopify API error ${statusCode}`);
+        this.statusCode = statusCode;
+        this.body = body;
+        this.name = 'ShopifyApiError';
+    }
+}
+exports.ShopifyApiError = ShopifyApiError;
+class ShopifyUserError extends Error {
+    constructor(errors) {
+        super(errors.map((e) => e.message).join(', '));
+        this.errors = errors;
+        this.name = 'ShopifyUserError';
+    }
+}
+exports.ShopifyUserError = ShopifyUserError;
+// ─── Resilience errors ─────────────────────────────────────────────────────
+class TimeoutError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'TimeoutError';
+    }
+}
+exports.TimeoutError = TimeoutError;
+class CircuitOpenError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CircuitOpenError';
+    }
+}
+exports.CircuitOpenError = CircuitOpenError;
+// ─── Global Express error handler ────────────────────────────────────────────
+const HTTP_STATUS_MAP = {
+    TenantNotFoundError: 404,
+    SecretNotFoundError: 404,
+    TokenExpiredError: 401,
+    TokenInvalidError: 401,
+    UnauthorizedError: 401,
+    CrossTenantAccessError: 403,
+    ForbiddenError: 403,
+    ShopifyUserError: 422,
+    TimeoutError: 504,
+    CircuitOpenError: 503,
+};
+function globalErrorHandler(err, req, res, 
+// Express only recognizes error-handling middleware by its 4-arg arity —
+// _next must stay in the signature even though it's never called.
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+_next) {
+    const sitehostHeader = req.headers['sitehost'];
+    const siteName = req.tenantId ?? (Array.isArray(sitehostHeader) ? sitehostHeader[0] : sitehostHeader) ?? 'unknown';
+    console.error(`[${siteName}] ${err.name}: ${err.message}`);
+    const status = HTTP_STATUS_MAP[err.name] ?? 500;
+    const message = status === 500
+        ? 'Internal server error'
+        : err.message;
+    res.status(status).json({ error: message, code: err.name });
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/extract-site-name.d.ts

@@ -0,0 +1,15 @@
+import type { Request } from 'express';
+/**
+ * Extracts and normalizes site name from request headers.
+ * Priority: sitehost > sitename > hostname
+ * Header 'sitehost: kiwi.hcl-x.com' => 'KIWI'
+ * Used to build Secret Manager keys: KIWI_SHOPIFY_STORE_DOMAIN
+ */
+export declare function extractSiteName(req: Request): string | null;
+/**
+ * Builds a Secret Manager secret ID using the convention:
+ * ${SITENAME}_${PROVIDER}_${KEY}
+ * e.g. buildSecretId('KIWI', 'SHOPIFY', 'STORE_DOMAIN') => 'KIWI_SHOPIFY_STORE_DOMAIN'
+ */
+export declare function buildSecretId(siteName: string, provider: string, key: string): string;
+//# sourceMappingURL=extract-site-name.d.ts.map

package/dist/extract-site-name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-site-name.d.ts","sourceRoot":"","sources":["../src/extract-site-name.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAU3D;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAErF"}

package/dist/extract-site-name.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractSiteName = extractSiteName;
+exports.buildSecretId = buildSecretId;
+/**
+ * Extracts and normalizes site name from request headers.
+ * Priority: sitehost > sitename > hostname
+ * Header 'sitehost: kiwi.hcl-x.com' => 'KIWI'
+ * Used to build Secret Manager keys: KIWI_SHOPIFY_STORE_DOMAIN
+ */
+function extractSiteName(req) {
+    const siteHeader = req.headers['sitehost'] ||
+        req.headers['sitename'] ||
+        req.hostname;
+    if (!siteHeader)
+        return null;
+    // 'kiwi.hcl-x.com' => 'KIWI'
+    return siteHeader.split('.')[0].toUpperCase();
+}
+/**
+ * Builds a Secret Manager secret ID using the convention:
+ * ${SITENAME}_${PROVIDER}_${KEY}
+ * e.g. buildSecretId('KIWI', 'SHOPIFY', 'STORE_DOMAIN') => 'KIWI_SHOPIFY_STORE_DOMAIN'
+ */
+function buildSecretId(siteName, provider, key) {
+    return `${siteName}_${provider}_${key}`.toUpperCase();
+}
+//# sourceMappingURL=extract-site-name.js.map