@opengeni/sdk 3.3.2-canary.1 → 3.4.0

package/src/site-data.ts

@@ -0,0 +1,372 @@
+/**
+ * Site Data for Site HTML: persistent JSON collections and files that belong
+ * to the published Site. Requests travel over the host's Site HTTP channel;
+ * the host adds the viewer's credentials and pins the Site, and the API
+ * enforces each collection's access mode. Stored records are untrusted input:
+ * render them with textContent, never innerHTML.
+ */
+
+export type OpenGeniSiteDataErrorCode =
+  | "validation"
+  | "conflict"
+  | "not_found"
+  | "forbidden"
+  /** This viewer may not do this on this Site (a role the Site's rules exclude). */
+  | "not_available_for_viewer"
+  | "quota_exceeded"
+  | "rate_limited"
+  | "site_data_unsupported"
+  | "request_failed";
+
+export class OpenGeniSiteDataError extends Error {
+  constructor(
+    readonly code: OpenGeniSiteDataErrorCode,
+    message: string,
+    readonly status: number,
+    readonly details: Record<string, unknown> = {},
+  ) {
+    super(message);
+    this.name = "OpenGeniSiteDataError";
+  }
+}
+
+export type OpenGeniSiteDataRecord<T extends Record<string, unknown> = Record<string, unknown>> = {
+  id: string;
+  key: string | null;
+  data: T;
+  /** Principal that owns the record, such as `user:<id>`. */
+  owner: string;
+  createdBy: string;
+  updatedBy: string;
+  version: number;
+  sizeBytes: number;
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type OpenGeniSiteDataScalar = string | number | boolean | null;
+
+export type OpenGeniSiteDataFilter = {
+  /** Dotted data path (up to 4 levels) or $id, $key, $owner, $createdAt, $updatedAt, $version. */
+  field: string;
+  op: "eq" | "ne" | "in" | "gt" | "gte" | "lt" | "lte" | "contains" | "exists";
+  value?: OpenGeniSiteDataScalar | OpenGeniSiteDataScalar[];
+};
+
+export type OpenGeniSiteDataListOptions = {
+  where?: OpenGeniSiteDataFilter[];
+  sort?: Array<{ field: string; direction?: "asc" | "desc" }>;
+  /** 1 to 200; 50 by default. */
+  limit?: number;
+  cursor?: string | null;
+  count?: boolean;
+  /** `own` returns only the viewer's records. */
+  scope?: "own" | "all";
+};
+
+export type OpenGeniSiteDataPage<T extends Record<string, unknown> = Record<string, unknown>> = {
+  records: OpenGeniSiteDataRecord<T>[];
+  nextCursor: string | null;
+  count?: number;
+};
+
+/** A record by id, or by your own key. A plain string is treated as a key. */
+export type OpenGeniSiteDataRef = string | { id: string } | { key: string };
+
+export type OpenGeniSiteDataOperation =
+  | { op: "insert"; collection: string; key?: string; data: Record<string, unknown> }
+  | {
+      op: "put";
+      collection: string;
+      key: string;
+      data: Record<string, unknown>;
+      expectedVersion?: number;
+    }
+  | ({
+      op: "patch";
+      collection: string;
+      data: Record<string, unknown>;
+      expectedVersion?: number;
+    } & RefFields)
+  | ({ op: "delete"; collection: string; expectedVersion?: number } & RefFields)
+  | ({ op: "increment"; collection: string; field: string; by?: number } & RefFields);
+
+type RefFields = { id: string; key?: never } | { key: string; id?: never };
+
+export type OpenGeniSiteDataWriteResult =
+  | { op: "insert" | "put" | "patch" | "increment"; record: OpenGeniSiteDataRecord }
+  | { op: "delete"; deleted: { id: string } };
+
+export type OpenGeniSiteDataCollection<
+  T extends Record<string, unknown> = Record<string, unknown>,
+> = {
+  readonly name: string;
+  list(options?: OpenGeniSiteDataListOptions): Promise<OpenGeniSiteDataPage<T>>;
+  /** Resolves null when the record does not exist or is not visible to the viewer. */
+  get(ref: OpenGeniSiteDataRef): Promise<OpenGeniSiteDataRecord<T> | null>;
+  insert(data: T, options?: { key?: string }): Promise<OpenGeniSiteDataRecord<T>>;
+  /** Create or replace the record with this key. */
+  put(
+    key: string,
+    data: T,
+    options?: { expectedVersion?: number },
+  ): Promise<OpenGeniSiteDataRecord<T>>;
+  /** Shallow-merge fields; expectedVersion turns concurrent edits into a conflict error. */
+  patch(
+    ref: OpenGeniSiteDataRef,
+    data: Partial<T>,
+    options?: { expectedVersion?: number },
+  ): Promise<OpenGeniSiteDataRecord<T>>;
+  delete(ref: OpenGeniSiteDataRef, options?: { expectedVersion?: number }): Promise<void>;
+  /** Atomically add to a numeric field; a missing key is created. */
+  increment(
+    ref: OpenGeniSiteDataRef,
+    field: string,
+    by?: number,
+  ): Promise<OpenGeniSiteDataRecord<T>>;
+  count(where?: OpenGeniSiteDataFilter[], options?: { scope?: "own" | "all" }): Promise<number>;
+};
+
+export type OpenGeniSiteData = {
+  collection<T extends Record<string, unknown> = Record<string, unknown>>(
+    name: string,
+  ): OpenGeniSiteDataCollection<T>;
+  /** Up to 100 operations across collections, applied together or not at all. */
+  batch(operations: OpenGeniSiteDataOperation[]): Promise<OpenGeniSiteDataWriteResult[]>;
+  count(collection: string, where?: OpenGeniSiteDataFilter[]): Promise<number>;
+};
+
+export type OpenGeniSiteFile = {
+  id: string;
+  name: string;
+  contentType: string;
+  sizeBytes: number;
+  sha256: string;
+  /** shared: every viewer can open it. private: only the uploader and the Site's managers. */
+  scope: "shared" | "private";
+  owner: string;
+  createdBy: string;
+  createdAt: string;
+};
+
+export type OpenGeniSiteFiles = {
+  upload(
+    file: Blob | ArrayBuffer | Uint8Array,
+    options?: { name?: string; contentType?: string; scope?: "shared" | "private" },
+  ): Promise<OpenGeniSiteFile>;
+  list(options?: { limit?: number; cursor?: string | null }): Promise<{
+    files: OpenGeniSiteFile[];
+    nextCursor: string | null;
+  }>;
+  /** A short-lived download URL for an img/src, link or fetch. */
+  url(fileId: string): Promise<{ url: string; expiresAt: string; file: OpenGeniSiteFile }>;
+  delete(fileId: string): Promise<void>;
+};
+
+/** Path prefix the host rewrites to its pinned Site; Site code never names a Site id. */
+export const SITE_DATA_PATH_PREFIX = "/v1/workspaces/site-host/published-artifacts/current";
+
+type SiteDataFetch = (path: string, init: RequestInit) => Promise<Response>;
+
+/**
+ * Build the typed Site Data facade over a Site HTTP fetch. `ready` resolves
+ * once the host has said whether it serves Site Data.
+ */
+export function createOpenGeniSiteData(
+  fetchSite: SiteDataFetch,
+  ready: () => Promise<boolean>,
+): { data: OpenGeniSiteData; files: OpenGeniSiteFiles } {
+  const send = async <T>(path: string, init: RequestInit = {}): Promise<T> => {
+    if (!(await ready()))
+      throw new OpenGeniSiteDataError(
+        "site_data_unsupported",
+        "This Site host does not provide Site Data",
+        0,
+      );
+    const response = await fetchSite(`${SITE_DATA_PATH_PREFIX}${path}`, init);
+    const text = await response.text();
+    let value: unknown = null;
+    try {
+      value = text ? JSON.parse(text) : null;
+    } catch {
+      value = null;
+    }
+    if (response.ok) return value as T;
+    throw siteDataErrorFromResponse(response.status, value);
+  };
+  const json = (body: unknown): RequestInit => ({
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  const write = async (operations: OpenGeniSiteDataOperation[]) =>
+    (await send<{ results: OpenGeniSiteDataWriteResult[] }>("/data/write", json({ operations })))
+      .results;
+  const one = async (operation: OpenGeniSiteDataOperation) => {
+    const [result] = await write([operation]);
+    if (!result || !("record" in result))
+      throw new OpenGeniSiteDataError("request_failed", "Unexpected Site Data response", 200);
+    return result.record;
+  };
+  const count = async (
+    collection: string,
+    where?: OpenGeniSiteDataFilter[],
+    scope?: "own" | "all",
+  ) =>
+    (
+      await send<OpenGeniSiteDataPage>(
+        "/data/query",
+        json({
+          collection,
+          limit: 1,
+          count: true,
+          ...(where ? { where } : {}),
+          ...(scope ? { scope } : {}),
+        }),
+      )
+    ).count ?? 0;
+
+  const data: OpenGeniSiteData = {
+    collection<T extends Record<string, unknown> = Record<string, unknown>>(name: string) {
+      const collection: OpenGeniSiteDataCollection<T> = {
+        name,
+        list: async (options = {}) =>
+          await send<OpenGeniSiteDataPage<T>>(
+            "/data/query",
+            json({ collection: name, ...options }),
+          ),
+        get: async (ref) => {
+          try {
+            return (
+              await send<{ record: OpenGeniSiteDataRecord<T> }>(
+                "/data/get",
+                json({ collection: name, ...refFields(ref) }),
+              )
+            ).record;
+          } catch (error) {
+            if (error instanceof OpenGeniSiteDataError && error.code === "not_found") return null;
+            throw error;
+          }
+        },
+        insert: async (value, options = {}) =>
+          (await one({
+            op: "insert",
+            collection: name,
+            data: value,
+            ...(options.key === undefined ? {} : { key: options.key }),
+          })) as OpenGeniSiteDataRecord<T>,
+        put: async (key, value, options = {}) =>
+          (await one({
+            op: "put",
+            collection: name,
+            key,
+            data: value,
+            ...options,
+          })) as OpenGeniSiteDataRecord<T>,
+        patch: async (ref, value, options = {}) =>
+          (await one({
+            op: "patch",
+            collection: name,
+            ...refFields(ref),
+            data: value as Record<string, unknown>,
+            ...options,
+          })) as OpenGeniSiteDataRecord<T>,
+        delete: async (ref, options = {}) => {
+          await write([{ op: "delete", collection: name, ...refFields(ref), ...options }]);
+        },
+        increment: async (ref, field, by) =>
+          (await one({
+            op: "increment",
+            collection: name,
+            ...refFields(ref),
+            field,
+            ...(by === undefined ? {} : { by }),
+          })) as OpenGeniSiteDataRecord<T>,
+        count: async (where, options = {}) => await count(name, where, options.scope),
+      };
+      return collection;
+    },
+    batch: write,
+    count: async (collection, where) => await count(collection, where),
+  };
+
+  const files: OpenGeniSiteFiles = {
+    upload: async (file, options = {}) => {
+      const blob =
+        file instanceof Blob
+          ? file
+          : new Blob([file instanceof Uint8Array ? file.slice() : file], {
+              type: options.contentType ?? "application/octet-stream",
+            });
+      const name =
+        options.name ?? (typeof File !== "undefined" && file instanceof File ? file.name : "file");
+      const query = new URLSearchParams({ name, scope: options.scope ?? "shared" });
+      return await send<OpenGeniSiteFile>(`/files?${query}`, {
+        method: "POST",
+        headers: {
+          "content-type": options.contentType ?? (blob.type || "application/octet-stream"),
+        },
+        body: await blob.arrayBuffer(),
+      });
+    },
+    list: async (options = {}) => {
+      const query = new URLSearchParams();
+      if (options.limit !== undefined) query.set("limit", String(options.limit));
+      if (options.cursor) query.set("cursor", options.cursor);
+      const suffix = query.size ? `?${query}` : "";
+      return await send(`/files${suffix}`, { method: "GET" });
+    },
+    url: async (fileId) => await send(`/files/${encodeURIComponent(fileId)}`, { method: "GET" }),
+    delete: async (fileId) => {
+      await send(`/files/${encodeURIComponent(fileId)}`, { method: "DELETE" });
+    },
+  };
+  return { data, files };
+}
+
+function refFields(ref: OpenGeniSiteDataRef): RefFields {
+  if (typeof ref === "string") return { key: ref };
+  if ("id" in ref) return { id: ref.id };
+  return { key: ref.key };
+}
+
+const KNOWN_CODES = new Set<OpenGeniSiteDataErrorCode>([
+  "validation",
+  "conflict",
+  "not_found",
+  "forbidden",
+  "not_available_for_viewer",
+  "quota_exceeded",
+  "rate_limited",
+]);
+
+function siteDataErrorFromResponse(status: number, value: unknown): OpenGeniSiteDataError {
+  const error =
+    typeof value === "object" && value !== null && "error" in value
+      ? (value as { error: unknown }).error
+      : null;
+  const record =
+    typeof error === "object" && error !== null ? (error as Record<string, unknown>) : {};
+  const details =
+    typeof record.details === "object" && record.details !== null
+      ? (record.details as Record<string, unknown>)
+      : {};
+  const detailCode = details.code as OpenGeniSiteDataErrorCode | undefined;
+  const code: OpenGeniSiteDataErrorCode =
+    detailCode && KNOWN_CODES.has(detailCode)
+      ? detailCode
+      : status === 404
+        ? "not_found"
+        : status === 403
+          ? "forbidden"
+          : status === 413
+            ? "quota_exceeded"
+            : status === 429
+              ? "rate_limited"
+              : "request_failed";
+  const message =
+    typeof record.message === "string" && record.message
+      ? record.message
+      : `Site Data request failed with HTTP ${status}`;
+  return new OpenGeniSiteDataError(code, message, status, details);
+}

package/src/site-document.test.ts

@@ -0,0 +1,64 @@
+import { expect, test } from "bun:test";
+import { runInNewContext } from "node:vm";
+import { resolveSiteClientScript, SITE_CLIENT_SCRIPT_PATH } from "./site-document";
+
+const tag = `<script src="${SITE_CLIENT_SCRIPT_PATH}"></script>`;
+
+test("ordinary bundled Sites remain byte-identical", () => {
+  const html =
+    '<!doctype html><script type="module">const client = "bundled SDK";</script><main>React</main>';
+  expect(resolveSiteClientScript(html)).toBe(html);
+  const comment = `<!-- ${tag} -->`;
+  expect(resolveSiteClientScript(comment)).toBe(comment);
+  const sample = `<script>const example = '<script src="${SITE_CLIENT_SCRIPT_PATH}"><\\/script>';</script>`;
+  expect(resolveSiteClientScript(sample)).toBe(sample);
+});
+
+test("optional script preserves document order and exposes the existing client", () => {
+  const html = `<!doctype html><title>Preview</title>${tag}<script>globalThis.authorRan = true</script>`;
+  const result = resolveSiteClientScript(html);
+  expect(result.startsWith("<!doctype html><title>Preview</title><script>")).toBe(true);
+  expect(result.endsWith("<script>globalThis.authorRan = true</script>")).toBe(true);
+  const script = result.match(/<script>([\s\S]*?)<\/script>/)![1]!;
+  const context: Record<string, unknown> = {
+    URL,
+    Request,
+    Response,
+    Headers,
+    AbortController,
+    TextEncoder,
+    TextDecoder,
+    setTimeout,
+    clearTimeout,
+  };
+  runInNewContext(script, context);
+  expect(typeof context.createOpenGeniSiteClient).toBe("function");
+});
+
+test("optional client uses the existing local catalog transport", async () => {
+  const html = resolveSiteClientScript(tag);
+  const calls: string[] = [];
+  const window: Record<string, unknown> = {};
+  window.parent = window;
+  const context: Record<string, any> = {
+    window,
+    URL,
+    Request,
+    Response,
+    Headers,
+    AbortController,
+    TextEncoder,
+    TextDecoder,
+    setTimeout,
+    clearTimeout,
+    fetch: async (url: string) => {
+      calls.push(url);
+      return Response.json({ version: 1, generation: 1, digest: "test", entries: [] });
+    },
+  };
+  runInNewContext(html.match(/<script>([\s\S]*?)<\/script>/)![1]!, context);
+  const client = context.createOpenGeniSiteClient();
+  await client.tools.$catalog();
+  expect(calls).toEqual(["/__opengeni/site-tools/catalog"]);
+  client.close();
+});

package/src/site-document.ts

@@ -0,0 +1,18 @@
+import { SITE_BROWSER_RUNTIME } from "./site-browser-runtime.gen";
+
+export const SITE_CLIENT_SCRIPT_PATH = "/__opengeni/site-tools/client.js";
+export { SITE_BROWSER_RUNTIME };
+
+/** Resolve only the optional client tag; ordinary bundled Sites remain unchanged. */
+export function resolveSiteClientScript(html: string): string {
+  // Consume whole scripts/comments so examples inside JS or comments stay literal.
+  return html.replace(/<!--[\s\S]*?-->|<script\b[^>]*>[\s\S]*?<\/script\s*>/gi, (tag) => {
+    if (
+      !/^<script\s+src\s*=\s*(["'])\/__opengeni\/site-tools\/client\.js\1\s*>\s*<\/script\s*>$/i.test(
+        tag,
+      )
+    )
+      return tag;
+    return "<script>" + SITE_BROWSER_RUNTIME.replace(/<\/script/gi, "<\\/script") + "</script>";
+  });
+}

package/src/site-http.ts

@@ -0,0 +1,171 @@
+/** HTTP transport for the ordinary SDK. One response port per request keeps
+ * event streams incremental and cancellation independent of other requests. */
+export const SITE_HTTP = "opengeni.site.http";
+export const SITE_WORKSPACE = "site-host";
+export type SiteHttpRequest = {
+  type: typeof SITE_HTTP;
+  requestId: string;
+  path: string;
+  method: string;
+  headers: [string, string][];
+  /** Text for JSON requests; bytes for Site Data file uploads. */
+  body?: string | ArrayBuffer;
+};
+
+import { siteSessionPath } from "@opengeni/contracts/site-session-http";
+export { siteSessionPath } from "@opengeni/contracts/site-session-http";
+
+export function isSiteHttpRequest(value: unknown): value is SiteHttpRequest {
+  if (!value || typeof value !== "object") return false;
+  const v = value as SiteHttpRequest;
+  return (
+    v.type === SITE_HTTP &&
+    typeof v.requestId === "string" &&
+    typeof v.path === "string" &&
+    typeof v.method === "string" &&
+    /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/u.test(v.method) &&
+    (v.body === undefined || typeof v.body === "string" || v.body instanceof ArrayBuffer) &&
+    Array.isArray(v.headers) &&
+    v.headers.every(
+      (h) => Array.isArray(h) && h.length === 2 && h.every((x) => typeof x === "string"),
+    )
+  );
+}
+
+export async function serveSiteHttp(
+  message: SiteHttpRequest,
+  port: MessagePort,
+  fetchResponse: (request: SiteHttpRequest, signal: AbortSignal) => Promise<Response>,
+  signal: AbortSignal,
+): Promise<void> {
+  let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+  let wake: (() => void) | undefined;
+  let pulling = false;
+  const onMessage = (event: MessageEvent) => {
+    if (event.data === "pull") {
+      pulling = true;
+      wake?.();
+    }
+  };
+  const abort = () => {
+    void reader?.cancel(signal.reason).catch(() => {});
+    wake?.();
+  };
+  port.addEventListener("message", onMessage);
+  signal.addEventListener("abort", abort, { once: true });
+  port.start();
+  try {
+    if (signal.aborted) throw signal.reason;
+    const response = await fetchResponse(message, signal);
+    reader = response.body?.getReader();
+    port.postMessage({ status: response.status, headers: [...response.headers], body: !!reader });
+    if (reader)
+      while (!signal.aborted) {
+        if (!pulling)
+          await new Promise<void>((resolve) => {
+            wake = resolve;
+          });
+        wake = undefined;
+        if (signal.aborted) break;
+        pulling = false;
+        const part = await reader.read();
+        if (part.done) {
+          port.postMessage({ done: true });
+          break;
+        }
+        port.postMessage({ chunk: part.value });
+      }
+    if (signal.aborted) throw signal.reason;
+  } catch (error) {
+    port.postMessage({ error: error instanceof Error ? error.message : "Site request failed" });
+  } finally {
+    signal.removeEventListener("abort", abort);
+    port.removeEventListener("message", onMessage);
+    await reader?.cancel().catch(() => {});
+    port.close();
+  }
+}
+
+export async function sitePortFetch(
+  port: MessagePort,
+  input: RequestInfo | URL,
+  init?: RequestInit,
+): Promise<Response> {
+  const request = new Request(input, init);
+  const url = new URL(request.url);
+  const path = `${url.pathname}${url.search}`;
+  siteSessionPath(path, SITE_WORKSPACE, request.method);
+  const channel = new MessageChannel();
+  const requestId = crypto.randomUUID();
+  const binary =
+    init?.body instanceof ArrayBuffer ||
+    ArrayBuffer.isView(init?.body) ||
+    (typeof Blob !== "undefined" && init?.body instanceof Blob);
+  const body = request.body
+    ? binary
+      ? await request.arrayBuffer()
+      : await request.text()
+    : undefined;
+  return await new Promise<Response>((resolve, reject) => {
+    let controller: ReadableStreamDefaultController<Uint8Array> | undefined;
+    let finished = false;
+    const cleanup = () => {
+      finished = true;
+      request.signal.removeEventListener("abort", abort);
+      channel.port1.close();
+    };
+    const abort = () => {
+      if (finished) return;
+      port.postMessage({ type: "opengeni.site.cancel", version: 2, requestId });
+      const error = request.signal.reason ?? new DOMException("Cancelled", "AbortError");
+      controller?.error(error);
+      reject(error);
+      cleanup();
+    };
+    channel.port1.onmessage = (event) => {
+      const data = event.data;
+      if (data.error) {
+        const error = new Error(data.error);
+        controller?.error(error);
+        reject(error);
+        cleanup();
+      } else if (data.status) {
+        const stream = data.body
+          ? new ReadableStream<Uint8Array>({
+              start(c) {
+                controller = c;
+              },
+              pull() {
+                channel.port1.postMessage("pull");
+              },
+              cancel() {
+                controller = undefined;
+                abort();
+              },
+            })
+          : null;
+        resolve(new Response(stream, { status: data.status, headers: data.headers }));
+        if (!data.body) cleanup();
+      } else if (data.done) {
+        controller?.close();
+        cleanup();
+      } else if (data.chunk) controller?.enqueue(data.chunk);
+    };
+    if (request.signal.aborted) {
+      abort();
+      return;
+    }
+    request.signal.addEventListener("abort", abort, { once: true });
+    port.postMessage(
+      {
+        type: SITE_HTTP,
+        requestId,
+        path,
+        method: request.method,
+        headers: [...request.headers],
+        ...(body === undefined ? {} : { body }),
+      } satisfies SiteHttpRequest,
+      [channel.port2],
+    );
+  });
+}