@omg-dev/sdk 0.4.24

package/src/notifications/index.tsx

@@ -0,0 +1,179 @@
+import { useCallback, useMemo, useState } from "react"
+import { useQuery, type SubscribePredicate } from "../index"
+import { getAuthContext, notifyAuthRequired } from "../auth/bridge"
+
+export interface VibesNotification {
+  id: string
+  appId: string
+  userId: string
+  kind: string
+  title: string
+  body: string
+  url: string
+  status: "unread" | "read" | "archived"
+  priority: "low" | "normal" | "high"
+  sourceType: string
+  sourceId: string
+  dedupeKey: string
+  dataJson: string
+  readAt: number
+  createdAt: number
+}
+
+function authHeaders(extra?: HeadersInit): Headers {
+  const h = new Headers(extra)
+  const { token } = getAuthContext()
+  if (token) h.set("Authorization", `Bearer ${token}`)
+  return h
+}
+
+async function notificationFetch(input: string, init?: RequestInit): Promise<Response> {
+  const res = await fetch(input, { ...init, headers: authHeaders(init?.headers) })
+  if (res.status === 401) {
+    if (getAuthContext().authReady) notifyAuthRequired()
+    throw new Error("Authentication required")
+  }
+  if (!res.ok) {
+    let msg = `request failed (${res.status})`
+    try {
+      const body = await res.clone().json()
+      if (body && typeof body.error === "string") msg = body.error
+    } catch {}
+    throw new Error(msg)
+  }
+  return res
+}
+
+function base64UrlToUint8Array(value: string): Uint8Array {
+  const padded = `${value}${"=".repeat((4 - (value.length % 4)) % 4)}`
+  const base64 = padded.replace(/-/g, "+").replace(/_/g, "/")
+  const raw = atob(base64)
+  const out = new Uint8Array(raw.length)
+  for (let i = 0; i < raw.length; i++) out[i] = raw.charCodeAt(i)
+  return out
+}
+
+export function notificationSupport() {
+  if (typeof window === "undefined" || typeof navigator === "undefined") {
+    return { supported: false, permission: "default" as NotificationPermission }
+  }
+  const supported =
+    "Notification" in window &&
+    "serviceWorker" in navigator &&
+    "PushManager" in window
+  return {
+    supported,
+    permission: supported ? Notification.permission : "default" as NotificationPermission,
+  }
+}
+
+export function useNotificationPermission() {
+  const initial = notificationSupport()
+  const [permission, setPermission] = useState<NotificationPermission>(initial.permission)
+  const [busy, setBusy] = useState(false)
+  const supported = initial.supported
+
+  const enablePush = useCallback(async (): Promise<boolean> => {
+    if (!supported) return false
+    setBusy(true)
+    try {
+      const configRes = await notificationFetch("/api/_notifications/config")
+      const config = await configRes.json() as { vapidPublicKey?: string }
+      if (!config.vapidPublicKey) return false
+
+      const nextPermission =
+        Notification.permission === "default"
+          ? await Notification.requestPermission()
+          : Notification.permission
+      setPermission(nextPermission)
+      if (nextPermission !== "granted") return false
+
+      const registration = await navigator.serviceWorker.register("/__vibes_push/sw.js", {
+        scope: "/__vibes_push/",
+      })
+      const existing = await registration.pushManager.getSubscription()
+      const subscription = existing ?? await registration.pushManager.subscribe({
+        userVisibleOnly: true,
+        applicationServerKey: base64UrlToUint8Array(config.vapidPublicKey),
+      })
+      await notificationFetch("/api/_notifications/subscribe", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ subscription: subscription.toJSON() }),
+      })
+      return true
+    } finally {
+      setBusy(false)
+    }
+  }, [supported])
+
+  return { supported, permission, busy, enablePush }
+}
+
+export function useNotifications(options?: { unreadOnly?: boolean }) {
+  const where = useMemo<SubscribePredicate | undefined>(() => {
+    if (!options?.unreadOnly) return undefined
+    return { op: "eq", column: "status", value: "unread" }
+  }, [options?.unreadOnly])
+
+  const query = useQuery<VibesNotification>({
+    collection: "vibesNotifications",
+    api: options?.unreadOnly ? "/api/_notifications/list?unread=1" : "/api/_notifications/list",
+    where,
+  })
+
+  const notifications = useMemo(
+    () => [...query.data].sort((a, b) => b.createdAt - a.createdAt),
+    [query.data],
+  )
+  const unreadCount = useMemo(
+    () => notifications.reduce((n, item) => n + (item.status === "unread" ? 1 : 0), 0),
+    [notifications],
+  )
+
+  const markRead = useCallback(async (ids: string[]) => {
+    if (ids.length === 0) return
+    await notificationFetch("/api/_notifications/read", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ ids }),
+    })
+    query.refresh()
+  }, [query])
+
+  const markAllRead = useCallback(async () => {
+    await notificationFetch("/api/_notifications/read", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ all: true }),
+    })
+    query.refresh()
+  }, [query])
+
+  return {
+    ...query,
+    notifications,
+    unreadCount,
+    markRead,
+    markAllRead,
+  }
+}
+
+export async function createNotification(input: {
+  kind?: string
+  title: string
+  body?: string
+  url?: string
+  priority?: "low" | "normal" | "high"
+  sourceType?: string
+  sourceId?: string
+  dedupeKey?: string
+  data?: Record<string, unknown>
+}) {
+  const res = await notificationFetch("/api/_notifications/create", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(input),
+  })
+  return res.json() as Promise<VibesNotification | null>
+}

