@cronvello/shop-sdk 0.2.3 → 0.3.0

package/dist/index.d.cts

@@ -5,4 +5,76 @@ export { RouteGroup, apiGroups, apiMountPrefixes } from './contract.cjs';
 
 declare function createShopClient(options?: ShopClientOptions): ShopClient;
 
-export { ShopClient, ShopClientOptions, createShopClient };
+/**
+ * Was node-shop kann — als Daten, ohne Netz und ohne Vermutung.
+ *
+ * Ein Verbindungs-Verwalter (node-amp) kann Kanten nur dann selbst herstellen, pruefen und
+ * reparieren, wenn er weiss, *was die Gegenseite ueberhaupt anbietet*. Bis hierher war das
+ * bei node-shop Handwissen: irgendwo im Verwalter stand einprogrammiert, dass der Shop
+ * Schluessel ausstellen kann. Wird eine Faehigkeit dort angenommen und fehlt sie hier, ist
+ * das Ergebnis eine Zeile, die gesund aussieht, weil nie jemand gefragt hat. Genau deshalb
+ * fuehrte AMP node-shop als "meldet nichts" — mit dem ausdruecklichen Auftrag, das hier zu
+ * schliessen.
+ *
+ * Der Bericht leitet sich ausschliesslich aus dem mitgelieferten Vertrag ab: eine
+ * Faehigkeit gilt genau dann als vorhanden, wenn die zugehoerige Operation in `apiRoutes`
+ * steht. Faellt sie in node-shop weg, verschwindet sie beim naechsten Vertrags-Abgleich
+ * auch hier — niemand muss daran denken.
+ *
+ * ⚠ Der Bericht sagt, was der Vertrag hergibt, nicht was der Aufrufer darf. Ob eine
+ * laufende Gegenstelle denselben Vertrag spricht, beantwortet {@link diagnoseShop}; ob ein
+ * Credential traegt, allein der echte Aufruf. Drei getrennte Fragen.
+ */
+/**
+ * Eine Faehigkeit und die Operationen, an denen sie haengt.
+ *
+ * `operations` ist der Beleg: wer die Angabe anzweifelt, schlaegt sie im Vertrag nach,
+ * statt dem Wort zu glauben.
+ */
+type ShopCapability = {
+    supported: boolean;
+    operations: string[];
+    /** Warum nicht — nur gesetzt, wenn `supported` falsch ist. */
+    reason?: string;
+};
+type ShopCapabilities = {
+    service: "node-shop";
+    sdkVersion: string;
+    contractSha256: string;
+    /** Wie viele Operationen der Vertrag insgesamt kennt. */
+    operationCount: number;
+    /** Welche Credential-Bahnen der Vertrag verlangt, gezaehlt nach Art. */
+    authChannels: Record<string, number>;
+    capabilities: {
+        /** Der Dienst nennt seinen eigenen Vertrags-Fingerabdruck. */
+        contractFingerprint: ShopCapability;
+        /** Ein unauthentisierter Erreichbarkeits-Endpunkt. */
+        healthCheck: ShopCapability;
+        /** Fremde Apps anlegen, aendern, loeschen und ihren Zustand abfragen. */
+        clientManagement: ShopCapability;
+        /** Den API-Schluessel einer fremden App erneuern. */
+        clientRotation: ShopCapability;
+        /** Gnadenfrist beim Wechsel: der alte Schluessel bleibt eine Weile gueltig. */
+        rotationGracePeriod: ShopCapability;
+        /** Zugang sofort entziehen, ohne die App zu loeschen. */
+        clientRevocation: ShopCapability;
+        /** Der Zustand einer angebundenen App, von aussen abfragbar. */
+        peerStatus: ShopCapability;
+        /** Berechtigungen lesen und zuweisen. */
+        entitlements: ShopCapability;
+        /** Kaufvorgaenge fuer fremde Apps (der eigentliche Grund, warum Apps am Shop haengen). */
+        commerce: ShopCapability;
+        /** Verbrauchsmeldungen fremder Apps einsammeln. */
+        usageMetering: ShopCapability;
+        /** Ein serverseitiger Probelauf, der schreibt *als ob*, aber nichts aendert. */
+        serverSideDryRun: ShopCapability;
+    };
+};
+/**
+ * Der Faehigkeitsbericht dieses Dienstes. Rein aus dem Vertrag, kein Netzzugriff, kein
+ * Credential noetig — damit ein Verwalter ihn auch dann fuehren kann, wenn die Verbindung
+ * gerade nicht steht.
+ */
+declare function shopCapabilities(): ShopCapabilities;
+
+export { type ShopCapabilities, type ShopCapability, ShopClient, ShopClientOptions, createShopClient, shopCapabilities };

