@lunora/bindings 0.0.0 → 1.0.0-alpha.10

package/dist/packem_shared/createImages-BzRnsz3H.mjs

@@ -0,0 +1,85 @@
+import { LunoraError } from '@lunora/errors';
+
+const ALLOWED_OUTPUT_FORMATS = /* @__PURE__ */ new Set(["image/avif", "image/gif", "image/jpeg", "image/png", "image/webp"]);
+const DEFAULT_MAX_DIMENSION = 1e4;
+const DEFAULT_OUTPUT_FORMAT = "image/webp";
+const isR2ObjectBody = (input) => {
+  if (typeof input !== "object") {
+    return false;
+  }
+  const object = input;
+  return "body" in object && !(input instanceof ArrayBuffer) && !(input instanceof Uint8Array);
+};
+const toStream = (input) => {
+  if (input instanceof ReadableStream) {
+    return input;
+  }
+  if (isR2ObjectBody(input)) {
+    if (input.body === null) {
+      throw new LunoraError("INTERNAL", "@lunora/bindings/images: R2 object body is null (object missing or already consumed)");
+    }
+    return input.body;
+  }
+  if (input instanceof Blob) {
+    return input.stream();
+  }
+  const bytes = input instanceof Uint8Array ? input : new Uint8Array(input);
+  return new ReadableStream({
+    start(controller) {
+      controller.enqueue(bytes);
+      controller.close();
+    }
+  });
+};
+const sanitizeTransform = (transform, maxDimension) => {
+  if (transform === void 0) {
+    return {};
+  }
+  const clampDimension = (value) => {
+    if (!Number.isFinite(value) || value <= 0) {
+      throw new TypeError("@lunora/bindings/images: width/height must be a positive finite number");
+    }
+    return Math.min(Math.floor(value), maxDimension);
+  };
+  const rest = { ...transform };
+  delete rest.draw;
+  return {
+    ...rest,
+    ...transform.width === void 0 ? {} : { width: clampDimension(transform.width) },
+    ...transform.height === void 0 ? {} : { height: clampDimension(transform.height) }
+  };
+};
+const splitOverlay = (overlay) => {
+  const { image, transform, ...drawOptions } = overlay;
+  return { drawOptions, image, transform };
+};
+const resolveOutput = (output) => {
+  const format = output?.format ?? DEFAULT_OUTPUT_FORMAT;
+  if (!ALLOWED_OUTPUT_FORMATS.has(format)) {
+    throw new LunoraError(
+      "INTERNAL",
+      `@lunora/bindings/images: unsupported output format "${format}" (allowed: ${[...ALLOWED_OUTPUT_FORMATS].join(", ")})`
+    );
+  }
+  return { ...output, format };
+};
+const createImages = (options) => {
+  const { binding } = options;
+  const maxDimension = options.maxDimension ?? DEFAULT_MAX_DIMENSION;
+  return {
+    info: async (input) => binding.info(toStream(input)),
+    transform: async (input, transform, output, overlays) => {
+      const safeTransform = sanitizeTransform(transform, maxDimension);
+      const outputOptions = resolveOutput(output);
+      let transformer = binding.input(toStream(input)).transform(safeTransform);
+      for (const overlay of overlays ?? []) {
+        const { drawOptions, image, transform: overlayTransform } = splitOverlay(overlay);
+        const overlayImage = overlayTransform === void 0 ? toStream(image) : binding.input(toStream(image)).transform(sanitizeTransform(overlayTransform, maxDimension));
+        transformer = transformer.draw(overlayImage, drawOptions);
+      }
+      return transformer.output(outputOptions);
+    }
+  };
+};
+
+export { createImages };

package/dist/packem_shared/createKv-C8Iyu5hD.mjs