package/src/sandbox.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from "vitest";
+import { createSandbox, forkSandbox, runtimeClaims } from "./sandbox";
+
+describe("sandbox SDK", () => {
+  it("posts create requests to the sandbox router", async () => {
+    const calls: Array<{ url: string; body: unknown }> = [];
+    const fetchImpl = async (url: string, init?: RequestInit) => {
+      calls.push({ url, body: JSON.parse(String(init?.body)) });
+      return new Response(JSON.stringify({ id: "child-sb" }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      });
+    };
+
+    const got = await createSandbox(
+      { ports: [5173], runtimeClaims: [runtimeClaims.llmInvoke] },
+      {
+        routerBase: "http://agent.test/_sandbox",
+        fetch: fetchImpl as typeof fetch,
+      },
+    );
+
+    expect(got.id).toBe("child-sb");
+    expect(calls).toEqual([
+      {
+        url: "http://agent.test/_sandbox/create",
+        body: { ports: [5173], runtimeClaims: ["llm.invoke"] },
+      },
+    ]);
+  });
+
+  it("requires snapshotId before posting fork requests", () => {
+    expect(() =>
+      forkSandbox(
+        { snapshotId: "" },
+        { fetch: (() => Promise.reject(new Error("unused"))) as typeof fetch },
+      ),
+    ).toThrow("snapshotId");
+  });
+
+  it("surfaces router JSON errors", async () => {
+    const fetchImpl = async () =>
+      new Response(
+        JSON.stringify({ error: "parent sandbox cannot create sandboxes" }),
+        {
+          status: 403,
+          headers: { "content-type": "application/json" },
+        },
+      );
+
+    await expect(
+      createSandbox(
+        {},
+        {
+          routerBase: "http://agent.test/_sandbox",
+          fetch: fetchImpl as typeof fetch,
+        },
+      ),
+    ).rejects.toThrow("parent sandbox cannot create sandboxes");
+  });
+});

package/src/sandbox.ts