package/dist/index.d.ts

@@ -5,4 +5,76 @@ export { RouteGroup, apiGroups, apiMountPrefixes } from './contract.js';
 
 declare function createShopClient(options?: ShopClientOptions): ShopClient;
 
-export { ShopClient, ShopClientOptions, createShopClient };
+/**
+ * Was node-shop kann — als Daten, ohne Netz und ohne Vermutung.
+ *
+ * Ein Verbindungs-Verwalter (node-amp) kann Kanten nur dann selbst herstellen, pruefen und
+ * reparieren, wenn er weiss, *was die Gegenseite ueberhaupt anbietet*. Bis hierher war das
+ * bei node-shop Handwissen: irgendwo im Verwalter stand einprogrammiert, dass der Shop
+ * Schluessel ausstellen kann. Wird eine Faehigkeit dort angenommen und fehlt sie hier, ist
+ * das Ergebnis eine Zeile, die gesund aussieht, weil nie jemand gefragt hat. Genau deshalb
+ * fuehrte AMP node-shop als "meldet nichts" — mit dem ausdruecklichen Auftrag, das hier zu
+ * schliessen.
+ *
+ * Der Bericht leitet sich ausschliesslich aus dem mitgelieferten Vertrag ab: eine
+ * Faehigkeit gilt genau dann als vorhanden, wenn die zugehoerige Operation in `apiRoutes`
+ * steht. Faellt sie in node-shop weg, verschwindet sie beim naechsten Vertrags-Abgleich
+ * auch hier — niemand muss daran denken.
+ *
+ * ⚠ Der Bericht sagt, was der Vertrag hergibt, nicht was der Aufrufer darf. Ob eine
+ * laufende Gegenstelle denselben Vertrag spricht, beantwortet {@link diagnoseShop}; ob ein
+ * Credential traegt, allein der echte Aufruf. Drei getrennte Fragen.
+ */
+/**
+ * Eine Faehigkeit und die Operationen, an denen sie haengt.
+ *
+ * `operations` ist der Beleg: wer die Angabe anzweifelt, schlaegt sie im Vertrag nach,
+ * statt dem Wort zu glauben.
+ */
+type ShopCapability = {
+    supported: boolean;
+    operations: string[];
+    /** Warum nicht — nur gesetzt, wenn `supported` falsch ist. */
+    reason?: string;
+};
+type ShopCapabilities = {
+    service: "node-shop";
+    sdkVersion: string;
+    contractSha256: string;
+    /** Wie viele Operationen der Vertrag insgesamt kennt. */
+    operationCount: number;
+    /** Welche Credential-Bahnen der Vertrag verlangt, gezaehlt nach Art. */
+    authChannels: Record<string, number>;
+    capabilities: {
+        /** Der Dienst nennt seinen eigenen Vertrags-Fingerabdruck. */
+        contractFingerprint: ShopCapability;
+        /** Ein unauthentisierter Erreichbarkeits-Endpunkt. */
+        healthCheck: ShopCapability;
+        /** Fremde Apps anlegen, aendern, loeschen und ihren Zustand abfragen. */
+        clientManagement: ShopCapability;
+        /** Den API-Schluessel einer fremden App erneuern. */
+        clientRotation: ShopCapability;
+        /** Gnadenfrist beim Wechsel: der alte Schluessel bleibt eine Weile gueltig. */
+        rotationGracePeriod: ShopCapability;
+        /** Zugang sofort entziehen, ohne die App zu loeschen. */
+        clientRevocation: ShopCapability;
+        /** Der Zustand einer angebundenen App, von aussen abfragbar. */
+        peerStatus: ShopCapability;
+        /** Berechtigungen lesen und zuweisen. */
+        entitlements: ShopCapability;
+        /** Kaufvorgaenge fuer fremde Apps (der eigentliche Grund, warum Apps am Shop haengen). */
+        commerce: ShopCapability;
+        /** Verbrauchsmeldungen fremder Apps einsammeln. */
+        usageMetering: ShopCapability;
+        /** Ein serverseitiger Probelauf, der schreibt *als ob*, aber nichts aendert. */
+        serverSideDryRun: ShopCapability;
+    };
+};
+/**
+ * Der Faehigkeitsbericht dieses Dienstes. Rein aus dem Vertrag, kein Netzzugriff, kein
+ * Credential noetig — damit ein Verwalter ihn auch dann fuehren kann, wenn die Verbindung
+ * gerade nicht steht.
+ */
+declare function shopCapabilities(): ShopCapabilities;
+
+export { type ShopCapabilities, type ShopCapability, ShopClient, ShopClientOptions, createShopClient, shopCapabilities };

