@aura3d/asset-index 1.0.5

package/dist/ranking.d.ts

@@ -0,0 +1,6 @@
+import type { AuraCanonicalAsset } from "./CanonicalAsset.js";
+import type { ResolveConstraints } from "./SourceAdapter.js";
+export declare function scoreAsset(asset: AuraCanonicalAsset, text: string): number;
+/** True when an asset satisfies every supplied constraint. */
+export declare function matchesConstraints(asset: AuraCanonicalAsset, constraints: ResolveConstraints | undefined): boolean;
+//# sourceMappingURL=ranking.d.ts.map

package/dist/ranking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ranking.d.ts","sourceRoot":"","sources":["../../../../packages/asset-index/src/ranking.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAoB7D,wBAAgB,UAAU,CAAC,KAAK,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAoB1E;AAED,8DAA8D;AAC9D,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,kBAAkB,EACzB,WAAW,EAAE,kBAAkB,GAAG,SAAS,GAC1C,OAAO,CAkCT"}

package/dist/ranking.js

@@ -0,0 +1,71 @@
+/**
+ * Lightweight, dependency-free relevance scoring for v1.
+ *
+ * Scores an asset against the query terms by weighted field hits:
+ *   title match  > tag match  > description match.
+ *
+ * This is deliberately a keyword baseline. The intended upgrade is vector
+ * embeddings (semantic match on `title`+`tags`+`description`); the federation
+ * layer calls `scoreAsset` through a single seam so that swap is local.
+ */
+function queryTerms(text) {
+    return text
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((t) => t.length > 1);
+}
+export function scoreAsset(asset, text) {
+    const terms = queryTerms(text);
+    if (terms.length === 0)
+        return 0;
+    const title = asset.title.toLowerCase();
+    const description = (asset.description ?? "").toLowerCase();
+    const tagSet = new Set(asset.tags);
+    let score = 0;
+    for (const term of terms) {
+        if (title.includes(term))
+            score += 5;
+        if (tagSet.has(term))
+            score += 3;
+        if (description.includes(term))
+            score += 1;
+    }
+    // Reward breadth of coverage so an asset hitting many query terms ranks above
+    // one that hits a single term repeatedly.
+    const covered = terms.filter((t) => title.includes(t) || tagSet.has(t) || description.includes(t)).length;
+    return score + covered * 2;
+}
+/** True when an asset satisfies every supplied constraint. */
+export function matchesConstraints(asset, constraints) {
+    if (!constraints)
+        return true;
+    if (constraints.redistributableOnly) {
+        if (asset.access !== "direct-download" || !asset.license.verified || !asset.license.redistributable) {
+            return false;
+        }
+    }
+    if (constraints.format && asset.format !== constraints.format) {
+        return false;
+    }
+    if (constraints.license && constraints.license.length > 0) {
+        const family = asset.license.spdx.startsWith("CC0")
+            ? "CC0"
+            : asset.license.spdx.startsWith("CC-BY")
+                ? "CC-BY"
+                : null;
+        if (!family || !constraints.license.includes(family))
+            return false;
+    }
+    if (typeof constraints.maxTriangles === "number" &&
+        typeof asset.triangles === "number" &&
+        asset.triangles > constraints.maxTriangles) {
+        return false;
+    }
+    if (typeof constraints.animated === "boolean" &&
+        typeof asset.hasAnimations === "boolean" &&
+        asset.hasAnimations !== constraints.animated) {
+        return false;
+    }
+    return true;
+}
+//# sourceMappingURL=ranking.js.map

package/dist/ranking.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ranking.js","sourceRoot":"","sources":["../../../../packages/asset-index/src/ranking.ts"],"names":[],"mappings":"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"}

package/dist/refresh.d.ts

@@ -0,0 +1,54 @@
+import type { AdapterContext, SourceAdapter } from "./SourceAdapter.js";
+import type { AuraCanonicalAsset } from "./CanonicalAsset.js";
+/**
+ * The minimal write surface {@link refreshIndex} needs from a store. The
+ * file-backed `IndexStore` satisfies this structurally, and so does a
+ * storage-backed implementation (e.g. an R2-backed store in a Cloudflare
+ * Worker) — so the cron logic is decoupled from `node:fs` and runs unchanged in
+ * a serverless runtime.
+ */
+export interface WritableAssetIndex {
+    getWatermark(source: string): string | null;
+    setWatermark(source: string, watermark: string): void;
+    upsertMany(source: string, assets: Iterable<AuraCanonicalAsset>): void;
+    save(updatedAt?: string): Promise<void>;
+}
+/**
+ * Outcome of a single {@link refreshIndex} pass.
+ *
+ * - `upserted` is the total number of canonical records written across sources.
+ * - `perSource` breaks that down by adapter id (0 for an adapter that failed).
+ * - `warnings` collects per-adapter failures so one flaky source cannot collapse
+ *   the whole refresh; the store is still saved with whatever succeeded.
+ */
+export interface RefreshResult {
+    readonly upserted: number;
+    readonly perSource: Record<string, number>;
+    readonly warnings: string[];
+}
+export interface RefreshOptions {
+    /**
+     * Caller-supplied timestamp threaded into {@link IndexStore.save} so the
+     * refresh stays deterministic (no internal wall-clock read). Typically an
+     * ISO-8601 string captured by the cron at the top of the run.
+     */
+    readonly updatedAt?: string;
+}
+/**
+ * Refresh the durable asset index from every adapter, then persist it.
+ *
+ * This is the engine of the "live" catalog: a scheduled cron / CI job calls
+ * {@link refreshIndex} on a cadence to pull new/changed assets into the
+ * {@link IndexStore}, and the resolver reads candidates back out of that same
+ * store at query time (decoupling user-facing latency from source fetches).
+ *
+ * For each adapter:
+ *  - if it exposes `fetchSince`, call it with the source's stored watermark to
+ *    pull only what changed, then advance the watermark;
+ *  - otherwise fall back to a broad `search({ text: "" })` to (re)load its
+ *    catalog.
+ * Failures are caught per-adapter and recorded as warnings; surviving results
+ * are upserted (last-write-wins by id) and the store is saved once at the end.
+ */
+export declare function refreshIndex(adapters: readonly SourceAdapter[], store: WritableAssetIndex, ctx: AdapterContext, opts?: RefreshOptions): Promise<RefreshResult>;
+//# sourceMappingURL=refresh.d.ts.map

