@moloodev/bundle-sdk 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "@moloodev/bundle-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./idb": "./src/idb.ts"
+  },
+  "dependencies": {
+    "@moloodev/platform": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "tsx": "^4.23.13",
+    "typescript": "^7.0.2",
+    "@moloodev/typescript-config": "0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test 'src/**/*.test.ts'"
+  }
 }

package/src/client.ts

@@ -0,0 +1,294 @@
+import { decodeJson, digestJson, encodeJson, sha256Hex } from "./digest";
+import { ConsumeError } from "./error";
+import {
+  consumeBytes,
+  consumeGet,
+  DEFAULT_API_ORIGIN,
+  type FetchLike,
+} from "./http";
+import {
+  fileMetaKey,
+  manifestKey,
+  memberKey,
+  MemoryStore,
+  type BundleStore,
+} from "./store";
+import type {
+  BundleSnapshot,
+  ConsumeLatest,
+  ConsumeManifest,
+  ConsumeMember,
+  ConsumeMemberMeta,
+  LoadedMember,
+  LoadOptions,
+  LoadProgress,
+} from "./types";
+
+export type BundleClientOptions = {
+  bundleId: string;
+  baseUrl?: string;
+  apiKey?: string;
+  store?: BundleStore;
+  fetch?: FetchLike;
+  sleep?: (ms: number) => Promise<void>;
+};
+
+export type BundleClient = {
+  load(options?: LoadOptions): Promise<BundleSnapshot>;
+  read(revision?: number): Promise<BundleSnapshot | null>;
+};
+
+type FileMeta = {
+  fileName: string;
+  contentType: string;
+  size: number;
+};
+
+const MEMBER_CONCURRENCY = 4;
+
+function joinUrl(base: string, path: string): string {
+  return `${base.replace(/\/$/, "")}${path}`;
+}
+
+async function mapPool<T, R>(
+  items: T[],
+  concurrency: number,
+  fn: (item: T) => Promise<R>,
+): Promise<R[]> {
+  if (items.length === 0) return [];
+  const results = new Array<R>(items.length);
+  let next = 0;
+  async function worker() {
+    for (;;) {
+      const index = next;
+      next += 1;
+      if (index >= items.length) return;
+      results[index] = await fn(items[index]!);
+    }
+  }
+  await Promise.all(
+    Array.from({ length: Math.min(concurrency, items.length) }, () => worker()),
+  );
+  return results;
+}
+
+export function createBundleClient(options: BundleClientOptions): BundleClient {
+  const { bundleId, apiKey, sleep } = options;
+  const baseUrl = options.baseUrl ?? DEFAULT_API_ORIGIN;
+  const store = options.store ?? new MemoryStore();
+  const fetchFn = options.fetch ?? globalThis.fetch.bind(globalThis);
+  const prefix = `/v1/bundles/${encodeURIComponent(bundleId)}`;
+  const manifestPrefix = `m:${bundleId}:`;
+
+  function request<T>(url: string, signal?: AbortSignal) {
+    return consumeGet<T>({
+      fetch: fetchFn,
+      url,
+      apiKey,
+      signal,
+      sleep,
+    });
+  }
+
+  async function readMember(meta: ConsumeMemberMeta): Promise<LoadedMember | null> {
+    const bytes = await store.get(memberKey(meta.assetId, meta.revision, meta.digest));
+    if (!bytes) return null;
+    if (meta.storage === "blob") {
+      if ((await sha256Hex(bytes)) !== meta.digest) return null;
+      const rawMeta = await store.get(fileMetaKey(meta.assetId, meta.revision, meta.digest));
+      if (!rawMeta) return null;
+      try {
+        const file = decodeJson<FileMeta>(rawMeta);
+        return { ...meta, file: { ...file, bytes } };
+      } catch {
+        return null;
+      }
+    }
+    try {
+      const payload = decodeJson<Record<string, unknown>>(bytes);
+      if ((await digestJson(payload)) !== meta.digest) return null;
+      return { ...meta, payload };
+    } catch {
+      return null;
+    }
+  }
+
+  async function writeMember(member: LoadedMember): Promise<void> {
+    const key = memberKey(member.assetId, member.revision, member.digest);
+    if (member.storage === "blob") {
+      if (!member.file) return;
+      await store.set(key, member.file.bytes);
+      await store.set(
+        fileMetaKey(member.assetId, member.revision, member.digest),
+        encodeJson({
+          fileName: member.file.fileName,
+          contentType: member.file.contentType,
+          size: member.file.size,
+        } satisfies FileMeta),
+      );
+      return;
+    }
+    if (!member.payload) return;
+    await store.set(key, encodeJson(member.payload));
+  }
+
+  async function readRevision(revision: number): Promise<BundleSnapshot | null> {
+    const raw = await store.get(manifestKey(bundleId, revision));
+    if (!raw) return null;
+    let manifest: ConsumeManifest;
+    try {
+      manifest = decodeJson<ConsumeManifest>(raw);
+    } catch {
+      return null;
+    }
+    const members: LoadedMember[] = [];
+    for (const meta of manifest.members) {
+      const loaded = await readMember(meta);
+      if (!loaded) return null;
+      members.push(loaded);
+    }
+    return { ...manifest, members };
+  }
+
+  async function listedRevisions(): Promise<number[]> {
+    const keys = await store.list(manifestPrefix);
+    return keys
+      .map((key) => Number(key.slice(manifestPrefix.length)))
+      .filter((revision) => Number.isInteger(revision) && revision > 0)
+      .sort((left, right) => right - left);
+  }
+
+  async function read(revision?: number): Promise<BundleSnapshot | null> {
+    if (revision != null) return readRevision(revision);
+    for (const candidate of await listedRevisions()) {
+      const snapshot = await readRevision(candidate);
+      if (snapshot) return snapshot;
+    }
+    return null;
+  }
+
+  async function downloadMember(
+    revision: number,
+    meta: ConsumeMemberMeta,
+    signal: AbortSignal | undefined,
+    onProgress?: (progress: LoadProgress) => void,
+  ): Promise<LoadedMember> {
+    let lastError: ConsumeError | undefined;
+    for (let attempt = 0; attempt < 2; attempt++) {
+      const member = await request<ConsumeMember>(
+        joinUrl(
+          baseUrl,
+          `${prefix}/revisions/${revision}/assets/${encodeURIComponent(meta.assetId)}`,
+        ),
+        signal,
+      );
+      if (meta.storage === "blob") {
+        if (!member.file?.url) {
+          lastError = new ConsumeError("integrity");
+          continue;
+        }
+        onProgress?.({
+          phase: "file",
+          done: 0,
+          total: 1,
+          assetId: meta.assetId,
+          bytesTotal: member.file.size,
+        });
+        const bytes = await consumeBytes({
+          fetch: fetchFn,
+          url: member.file.url,
+          signal,
+          sleep,
+        });
+        if ((await sha256Hex(bytes)) !== meta.digest) {
+          lastError = new ConsumeError("integrity");
+          continue;
+        }
+        return {
+          ...meta,
+          file: {
+            bytes,
+            fileName: member.file.fileName,
+            contentType: member.file.contentType,
+            size: member.file.size,
+          },
+        };
+      }
+      if (!member.payload || (await digestJson(member.payload)) !== meta.digest) {
+        lastError = new ConsumeError("integrity");
+        continue;
+      }
+      return { ...meta, payload: member.payload };
+    }
+    throw lastError ?? new ConsumeError("integrity");
+  }
+
+  async function pull(load: LoadOptions | undefined): Promise<BundleSnapshot> {
+    const signal = load?.signal;
+    let revision = load?.revision;
+    if (revision == null) {
+      load?.onProgress?.({ phase: "latest", done: 0, total: 1 });
+      const latest = await request<ConsumeLatest>(
+        joinUrl(baseUrl, `${prefix}/latest`),
+        signal,
+      );
+      revision = latest.revision;
+      load?.onProgress?.({ phase: "latest", done: 1, total: 1 });
+    }
+    load?.onProgress?.({ phase: "manifest", done: 0, total: 1 });
+    const manifest = await request<ConsumeManifest>(
+      joinUrl(baseUrl, `${prefix}/revisions/${revision}`),
+      signal,
+    );
+    load?.onProgress?.({ phase: "manifest", done: 1, total: 1 });
+
+    const total = manifest.members.length;
+    let done = 0;
+    const members = await mapPool(manifest.members, MEMBER_CONCURRENCY, async (meta) => {
+      let loaded = load?.recover ? null : await readMember(meta);
+      if (!loaded) {
+        loaded = await downloadMember(manifest.revision, meta, signal, load?.onProgress);
+        await writeMember(loaded);
+      }
+      done += 1;
+      load?.onProgress?.({
+        phase: "member",
+        done,
+        total,
+        assetId: meta.assetId,
+      });
+      return loaded;
+    });
+
+    await store.set(
+      manifestKey(bundleId, manifest.revision),
+      encodeJson({
+        workspaceId: manifest.workspaceId,
+        bundleId: manifest.bundleId,
+        revision: manifest.revision,
+        name: manifest.name,
+        message: manifest.message,
+        createdAt: manifest.createdAt,
+        members: manifest.members,
+      } satisfies ConsumeManifest),
+    );
+    return { ...manifest, members };
+  }
+
+  return {
+    async load(load) {
+      try {
+        return await pull(load);
+      } catch (error) {
+        if (error instanceof ConsumeError && error.code === "offline") {
+          const local =
+            (load?.revision != null ? await readRevision(load.revision) : null) ??
+            (await read());
+          if (local) return local;
+        }
+        throw error;
+      }
+    },
+    read,
+  };
+}

