@garretapp/sdk 0.1.0

package/dist/ui.cjs

@@ -0,0 +1,249 @@
+'use strict';
+
+// src/errors.ts
+var GarretError = class _GarretError extends Error {
+  code;
+  hint;
+  constructor(code, message, options) {
+    super(message);
+    this.name = "GarretError";
+    this.code = code;
+    this.hint = options?.hint;
+    Object.setPrototypeOf(this, _GarretError.prototype);
+  }
+};
+function garretErrorFromWire(code, message, hint) {
+  const known = [
+    "BINARY_NOT_FOUND",
+    "NOT_FOUND",
+    "PERMISSION",
+    "UNAVAILABLE",
+    "BAD_ARGS",
+    "TIMEOUT",
+    "CANCELLED",
+    "NETWORK",
+    "INTERNAL"
+  ];
+  const c = known.includes(code) ? code : "INTERNAL";
+  return new GarretError(c, message, hint ? { hint } : void 0);
+}
+
+// src/client.ts
+var MAX_PREATTACH_CHUNKS = 1e3;
+var IDLE_TIMEOUT_MS = 3e4;
+function createHostClient(transport, opts) {
+  const calls = /* @__PURE__ */ new Map();
+  const events = /* @__PURE__ */ new Map();
+  const eventBuffer = /* @__PURE__ */ new Map();
+  let seq = 0;
+  const nextId = () => `${opts.instanceId}:${++seq}`;
+  const settle = (id, fn) => {
+    const s = calls.get(id);
+    if (!s) return;
+    clearTimeout(s.timer);
+    calls.delete(id);
+    fn(s);
+  };
+  const timeoutError = (method) => new GarretError("TIMEOUT", `"${method}" timed out`);
+  const off = transport.onMessage((msg) => {
+    switch (msg.t) {
+      case "res":
+        settle(msg.id, (s) => s.resolve(msg.result));
+        break;
+      case "stream_end":
+        settle(msg.id, (s) => {
+          s.onEnd.forEach((cb) => cb(msg.result));
+          s.resolve(msg.result);
+        });
+        break;
+      case "err":
+        settle(msg.id, (s) => {
+          const e = garretErrorFromWire(msg.code, msg.message, msg.hint);
+          s.onError.forEach((cb) => cb(e));
+          s.reject(e);
+        });
+        break;
+      case "stream_err":
+        settle(msg.id, (s) => {
+          const e = garretErrorFromWire(msg.code, msg.message);
+          s.onError.forEach((cb) => cb(e));
+          s.reject(e);
+        });
+        break;
+      case "chunk": {
+        const s = calls.get(msg.id);
+        if (!s) break;
+        clearTimeout(s.timer);
+        s.timer = setTimeout(() => settle(msg.id, (st) => st.reject(timeoutError(msg.id))), IDLE_TIMEOUT_MS);
+        if (s.onData.length) s.onData.forEach((cb) => cb(msg.data));
+        else if (s.buffer.length < MAX_PREATTACH_CHUNKS) s.buffer.push(msg.data);
+        else s.overflow = true;
+        break;
+      }
+      case "event": {
+        const subs = events.get(msg.channel);
+        if (subs && subs.size) subs.forEach((cb) => cb(msg.payload));
+        else {
+          const buf = eventBuffer.get(msg.channel) ?? [];
+          if (buf.length < 100) buf.push(msg.payload);
+          eventBuffer.set(msg.channel, buf);
+        }
+        break;
+      }
+    }
+  });
+  function makeCall(method, args) {
+    const id = nextId();
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => {
+      resolve = res;
+      reject = rej;
+    });
+    promise.catch(() => {
+    });
+    const s = {
+      onData: [],
+      onEnd: [],
+      onError: [],
+      buffer: [],
+      overflow: false,
+      resolve,
+      reject,
+      timer: setTimeout(() => {
+        const e = timeoutError(method);
+        settle(id, (st) => {
+          st.onError.forEach((cb) => cb(e));
+          st.reject(e);
+        });
+      }, IDLE_TIMEOUT_MS)
+    };
+    calls.set(id, s);
+    transport.send({ t: "req", id, method, args });
+    const flush = (cb) => {
+      const buf = s.buffer;
+      s.buffer = [];
+      buf.forEach((c) => cb(c));
+    };
+    const call = {
+      then: (onF, onR) => promise.then(onF, onR),
+      catch: (onR) => promise.catch(onR),
+      finally: (cb) => promise.finally(cb),
+      result: () => promise,
+      onData(cb) {
+        s.onData.push(cb);
+        flush(cb);
+        return call;
+      },
+      onEnd(cb) {
+        s.onEnd.push(cb);
+        return call;
+      },
+      onError(cb) {
+        s.onError.push(cb);
+        return call;
+      },
+      cancel() {
+        if (!calls.has(id)) return;
+        clearTimeout(s.timer);
+        calls.delete(id);
+        transport.send({ t: "cancel", id });
+      }
+    };
+    return call;
+  }
+  const base = {
+    on(channel, cb) {
+      let set = events.get(channel);
+      if (!set) events.set(channel, set = /* @__PURE__ */ new Set());
+      set.add(cb);
+      const buffered = eventBuffer.get(channel);
+      if (buffered?.length) {
+        eventBuffer.delete(channel);
+        buffered.forEach((p) => cb(p));
+      }
+      return () => set.delete(cb);
+    },
+    dispose() {
+      off();
+      for (const s of calls.values()) clearTimeout(s.timer);
+      calls.clear();
+      events.clear();
+      eventBuffer.clear();
+    }
+  };
+  return new Proxy(base, {
+    get(target, prop) {
+      if (prop in target) return target[prop];
+      return (args) => makeCall(prop, args);
+    }
+  });
+}
+
+// src/platform.ts
+function getRuntime() {
+  return typeof window !== "undefined" ? window.__garret : void 0;
+}
+function getHostTransport() {
+  return getRuntime()?.hostTransport ?? null;
+}
+function getInstanceId() {
+  return getRuntime()?.instanceId ?? "dev";
+}
+function nope() {
+  throw new GarretError("UNAVAILABLE", "not running inside Garret");
+}
+var stubStorage = { get: nope, set: nope, delete: nope, keys: nope, clear: nope };
+var stubSecrets = { get: nope, set: nope, delete: nope };
+function getGarret() {
+  const rt = getRuntime();
+  if (rt) return rt;
+  return {
+    inGarret: false,
+    storage: stubStorage,
+    instanceStorage: stubStorage,
+    secrets: stubSecrets,
+    shared: { storage: stubStorage, secrets: stubSecrets },
+    fetch: async () => {
+      throw new GarretError("UNAVAILABLE", "g.fetch is only available inside Garret");
+    },
+    service: () => ({ status: nope, query: nope }),
+    notify: () => {
+    },
+    openExternal: async () => false,
+    clipboard: { readText: nope, writeText: nope },
+    active: true,
+    onActiveChange: () => () => {
+    },
+    onOpenSettings: () => () => {
+    },
+    surfaces: { open: nope, onClosed: () => () => {
+    } },
+    window: { setAspectRatio: () => {
+    }, resize: () => {
+    }, close: () => {
+    } },
+    onReady: (cb) => {
+      cb({});
+      return () => {
+      };
+    }
+  };
+}
+
+// src/types.ts
+function defineManifest(manifest) {
+  return manifest;
+}
+function defineConfig(schema) {
+  return schema;
+}
+
+exports.GarretError = GarretError;
+exports.createHostClient = createHostClient;
+exports.defineConfig = defineConfig;
+exports.defineManifest = defineManifest;
+exports.getGarret = getGarret;
+exports.getHostTransport = getHostTransport;
+exports.getInstanceId = getInstanceId;
+exports.getRuntime = getRuntime;