package/dist/index.js

@@ -5735,7 +5735,7 @@ function createShopClient(options = {}) {
 var CONTRACT_SHA256 = "32f132210ee188c28a330c9db5c6db6eaf5b7c3a65ecc041e029aca6e1335a60";
 
 // src/client/diagnose.ts
-var SDK_VERSION = "0.2.3" ;
+var SDK_VERSION = "0.3.0" ;
 async function resolveBaseUrl(options) {
   const provider = options.client?.baseUrl ?? options.baseUrl ?? SHOP_API_URL;
   const value = typeof provider === "function" ? await provider() : provider;
@@ -5827,6 +5827,104 @@ async function diagnoseShop(options = {}) {
   };
 }
 
-export { CONTRACT_SHA256, SHOP_API_URL, ShopApiError, ShopConfigurationError, apiGroups, apiMountPrefixes, apiRoutes, apiRoutes_api, apiRoutes_app_info, apiRoutes_assigned_entitlements, apiRoutes_attribute_assignments, apiRoutes_attribute_categories, apiRoutes_attribute_options, apiRoutes_attributes, apiRoutes_b2b, apiRoutes_brands, apiRoutes_credits, apiRoutes_customers, apiRoutes_data_exchange, apiRoutes_designs, apiRoutes_discount_codes, apiRoutes_entitlement_limits, apiRoutes_entitlements, apiRoutes_events, apiRoutes_external_apps, apiRoutes_fulfillment, apiRoutes_iap, apiRoutes_invoices, apiRoutes_item_variants, apiRoutes_lager_inventory, apiRoutes_logs, apiRoutes_media_sets, apiRoutes_oauth2, apiRoutes_orders, apiRoutes_payments, apiRoutes_paypal, apiRoutes_permissions, apiRoutes_product_categories, apiRoutes_product_items, apiRoutes_products, apiRoutes_roles, apiRoutes_sender_brands, apiRoutes_settings, apiRoutes_status_changes, apiRoutes_stripe, apiRoutes_subscriptions, apiRoutes_suppliers, apiRoutes_tickets, apiRoutes_translations, apiRoutes_usage_reports, apiRoutes_user_activity, apiRoutes_users, apiRoutes_variant_entitlements, apiRoutes_webhooks, createShopClient, diagnoseShop };
+// src/capabilities.ts
+var SDK_VERSION2 = "0.3.0" ;
+var ROUTES = apiRoutes;
+var CLIENT_MANAGEMENT_OPS = [
+  "external_apps_service_register",
+  "external_apps_service_update",
+  "external_apps_service_delete"
+];
+var CLIENT_ROTATION_OPS = ["external_apps_service_rotate_key"];
+var PEER_STATUS_OPS = ["external_apps_service_status"];
+function has(operationId) {
+  return Object.prototype.hasOwnProperty.call(ROUTES, operationId);
+}
+function capabilityFrom(operationIds, reasonWhenMissing) {
+  const present = operationIds.filter(has);
+  if (present.length === operationIds.length) {
+    return { supported: true, operations: present };
+  }
+  const missing = operationIds.filter((id) => !present.includes(id));
+  return {
+    supported: false,
+    operations: present,
+    reason: `${reasonWhenMissing} Fehlend im Vertrag: ${missing.join(", ")}.`
+  };
+}
+function capabilityFromPrefix(prefix, reasonWhenMissing) {
+  const present = Object.keys(ROUTES).filter((id) => id.startsWith(prefix));
+  return present.length > 0 ? { supported: true, operations: present } : { supported: false, operations: [], reason: reasonWhenMissing };
+}
+function shopCapabilities() {
+  const operationIds = Object.keys(ROUTES);
+  const authChannels = {};
+  for (const id of operationIds) {
+    const channel = ROUTES[id]?.auth?.type ?? "none";
+    authChannels[channel] = (authChannels[channel] ?? 0) + 1;
+  }
+  return {
+    service: "node-shop",
+    sdkVersion: SDK_VERSION2,
+    contractSha256: CONTRACT_SHA256,
+    operationCount: operationIds.length,
+    authChannels,
+    capabilities: {
+      // Der Endpunkt beschreibt den Vertrag und kann deshalb nicht in ihm stehen. Er
+      // gehoert zur Zusage dieses SDK und wird von `diagnoseShop` live geprueft.
+      contractFingerprint: { supported: true, operations: [] },
+      healthCheck: capabilityFrom(
+        ["app_info_health"],
+        "Ohne Erreichbarkeits-Endpunkt bleibt nur der Umweg ueber eine echte Anfrage."
+      ),
+      clientManagement: capabilityFrom(
+        CLIENT_MANAGEMENT_OPS,
+        "Ohne diese Routen kann ein Verwalter keine Anbindung fuer andere Apps einrichten."
+      ),
+      clientRotation: capabilityFrom(
+        CLIENT_ROTATION_OPS,
+        "Ohne Erneuerung ist ein einmal ausgegebener Schluessel dauerhaft."
+      ),
+      // Anders als bei orvello haengt die Gnadenfrist nicht an eigenen Routen, sondern am
+      // Feld `gracePeriodHours` derselben Rotation: der alte Schluessel bleibt so lange
+      // gueltig und laeuft dann von selbst ab. Das ist eine Zusage des Vertrags, aber
+      // keine, die sich anhand einer Operation belegen laesst — deshalb steht als Beleg
+      // die Rotation selbst und nicht eine erfundene zweite Operation.
+      rotationGracePeriod: has("external_apps_service_rotate_key") ? { supported: true, operations: CLIENT_ROTATION_OPS } : {
+        supported: false,
+        operations: [],
+        reason: "Ohne Rotation gibt es auch keine Gnadenfrist."
+      },
+      clientRevocation: {
+        supported: false,
+        operations: [],
+        reason: "node-shop kennt keinen eigenen Widerruf. Ein Zugang wird entzogen, indem die App auf `isActive: false` gesetzt (external_apps_service_update) oder geloescht wird (external_apps_service_delete) \u2014 das erste ist reversibel, das zweite endgueltig. Ein Verwalter, der nur den Schluessel ungueltig machen will, ohne die Anbindung anzufassen, hat dafuer heute keine Operation."
+      },
+      peerStatus: capabilityFrom(
+        PEER_STATUS_OPS,
+        "Ohne Statusroute kann ein Verwalter nur raten, was der Shop ueber die App fuehrt."
+      ),
+      entitlements: capabilityFromPrefix(
+        "entitlements_",
+        "Dieser Vertrag kennt keine Berechtigungs-Routen."
+      ),
+      commerce: capabilityFromPrefix(
+        "b2b_",
+        "Dieser Vertrag kennt keine B2B-Routen \u2014 fremde Apps koennen darueber nichts verkaufen."
+      ),
+      usageMetering: capabilityFromPrefix(
+        "usage_reports_",
+        "Dieser Vertrag kennt keine Verbrauchs-Routen."
+      ),
+      serverSideDryRun: {
+        supported: false,
+        operations: [],
+        reason: "node-shop bietet keinen serverseitigen Probelauf an. Nebenwirkungsfrei pruefbar ist der Weg trotzdem: `diagnoseShop` beweist Erreichbarkeit und Vertrag ohne zu schreiben, und `external_apps_service_status` beweist, was der Shop ueber die App fuehrt \u2014 beides beweist die Voraussetzung, nicht das Ergebnis."
+      }
+    }
+  };
+}
+
+export { CONTRACT_SHA256, SHOP_API_URL, ShopApiError, ShopConfigurationError, apiGroups, apiMountPrefixes, apiRoutes, apiRoutes_api, apiRoutes_app_info, apiRoutes_assigned_entitlements, apiRoutes_attribute_assignments, apiRoutes_attribute_categories, apiRoutes_attribute_options, apiRoutes_attributes, apiRoutes_b2b, apiRoutes_brands, apiRoutes_credits, apiRoutes_customers, apiRoutes_data_exchange, apiRoutes_designs, apiRoutes_discount_codes, apiRoutes_entitlement_limits, apiRoutes_entitlements, apiRoutes_events, apiRoutes_external_apps, apiRoutes_fulfillment, apiRoutes_iap, apiRoutes_invoices, apiRoutes_item_variants, apiRoutes_lager_inventory, apiRoutes_logs, apiRoutes_media_sets, apiRoutes_oauth2, apiRoutes_orders, apiRoutes_payments, apiRoutes_paypal, apiRoutes_permissions, apiRoutes_product_categories, apiRoutes_product_items, apiRoutes_products, apiRoutes_roles, apiRoutes_sender_brands, apiRoutes_settings, apiRoutes_status_changes, apiRoutes_stripe, apiRoutes_subscriptions, apiRoutes_suppliers, apiRoutes_tickets, apiRoutes_translations, apiRoutes_usage_reports, apiRoutes_user_activity, apiRoutes_users, apiRoutes_variant_entitlements, apiRoutes_webhooks, createShopClient, diagnoseShop, shopCapabilities };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map