@@ -0,0 +1,145 @@
+import { LunoraError } from '@lunora/errors';
+
+const MAX_KEY_LENGTH = 512;
+const MAX_LIST_LIMIT = 1e3;
+const TEXT_ENCODER = new TextEncoder();
+const byteLength = (value) => TEXT_ENCODER.encode(value).length;
+const validateKey = (key) => {
+  if (typeof key !== "string" || key.length === 0) {
+    throw new TypeError("@lunora/bindings/kv: key must be a non-empty string");
+  }
+  if (byteLength(key) > MAX_KEY_LENGTH) {
+    throw new LunoraError("INTERNAL", `@lunora/bindings/kv: key exceeds ${String(MAX_KEY_LENGTH)}-byte limit`);
+  }
+  if (key.includes("\0")) {
+    throw new LunoraError("INTERNAL", "@lunora/bindings/kv: key contains NUL byte");
+  }
+  const segments = key.split("/");
+  for (const segment of segments) {
+    if (segment === "." || segment === "..") {
+      throw new LunoraError("INTERNAL", "@lunora/bindings/kv: key contains a `.`/`..` path component");
+    }
+  }
+};
+const validatePrefix = (prefix) => {
+  if (prefix.length === 0) {
+    return;
+  }
+  if (byteLength(prefix) > MAX_KEY_LENGTH) {
+    throw new LunoraError("INTERNAL", `@lunora/bindings/kv: prefix exceeds ${String(MAX_KEY_LENGTH)}-byte limit`);
+  }
+  if (prefix.includes("\0")) {
+    throw new LunoraError("INTERNAL", "@lunora/bindings/kv: prefix contains NUL byte");
+  }
+  const segments = prefix.split("/");
+  for (const segment of segments) {
+    if (segment === "." || segment === "..") {
+      throw new LunoraError("INTERNAL", "@lunora/bindings/kv: prefix contains a `.`/`..` path component");
+    }
+  }
+};
+const scopeKey = (prefix, key) => {
+  validateKey(prefix);
+  validateKey(key);
+  const trimmedPrefix = prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
+  const composed = `${trimmedPrefix}/${key}`;
+  if (byteLength(composed) > MAX_KEY_LENGTH) {
+    throw new LunoraError("INTERNAL", `@lunora/bindings/kv: scoped key exceeds ${String(MAX_KEY_LENGTH)}-byte limit`);
+  }
+  return composed;
+};
+const toPutOptions = (options) => {
+  const out = {};
+  if (options.expiration !== void 0 && options.expirationTtl !== void 0) {
+    throw new LunoraError("INTERNAL", "@lunora/bindings/kv: `expiration` and `expirationTtl` are mutually exclusive");
+  }
+  if (options.expiration !== void 0) {
+    out.expiration = options.expiration;
+  }
+  if (options.expirationTtl !== void 0) {
+    out.expirationTtl = options.expirationTtl;
+  }
+  if (options.metadata !== void 0) {
+    out.metadata = options.metadata;
+  }
+  return Object.keys(out).length > 0 ? out : void 0;
+};
+const createKv = (options) => {
+  if (!options.namespace) {
+    throw new TypeError("@lunora/bindings/kv: `namespace` is required");
+  }
+  const { keyPrefix, namespace } = options;
+  if (keyPrefix !== void 0) {
+    validateKey(keyPrefix);
+  }
+  const resolve = (key) => {
+    if (keyPrefix === void 0) {
+      validateKey(key);
+      return key;
+    }
+    return scopeKey(keyPrefix, key);
+  };
+  const stripPrefix = (name) => {
+    if (keyPrefix === void 0) {
+      return name;
+    }
+    const trimmed = keyPrefix.endsWith("/") ? keyPrefix : `${keyPrefix}/`;
+    return name.startsWith(trimmed) ? name.slice(trimmed.length) : name;
+  };
+  const get = async (key, getOptions = {}) => {
+    const value = await namespace.get(resolve(key), { cacheTtl: getOptions.cacheTtl, type: "json" });
+    return value ?? null;
+  };
+  const getRaw = async (key, getOptions = {}) => {
+    const value = await namespace.get(resolve(key), { cacheTtl: getOptions.cacheTtl, type: getOptions.type ?? "text" });
+    return value ?? null;
+  };
+  const getWithMetadata = async (key, getOptions = {}) => {
+    const result = await namespace.getWithMetadata(resolve(key), { cacheTtl: getOptions.cacheTtl, type: "json" });
+    return { metadata: result.metadata ?? null, value: result.value ?? null };
+  };
+  const put = async (key, value, putOptions = {}) => {
+    const body = putOptions.raw ? value : JSON.stringify(value);
+    await namespace.put(resolve(key), body, toPutOptions(putOptions));
+  };
+  const deleteKey = async (key) => {
+    await namespace.delete(resolve(key));
+  };
+  const list = async (listOptions = {}) => {
+    if (listOptions.limit !== void 0 && (!Number.isInteger(listOptions.limit) || listOptions.limit <= 0)) {
+      throw new TypeError("@lunora/bindings/kv: `limit` must be a positive integer");
+    }
+    let { prefix } = listOptions;
+    if (prefix !== void 0) {
+      validatePrefix(prefix);
+    }
+    if (keyPrefix !== void 0) {
+      const base = keyPrefix.endsWith("/") ? keyPrefix : `${keyPrefix}/`;
+      prefix = listOptions.prefix === void 0 ? base : `${base}${listOptions.prefix}`;
+      validatePrefix(prefix);
+    }
+    const limit = listOptions.limit === void 0 ? void 0 : Math.min(listOptions.limit, MAX_LIST_LIMIT);
+    const result = await namespace.list({ cursor: listOptions.cursor, limit, prefix });
+    const keys = result.keys.map((entry) => {
+      return {
+        ...entry,
+        name: stripPrefix(entry.name)
+      };
+    });
+    return {
+      cursor: result.list_complete ? void 0 : result.cursor,
+      keys,
+      listComplete: result.list_complete
+    };
+  };
+  return {
+    delete: deleteKey,
+    get,
+    getRaw,
+    getWithMetadata,
+    list,
+    put
+  };
+};
+
+export { createKv, scopeKey };