package/src/digest.ts

@@ -0,0 +1,20 @@
+const encoder = new TextEncoder();
+
+export function encodeJson(value: unknown): Uint8Array {
+  return encoder.encode(JSON.stringify(value));
+}
+
+export function decodeJson<T>(bytes: Uint8Array): T {
+  return JSON.parse(new TextDecoder().decode(bytes)) as T;
+}
+
+export async function sha256Hex(data: Uint8Array): Promise<string> {
+  const digest = await crypto.subtle.digest("SHA-256", data as BufferSource);
+  return Array.from(new Uint8Array(digest), (byte) =>
+    byte.toString(16).padStart(2, "0"),
+  ).join("");
+}
+
+export async function digestJson(value: unknown): Promise<string> {
+  return sha256Hex(encodeJson(value));
+}

package/src/error.ts

@@ -0,0 +1,24 @@
+export type ConsumeErrorCode =
+  | "not_found"
+  | "unauthorized"
+  | "forbidden"
+  | "offline"
+  | "integrity"
+  | "aborted"
+  | "http";
+
+export class ConsumeError extends Error {
+  readonly code: ConsumeErrorCode;
+  readonly status?: number;
+
+  constructor(code: ConsumeErrorCode, message?: string, status?: number) {
+    super(message ?? code);
+    this.name = "ConsumeError";
+    this.code = code;
+    this.status = status;
+  }
+}
+
+export function isConsumeError(error: unknown): error is ConsumeError {
+  return error instanceof ConsumeError;
+}

