@driggsby/sdk 0.4.0 → 0.5.0

package/README.md

@@ -22,6 +22,22 @@ the callback runs again with fresh data. It returns an unsubscribe
 function. Identical results are deduped, so unchanged data never
 re-renders.
 
+To show a section's own failure, pass `onError`. It runs when a watch
+fails, after any retries the host makes, with `{ message, kind }`. A
+repeat of the same failure is skipped. `kind` is `"timeout"`,
+`"unavailable"`, `"busy"`, `"rate_limited"` or `null`. Under
+`driggsby dev`, which doesn't retry, `kind` is always `null`. The next
+successful result always reaches your callback, even when it matches
+the data from before the failure, so clear the failure there. Show
+`error.message` as text (for example with `textContent`), never as
+HTML:
+
+```js
+driggsby.watch("list_accounts", {}, render, {
+  onError: (error) => showFailure(error.message),
+});
+```
+
 This package exists for two narrower uses:
 
 - `driggsby dev` serves the same runtime locally from this package's

package/dist/driggsby-sdk.js

@@ -11,6 +11,7 @@ function isAllowedHostOrigin(origin, allowLocalHostOrigins) {
   if (EXACT_ALLOWED_HOST_ORIGINS.has(origin)) return true;
   return allowLocalHostOrigins && LOCAL_HOST_ORIGIN_PATTERN.test(origin);
 }