package/dist/packem_shared/createKvIntrospector-Byk4GfsY.mjs

@@ -0,0 +1,77 @@
+import { LunoraError } from '@lunora/errors';
+
+const createKvIntrospector = (options) => {
+  const { namespaces } = options;
+  const resolveNamespace = (binding) => {
+    const ns = namespaces[binding];
+    if (!Object.hasOwn(namespaces, binding) || ns === void 0) {
+      throw new LunoraError("BAD_REQUEST", `@lunora/bindings/kv: no namespace registered under binding "${binding}"`);
+    }
+    return ns;
+  };
+  const listNamespaces = () => Promise.resolve(
+    Object.keys(namespaces).map((binding) => {
+      return { binding };
+    })
+  );
+  const listKeys = async (listOptions) => {
+    const ns = resolveNamespace(listOptions.namespace);
+    const result = await ns.list({ cursor: listOptions.cursor, limit: listOptions.limit, prefix: listOptions.prefix });
+    const keys = result.keys.map((entry) => {
+      return {
+        expiration: entry.expiration,
+        metadata: entry.metadata,
+        name: entry.name
+      };
+    });
+    return {
+      cursor: result.list_complete ? void 0 : result.cursor,
+      keys,
+      listComplete: result.list_complete
+    };
+  };
+  const getValue = async (getOptions) => {
+    const ns = resolveNamespace(getOptions.namespace);
+    const result = await ns.getWithMetadata(getOptions.key, "text");
+    return { metadata: result.metadata ?? null, value: result.value ?? null };
+  };
+  const putValue = async (putOptions) => {
+    const ns = resolveNamespace(putOptions.namespace);
+    await ns.put(putOptions.key, putOptions.value, {
+      expiration: putOptions.expiration,
+      expirationTtl: putOptions.expirationTtl,
+      metadata: putOptions.metadata
+    });
+  };
+  const deleteKey = async (deleteOptions) => {
+    const ns = resolveNamespace(deleteOptions.namespace);
+    await ns.delete(deleteOptions.key);
+  };
+  return {
+    deleteKey,
+    getValue,
+    listKeys,
+    listNamespaces,
+    putValue
+  };
+};
+const isKvNamespace = (value) => {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const candidate = value;
+  return typeof candidate.getWithMetadata === "function" && typeof candidate.list === "function" && typeof candidate.put === "function" && typeof candidate.delete === "function";
+};
+const createKvIntrospectorFromEnv = (env) => {
+  const namespaces = {};
+  if (typeof env === "object" && env !== null) {
+    for (const [binding, value] of Object.entries(env)) {
+      if (isKvNamespace(value)) {
+        namespaces[binding] = value;
+      }
+    }
+  }
+  return createKvIntrospector({ namespaces });
+};
+
+export { createKvIntrospector, createKvIntrospectorFromEnv };

