@cronvello/shop-sdk 0.1.0 → 0.2.2

package/dist/{error-C-cJ6OgX.d.cts → error-1WqH-FhJ.d.cts}

@@ -1,4 +1,4 @@
-import { M6 as apiRoutes } from './index-CIpUb0vL.cjs';
+import { Mb as apiRoutes } from './index-DC6jGVkP.cjs';
 
 type ShopRouteKey = keyof typeof apiRoutes;
 type ShopRoute<K extends ShopRouteKey> = (typeof apiRoutes)[K];
@@ -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 = "05f34929e71fb2fcb3a4c04707facca22ee46f8960a4cc47ce0a3f1a6df36056";
+
 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-D3Jrcd-j.d.ts}

@@ -1,4 +1,4 @@
-import { M6 as apiRoutes } from './index-CIpUb0vL.js';
+import { Mb as apiRoutes } from './index-DC6jGVkP.js';
 
 type ShopRouteKey = keyof typeof apiRoutes;
 type ShopRoute<K extends ShopRouteKey> = (typeof apiRoutes)[K];
@@ -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 = "05f34929e71fb2fcb3a4c04707facca22ee46f8960a4cc47ce0a3f1a6df36056";
+
 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 };