package/dist/ui.d.cts

@@ -0,0 +1,23 @@
+import { T as Transport } from './protocol-Do0BJdeE.cjs';
+import { E as EventMap, H as HostClient } from './types-BxSYAH_H.cjs';
+export { C as Capability, G as GarretError, M as Manifest, S as Stream, f as StreamCall, g as defineConfig, h as defineManifest } from './types-BxSYAH_H.cjs';
+export { G as GarretPlatform, c as GarretRuntime, d as SecretsApi, e as ServiceClient, f as StorageApi, S as SurfaceApi, a as SurfaceHandle, b as SurfaceOpenOptions, W as WindowControls, g as getGarret, h as getHostTransport, i as getInstanceId, j as getRuntime } from './platform-DnI7gJTx.cjs';
+
+/**
+ * UI-side host client — a typed proxy over the wire (protocol.ts). Every call returns ONE handle
+ * that is both a Promise (plain methods `await` it) and a stream sink (stream methods use
+ * `.onData/.onEnd`). The `HostClient<Api>` TYPE narrows it per method from the `Api` return type —
+ * so authors never restate which methods stream. The host decides stream-vs-value from the runtime
+ * return; the client handles either response on the same id.
+ */
+interface HostClientOptions {
+    /** Correlation namespace so two placements of a widget never cross wires. */
+    instanceId: string;
+}
+type Client<Api, Events extends EventMap> = HostClient<Api> & {
+    on<K extends keyof Events & string>(channel: K, cb: (payload: Events[K]) => void): () => void;
+    dispose(): void;
+};
+declare function createHostClient<Api, Events extends EventMap = EventMap>(transport: Transport, opts: HostClientOptions): Client<Api, Events>;
+
+export { type Client, EventMap, HostClient, type HostClientOptions, createHostClient };

