@foir/sdk 0.1.0

package/dist/media.js

@@ -0,0 +1,399 @@
+// src/media/ProgressiveMedia.tsx
+import { useRef as useRef2, useState as useState2, useCallback as useCallback2, useEffect as useEffect3 } from "react";
+
+// src/graphql/foir-request.ts
+import { print } from "graphql";
+var FOIR_CDN_BASE = "https://cdn.foir.dev/";
+function absolutiseFoirMediaUrl(url, cdnBase = FOIR_CDN_BASE) {
+  if (!url) return void 0;
+  if (/^https?:\/\//i.test(url)) return url;
+  return cdnBase + url.replace(/^\/+/, "");
+}
+
+// src/media/media.ts
+var DEFAULT_VARIANT_TIERS = [
+  "thumbnail",
+  "small",
+  "medium",
+  "large",
+  "xlarge",
+  "_2xl",
+  "_3xl",
+  "_4xl"
+];
+function toProgressiveImage(img) {
+  if (!img?.url) return void 0;
+  const rawCrop = img.crop;
+  const crop = rawCrop && typeof rawCrop === "object" ? {
+    x: typeof rawCrop.x === "number" ? rawCrop.x : void 0,
+    y: typeof rawCrop.y === "number" ? rawCrop.y : void 0,
+    width: typeof rawCrop.width === "number" ? rawCrop.width : void 0,
+    height: typeof rawCrop.height === "number" ? rawCrop.height : void 0
+  } : void 0;
+  return {
+    url: img.url,
+    alt: img.alt ?? void 0,
+    width: img.width ?? void 0,
+    height: img.height ?? void 0,
+    blurhash: img.blurhash ?? void 0,
+    dominantColor: img.dominantColor ?? void 0,
+    thumbnailUrl: img.webp?.thumbnail?.url ?? void 0,
+    webp: img.webp ?? void 0,
+    avif: img.avif ?? void 0,
+    crop
+  };
+}
+function toProgressiveVideo(v) {
+  if (!v?.url) return void 0;
+  return {
+    url: v.url,
+    width: v.width ?? void 0,
+    height: v.height ?? void 0,
+    hlsUrl: absolutiseFoirMediaUrl(v.hlsManifestUrl),
+    blurhash: v.blurhash ?? void 0,
+    dominantColor: v.dominantColor ?? void 0,
+    thumbnailUrl: v.thumbnailUrl ?? void 0,
+    previewUrl: v.previewUrl ?? void 0
+  };
+}
+function effectiveImageDimensions(image) {
+  if (!image?.width || !image?.height) return null;
+  const crop = image.crop;
+  const cw = typeof crop?.width === "number" ? crop.width : null;
+  const ch = typeof crop?.height === "number" ? crop.height : null;
+  if (cw != null && ch != null && cw > 0 && ch > 0) {
+    return {
+      width: image.width * cw / 100,
+      height: image.height * ch / 100
+    };
+  }
+  return { width: image.width, height: image.height };
+}
+function cropAspectRatio(image) {
+  const dims = effectiveImageDimensions(image);
+  if (!dims) return null;
+  return `${dims.width} / ${dims.height}`;
+}
+
+// src/media/useProgressiveLoad.ts
+import { useState, useEffect, useCallback } from "react";
+var STAGE_ORDER = ["color", "blurhash", "thumbnail", "full"];
+function stageIndex(s) {
+  return STAGE_ORDER.indexOf(s);
+}
+function useProgressiveLoad({
+  blurhash,
+  thumbnailUrl,
+  fullUrl,
+  fullSrcSet,
+  fullSizes,
+  isVideo
+}) {
+  const [stage, setStage] = useState(() => {
+    if (blurhash) return "blurhash";
+    if (thumbnailUrl) return "thumbnail";
+    return "color";
+  });
+  const advance = useCallback((target) => {
+    setStage(
+      (current) => stageIndex(target) > stageIndex(current) ? target : current
+    );
+  }, []);
+  useEffect(() => {
+    if (!thumbnailUrl) return;
+    const img = new Image();
+    img.onload = () => advance("thumbnail");
+    img.src = thumbnailUrl;
+  }, [thumbnailUrl, advance]);
+  useEffect(() => {
+    if (!fullUrl || isVideo) return;
+    const img = new Image();
+    img.onload = () => advance("full");
+    if (fullSizes) img.sizes = fullSizes;
+    if (fullSrcSet) img.srcset = fullSrcSet;
+    img.src = fullUrl;
+  }, [fullUrl, fullSrcSet, fullSizes, isVideo, advance]);
+  const onFullReady = useCallback(() => advance("full"), [advance]);
+  return { stage, onFullReady };
+}
+
+// src/media/BlurhashCanvas.tsx
+import { useEffect as useEffect2, useRef } from "react";
+import { jsx } from "react/jsx-runtime";
+var SIZE = 32;
+function BlurhashCanvas({ hash, className }) {
+  const canvasRef = useRef(null);
+  useEffect2(() => {
+    const canvas = canvasRef.current;
+    if (!canvas) return;
+    import("blurhash").then(({ decode }) => {
+      const pixels = decode(hash, SIZE, SIZE);
+      canvas.width = SIZE;
+      canvas.height = SIZE;
+      const ctx = canvas.getContext("2d");
+      if (!ctx) return;
+      const imageData = ctx.createImageData(SIZE, SIZE);
+      imageData.data.set(pixels);
+      ctx.putImageData(imageData, 0, 0);
+    }).catch(() => {
+    });
+  }, [hash]);
+  return /* @__PURE__ */ jsx(
+    "canvas",
+    {
+      ref: canvasRef,
+      className: `h-full w-full object-cover${className ? ` ${className}` : ""}`
+    }
+  );
+}
+
+// src/media/ProgressiveMedia.tsx
+import { jsx as jsx2, jsxs } from "react/jsx-runtime";
+function useInViewport(rootMargin = "300px", skip = false) {
+  const [inView, setInView] = useState2(skip);
+  const elRef = useRef2(null);
+  const obsRef = useRef2(null);
+  const setRef = useCallback2(
+    (el) => {
+      elRef.current = el;
+      if (skip || !el) return;
+      if (typeof IntersectionObserver === "undefined") {
+        setInView(true);
+        return;
+      }
+      obsRef.current?.disconnect();
+      obsRef.current = new IntersectionObserver(
+        (entries) => {
+          for (const e of entries) {
+            if (e.isIntersecting) {
+              setInView(true);
+              obsRef.current?.disconnect();
+              obsRef.current = null;
+              break;
+            }
+          }
+        },
+        { rootMargin }
+      );
+      obsRef.current.observe(el);
+    },
+    [rootMargin, skip]
+  );
+  useEffect3(() => {
+    return () => obsRef.current?.disconnect();
+  }, []);
+  return [setRef, inView];
+}
+function buildSrcset(set, tiers) {
+  if (!set) return void 0;
+  const entries = [];
+  for (const key of tiers) {
+    const tier = set[key];
+    if (tier?.url && tier.width) entries.push(`${tier.url} ${tier.width}w`);
+  }
+  return entries.length > 0 ? entries.join(", ") : void 0;
+}
+function pickFallbackSrc(set) {
+  if (!set) return void 0;
+  return set.large?.url ?? set.medium?.url ?? set.xlarge?.url ?? set.small?.url ?? set.thumbnail?.url ?? void 0;
+}
+function ProgressiveMedia({
+  image,
+  video,
+  alt,
+  className,
+  fill,
+  fit = "cover",
+  placeholder,
+  autoplay = true,
+  muted = true,
+  loop = true,
+  active = true,
+  sizes = "100vw",
+  priority = false,
+  variantTiers = DEFAULT_VARIANT_TIERS
+}) {
+  const fitClass = fit === "contain" ? "object-contain" : "object-cover";
+  const videoRef = useRef2(null);
+  const hlsRef = useRef2(null);
+  const cleanupRef = useRef2(null);
+  const source = video ?? image;
+  const isVideo = !!video;
+  const [wrapperRef, inViewport] = useInViewport("300px", priority);
+  const videoActive = isVideo && active && (priority || inViewport);
+  const imageActive = !isVideo && active;
+  const hlsUrl = video?.hlsUrl;
+  const useHls = isVideo && !!hlsUrl;
+  const fullUrl = isVideo ? video?.url : pickFallbackSrc(image?.webp) ?? image?.url;
+  const avifSrcSet = !isVideo ? buildSrcset(image?.avif, variantTiers) : void 0;
+  const webpSrcSet = !isVideo ? buildSrcset(image?.webp, variantTiers) : void 0;
+  const srcSet = webpSrcSet;
+  const thumbnailUrl = source?.thumbnailUrl;
+  const blurhash = source?.blurhash;
+  const dominantColor = source?.dominantColor;
+  const { stage, onFullReady } = useProgressiveLoad({
+    blurhash,
+    thumbnailUrl,
+    // Skip the full-image preloader when this branch is inactive — the
+    // dual-render responsive pattern mounts both variants but only one should
+    // download its full asset.
+    fullUrl: imageActive ? fullUrl : void 0,
+    fullSrcSet: imageActive ? srcSet : void 0,
+    fullSizes: imageActive && srcSet ? sizes : void 0,
+    isVideo
+  });
+  useEffect3(() => {
+    if (!videoActive || !useHls || !videoRef.current) return;
+    const el = videoRef.current;
+    if (el.canPlayType("application/vnd.apple.mpegurl")) {
+      el.src = hlsUrl;
+      return;
+    }
+    let hls;
+    import("hls.js").then((mod) => {
+      const Hls = mod.default;
+      if (!Hls.isSupported()) {
+        if (video?.url) el.src = video.url;
+        return;
+      }
+      hls = new Hls({ capLevelToPlayerSize: true });
+      hlsRef.current = hls;
+      hls.loadSource(hlsUrl);
+      hls.attachMedia(el);
+    }).catch(() => {
+      if (video?.url) el.src = video.url;
+    });
+    return () => {
+      if (hls) {
+        hls.destroy();
+        hlsRef.current = null;
+      }
+    };
+  }, [videoActive, useHls, hlsUrl, video?.url]);
+  const videoCallbackRef = useCallback2(
+    (el) => {
+      if (cleanupRef.current) {
+        cleanupRef.current();
+        cleanupRef.current = null;
+      }
+      videoRef.current = el;
+      if (!el) return;
+      if (el.readyState >= 3) {
+        onFullReady();
+        return;
+      }
+      const handler = () => {
+        onFullReady();
+        el.removeEventListener("canplay", handler);
+        el.removeEventListener("playing", handler);
+      };
+      el.addEventListener("canplay", handler);
+      el.addEventListener("playing", handler);
+      cleanupRef.current = () => {
+        el.removeEventListener("canplay", handler);
+        el.removeEventListener("playing", handler);
+      };
+    },
+    [onFullReady]
+  );
+  if (!source) {
+    if (!placeholder) return null;
+    const aspect2 = placeholder.aspectRatio ?? 16 / 10;
+    return /* @__PURE__ */ jsx2(
+      "div",
+      {
+        className: `relative overflow-hidden ${fill ? "h-full w-full" : ""} ${className ?? ""}`,
+        style: fill ? { backgroundColor: placeholder.color } : { aspectRatio: `${aspect2}`, backgroundColor: placeholder.color },
+        "aria-label": alt
+      }
+    );
+  }
+  const effective = !isVideo ? effectiveImageDimensions(image) : null;
+  const w = effective?.width ?? source.width;
+  const h = effective?.height ?? source.height;
+  const aspect = w && h ? w / h : 16 / 10;
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      ref: wrapperRef,
+      className: `relative overflow-hidden ${fill ? "h-full w-full" : ""} ${className ?? ""}`,
+      style: fill ? void 0 : { aspectRatio: `${aspect}` },
+      children: [
+        dominantColor && /* @__PURE__ */ jsx2(
+          "div",
+          {
+            className: "absolute inset-0",
+            style: { backgroundColor: dominantColor }
+          }
+        ),
+        blurhash && /* @__PURE__ */ jsx2(
+          "div",
+          {
+            className: `absolute inset-0 transition-opacity duration-300 ease-in-out ${stage === "color" ? "opacity-0" : "opacity-100"}`,
+            children: /* @__PURE__ */ jsx2(BlurhashCanvas, { hash: blurhash })
+          }
+        ),
+        thumbnailUrl && /* @__PURE__ */ jsx2(
+          "img",
+          {
+            src: thumbnailUrl,
+            alt: "",
+            "aria-hidden": true,
+            width: w,
+            height: h,
+            loading: priority ? "eager" : "lazy",
+            fetchPriority: priority ? "high" : void 0,
+            className: `absolute inset-0 h-full w-full ${fitClass} transition-opacity duration-400 ease-in-out ${stage === "thumbnail" || stage === "full" ? "opacity-100" : "opacity-0"}`
+          }
+        ),
+        videoActive ? /* @__PURE__ */ jsx2(
+          "video",
+          {
+            ref: videoCallbackRef,
+            src: useHls ? void 0 : fullUrl,
+            poster: thumbnailUrl,
+            width: w,
+            height: h,
+            autoPlay: autoplay,
+            muted,
+            loop,
+            playsInline: true,
+            controls: !autoplay,
+            className: `absolute inset-0 h-full w-full ${fitClass} transition-opacity duration-500 ease-in-out ${stage === "full" ? "opacity-100" : "opacity-0"}`
+          }
+        ) : imageActive ? (
+          // <picture>: browser picks AVIF when it can decode it, else WebP. The
+          // <img> (WebP) is the universal fallback and carries the layout attrs.
+          /* @__PURE__ */ jsxs("picture", { children: [
+            avifSrcSet ? /* @__PURE__ */ jsx2("source", { type: "image/avif", srcSet: avifSrcSet, sizes }) : null,
+            webpSrcSet ? /* @__PURE__ */ jsx2("source", { type: "image/webp", srcSet: webpSrcSet, sizes }) : null,
+            /* @__PURE__ */ jsx2(
+              "img",
+              {
+                src: fullUrl,
+                srcSet,
+                sizes: srcSet ? sizes : void 0,
+                alt: alt ?? image?.alt ?? "",
+                width: w,
+                height: h,
+                loading: priority ? "eager" : "lazy",
+                fetchPriority: priority ? "high" : void 0,
+                className: `absolute inset-0 h-full w-full ${fitClass} transition-opacity duration-500 ease-in-out ${stage === "full" ? "opacity-100" : "opacity-0"}`
+              }
+            )
+          ] })
+        ) : null
+      ]
+    }
+  );
+}
+export {
+  BlurhashCanvas,
+  DEFAULT_VARIANT_TIERS,
+  ProgressiveMedia,
+  cropAspectRatio,
+  effectiveImageDimensions,
+  toProgressiveImage,
+  toProgressiveVideo,
+  useProgressiveLoad
+};

