@cronvello/shop-sdk 0.1.0 → 0.2.0

package/dist/{error-C-cJ6OgX.d.cts → error-C5_qRXMp.d.cts}

@@ -53,6 +53,59 @@ interface ShopClient {
 /** Stable production endpoint used when no override or resolver is supplied. */
 declare const SHOP_API_URL = "https://node-shop-production-86b7.up.railway.app";
 
+/**
+ * `match`  — the deployment reports exactly the contract compiled into this SDK.
+ * `drift`  — it reports a different one. The types here are a lie about that
+ *            deployment; requests can fail on shapes the compiler called fine.
+ * `unknown` — nobody could be asked (offline, 503, or a node-shop old enough not
+ *            to serve the endpoint yet). Explicitly NOT the same as `match`.
+ */
+type ShopContractStatus = "match" | "drift" | "unknown";
+type ShopDiagnosis = {
+    /**
+     * True only when the contract was actually VERIFIED to match. `unknown` is
+     * false on purpose: a green light that means "could not check" is exactly the
+     * failure this whole mechanism exists to remove.
+     */
+    ok: boolean;
+    baseUrl: string | null;
+    sdkVersion: string;
+    reachable: boolean;
+    contract: {
+        status: ShopContractStatus;
+        sdk: string;
+        live: string | null;
+        files: number | null;
+    };
+    /** Plain sentences, safe to log or show. Empty when `ok` is true. */
+    problems: string[];
+    checkedAt: string;
+};
+type ShopDiagnoseOptions = {
+    /** Preferred: reuses the client's own base URL, including a dynamic resolver. */
+    client?: Pick<ShopClient, "baseUrl">;
+    baseUrl?: BaseUrlProvider;
+    fetch?: typeof globalThis.fetch;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+};
+/**
+ * Ask a running node-shop which contract it speaks and compare it to the one
+ * this SDK was built against.
+ *
+ * Read-only, unauthenticated, and cheap — meant to sit behind a consumer's own
+ * health endpoint so the answer is a fact anyone can pull, rather than something
+ * a person has to remember to check after a release.
+ *
+ * Never throws for an operational reason: an unreachable shop is a RESULT
+ * (`reachable: false`), not an exception, so a health route cannot accidentally
+ * turn a diagnosis into a 500. Only a genuinely unusable base URL throws
+ * (`ShopConfigurationError`), because that is a wiring mistake, not a state.
+ */
+declare function diagnoseShop(options?: ShopDiagnoseOptions): Promise<ShopDiagnosis>;
+
+declare const CONTRACT_SHA256 = "335eed391a2786a4f7f010b056d2a6a5b49d9e1244960a15516a5d77b93693b5";
+
 type ShopErrorDetails = {
     status: number;
     method: string;
@@ -75,4 +128,4 @@ declare class ShopConfigurationError extends Error {
     constructor(message: string);
 }
 
-export { type BaseUrlProvider as B, type HeaderProvider as H, type MaybePromise as M, type ShopClientOptions as S, type ShopClient as a, SHOP_API_URL as b, ShopApiError as c, type ShopAuthType as d, ShopConfigurationError as e, type ShopRequestContext as f, type ShopRequestOptions as g, type ShopRoute as h, type ShopRouteAuth as i, type ShopRouteBody as j, type ShopRouteInput as k, type ShopRouteKey as l, type ShopRouteMethod as m, type ShopRouteParams as n, type ShopRouteQuery as o, type ShopRouteResponse as p, type ShopRouteResponseData as q };
+export { type BaseUrlProvider as B, CONTRACT_SHA256 as C, type HeaderProvider as H, type MaybePromise as M, type ShopClientOptions as S, type ShopClient as a, SHOP_API_URL as b, ShopApiError as c, type ShopAuthType as d, ShopConfigurationError as e, type ShopContractStatus as f, type ShopDiagnoseOptions as g, type ShopDiagnosis as h, type ShopRequestContext as i, type ShopRequestOptions as j, type ShopRoute as k, type ShopRouteAuth as l, type ShopRouteBody as m, type ShopRouteInput as n, type ShopRouteKey as o, type ShopRouteMethod as p, type ShopRouteParams as q, type ShopRouteQuery as r, type ShopRouteResponse as s, type ShopRouteResponseData as t, diagnoseShop as u };

package/dist/{error-BFzxyQkW.d.ts → error-Do0kyiZ6.d.ts}

@@ -53,6 +53,59 @@ interface ShopClient {
 /** Stable production endpoint used when no override or resolver is supplied. */
 declare const SHOP_API_URL = "https://node-shop-production-86b7.up.railway.app";
 
+/**
+ * `match`  — the deployment reports exactly the contract compiled into this SDK.
+ * `drift`  — it reports a different one. The types here are a lie about that
+ *            deployment; requests can fail on shapes the compiler called fine.
+ * `unknown` — nobody could be asked (offline, 503, or a node-shop old enough not
+ *            to serve the endpoint yet). Explicitly NOT the same as `match`.
+ */
+type ShopContractStatus = "match" | "drift" | "unknown";
+type ShopDiagnosis = {
+    /**
+     * True only when the contract was actually VERIFIED to match. `unknown` is
+     * false on purpose: a green light that means "could not check" is exactly the
+     * failure this whole mechanism exists to remove.
+     */
+    ok: boolean;
+    baseUrl: string | null;
+    sdkVersion: string;
+    reachable: boolean;
+    contract: {
+        status: ShopContractStatus;
+        sdk: string;
+        live: string | null;
+        files: number | null;
+    };
+    /** Plain sentences, safe to log or show. Empty when `ok` is true. */
+    problems: string[];
+    checkedAt: string;
+};
+type ShopDiagnoseOptions = {
+    /** Preferred: reuses the client's own base URL, including a dynamic resolver. */
+    client?: Pick<ShopClient, "baseUrl">;
+    baseUrl?: BaseUrlProvider;
+    fetch?: typeof globalThis.fetch;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+};
+/**
+ * Ask a running node-shop which contract it speaks and compare it to the one
+ * this SDK was built against.
+ *
+ * Read-only, unauthenticated, and cheap — meant to sit behind a consumer's own
+ * health endpoint so the answer is a fact anyone can pull, rather than something
+ * a person has to remember to check after a release.
+ *
+ * Never throws for an operational reason: an unreachable shop is a RESULT
+ * (`reachable: false`), not an exception, so a health route cannot accidentally
+ * turn a diagnosis into a 500. Only a genuinely unusable base URL throws
+ * (`ShopConfigurationError`), because that is a wiring mistake, not a state.
+ */
+declare function diagnoseShop(options?: ShopDiagnoseOptions): Promise<ShopDiagnosis>;
+
+declare const CONTRACT_SHA256 = "335eed391a2786a4f7f010b056d2a6a5b49d9e1244960a15516a5d77b93693b5";
+
 type ShopErrorDetails = {
     status: number;
     method: string;
@@ -75,4 +128,4 @@ declare class ShopConfigurationError extends Error {
     constructor(message: string);
 }
 
-export { type BaseUrlProvider as B, type HeaderProvider as H, type MaybePromise as M, type ShopClientOptions as S, type ShopClient as a, SHOP_API_URL as b, ShopApiError as c, type ShopAuthType as d, ShopConfigurationError as e, type ShopRequestContext as f, type ShopRequestOptions as g, type ShopRoute as h, type ShopRouteAuth as i, type ShopRouteBody as j, type ShopRouteInput as k, type ShopRouteKey as l, type ShopRouteMethod as m, type ShopRouteParams as n, type ShopRouteQuery as o, type ShopRouteResponse as p, type ShopRouteResponseData as q };
+export { type BaseUrlProvider as B, CONTRACT_SHA256 as C, type HeaderProvider as H, type MaybePromise as M, type ShopClientOptions as S, type ShopClient as a, SHOP_API_URL as b, ShopApiError as c, type ShopAuthType as d, ShopConfigurationError as e, type ShopContractStatus as f, type ShopDiagnoseOptions as g, type ShopDiagnosis as h, type ShopRequestContext as i, type ShopRequestOptions as j, type ShopRoute as k, type ShopRouteAuth as l, type ShopRouteBody as m, type ShopRouteInput as n, type ShopRouteKey as o, type ShopRouteMethod as p, type ShopRouteParams as q, type ShopRouteQuery as r, type ShopRouteResponse as s, type ShopRouteResponseData as t, diagnoseShop as u };

package/dist/index.cjs

@@ -5621,7 +5621,7 @@ function createShopClient(options = {}) {
   const defaultTimeoutMs = options.timeoutMs ?? 3e4;
   const defaultRetries = options.retries ?? 2;
   const retryDelayMs = options.retryDelayMs ?? 250;
-  async function resolveBaseUrl() {
+  async function resolveBaseUrl2() {
     const value = typeof baseUrl === "function" ? await baseUrl() : baseUrl;
     return normalizeBaseUrl(value);
   }
@@ -5643,7 +5643,7 @@ function createShopClient(options = {}) {
     const body = hasBody ? JSON.stringify(values.body) : void 0;
     const retries = Math.max(0, requestOptions.retries ?? defaultRetries);
     const canRetry = SAFE_METHODS.has(route.method) || requestOptions.retryUnsafe === true;
-    const resolvedBaseUrl = await resolveBaseUrl();
+    const resolvedBaseUrl = await resolveBaseUrl2();
     for (let attempt = 0; ; attempt += 1) {
       const timeout = createRequestSignal(requestOptions.signal, requestOptions.timeoutMs ?? defaultTimeoutMs);
       try {
@@ -5720,6 +5720,103 @@ function createShopClient(options = {}) {
   return { baseUrl, request, requestText, requestRaw };
 }
 
+// src/contract-hash.ts
+var CONTRACT_SHA256 = "335eed391a2786a4f7f010b056d2a6a5b49d9e1244960a15516a5d77b93693b5";
+
+// src/client/diagnose.ts
+var SDK_VERSION = "0.2.0" ;
+async function resolveBaseUrl(options) {
+  const provider = options.client?.baseUrl ?? options.baseUrl ?? SHOP_API_URL;
+  const value = typeof provider === "function" ? await provider() : provider;
+  return normalizeBaseUrl(value);
+}
+async function diagnoseShop(options = {}) {
+  const checkedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const baseUrl = await resolveBaseUrl(options);
+  const doFetch = options.fetch ?? globalThis.fetch;
+  const timeoutMs = options.timeoutMs ?? 5e3;
+  const base = {
+    ok: false,
+    baseUrl,
+    sdkVersion: SDK_VERSION,
+    reachable: false,
+    contract: { status: "unknown", sdk: CONTRACT_SHA256, live: null, files: null },
+    problems: [],
+    checkedAt
+  };
+  if (typeof doFetch !== "function") {
+    return { ...base, problems: ["No fetch implementation available; pass `fetch` explicitly."] };
+  }
+  const controller = new AbortController();
+  const onAbort = () => controller.abort(options.signal?.reason);
+  options.signal?.addEventListener("abort", onAbort, { once: true });
+  if (options.signal?.aborted) controller.abort(options.signal.reason);
+  const timer = setTimeout(() => controller.abort(new Error(`Contract probe timed out after ${timeoutMs}ms`)), timeoutMs);
+  let response;
+  try {
+    response = await doFetch(`${baseUrl}/health/contract`, {
+      method: "GET",
+      headers: { accept: "application/json" },
+      signal: controller.signal
+    });
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    return { ...base, problems: [`node-shop at ${baseUrl} could not be reached: ${detail}`] };
+  } finally {
+    clearTimeout(timer);
+    options.signal?.removeEventListener("abort", onAbort);
+  }
+  if (response.status === 404) {
+    return {
+      ...base,
+      reachable: true,
+      problems: [
+        `node-shop at ${baseUrl} does not serve GET /health/contract, so the contract cannot be verified. Deploy a node-shop that includes it.`
+      ]
+    };
+  }
+  if (!response.ok) {
+    return {
+      ...base,
+      reachable: true,
+      problems: [`node-shop at ${baseUrl} answered ${response.status} for GET /health/contract; contract not verified.`]
+    };
+  }
+  let body;
+  try {
+    body = await response.json();
+  } catch {
+    return { ...base, reachable: true, problems: [`node-shop at ${baseUrl} returned a non-JSON contract fingerprint.`] };
+  }
+  const live = typeof body.contractSha256 === "string" && body.contractSha256 ? body.contractSha256 : null;
+  const files = typeof body.files === "number" ? body.files : null;
+  if (!live) {
+    return {
+      ...base,
+      reachable: true,
+      contract: { ...base.contract, files },
+      problems: [`node-shop at ${baseUrl} could not compute its own contract fingerprint; contract not verified.`]
+    };
+  }
+  if (live !== CONTRACT_SHA256) {
+    return {
+      ...base,
+      reachable: true,
+      contract: { status: "drift", sdk: CONTRACT_SHA256, live, files },
+      problems: [
+        `Contract drift: node-shop at ${baseUrl} speaks ${live.slice(0, 12)}, @cronvello/shop-sdk ${SDK_VERSION} was built against ${CONTRACT_SHA256.slice(0, 12)}. Pin a newer SDK version, or deploy the node-shop the SDK was built from.`
+      ]
+    };
+  }
+  return {
+    ...base,
+    ok: true,
+    reachable: true,
+    contract: { status: "match", sdk: CONTRACT_SHA256, live, files }
+  };
+}
+
+exports.CONTRACT_SHA256 = CONTRACT_SHA256;
 exports.SHOP_API_URL = SHOP_API_URL;
 exports.ShopApiError = ShopApiError;
 exports.ShopConfigurationError = ShopConfigurationError;
@@ -5774,5 +5871,6 @@ exports.apiRoutes_users = apiRoutes_users;
 exports.apiRoutes_variant_entitlements = apiRoutes_variant_entitlements;
 exports.apiRoutes_webhooks = apiRoutes_webhooks;
 exports.createShopClient = createShopClient;
+exports.diagnoseShop = diagnoseShop;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map