package/dist/ui.d.ts

@@ -0,0 +1,23 @@
+import { T as Transport } from './protocol-Do0BJdeE.js';
+import { E as EventMap, H as HostClient } from './types-BxSYAH_H.js';
+export { C as Capability, G as GarretError, M as Manifest, S as Stream, f as StreamCall, g as defineConfig, h as defineManifest } from './types-BxSYAH_H.js';
+export { G as GarretPlatform, c as GarretRuntime, d as SecretsApi, e as ServiceClient, f as StorageApi, S as SurfaceApi, a as SurfaceHandle, b as SurfaceOpenOptions, W as WindowControls, g as getGarret, h as getHostTransport, i as getInstanceId, j as getRuntime } from './platform-CZHtdUK0.js';
+
+/**
+ * UI-side host client — a typed proxy over the wire (protocol.ts). Every call returns ONE handle
+ * that is both a Promise (plain methods `await` it) and a stream sink (stream methods use
+ * `.onData/.onEnd`). The `HostClient<Api>` TYPE narrows it per method from the `Api` return type —
+ * so authors never restate which methods stream. The host decides stream-vs-value from the runtime
+ * return; the client handles either response on the same id.
+ */
+interface HostClientOptions {
+    /** Correlation namespace so two placements of a widget never cross wires. */
+    instanceId: string;
+}
+type Client<Api, Events extends EventMap> = HostClient<Api> & {
+    on<K extends keyof Events & string>(channel: K, cb: (payload: Events[K]) => void): () => void;
+    dispose(): void;
+};
+declare function createHostClient<Api, Events extends EventMap = EventMap>(transport: Transport, opts: HostClientOptions): Client<Api, Events>;
+
+export { type Client, EventMap, HostClient, type HostClientOptions, createHostClient };

package/dist/ui.js

@@ -0,0 +1,3 @@
+export { defineConfig, defineManifest } from './chunk-RZJO3X6O.js';
+export { createHostClient, getGarret, getHostTransport, getInstanceId, getRuntime } from './chunk-ZJYHRC5C.js';
+export { GarretError } from './chunk-ENIDFSMM.js';

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@garretapp/sdk",
+  "version": "0.1.0",
+  "description": "Build extensions for Garret — one SDK for both web widgets and full-access native extensions. Host runtime (defineHost), UI client + React hooks. See docs/garret.html.",
+  "license": "MIT",
+  "author": "Sudharsan Selvaraj",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
+      "require": { "types": "./dist/index.d.cts", "default": "./dist/index.cjs" }
+    },
+    "./host": {
+      "import": { "types": "./dist/host.d.ts", "default": "./dist/host.js" },
+      "require": { "types": "./dist/host.d.cts", "default": "./dist/host.cjs" }
+    },
+    "./ui": {
+      "import": { "types": "./dist/ui.d.ts", "default": "./dist/ui.js" },
+      "require": { "types": "./dist/ui.d.cts", "default": "./dist/ui.cjs" }
+    },
+    "./react": {
+      "import": { "types": "./dist/react.d.ts", "default": "./dist/react.js" },
+      "require": { "types": "./dist/react.d.cts", "default": "./dist/react.cjs" }
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsup src/index.ts src/host.ts src/ui.ts src/react.ts --format esm,cjs --dts --clean --treeshake",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": { "optional": true }
+  }
+}