package/dist/refresh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refresh.d.ts","sourceRoot":"","sources":["../../../../packages/asset-index/src/refresh.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAE9D;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC5C,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACtD,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,kBAAkB,CAAC,GAAG,IAAI,CAAC;IACvE,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3C,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,SAAS,aAAa,EAAE,EAClC,KAAK,EAAE,kBAAkB,EACzB,GAAG,EAAE,cAAc,EACnB,IAAI,GAAE,cAAmB,GACxB,OAAO,CAAC,aAAa,CAAC,CA8BxB"}

package/dist/refresh.js

@@ -0,0 +1,48 @@
+/**
+ * Refresh the durable asset index from every adapter, then persist it.
+ *
+ * This is the engine of the "live" catalog: a scheduled cron / CI job calls
+ * {@link refreshIndex} on a cadence to pull new/changed assets into the
+ * {@link IndexStore}, and the resolver reads candidates back out of that same
+ * store at query time (decoupling user-facing latency from source fetches).
+ *
+ * For each adapter:
+ *  - if it exposes `fetchSince`, call it with the source's stored watermark to
+ *    pull only what changed, then advance the watermark;
+ *  - otherwise fall back to a broad `search({ text: "" })` to (re)load its
+ *    catalog.
+ * Failures are caught per-adapter and recorded as warnings; surviving results
+ * are upserted (last-write-wins by id) and the store is saved once at the end.
+ */
+export async function refreshIndex(adapters, store, ctx, opts = {}) {
+    const perSource = {};
+    const warnings = [];
+    let upserted = 0;
+    for (const adapter of adapters) {
+        perSource[adapter.id] = 0;
+        try {
+            if (adapter.fetchSince) {
+                const { watermark, assets } = await adapter.fetchSince(store.getWatermark(adapter.id), ctx);
+                store.upsertMany(adapter.id, assets);
+                store.setWatermark(adapter.id, watermark);
+                perSource[adapter.id] = assets.length;
+                upserted += assets.length;
+            }
+            else {
+                const assets = await adapter.search({ text: "" }, ctx);
+                store.upsertMany(adapter.id, assets);
+                perSource[adapter.id] = assets.length;
+                upserted += assets.length;
+            }
+        }
+        catch (err) {
+            warnings.push(`${adapter.id}: ${errorMessage(err)}`);
+        }
+    }
+    await store.save(opts.updatedAt);
+    return { upserted, perSource, warnings };
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=refresh.js.map

package/dist/refresh.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refresh.js","sourceRoot":"","sources":["../../../../packages/asset-index/src/refresh.ts"],"names":[],"mappings":"AAwCA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,QAAkC,EAClC,KAAyB,EACzB,GAAmB,EACnB,OAAuB,EAAE;IAEzB,MAAM,SAAS,GAA2B,EAAE,CAAC;IAC7C,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,IAAI,QAAQ,GAAG,CAAC,CAAC;IAEjB,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;QAC1B,IAAI,CAAC;YACH,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;gBACvB,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,MAAM,OAAO,CAAC,UAAU,CACpD,KAAK,CAAC,YAAY,CAAC,OAAO,CAAC,EAAE,CAAC,EAC9B,GAAG,CACJ,CAAC;gBACF,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;gBACrC,KAAK,CAAC,YAAY,CAAC,OAAO,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;gBAC1C,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC;gBACtC,QAAQ,IAAI,MAAM,CAAC,MAAM,CAAC;YAC5B,CAAC;iBAAM,CAAC;gBACN,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC;gBACvD,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;gBACrC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC;gBACtC,QAAQ,IAAI,MAAM,CAAC,MAAM,CAAC;YAC5B,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,QAAQ,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,EAAE,KAAK,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACvD,CAAC;IACH,CAAC;IAED,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACjC,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC;AAC3C,CAAC;AAED,SAAS,YAAY,CAAC,GAAY;IAChC,OAAO,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AAC1D,CAAC"}

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@aura3d/asset-index",
+  "version": "1.0.5",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}