package/src/http.ts

@@ -0,0 +1,91 @@
+import { getApiOrigin } from "@moloodev/platform";
+import { ConsumeError, type ConsumeErrorCode } from "./error";
+
+/** Production gateway. Callers pass `baseUrl` when they need another origin. */
+export const DEFAULT_API_ORIGIN = getApiOrigin("production");
+
+export type FetchLike = typeof fetch;
+
+export type ConsumeRequestOptions = {
+  fetch: FetchLike;
+  url: string;
+  apiKey?: string;
+  signal?: AbortSignal;
+  sleep?: (ms: number) => Promise<void>;
+};
+
+function defaultSleep(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+function isAbortError(error: unknown): boolean {
+  return Boolean(error && typeof error === "object" && "name" in error && error.name === "AbortError");
+}
+
+function codeForStatus(status: number): ConsumeErrorCode {
+  if (status === 401) return "unauthorized";
+  if (status === 403) return "forbidden";
+  if (status === 404) return "not_found";
+  return "http";
+}
+
+function retryDelayMs(response: Response, attempt: number): number {
+  const header = response.headers.get("retry-after");
+  if (header) {
+    const seconds = Number(header);
+    if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1000;
+  }
+  return 200 * 2 ** attempt;
+}
+
+async function request(options: ConsumeRequestOptions): Promise<Response> {
+  const headers = new Headers();
+  if (options.apiKey) headers.set("x-api-key", options.apiKey);
+  const sleep = options.sleep ?? defaultSleep;
+
+  for (let attempt = 0; attempt < 3; attempt++) {
+    let response: Response;
+    try {
+      response = await options.fetch(options.url, {
+        headers,
+        signal: options.signal,
+      });
+    } catch (error) {
+      if (isAbortError(error) || options.signal?.aborted) {
+        throw new ConsumeError("aborted");
+      }
+      throw new ConsumeError(
+        "offline",
+        error instanceof Error ? error.message : "offline",
+      );
+    }
+
+    if (response.ok) return response;
+    if (response.status === 429 || response.status >= 500) {
+      if (attempt === 2) {
+        throw new ConsumeError(codeForStatus(response.status), undefined, response.status);
+      }
+      await sleep(retryDelayMs(response, attempt));
+      continue;
+    }
+    throw new ConsumeError(codeForStatus(response.status), undefined, response.status);
+  }
+
+  throw new ConsumeError("http");
+}
+
+export async function consumeGet<T>(options: ConsumeRequestOptions): Promise<T> {
+  const response = await request(options);
+  const body = (await response.json()) as { data?: T };
+  if (!body || typeof body !== "object" || !("data" in body)) {
+    throw new ConsumeError("http", "invalid response", response.status);
+  }
+  return body.data as T;
+}
+
+export async function consumeBytes(options: ConsumeRequestOptions): Promise<Uint8Array> {
+  const response = await request(options);
+  return new Uint8Array(await response.arrayBuffer());
+}

package/src/idb.ts

@@ -0,0 +1,71 @@
+import type { BundleStore } from "./store";
+
+const STORE = "entries";
+
+export type IdbStoreOptions = {
+  name?: string;
+  indexedDB?: IDBFactory;
+};
+
+function requestValue<T>(request: IDBRequest<T>): Promise<T> {
+  return new Promise((resolve, reject) => {
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error ?? new Error("IndexedDB request failed"));
+  });
+}
+
+function openDatabase(factory: IDBFactory, name: string): Promise<IDBDatabase> {
+  return new Promise((resolve, reject) => {
+    const request = factory.open(name, 1);
+    request.onupgradeneeded = () => {
+      const db = request.result;
+      if (!db.objectStoreNames.contains(STORE)) {
+        db.createObjectStore(STORE);
+      }
+    };
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error ?? new Error("IndexedDB open failed"));
+  });
+}
+
+function asBytes(value: unknown): Uint8Array | null {
+  if (value == null) return null;
+  if (value instanceof Uint8Array) return new Uint8Array(value);
+  if (value instanceof ArrayBuffer) return new Uint8Array(value);
+  return null;
+}
+
+export function createIdbStore(options: IdbStoreOptions = {}): BundleStore {
+  const factory = options.indexedDB ?? globalThis.indexedDB;
+  if (!factory) {
+    throw new Error("IndexedDB is not available");
+  }
+  const ready = openDatabase(factory, options.name ?? "moloo-bundle");
+
+  return {
+    async get(key) {
+      const db = await ready;
+      const value = await requestValue(
+        db.transaction(STORE, "readonly").objectStore(STORE).get(key),
+      );
+      return asBytes(value);
+    },
+    async set(key, value) {
+      const db = await ready;
+      await requestValue(
+        db.transaction(STORE, "readwrite").objectStore(STORE).put(new Uint8Array(value), key),
+      );
+    },
+    async delete(key) {
+      const db = await ready;
+      await requestValue(db.transaction(STORE, "readwrite").objectStore(STORE).delete(key));
+    },
+    async list(prefix) {
+      const db = await ready;
+      const keys = await requestValue(
+        db.transaction(STORE, "readonly").objectStore(STORE).getAllKeys(),
+      );
+      return keys.map(String).filter((key) => key.startsWith(prefix)).sort();
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+export {
+  createBundleClient,
+  type BundleClient,
+  type BundleClientOptions,
+} from "./client";
+export { ConsumeError, isConsumeError, type ConsumeErrorCode } from "./error";
+export { DEFAULT_API_ORIGIN } from "./http";
+export { MemoryStore, type BundleStore } from "./store";
+export type {
+  BundleSnapshot,
+  ConsumeFile,
+  ConsumeLatest,
+  ConsumeManifest,
+  ConsumeMember,
+  ConsumeMemberMeta,
+  LoadedFile,
+  LoadedMember,
+  LoadOptions,
+  LoadProgress,
+} from "./types";

package/src/store.ts

@@ -0,0 +1,47 @@
+export type BundleStore = {
+  get(key: string): Promise<Uint8Array | null>;
+  set(key: string, value: Uint8Array): Promise<void>;
+  delete(key: string): Promise<void>;
+  list(prefix: string): Promise<string[]>;
+};
+
+export function manifestKey(bundleId: string, revision: number): string {
+  return `m:${bundleId}:${revision}`;
+}
+
+export function memberKey(
+  assetId: string,
+  revision: number,
+  digest: string,
+): string {
+  return `a:${assetId}:${revision}:${digest}`;
+}
+
+export function fileMetaKey(
+  assetId: string,
+  revision: number,
+  digest: string,
+): string {
+  return `f:${assetId}:${revision}:${digest}`;
+}
+
+export class MemoryStore implements BundleStore {
+  #data = new Map<string, Uint8Array>();
+
+  async get(key: string): Promise<Uint8Array | null> {
+    const value = this.#data.get(key);
+    return value ? new Uint8Array(value) : null;
+  }
+
+  async set(key: string, value: Uint8Array): Promise<void> {
+    this.#data.set(key, new Uint8Array(value));
+  }
+
+  async delete(key: string): Promise<void> {
+    this.#data.delete(key);
+  }
+
+  async list(prefix: string): Promise<string[]> {
+    return [...this.#data.keys()].filter((key) => key.startsWith(prefix)).sort();
+  }
+}

package/src/types.ts

@@ -0,0 +1,70 @@
+export type ConsumeMemberMeta = {
+  assetId: string;
+  type: string;
+  revision: number;
+  inclusion: string;
+  storage: "document" | "blob";
+  size: number;
+  digest: string;
+};
+
+export type ConsumeManifest = {
+  workspaceId: string;
+  bundleId: string;
+  revision: number;
+  name: string;
+  message: string;
+  createdAt: string;
+  members: ConsumeMemberMeta[];
+};
+
+export type ConsumeLatest = {
+  workspaceId: string;
+  bundleId: string;
+  revision: number;
+};
+
+export type ConsumeFile = {
+  url: string;
+  variants: Record<string, string> | null;
+  fileName: string;
+  contentType: string;
+  size: number;
+};
+
+export type ConsumeMember = ConsumeMemberMeta & {
+  payload?: Record<string, unknown>;
+  file?: ConsumeFile;
+};
+
+export type LoadedFile = {
+  bytes: Uint8Array;
+  fileName: string;
+  contentType: string;
+  size: number;
+};
+
+export type LoadedMember = ConsumeMemberMeta & {
+  payload?: Record<string, unknown>;
+  file?: LoadedFile;
+};
+
+export type BundleSnapshot = Omit<ConsumeManifest, "members"> & {
+  members: LoadedMember[];
+};
+
+export type LoadProgress = {
+  phase: "latest" | "manifest" | "member" | "file";
+  done: number;
+  total: number;
+  bytesDone?: number;
+  bytesTotal?: number;
+  assetId?: string;
+};
+
+export type LoadOptions = {
+  revision?: number;
+  recover?: boolean;
+  signal?: AbortSignal;
+  onProgress?: (progress: LoadProgress) => void;
+};

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.