package/dist/packem_shared/createPipelines-CfyJ6VGu.mjs

@@ -0,0 +1,10 @@
+const createPipelines = (options) => {
+  const { binding } = options;
+  return {
+    send: async (records) => {
+      await binding.send(Array.isArray(records) ? records : [records]);
+    }
+  };
+};
+
+export { createPipelines };

package/dist/packem_shared/createVectorAdminIntrospector-DuSvcBa5.mjs

@@ -0,0 +1,53 @@
+import { LunoraError } from '@lunora/errors';
+
+const MAX_TOP_K = 20;
+const DEFAULT_TOP_K = 10;
+const createVectorAdminIntrospector = (options) => {
+  const { embedders, indexes, registry } = options;
+  const listIndexes = async () => Promise.all(
+    registry.map(async (entry) => {
+      const binding = indexes[entry.name];
+      if (binding?.describe === void 0) {
+        return { ...entry };
+      }
+      try {
+        const details = await binding.describe();
+        return {
+          ...entry,
+          dimensions: entry.dimensions ?? details.dimensions,
+          processedUpToMutation: details.processedUpToMutation,
+          vectorsCount: details.vectorsCount
+        };
+      } catch {
+        return { ...entry };
+      }
+    })
+  );
+  const hasEmbedders = embedders !== void 0 && Object.keys(embedders).length > 0;
+  if (!hasEmbedders) {
+    return { listIndexes };
+  }
+  const queryIndex = async ({ name, text, topK }) => {
+    const binding = indexes[name];
+    if (!Object.hasOwn(indexes, name) || binding === void 0) {
+      throw new LunoraError("INTERNAL", `@lunora/bindings/vectors: no Vectorize binding registered for index "${name}"`);
+    }
+    const embed = embedders[name];
+    if (!Object.hasOwn(embedders, name) || embed === void 0) {
+      throw new LunoraError("INTERNAL", `@lunora/bindings/vectors: no embedder registered for index "${name}" — it lists read-only`);
+    }
+    const vector = await embed(text);
+    const result = await binding.query(vector, {
+      returnMetadata: "all",
+      topK: Math.min(topK ?? DEFAULT_TOP_K, MAX_TOP_K)
+    });
+    return {
+      matches: result.matches.map((match) => {
+        return { id: match.id, metadata: match.metadata, score: match.score };
+      })
+    };
+  };
+  return { listIndexes, queryIndex };
+};
+
+export { createVectorAdminIntrospector };

package/dist/packem_shared/createVectors-CTSrctiK.mjs

