sdk-garden-js 0.2.0 → 0.3.0

package/README.md

@@ -63,6 +63,8 @@ Requires Node.js 18+ (for the global `fetch`) or any modern browser.
 | `startedAt` | `number` | module load time | `Date.now()` when your SDK began initializing; reported as `time_to_init_ms` for the dashboard's init timing |
 | `methods` | `string[]` | `[]` | Public methods of your SDK that are not wrapped with `trackMethod()`, so the dashboard's API Surface panel can show them when nobody calls them |
 | `customer` | `{ id: string; name?: string }` | _(none)_ | The app or customer account this session runs for (see [Customers](#customers)) |
+| `advisories` | `boolean` | `true` | Show the version advisories you set on the Releases page as one `console.warn` per process (0.3.0+) |
+| `onAdvisory` | `(advisory) => void` | _(none)_ | Handle an advisory yourself instead: `{ version, severity, message, upgradeTo? }` |
 
 ### API surface
 

package/dist/index.d.mts

@@ -60,6 +60,29 @@ interface SdkGardenConfig {
      * setCustomer(). Default: none.
      */
     customer?: SdkGardenCustomer;
+    /**
+     * Show the notices you attach to versions on the SDK Garden Releases page
+     * (deprecated, broken, security) to developers still running them, as one
+     * console.warn per process. Default: true. Set onAdvisory to handle them
+     * yourself instead.
+     */
+    advisories?: boolean;
+    /**
+     * Called once per process when the version in use has an advisory, instead
+     * of the default console.warn. Use it to route the notice through your
+     * SDK's own logger. Exceptions it throws are ignored.
+     */
+    onAdvisory?: (advisory: SdkGardenAdvisory) => void;
+}
+/** A notice the SDK publisher attached to the running version (see SdkGardenConfig.advisories). */
+interface SdkGardenAdvisory {
+    /** The version this process runs, e.g. "1.2.0". */
+    version: string;
+    severity: 'deprecated' | 'broken' | 'security';
+    /** The publisher's message; may be empty. */
+    message: string;
+    /** The version the publisher recommends, if they named one. */
+    upgradeTo?: string;
 }
 /** The app or customer account a session is attributed to (see setCustomer()). */
 interface SdkGardenCustomer {
@@ -140,4 +163,4 @@ interface SdkGardenObject {
  */
 declare const SdkGarden: SdkGardenObject;
 
-export { type SdkGardenConfig, type SdkGardenCustomer, type SdkMethodDecorator, SdkGarden as default };
+export { type SdkGardenAdvisory, type SdkGardenConfig, type SdkGardenCustomer, type SdkMethodDecorator, SdkGarden as default };

package/dist/index.d.ts

@@ -60,6 +60,29 @@ interface SdkGardenConfig {
      * setCustomer(). Default: none.
      */
     customer?: SdkGardenCustomer;
+    /**
+     * Show the notices you attach to versions on the SDK Garden Releases page
+     * (deprecated, broken, security) to developers still running them, as one
+     * console.warn per process. Default: true. Set onAdvisory to handle them
+     * yourself instead.
+     */
+    advisories?: boolean;
+    /**
+     * Called once per process when the version in use has an advisory, instead
+     * of the default console.warn. Use it to route the notice through your
+     * SDK's own logger. Exceptions it throws are ignored.
+     */
+    onAdvisory?: (advisory: SdkGardenAdvisory) => void;
+}
+/** A notice the SDK publisher attached to the running version (see SdkGardenConfig.advisories). */
+interface SdkGardenAdvisory {
+    /** The version this process runs, e.g. "1.2.0". */
+    version: string;
+    severity: 'deprecated' | 'broken' | 'security';
+    /** The publisher's message; may be empty. */
+    message: string;
+    /** The version the publisher recommends, if they named one. */
+    upgradeTo?: string;
 }
 /** The app or customer account a session is attributed to (see setCustomer()). */
 interface SdkGardenCustomer {
@@ -140,4 +163,4 @@ interface SdkGardenObject {
  */
 declare const SdkGarden: SdkGardenObject;
 
-export { type SdkGardenConfig, type SdkGardenCustomer, type SdkMethodDecorator, SdkGarden as default };
+export { type SdkGardenAdvisory, type SdkGardenConfig, type SdkGardenCustomer, type SdkMethodDecorator, SdkGarden as default };

package/dist/index.js

@@ -41,6 +41,8 @@ var _pending = /* @__PURE__ */ new Set();
 var _registered = /* @__PURE__ */ new Set();
 var _undeclared = [];
 var _declareScheduled = false;
+var _advisoriesShown = /* @__PURE__ */ new Set();
+var ADVISORY_HEADER = "SDK-Garden-Advisory";
 var DEFAULT_ENDPOINT = "https://ingest.sdkgarden.com/track";
 var MAX_BATCH_SIZE = 100;
 var MAX_QUEUE_SIZE = 1e3;
@@ -69,7 +71,7 @@ function _clamp(value, min, max, fallback) {
   return Math.min(max, Math.max(min, Math.floor(value)));
 }
 function _mergeDefaults(config) {
-  var _a, _b;
+  var _a, _b, _c;
   return {
     apiKey: config.apiKey,
     sdkName: config.sdkName,
@@ -81,7 +83,9 @@ function _mergeDefaults(config) {
     // A batch size below 1 would never empty the queue; above 100 the endpoint rejects it.
     batchSize: _clamp(config.batchSize, 1, MAX_BATCH_SIZE, 10),
     // A tiny interval would send constantly; one too large for a timer would fire every 1 ms.
-    flushInterval: _clamp(config.flushInterval, 100, MAX_TIMER_MS, 5e3)
+    flushInterval: _clamp(config.flushInterval, 100, MAX_TIMER_MS, 5e3),
+    advisories: (_c = config.advisories) != null ? _c : true,
+    onAdvisory: typeof config.onAdvisory === "function" ? config.onAdvisory : null
   };
 }
 function _generateSessionId() {
@@ -385,6 +389,55 @@ function _takeBatch(events, maxEvents) {
   }
   return events.splice(0, count).map((event) => event.json);
 }
+function _parseAdvisory(raw) {
+  var _a;
+  const fields = {};
+  for (const part of raw.split("&")) {
+    const eq = part.indexOf("=");
+    if (eq <= 0) continue;
+    try {
+      fields[decodeURIComponent(part.slice(0, eq))] = decodeURIComponent(part.slice(eq + 1).replace(/\+/g, " "));
+    } catch (e) {
+      return null;
+    }
+  }
+  const severity = fields["severity"];
+  if (!fields["version"] || severity !== "deprecated" && severity !== "broken" && severity !== "security") {
+    return null;
+  }
+  return {
+    version: fields["version"],
+    severity,
+    message: ((_a = fields["message"]) != null ? _a : "").slice(0, 280),
+    ...fields["upgrade_to"] ? { upgradeTo: fields["upgrade_to"].slice(0, 50) } : {}
+  };
+}
+function _advisoryText(sdkName, a) {
+  const what = { deprecated: "is deprecated", broken: "has a known problem", security: "has a security issue" }[a.severity];
+  let text = `[${sdkName}] Version ${a.version} ${what}.`;
+  if (a.message) text += ` ${a.message}`;
+  if (a.upgradeTo) text += ` Upgrade to ${a.upgradeTo}.`;
+  return text;
+}
+function _handleAdvisory(config, response) {
+  var _a, _b;
+  if (!config.advisories) return;
+  const raw = (_b = (_a = response == null ? void 0 : response.headers) == null ? void 0 : _a.get) == null ? void 0 : _b.call(_a, ADVISORY_HEADER);
+  if (typeof raw !== "string" || raw === "") return;
+  const advisory = _parseAdvisory(raw);
+  if (!advisory || _advisoriesShown.has(advisory.version)) return;
+  _advisoriesShown.add(advisory.version);
+  if (config.onAdvisory) {
+    try {
+      config.onAdvisory(advisory);
+    } catch (e) {
+    }
+    return;
+  }
+  if (typeof console !== "undefined" && typeof console.warn === "function") {
+    console.warn(_advisoryText(config.sdkName, advisory));
+  }
+}
 function _send(config, batch, keepalive) {
   var _a;
   if (typeof fetch !== "function") {
@@ -449,6 +502,7 @@ function _send(config, batch, keepalive) {
           if (stream && typeof stream.cancel === "function") discarded = stream.cancel();
         } catch (e) {
         }
+        if (delivered) _safely(() => _handleAdvisory(config, response));
         Promise.resolve(discarded).then(settle, settle);
       },
       () => settle()
@@ -846,6 +900,7 @@ var SdkGarden = {
     _pending.clear();
     _registered.clear();
     _undeclared = [];
+    _advisoriesShown.clear();
   }
 };
 var index_default = SdkGarden;

package/dist/index.mjs

@@ -17,6 +17,8 @@ var _pending = /* @__PURE__ */ new Set();
 var _registered = /* @__PURE__ */ new Set();
 var _undeclared = [];
 var _declareScheduled = false;
+var _advisoriesShown = /* @__PURE__ */ new Set();
+var ADVISORY_HEADER = "SDK-Garden-Advisory";
 var DEFAULT_ENDPOINT = "https://ingest.sdkgarden.com/track";
 var MAX_BATCH_SIZE = 100;
 var MAX_QUEUE_SIZE = 1e3;
@@ -45,7 +47,7 @@ function _clamp(value, min, max, fallback) {
   return Math.min(max, Math.max(min, Math.floor(value)));
 }
 function _mergeDefaults(config) {
-  var _a, _b;
+  var _a, _b, _c;
   return {
     apiKey: config.apiKey,
     sdkName: config.sdkName,
@@ -57,7 +59,9 @@ function _mergeDefaults(config) {
     // A batch size below 1 would never empty the queue; above 100 the endpoint rejects it.
     batchSize: _clamp(config.batchSize, 1, MAX_BATCH_SIZE, 10),
     // A tiny interval would send constantly; one too large for a timer would fire every 1 ms.
-    flushInterval: _clamp(config.flushInterval, 100, MAX_TIMER_MS, 5e3)
+    flushInterval: _clamp(config.flushInterval, 100, MAX_TIMER_MS, 5e3),
+    advisories: (_c = config.advisories) != null ? _c : true,
+    onAdvisory: typeof config.onAdvisory === "function" ? config.onAdvisory : null
   };
 }
 function _generateSessionId() {
@@ -361,6 +365,55 @@ function _takeBatch(events, maxEvents) {
   }
   return events.splice(0, count).map((event) => event.json);
 }
+function _parseAdvisory(raw) {
+  var _a;
+  const fields = {};
+  for (const part of raw.split("&")) {
+    const eq = part.indexOf("=");
+    if (eq <= 0) continue;
+    try {
+      fields[decodeURIComponent(part.slice(0, eq))] = decodeURIComponent(part.slice(eq + 1).replace(/\+/g, " "));
+    } catch (e) {
+      return null;
+    }
+  }
+  const severity = fields["severity"];
+  if (!fields["version"] || severity !== "deprecated" && severity !== "broken" && severity !== "security") {
+    return null;
+  }
+  return {
+    version: fields["version"],
+    severity,
+    message: ((_a = fields["message"]) != null ? _a : "").slice(0, 280),
+    ...fields["upgrade_to"] ? { upgradeTo: fields["upgrade_to"].slice(0, 50) } : {}
+  };
+}
+function _advisoryText(sdkName, a) {
+  const what = { deprecated: "is deprecated", broken: "has a known problem", security: "has a security issue" }[a.severity];
+  let text = `[${sdkName}] Version ${a.version} ${what}.`;
+  if (a.message) text += ` ${a.message}`;
+  if (a.upgradeTo) text += ` Upgrade to ${a.upgradeTo}.`;
+  return text;
+}
+function _handleAdvisory(config, response) {
+  var _a, _b;
+  if (!config.advisories) return;
+  const raw = (_b = (_a = response == null ? void 0 : response.headers) == null ? void 0 : _a.get) == null ? void 0 : _b.call(_a, ADVISORY_HEADER);
+  if (typeof raw !== "string" || raw === "") return;
+  const advisory = _parseAdvisory(raw);
+  if (!advisory || _advisoriesShown.has(advisory.version)) return;
+  _advisoriesShown.add(advisory.version);
+  if (config.onAdvisory) {
+    try {
+      config.onAdvisory(advisory);
+    } catch (e) {
+    }
+    return;
+  }
+  if (typeof console !== "undefined" && typeof console.warn === "function") {
+    console.warn(_advisoryText(config.sdkName, advisory));
+  }
+}
 function _send(config, batch, keepalive) {
   var _a;
   if (typeof fetch !== "function") {
@@ -425,6 +478,7 @@ function _send(config, batch, keepalive) {
           if (stream && typeof stream.cancel === "function") discarded = stream.cancel();
         } catch (e) {
         }
+        if (delivered) _safely(() => _handleAdvisory(config, response));
         Promise.resolve(discarded).then(settle, settle);
       },
       () => settle()
@@ -822,6 +876,7 @@ var SdkGarden = {
     _pending.clear();
     _registered.clear();
     _undeclared = [];
+    _advisoriesShown.clear();
   }
 };
 var index_default = SdkGarden;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdk-garden-js",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Lightweight SDK observability client for JavaScript/TypeScript \u2014 zero runtime dependencies",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",