@@ -0,0 +1,106 @@
+export const runtimeClaims = {
+  llmInvoke: "llm.invoke",
+  mediaInvoke: "media.invoke",
+  browserUse: "browser.use",
+  sandboxCreate: "sandbox.create",
+  sandboxDelegate: "sandbox.delegate",
+} as const;
+
+export type RuntimeClaim = (typeof runtimeClaims)[keyof typeof runtimeClaims];
+
+export interface SandboxInfo {
+  id: string;
+  status?: string;
+  url?: string;
+  ports?: Record<string, number>;
+  [key: string]: unknown;
+}
+
+export interface CreateSandboxOptions {
+  ports?: number[];
+  templateId?: string;
+  runtimeClaims?: RuntimeClaim[];
+  agentServerSource?: string;
+  skipAppProcesses?: boolean;
+  agentBootstrap?: unknown;
+  sessionId?: string;
+  preferredModel?: string;
+}
+
+export interface ForkSandboxOptions {
+  snapshotId: string;
+  ports?: number[];
+  runtimeClaims?: RuntimeClaim[];
+  agentServerSource?: string;
+  sessionId?: string;
+  preferredModel?: string;
+}
+
+export interface SandboxRouterOptions {
+  /**
+   * Override for tests or custom runtimes. In a Vibes sandbox this defaults to
+   * the local in-VM agent router at http://localhost:8080/_sandbox.
+   */
+  routerBase?: string;
+  fetch?: typeof fetch;
+}
+
+function defaultSandboxRouterBase(): string {
+  const envBase =
+    typeof process !== "undefined"
+      ? process.env?.VIBES_SANDBOX_ROUTER_URL || process.env?.VIBES_AGENT_URL
+      : undefined;
+  if (envBase) return envBase.replace(/\/$/, "");
+  if (typeof window !== "undefined") {
+    throw new Error(
+      "sandbox SDK calls must run in a server function inside a Vibes sandbox",
+    );
+  }
+  return "http://localhost:8080/_sandbox";
+}
+
+async function postSandboxRouter<T>(
+  path: string,
+  body: unknown,
+  opts: SandboxRouterOptions = {},
+): Promise<T> {
+  const fetchImpl = opts.fetch ?? fetch;
+  const base = (opts.routerBase ?? defaultSandboxRouterBase()).replace(
+    /\/$/,
+    "",
+  );
+  const res = await fetchImpl(`${base}${path}`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body ?? {}),
+  });
+  if (!res.ok) {
+    let message = `sandbox router ${res.status}`;
+    try {
+      const parsed = await res.clone().json();
+      if (parsed && typeof parsed.error === "string") message = parsed.error;
+    } catch {
+      const text = await res.text().catch(() => "");
+      if (text) message = text;
+    }
+    throw new Error(message);
+  }
+  return res.json();
+}
+
+export function createSandbox(
+  options: CreateSandboxOptions = {},
+  routerOptions?: SandboxRouterOptions,
+): Promise<SandboxInfo> {
+  return postSandboxRouter<SandboxInfo>("/create", options, routerOptions);
+}
+
+export function forkSandbox(
+  options: ForkSandboxOptions,
+  routerOptions?: SandboxRouterOptions,
+): Promise<SandboxInfo> {
+  if (!options?.snapshotId) {
+    throw new Error("forkSandbox requires snapshotId");
+  }
+  return postSandboxRouter<SandboxInfo>("/fork", options, routerOptions);
+}

package/src/storage/VibesUpload.tsx