package/dist/realtime.d.ts

@@ -0,0 +1,111 @@
+import * as Y from 'yjs';
+import { WebsocketProvider } from 'y-websocket';
+
+/**
+ * @foir/sdk/realtime — optional thin web helper over y-websocket (EID-103).
+ *
+ * The apollo-link analogue for Foir realtime collaboration: sugar over the
+ * off-the-shelf `y-websocket` provider that adds exactly the wire-protocol
+ * contract conventions — explicit URL, canonical `{namespace}/{roomId}` path,
+ * presence payload shape — plus the one thing `y-websocket` lacks out of the
+ * box: token refresh that the next reconnect picks up. Tokens are ~5-min-lived
+ * and the gateway re-validates on every upgrade (a live socket survives past
+ * TTL; the token only matters at (re)connect), so "refresh" means keeping the
+ * provider's url params current for whenever it next reconnects.
+ *
+ * Agnostic by design: token-agnostic (caller supplies `getToken` — an internal
+ * mint for admin, a customer access token for an app), persistence-agnostic
+ * (never persists), doc-schema-agnostic (caller owns the `Y.Doc` + shared types).
+ *
+ * `yjs` + `y-websocket` are OPTIONAL peer deps gated to this subpath, so a
+ * consumer importing only other `@foir/sdk/*` exports pulls no Yjs.
+ *
+ * Wire-protocol contract: `docs/realtime-collab-contract.md` (EID-117).
+ */
+
+type Awareness = WebsocketProvider['awareness'];
+interface RoomAddress {
+    /** Room-type selector — e.g. `record`, `ephemeral`, `tilly_note`. */
+    namespace: string;
+    /** Namespace-specific id. For `record`: `{modelKey}:{recordId}:{variantId}`. */
+    id: string;
+}
+interface CollabPresence {
+    id: string;
+    name: string;
+    /** Stable per-user colour; derived deterministically from `id` when omitted. */
+    color?: string;
+    [key: string]: unknown;
+}
+interface CollabPeer {
+    /** The remote peer's y-awareness client id. */
+    clientId: number;
+    id: string;
+    name: string;
+    color?: string;
+    [key: string]: unknown;
+}
+interface CreateCollabSessionOptions {
+    /** Explicit realtime origin, e.g. `wss://realtime.foir.io`. Never derived from the API host. */
+    url: string;
+    /** Room address; built into the canonical bare `{namespace}/{id}` path. A raw string path is also accepted. */
+    room: RoomAddress | string;
+    /** Async token source. Invoked before the first connect and on each refresh tick. */
+    getToken: () => string | Promise<string>;
+    /** Caller-owned `Y.Doc` carrying the app-defined shared types. */
+    doc: Y.Doc;
+    /** Local presence. Sets awareness under the `user` field (contract shape). Omit for no presence. */
+    presence?: CollabPresence;
+    /** Token refresh cadence (ms). Default `240_000` (4 min; tokens are ~5-min TTL). `0` disables. */
+    refreshMs?: number;
+    /** Connect immediately once the first token resolves (default `true`). */
+    connect?: boolean;
+    /** Extra y-websocket url params, merged with `token`. */
+    params?: Record<string, string>;
+    /** WebSocket implementation for non-browser runtimes. */
+    WebSocketPolyfill?: typeof WebSocket;
+}
+type CollabEventMap = {
+    /** Connection status flipped. */
+    status: {
+        connected: boolean;
+    };
+    /** Initial (or post-reconnect) Yjs sync completed (`true`) or lost (`false`). */
+    synced: boolean;
+    /** Remote peer set changed (always excludes the local client). */
+    'presence-changed': Array<CollabPeer>;
+    /** A `getToken()` (or other internal) error surfaced. */
+    error: unknown;
+};
+interface CollabSession {
+    /** The underlying y-websocket provider (escape hatch). */
+    readonly provider: WebsocketProvider;
+    /** The y-awareness instance (escape hatch). */
+    readonly awareness: Awareness;
+    /** The caller's `Y.Doc`. */
+    readonly doc: Y.Doc;
+    /** Canonical room path actually used (`{namespace}/{id}`). */
+    readonly room: string;
+    readonly connected: boolean;
+    readonly synced: boolean;
+    /** Current remote peers (excludes self). */
+    readonly peers: Array<CollabPeer>;
+    on<E extends keyof CollabEventMap>(event: E, handler: (data: CollabEventMap[E]) => void): () => void;
+    /** Manually push a fresh token, used by the next reconnect. Refresh is automatic; rarely needed. */
+    updateToken(token: string): void;
+    /** Update or clear local presence. */
+    setPresence(presence: CollabPresence | null): void;
+    /** Disconnect, stop refresh, tear down awareness. Does NOT destroy the caller's doc. */
+    destroy(): void;
+}
+/** Deterministic per-id presence colour (stable across sessions and clients). */
+declare function colorForId(id: string): string;
+/** Build the canonical bare `{namespace}/{id}` room path (contract §2). */
+declare function roomPath(room: RoomAddress | string): string;
+/**
+ * Create a collaboration session: a wrapped `y-websocket` provider that conforms
+ * to the Foir realtime contract and keeps its auth token fresh for reconnects.
+ */
+declare function createCollabSession(options: CreateCollabSessionOptions): CollabSession;
+
+export { type CollabEventMap, type CollabPeer, type CollabPresence, type CollabSession, type CreateCollabSessionOptions, type RoomAddress, colorForId, createCollabSession, roomPath };