+var WATCH_ERROR_KINDS = /* @__PURE__ */ new Set(["timeout", "unavailable", "busy", "rate_limited"]);
 var APP_ROUTE_PATTERN = /^#[A-Za-z0-9/\-._]{1,256}$/;
 function sanitizeAppRoute(value) {
   return typeof value === "string" && APP_ROUTE_PATTERN.test(value) ? value : "";
@@ -22,16 +23,20 @@ function parseProtocolMessage(data) {
   const type = record.type;
   if (typeof type !== "string") return null;
   let errorMessage = null;
+  let errorKind = null;
   const error = record.error;
   if (typeof error === "object" && error !== null) {
     const message = error.message;
     errorMessage = typeof message === "string" ? message : "Something went wrong running this tool.";
+    const kind = error.kind;
+    errorKind = typeof kind === "string" && WATCH_ERROR_KINDS.has(kind) ? kind : null;
   }
   return {
     type,
     id: typeof record.id === "string" ? record.id : null,
     result: record.result,
     errorMessage,
+    errorKind,
     route: sanitizeAppRoute(record.route)
   };
 }
@@ -57,14 +62,15 @@ var SdkCore = class {
   // params is typed loose on purpose: app authors call this from untyped
   // JavaScript, and a null/omitted params should mean "no params", not a
   // crash.
-  watch(tool, params, callback) {
+  watch(tool, params, callback, options) {
     if (this.watches.size >= MAX_WATCHES) {
       this.onToolError?.(tool, `Watch limit reached (${String(MAX_WATCHES)}); this watch will not receive data. Unsubscribe watches you no longer need.`);
       return () => void 0;
     }
     this.sequence += 1;
     const id = `w${this.sequence}`;
-    this.watches.set(id, { tool, params: params ?? {}, callback, lastDeliveredJson: null });
+    const onError = typeof options?.onError === "function" ? options.onError : null;
+    this.watches.set(id, { tool, params: params ?? {}, callback, onError, lastDeliveredJson: null });
     this.requestWatch(id);
     return () => {
       this.watches.delete(id);
@@ -116,10 +122,11 @@ var SdkCore = class {
     const entry = message.id === null ? void 0 : this.watches.get(message.id);
     if (entry === void 0) return;
     if (message.errorMessage !== null) {
-      const json2 = JSON.stringify({ error: message.errorMessage });
+      const json2 = JSON.stringify({ error: message.errorMessage, kind: message.errorKind });
       if (json2 === entry.lastDeliveredJson) return;
       entry.lastDeliveredJson = json2;
       this.onToolError?.(entry.tool, message.errorMessage);
+      entry.onError?.({ message: message.errorMessage, kind: message.errorKind });
       return;
     }
     const json = JSON.stringify({ result: message.result });
@@ -191,7 +198,7 @@ window.addEventListener("message", (event) => {
   core.handleMessage(event.origin, event.source === window.parent, event.data);
 });
 window.driggsby = {
-  watch: (tool, params, callback) => core.watch(tool, params, callback)
+  watch: (tool, params, callback, options) => core.watch(tool, params, callback, options)
 };
 if (window.parent === window) {
   whenBodyReady(showStandaloneNote);

package/dist/index.d.ts

@@ -1 +1 @@
-export { MAX_WATCHES, PROTOCOL, SdkCore, isAllowedHostOrigin, isLocalAppHostname, type PostFunction, type WatchCallback, } from "./sdk-core.ts";
+export { MAX_WATCHES, PROTOCOL, SdkCore, isAllowedHostOrigin, isLocalAppHostname, type PostFunction, type WatchCallback, type WatchError, type WatchOptions, } from "./sdk-core.ts";

package/dist/sdk-core.d.ts

@@ -3,6 +3,13 @@ export declare const MAX_WATCHES = 32;
 export declare function isLocalAppHostname(hostname: string): boolean;
 export declare function isAllowedHostOrigin(origin: string, allowLocalHostOrigins: boolean): boolean;
 export type WatchCallback = (result: unknown) => void;
+export interface WatchError {
+    message: string;
+    kind: string | null;
+}
+export interface WatchOptions {
+    onError?: (error: WatchError) => void;
+}
 export type PostFunction = (message: Record<string, unknown>, targetOrigin: string) => void;
 export declare function sanitizeAppRoute(value: unknown): string;
 export declare class SdkCore {
@@ -19,7 +26,7 @@ export declare class SdkCore {
         allowLocalHostOrigins?: boolean;
     });
     get hostReady(): boolean;
-    watch(tool: string, params: Record<string, unknown> | null | undefined, callback: WatchCallback): () => void;
+    watch(tool: string, params: Record<string, unknown> | null | undefined, callback: WatchCallback, options?: WatchOptions | null): () => void;
     handleMessage(origin: string, fromParent: boolean, data: unknown): void;
     private handleHello;
     reportRoute(hash: string): void;

package/dist/sdk-core.js

@@ -6,7 +6,10 @@
 // first-valid-hello pin, and the parent-source requirement.
 //
 // The whole public surface an app sees is:
-//   driggsby.watch(tool, params, callback) -> unsubscribe()
+//   driggsby.watch(tool, params, callback[, { onError }]) -> unsubscribe()
+// onError(error) receives { message, kind } when a watch's call fails
+// after the host's retries; kind is "timeout", "unavailable", "busy",
+// "rate_limited" or null.
 // Every read is a live subscription: the host announces "data-changed" and
 // each watch re-runs; results are deduped by JSON identity so unchanged
 // data never re-renders.
@@ -38,6 +41,9 @@ export function isAllowedHostOrigin(origin, allowLocalHostOrigins) {
         return true;
     return allowLocalHostOrigins && LOCAL_HOST_ORIGIN_PATTERN.test(origin);
 }
+// The failure kinds a watch may be told about; the host forwards only
+// these, and anything else reads as null.
+const WATCH_ERROR_KINDS = new Set(["timeout", "unavailable", "busy", "rate_limited"]);
 // The app's in-page location, as a URL fragment. The host mirrors it into
 // its own page URL (so refresh and shared links restore it) and hands it
 // back in the hello after a reload. The shape is deliberately narrow — a
@@ -58,16 +64,20 @@ function parseProtocolMessage(data) {
     if (typeof type !== "string")
         return null;
     let errorMessage = null;
+    let errorKind = null;
     const error = record.error;
     if (typeof error === "object" && error !== null) {
         const message = error.message;
         errorMessage = typeof message === "string" ? message : "Something went wrong running this tool.";
+        const kind = error.kind;
+        errorKind = typeof kind === "string" && WATCH_ERROR_KINDS.has(kind) ? kind : null;
     }
     return {
         type,
         id: typeof record.id === "string" ? record.id : null,
         result: record.result,
         errorMessage,
+        errorKind,
         route: sanitizeAppRoute(record.route),
     };
 }
@@ -93,7 +103,7 @@ export class SdkCore {
     // params is typed loose on purpose: app authors call this from untyped
     // JavaScript, and a null/omitted params should mean "no params", not a
     // crash.
-    watch(tool, params, callback) {
+    watch(tool, params, callback, options) {
         // Watches are registered by arbitrary app code; a watch() call that
         // leaked into a render loop would otherwise grow forever and turn
         // every data-changed into an unbounded fan-out of real tool calls.
@@ -104,7 +114,10 @@ export class SdkCore {
         }
         this.sequence += 1;
         const id = `w${this.sequence}`;
-        this.watches.set(id, { tool, params: params ?? {}, callback, lastDeliveredJson: null });
+        // Options come from untyped app code: a non-function onError is
+        // ignored rather than thrown at on the first failure.
+        const onError = typeof options?.onError === "function" ? options.onError : null;
+        this.watches.set(id, { tool, params: params ?? {}, callback, onError, lastDeliveredJson: null });
         // Before the host pins, requestWatch posts nothing; the pinning hello
         // fires every registered watch, so pre-hello watches are simply held.
         this.requestWatch(id);
@@ -172,11 +185,12 @@ export class SdkCore {
         if (entry === undefined)
             return;
         if (message.errorMessage !== null) {
-            const json = JSON.stringify({ error: message.errorMessage });
+            const json = JSON.stringify({ error: message.errorMessage, kind: message.errorKind });
             if (json === entry.lastDeliveredJson)
                 return;
             entry.lastDeliveredJson = json;
             this.onToolError?.(entry.tool, message.errorMessage);
+            entry.onError?.({ message: message.errorMessage, kind: message.errorKind });
             return;
         }
         // Wrapping in an object keeps stringify total: even `result: undefined`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driggsby/sdk",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "The browser SDK for Driggsby apps: live financial data through driggsby.watch().",
   "license": "Apache-2.0",
   "repository": {