@@ -0,0 +1,95 @@
+import { LunoraError } from '@lunora/errors';
+import { c as concurrentMap, U as UPSERT_EMBED_CONCURRENCY } from './concurrent-CkCEVwqP.mjs';
+
+const resolveIndex = (indexes, name) => {
+  const index = indexes[name];
+  if (!Object.hasOwn(indexes, name) || index === void 0) {
+    throw new LunoraError(
+      "INTERNAL",
+      `@lunora/bindings/vectors: no index registered for "${name}". Known indexes: ${Object.keys(indexes).join(", ") || "(none)"}`
+    );
+  }
+  return index;
+};
+const toVector = async (input) => {
+  const values = await input.embed(input.input);
+  return {
+    id: input.id,
+    metadata: input.metadata,
+    namespace: input.namespace,
+    values
+  };
+};
+const MAX_TOP_K = 100;
+const MAX_TOP_K_WITH_VALUES = 20;
+const MAX_ID_BATCH = 1e3;
+const MAX_UPSERT_BATCH = 1e3;
+const createVectors = (options) => {
+  if (Object.keys(options.indexes).length === 0) {
+    throw new TypeError("@lunora/bindings/vectors: at least one index binding is required");
+  }
+  const upsert = async (indexName, input) => {
+    const index = resolveIndex(options.indexes, indexName);
+    const vector = await toVector(input);
+    return index.upsert([vector]);
+  };
+  const upsertMany = async (indexName, inputs) => {
+    const index = resolveIndex(options.indexes, indexName);
+    if (inputs.length > MAX_UPSERT_BATCH) {
+      throw new RangeError(
+        `@lunora/bindings/vectors: upsertMany batch exceeds ${String(MAX_UPSERT_BATCH)} (got ${String(inputs.length)}) — split across calls`
+      );
+    }
+    const vectors = await concurrentMap(inputs, UPSERT_EMBED_CONCURRENCY, toVector);
+    return index.upsert(vectors);
+  };
+  const query = async (indexName, input) => {
+    const index = resolveIndex(options.indexes, indexName);
+    const wantsHeavyPayload = input.returnValues === true || input.returnMetadata === "all";
+    const topKCeiling = wantsHeavyPayload ? MAX_TOP_K_WITH_VALUES : MAX_TOP_K;
+    if (input.topK !== void 0 && (!Number.isInteger(input.topK) || input.topK < 1 || input.topK > topKCeiling)) {
+      const reason = wantsHeavyPayload ? ' (lowered to 20 because returnValues/returnMetadata:"all" is set)' : "";
+      throw new RangeError(`@lunora/bindings/vectors: topK must be an integer in [1, ${String(topKCeiling)}]${reason} (got ${String(input.topK)})`);
+    }
+    let values;
+    if (input.vector && input.vector.length > 0) {
+      values = input.vector;
+    } else {
+      if (!input.embed || input.input === void 0) {
+        throw new TypeError("@lunora/bindings/vectors: query requires either `vector` or both `input` and `embed`");
+      }
+      values = await input.embed(input.input);
+    }
+    return index.query(values, {
+      filter: input.filter,
+      namespace: input.namespace,
+      returnMetadata: input.returnMetadata,
+      returnValues: input.returnValues,
+      topK: input.topK
+    });
+  };
+  const getByIds = async (indexName, ids) => {
+    const index = resolveIndex(options.indexes, indexName);
+    if (ids.length > MAX_ID_BATCH) {
+      throw new RangeError(`@lunora/bindings/vectors: getByIds accepts at most ${String(MAX_ID_BATCH)} ids (got ${String(ids.length)})`);
+    }
+    return index.getByIds(ids);
+  };
+  const deleteByIds = async (indexName, ids) => {
+    const index = resolveIndex(options.indexes, indexName);
+    if (ids.length > MAX_ID_BATCH) {
+      throw new RangeError(`@lunora/bindings/vectors: deleteByIds accepts at most ${String(MAX_ID_BATCH)} ids (got ${String(ids.length)})`);
+    }
+    return index.deleteByIds(ids);
+  };
+  const describe = async (indexName) => {
+    const index = resolveIndex(options.indexes, indexName);
+    if (!index.describe) {
+      throw new LunoraError("INTERNAL", `@lunora/bindings/vectors: binding for "${indexName}" does not implement describe()`);
+    }
+    return index.describe();
+  };
+  return { deleteByIds, describe, getByIds, query, upsert, upsertMany };
+};
+
+export { createVectors as default };

package/dist/pipelines/index.d.mts