package/dist/realtime.js

@@ -0,0 +1,168 @@
+// src/realtime/index.ts
+import { WebsocketProvider } from "y-websocket";
+var PRESENCE_COLORS = [
+  "#ef4444",
+  "#f97316",
+  "#eab308",
+  "#22c55e",
+  "#14b8a6",
+  "#3b82f6",
+  "#8b5cf6",
+  "#ec4899"
+];
+function colorForId(id) {
+  let hash = 0;
+  for (let i = 0; i < id.length; i++) {
+    hash = id.charCodeAt(i) + ((hash << 5) - hash);
+  }
+  return PRESENCE_COLORS[Math.abs(hash) % PRESENCE_COLORS.length];
+}
+function roomPath(room) {
+  if (typeof room === "string") {
+    const p = room.replace(/^\/+/, "");
+    if (!p) throw new Error("createCollabSession: room path is empty");
+    return p;
+  }
+  const namespace = room.namespace?.trim();
+  const id = room.id?.trim();
+  if (!namespace || !id) {
+    throw new Error("createCollabSession: room.namespace and room.id are required");
+  }
+  return `${namespace}/${id}`;
+}
+function createCollabSession(options) {
+  const {
+    url,
+    doc,
+    getToken,
+    presence,
+    refreshMs = 4 * 60 * 1e3,
+    connect = true,
+    params: extraParams,
+    WebSocketPolyfill
+  } = options;
+  const room = roomPath(options.room);
+  const provider = new WebsocketProvider(url, room, doc, {
+    connect: false,
+    params: { ...extraParams },
+    ...WebSocketPolyfill ? { WebSocketPolyfill } : {}
+  });
+  const awareness = provider.awareness;
+  const listeners = /* @__PURE__ */ new Map();
+  function on(event, handler) {
+    let set = listeners.get(event);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      listeners.set(event, set);
+    }
+    set.add(handler);
+    return () => {
+      listeners.get(event)?.delete(handler);
+    };
+  }
+  function emit(event, data) {
+    for (const handler of listeners.get(event) ?? []) {
+      try {
+        handler(data);
+      } catch {
+      }
+    }
+  }
+  let connected = false;
+  let synced = false;
+  let peers = [];
+  let destroyed = false;
+  let refreshTimer = null;
+  const onStatus = (event) => {
+    const now = event.status === "connected";
+    if (now === connected) return;
+    connected = now;
+    emit("status", { connected });
+  };
+  const onSync = (state) => {
+    synced = state;
+    emit("synced", state);
+  };
+  provider.on("status", onStatus);
+  provider.on("sync", onSync);
+  function readPeers() {
+    const next = [];
+    awareness.getStates().forEach((state, clientId) => {
+      if (clientId === awareness.clientID) return;
+      const user = state["user"];
+      if (user && typeof user.id === "string") {
+        next.push({ clientId, id: user.id, name: user.name, color: user.color });
+      }
+    });
+    peers = next;
+    emit("presence-changed", peers);
+  }
+  const onAwarenessChange = () => readPeers();
+  awareness.on("change", onAwarenessChange);
+  function setPresence(next) {
+    if (!next) {
+      awareness.setLocalState(null);
+      return;
+    }
+    awareness.setLocalStateField("user", {
+      ...next,
+      color: next.color ?? colorForId(next.id)
+    });
+  }
+  if (presence) setPresence(presence);
+  function updateToken(token) {
+    provider.params = { ...provider.params, token };
+  }
+  async function refreshToken() {
+    try {
+      updateToken(await getToken());
+    } catch (err) {
+      emit("error", err);
+    }
+  }
+  void (async () => {
+    await refreshToken();
+    if (destroyed) return;
+    if (connect) provider.connect();
+    if (refreshMs > 0) {
+      refreshTimer = setInterval(() => {
+        void refreshToken();
+      }, refreshMs);
+    }
+  })();
+  function destroy() {
+    if (destroyed) return;
+    destroyed = true;
+    if (refreshTimer) clearInterval(refreshTimer);
+    refreshTimer = null;
+    provider.off("status", onStatus);
+    provider.off("sync", onSync);
+    awareness.off("change", onAwarenessChange);
+    listeners.clear();
+    provider.destroy();
+  }
+  return {
+    provider,
+    awareness,
+    doc,
+    room,
+    get connected() {
+      return connected;
+    },
+    get synced() {
+      return synced;
+    },
+    get peers() {
+      return peers;
+    },
+    on,
+    updateToken,
+    setPresence,
+    destroy
+  };
+}
+export {
+  colorForId,
+  createCollabSession,
+  roomPath
+};