@@ -0,0 +1,140 @@
+import { useRef, useState, useId, useCallback, type CSSProperties, type DragEvent, type ChangeEvent } from "react"
+import { useUpload, type UploadOptions, type UploadResult } from "./useUpload"
+
+export interface VibesUploadProps {
+  /**
+   * Accept attribute for the file input (e.g. "image/*"). Mirrored on the
+   * drop-zone so the browser shows a no-drop cursor for the wrong type.
+   */
+  accept?: string
+  /**
+   * Function that picks a key for the uploaded file. Defaults to
+   * `uploads/<crypto.randomUUID>-<filename>`.
+   */
+  keyFor?: (file: File) => string
+  /** "user" (default) or "app". */
+  scope?: "user" | "app"
+  /** Fired after a successful upload. Use this to write the file's key into a DB row. */
+  onUploaded?: (result: UploadResult, file: File) => void
+  /** Fired when an upload fails. */
+  onError?: (error: Error) => void
+  /** Label rendered inside the drop zone. Defaults to "Upload" / drag instructions. */
+  label?: string
+  /** Disable the picker. */
+  disabled?: boolean
+  /** Style overrides. The component ships unopinionated, hostable styles. */
+  style?: CSSProperties
+  className?: string
+  /** Override the presign endpoint (defaults to /api/_storage/presign). */
+  presignUrl?: string
+}
+
+function defaultKeyFor(file: File): string {
+  const safe = file.name.replace(/[^a-zA-Z0-9._-]/g, "-")
+  const id = typeof crypto !== "undefined" && "randomUUID" in crypto ? crypto.randomUUID() : Math.random().toString(36).slice(2)
+  return `uploads/${id}-${safe}`
+}
+
+/**
+ * Drop-zone + file picker. Calls onUploaded with the stored key + signed
+ * download URL on success. Renders nothing during prerender (SSR) — the
+ * hook depends on browser-only APIs (XHR, FormData).
+ */
+export function VibesUpload(props: VibesUploadProps): JSX.Element {
+  const { upload, uploading, progress, error } = useUpload()
+  const [dragOver, setDragOver] = useState(false)
+  const inputRef = useRef<HTMLInputElement>(null)
+  const inputId = useId()
+
+  const handleFiles = useCallback(async (files: FileList | File[]) => {
+    const list = Array.from(files)
+    for (const file of list) {
+      const opts: UploadOptions = {
+        key: (props.keyFor ?? defaultKeyFor)(file),
+        contentType: file.type || "application/octet-stream",
+        scope: props.scope ?? "user",
+        presignUrl: props.presignUrl,
+      }
+      try {
+        const result = await upload(file, opts)
+        props.onUploaded?.(result, file)
+      } catch (err) {
+        props.onError?.(err as Error)
+      }
+    }
+  }, [props, upload])
+
+  const onChange = useCallback((e: ChangeEvent<HTMLInputElement>) => {
+    if (e.target.files && e.target.files.length > 0) {
+      void handleFiles(e.target.files)
+      e.target.value = "" // reset so re-selecting the same file fires onChange again
+    }
+  }, [handleFiles])
+
+  const onDrop = useCallback((e: DragEvent<HTMLDivElement>) => {
+    e.preventDefault()
+    setDragOver(false)
+    if (e.dataTransfer.files && e.dataTransfer.files.length > 0) {
+      void handleFiles(e.dataTransfer.files)
+    }
+  }, [handleFiles])
+
+  const onDragOver = useCallback((e: DragEvent<HTMLDivElement>) => {
+    e.preventDefault()
+    if (!dragOver) setDragOver(true)
+  }, [dragOver])
+
+  const onDragLeave = useCallback(() => setDragOver(false), [])
+
+  const baseStyle: CSSProperties = {
+    border: `1px dashed ${dragOver ? "#2563eb" : "rgba(0,0,0,0.18)"}`,
+    background: dragOver ? "rgba(37, 99, 235, 0.05)" : "transparent",
+    borderRadius: 10,
+    padding: "16px 18px",
+    display: "flex",
+    flexDirection: "column",
+    gap: 6,
+    alignItems: "center",
+    justifyContent: "center",
+    cursor: props.disabled ? "not-allowed" : "pointer",
+    opacity: props.disabled ? 0.5 : 1,
+    fontSize: 14,
+    color: "rgba(0,0,0,0.7)",
+    minHeight: 88,
+    userSelect: "none",
+    transition: "border-color 80ms ease, background 80ms ease",
+    ...props.style,
+  }
+
+  return (
+    <label htmlFor={inputId} style={baseStyle} className={props.className}
+           onDrop={onDrop} onDragOver={onDragOver} onDragLeave={onDragLeave}
+           data-uploading={uploading || undefined}>
+      <input
+        ref={inputRef}
+        id={inputId}
+        type="file"
+        accept={props.accept}
+        onChange={onChange}
+        disabled={props.disabled || uploading}
+        style={{ display: "none" }}
+      />
+      {uploading ? (
+        <>
+          <span>Uploading…</span>
+          <span style={{ fontSize: 12, opacity: 0.6 }}>{Math.round(progress * 100)}%</span>
+        </>
+      ) : error ? (
+        <>
+          <span style={{ color: "#dc2626" }}>Upload failed</span>
+          <span style={{ fontSize: 12, opacity: 0.7 }}>{error}</span>
+        </>
+      ) : (
+        <>
+          <span>{props.label ?? "Drop file or click to upload"}</span>
+          <span style={{ fontSize: 12, opacity: 0.55 }}>{props.accept ?? "any file"} · up to 25MB</span>
+        </>
+      )}
+    </label>
+  )
+}