@@ -0,0 +1,41 @@
+/**
+ * Structural types for the Cloudflare Pipelines write path (R2-backed streaming
+ * ingestion). Pipelines is the other "emit data to a sink" surface alongside
+ * Analytics Engine — telemetry/events out, no in-handler read-back. The binding
+ * is mirrored structurally (`*Like`) so a plain-object fake satisfies it in unit
+ * tests, like `@lunora/bindings/analytics`'s `AnalyticsEngineDatasetLike`.
+ */
+/** One Pipelines record — a JSON object matching the stream's schema. */
+type PipelineRecord = Record<string, unknown>;
+/**
+ * Minimal structural projection of workers-types' `Pipeline&lt;T>` binding. The
+ * real binding's `send` takes an array of records and resolves once accepted.
+ */
+interface PipelineBindingLike<T extends PipelineRecord = PipelineRecord> {
+  send: (records: T[]) => Promise<void>;
+}
+/**
+ * The write-side client bound to `ctx.pipelines` (the generated context imports
+ * this exact type as `import("@lunora/bindings/pipelines").PipelineClient`).
+ * Ingestion is durable, batched, and fire-and-forget — never read a record back
+ * in-handler.
+ */
+interface PipelineClient<T extends PipelineRecord = PipelineRecord> {
+  /** Ingest one record or an array of records into the R2-backed sink. */
+  send: (records: T | T[]) => Promise<void>;
+}
+/**
+ * Wrap a Cloudflare Pipelines binding in the write-side {@link PipelineClient}
+ * bound to `ctx.pipelines`. The binding is `env.PIPELINES` (the `pipelines`
+ * binding the config layer recognizes; the remote pipeline name is minted with
+ * `wrangler pipelines create`).
+ *
+ * Ingestion is durable and batched: `send` accepts one record or an array and
+ * resolves once Cloudflare has accepted them for delivery to the R2-backed sink.
+ * There is no in-handler read-back — this is a fire-and-forget egress path, so
+ * it belongs on ActionCtx only (external I/O), mirroring `ctx.images`.
+ */
+declare const createPipelines: <T extends PipelineRecord = PipelineRecord>(options: {
+  binding: PipelineBindingLike<T>;
+}) => PipelineClient<T>;
+export { type PipelineBindingLike, type PipelineClient, type PipelineRecord, createPipelines };

package/dist/pipelines/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Structural types for the Cloudflare Pipelines write path (R2-backed streaming
+ * ingestion). Pipelines is the other "emit data to a sink" surface alongside
+ * Analytics Engine — telemetry/events out, no in-handler read-back. The binding
+ * is mirrored structurally (`*Like`) so a plain-object fake satisfies it in unit
+ * tests, like `@lunora/bindings/analytics`'s `AnalyticsEngineDatasetLike`.
+ */
+/** One Pipelines record — a JSON object matching the stream's schema. */
+type PipelineRecord = Record<string, unknown>;
+/**
+ * Minimal structural projection of workers-types' `Pipeline&lt;T>` binding. The
+ * real binding's `send` takes an array of records and resolves once accepted.
+ */
+interface PipelineBindingLike<T extends PipelineRecord = PipelineRecord> {
+  send: (records: T[]) => Promise<void>;
+}
+/**
+ * The write-side client bound to `ctx.pipelines` (the generated context imports
+ * this exact type as `import("@lunora/bindings/pipelines").PipelineClient`).
+ * Ingestion is durable, batched, and fire-and-forget — never read a record back
+ * in-handler.
+ */
+interface PipelineClient<T extends PipelineRecord = PipelineRecord> {
+  /** Ingest one record or an array of records into the R2-backed sink. */
+  send: (records: T | T[]) => Promise<void>;
+}
+/**
+ * Wrap a Cloudflare Pipelines binding in the write-side {@link PipelineClient}
+ * bound to `ctx.pipelines`. The binding is `env.PIPELINES` (the `pipelines`
+ * binding the config layer recognizes; the remote pipeline name is minted with
+ * `wrangler pipelines create`).
+ *
+ * Ingestion is durable and batched: `send` accepts one record or an array and
+ * resolves once Cloudflare has accepted them for delivery to the R2-backed sink.
+ * There is no in-handler read-back — this is a fire-and-forget egress path, so
+ * it belongs on ActionCtx only (external I/O), mirroring `ctx.images`.
+ */
+declare const createPipelines: <T extends PipelineRecord = PipelineRecord>(options: {
+  binding: PipelineBindingLike<T>;
+}) => PipelineClient<T>;
+export { type PipelineBindingLike, type PipelineClient, type PipelineRecord, createPipelines };

package/dist/pipelines/index.mjs

@@ -0,0 +1 @@
+export { createPipelines } from '../packem_shared/createPipelines-CfyJ6VGu.mjs';