package/src/storage/index.ts

@@ -0,0 +1,12 @@
+// @omg-dev/sdk storage — client-side hook + component for uploading files to a
+// vibes app. Pairs with @omg-dev/server's `storage` API on the server.
+//
+// Auth model: every call (presign + actual PUT) carries the user's bearer
+// token from the auth bridge. Files default to scope:"user" — the server-side
+// presign endpoint scopes the storage key to the authed user's id, so a
+// browser without a logged-in user gets a 401 from the presign route.
+
+export { useUpload } from "./useUpload"
+export type { UploadOptions, UploadResult, UploadState } from "./useUpload"
+export { VibesUpload } from "./VibesUpload"
+export type { VibesUploadProps } from "./VibesUpload"

package/src/storage/useUpload.ts

@@ -0,0 +1,167 @@
+import { useCallback, useState } from "react"
+import { getAuthContext, notifyAuthRequired } from "../auth/bridge"
+
+export interface UploadOptions {
+  /** Object key (e.g. "avatar.png", "uploads/photo.jpg"). */
+  key: string
+  /** Content-Type for the PUT. Auto-detected from File when omitted. */
+  contentType?: string
+  /** "user" (default) or "app". */
+  scope?: "user" | "app"
+  /**
+   * Endpoint that mints the presigned URL. Defaults to "/api/_storage/presign",
+   * which the vibes vite-plugin auto-injects. Pass a custom path if you wrote
+   * your own functions/_storage.ts handler.
+   */
+  presignUrl?: string
+  /** Optional callback for progress (0..1) during the PUT. */
+  onProgress?: (fraction: number) => void
+}
+
+export interface UploadResult {
+  /** Public-ish key returned by the server — store this on the row that references the file. */
+  key: string
+  /** Pre-signed download URL valid for an hour. Use to render a preview. */
+  downloadUrl: string
+  size: number
+  contentType: string
+}
+
+export interface UploadState {
+  uploading: boolean
+  progress: number
+  error: string | null
+  result: UploadResult | null
+}
+
+function bearerHeaders(): Record<string, string> {
+  const { token } = getAuthContext()
+  return token ? { Authorization: `Bearer ${token}` } : {}
+}
+
+/**
+ * Headless upload hook. Returns the upload function plus state.
+ *
+ * Usage:
+ *   const { upload, uploading, progress, error } = useUpload()
+ *   await upload(file, { key: `avatars/${user.id}.png` })
+ */
+export function useUpload(): UploadState & {
+  upload: (file: File | Blob, opts: UploadOptions) => Promise<UploadResult>
+  reset: () => void
+} {
+  const [state, setState] = useState<UploadState>({
+    uploading: false,
+    progress: 0,
+    error: null,
+    result: null,
+  })
+
+  const reset = useCallback(() => {
+    setState({ uploading: false, progress: 0, error: null, result: null })
+  }, [])
+
+  const upload = useCallback(async (file: File | Blob, opts: UploadOptions): Promise<UploadResult> => {
+    setState({ uploading: true, progress: 0, error: null, result: null })
+    const presignUrl = opts.presignUrl ?? "/api/_storage/presign"
+    const contentType = opts.contentType ?? (file as File).type ?? "application/octet-stream"
+
+    try {
+      const presignRes = await fetch(presignUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", ...bearerHeaders() },
+        body: JSON.stringify({
+          action: "put",
+          key: opts.key,
+          contentType,
+          scope: opts.scope ?? "user",
+        }),
+      })
+      if (!presignRes.ok) {
+        if (presignRes.status === 401 && getAuthContext().authReady) notifyAuthRequired()
+        const text = await presignRes.text().catch(() => "")
+        throw new Error(`presign ${presignRes.status}: ${text.slice(0, 200)}`)
+      }
+      const { url, key: storedKey, maxBytes } = (await presignRes.json()) as {
+        url: string
+        key: string
+        maxBytes?: number
+      }
+      if (typeof maxBytes === "number" && file.size > maxBytes) {
+        throw new Error(`file too large (${file.size} > ${maxBytes} bytes)`)
+      }
+
+      // PUT with progress via XHR — fetch() doesn't expose request-side progress.
+      await new Promise<void>((resolve, reject) => {
+        const xhr = new XMLHttpRequest()
+        xhr.open("PUT", url)
+        xhr.setRequestHeader("Content-Type", contentType)
+        xhr.upload.onprogress = (e) => {
+          if (e.lengthComputable) {
+            const frac = e.loaded / e.total
+            setState(s => ({ ...s, progress: frac }))
+            opts.onProgress?.(frac)
+          }
+        }
+        xhr.onload = () => {
+          if (xhr.status >= 200 && xhr.status < 300) {
+            resolve()
+          } else {
+            reject(new Error(`PUT ${xhr.status}: ${xhr.responseText.slice(0, 200)}`))
+          }
+        }
+        xhr.onerror = () => reject(new Error("network error during upload"))
+        xhr.send(file)
+      })
+
+      // Resolve a download URL so the caller can immediately render the new file.
+      const dlRes = await fetch(presignUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", ...bearerHeaders() },
+        body: JSON.stringify({
+          action: "get",
+          key: opts.key,
+          scope: opts.scope ?? "user",
+        }),
+      })
+      let downloadUrl = ""
+      if (dlRes.ok) {
+        const dl = (await dlRes.json()) as { url?: string }
+        downloadUrl = dl.url ?? ""
+      }
+
+      // Fire-and-forget: tell the app server the upload landed so any
+      // `storage.onUpload(...)` handler in functions/*.ts gets invoked.
+      // Failure here doesn't block the upload — the file already exists
+      // in Tigris, the hook just won't fire.
+      void fetch(presignUrl.replace(/\/presign$/, "/notify"), {
+        method: "POST",
+        headers: { "Content-Type": "application/json", ...bearerHeaders() },
+        body: JSON.stringify({
+          action: "upload",
+          key: opts.key,
+          size: file.size,
+          contentType,
+          scope: opts.scope ?? "user",
+        }),
+      }).catch(() => {
+        // Notify failure is non-fatal; the upload itself succeeded.
+      })
+
+      const result: UploadResult = {
+        key: storedKey,
+        downloadUrl,
+        size: file.size,
+        contentType,
+      }
+      setState({ uploading: false, progress: 1, error: null, result })
+      return result
+    } catch (err) {
+      const msg = (err as Error).message ?? String(err)
+      setState({ uploading: false, progress: 0, error: msg, result: null })
+      throw err
+    }
+  }, [])
+
+  return { ...state, upload, reset }
+}