Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
feat(sketchfab): add a dry-run-first backfill that tags pre-2026-10-09 uploads createdwithai, with tests and docs
nirholas309a22c284c7
diff --git a/docs/sketchfab.md b/docs/sketchfab.mdindex b35bff5e9..fc9e07fa7 100644--- a/docs/sketchfab.md+++ b/docs/sketchfab.md@@ -91,3 +91,21 @@ State lives in the `sketchfab_uploads` table (one row per creation:when the brand-safety gate parked it). Code:[`api/cron/sketchfab-showcase.js`](https://github.com/nirholas/three.ws/blob/main/api/cron/sketchfab-showcase.js)and [`api/_lib/sketchfab.js`](https://github.com/nirholas/three.ws/blob/main/api/_lib/sketchfab.js).++## Backfilling the AI tag on older uploads++New uploads carry `createdwithai` from 2026-10-09 (commit `919e54e82`). Models the account+published before that date do not, and Sketchfab can file them as "Human Created". The backfill+script adds the tag to every model that lacks it and changes nothing else:++```bash+eval "$(node scripts/read-service-env.mjs '^SKETCHFAB_API_TOKEN$')"+node scripts/sketchfab-retag.mjs # dry run: prints exactly what would change+node scripts/sketchfab-retag.mjs --apply # PATCH /v3/models/{uid} for each model missing the tag+node scripts/sketchfab-retag.mjs # second dry run: must report 0 to change+```++Without a token, `--user <username>` runs a read-only dry run against the public listing. Sketchfab+replaces the whole tag list on PATCH, so each request carries the model's existing tags in order+plus `createdwithai`, and nothing else. A `429` is retried after Sketchfab's `Retry-After`.+Tests: `tests/sketchfab-retag.test.js`.diff --git a/scripts/sketchfab-retag.mjs b/scripts/sketchfab-retag.mjsnew file mode 100644index 000000000..7065a68e4--- /dev/null+++ b/scripts/sketchfab-retag.mjs@@ -0,0 +1,128 @@+#!/usr/bin/env node+// Backfill Sketchfab's "Created With AI" tag (slug `createdwithai`) onto models the+// three.ws showcase account uploaded before commit 919e54e82 (2026-10-09), when new+// uploads started carrying it. Dry run by default; --apply performs the edits.+//+// USAGE+// node scripts/sketchfab-retag.mjs --user <sketchfab-username> # dry run, public listing+// SKETCHFAB_API_TOKEN=... node scripts/sketchfab-retag.mjs # dry run, own account (/v3/me/models)+// SKETCHFAB_API_TOKEN=... node scripts/sketchfab-retag.mjs --apply # make the changes+//+// The token is the same Data API token the showcase cron uses. Get it with:+// eval "$(node scripts/read-service-env.mjs '^SKETCHFAB_API_TOKEN$')"+//+// Only the `tags` field is sent. Sketchfab's PATCH /v3/models/{uid} replaces the whole+// tag list, so the request carries every existing tag plus `createdwithai`, in the+// original order, and nothing else about the model is touched.++import { pathToFileURL } from 'node:url';++export const AI_TAG = 'createdwithai';+const API_BASE = 'https://api.sketchfab.com/v3';+const PAGE_SIZE = 24;+const MAX_RETRIES = 5;++export function tagNames(model) {+ return (model.tags || []).map((t) => (typeof t === 'string' ? t : t.name)).filter(Boolean);+}++export function hasAiTag(model) {+ return tagNames(model).some((n) => n.toLowerCase() === AI_TAG);+}++// The exact PATCH body for a model, or null when it already carries the tag.+export function buildPatch(model) {+ if (hasAiTag(model)) return null;+ return { tags: [...tagNames(model), AI_TAG] };+}++// Plan the whole backfill: what would change and what is already compliant.+export function planRetag(models) {+ const changes = [];+ let compliant = 0;+ for (const m of models) {+ const body = buildPatch(m);+ if (body) changes.push({ uid: m.uid, name: m.name, url: m.viewerUrl, body });+ else compliant++;+ }+ return { changes, compliant, total: models.length };+}++function sleep(ms) {+ return new Promise((r) => setTimeout(r, ms));+}++// fetch that honours Sketchfab's 429 Retry-After (seconds) with a bounded retry budget.+export async function sfFetch(url, init = {}, fetchImpl = fetch, wait = sleep) {+ for (let attempt = 0; ; attempt++) {+ const res = await fetchImpl(url, init);+ if (res.status !== 429 || attempt >= MAX_RETRIES) return res;+ const retryAfter = Number(res.headers.get('retry-after'));+ await wait((Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter : 2 ** attempt) * 1000);+ }+}++export async function listModels({ token, user }, fetchImpl = fetch, wait = sleep) {+ const headers = token ? { authorization: `Token ${token}` } : {};+ let url = token && !user+ ? `${API_BASE}/me/models?count=${PAGE_SIZE}`+ : `${API_BASE}/models?user=${encodeURIComponent(user)}&count=${PAGE_SIZE}`;+ const models = [];+ while (url) {+ const res = await sfFetch(url, { headers }, fetchImpl, wait);+ if (!res.ok) throw new Error(`list failed: ${res.status} ${(await res.text()).slice(0, 200)}`);+ const body = await res.json();+ models.push(...(body.results || []));+ url = body.next || null;+ }+ return models;+}++export async function applyChange(change, token, fetchImpl = fetch, wait = sleep) {+ const res = await sfFetch(+ `${API_BASE}/models/${encodeURIComponent(change.uid)}`,+ {+ method: 'PATCH',+ headers: { authorization: `Token ${token}`, 'content-type': 'application/json' },+ body: JSON.stringify(change.body),+ },+ fetchImpl,+ wait,+ );+ if (res.status !== 200 && res.status !== 204) {+ throw new Error(`patch ${change.uid} failed: ${res.status} ${(await res.text()).slice(0, 200)}`);+ }+}++async function main() {+ const argv = process.argv.slice(2);+ const apply = argv.includes('--apply');+ const ui = argv.indexOf('--user');+ const user = ui >= 0 ? argv[ui + 1] : null;+ const token = process.env.SKETCHFAB_API_TOKEN || null;+ if (!token && !user) {+ console.error('Set SKETCHFAB_API_TOKEN (own account) or pass --user <username> (public dry run).');+ process.exit(2);+ }+ if (apply && !token) {+ console.error('--apply needs SKETCHFAB_API_TOKEN.');+ process.exit(2);+ }++ const models = await listModels({ token, user });+ const plan = planRetag(models);+ console.log(`${plan.total} models listed, ${plan.compliant} already tagged, ${plan.changes.length} to change.`);+ for (const c of plan.changes) {+ console.log(`${apply ? 'PATCH' : 'would PATCH'} ${c.uid} "${c.name}" tags -> ${JSON.stringify(c.body.tags)}`);+ if (apply) await applyChange(c, token);+ }+ if (!apply && plan.changes.length) console.log('Dry run. Re-run with --apply to make these changes.');+ if (apply) console.log(`Applied ${plan.changes.length} changes. Re-run without --apply: it should report 0 to change.`);+}++if (import.meta.url === pathToFileURL(process.argv[1] || '').href) {+ main().catch((e) => {+ console.error(e.message);+ process.exit(1);+ });+}diff --git a/tests/sketchfab-retag.test.js b/tests/sketchfab-retag.test.jsnew file mode 100644index 000000000..8712b2380--- /dev/null+++ b/tests/sketchfab-retag.test.js@@ -0,0 +1,65 @@+import { describe, it, expect } from 'vitest';+import {+ AI_TAG,+ buildPatch,+ planRetag,+ sfFetch,+ listModels,+ applyChange,+} from '../scripts/sketchfab-retag.mjs';++const tag = (n) => ({ name: n, slug: n });++describe('sketchfab-retag', () => {+ it('adds createdwithai after the existing tags and sends only tags', () => {+ const body = buildPatch({ uid: 'a', tags: [tag('threews'), tag('ai-generated')] });+ expect(body).toEqual({ tags: ['threews', 'ai-generated', AI_TAG] });+ });++ it('returns null when the tag is already present (case-insensitive)', () => {+ expect(buildPatch({ uid: 'a', tags: [tag('CreatedWithAI')] })).toBeNull();+ });++ it('plans only the models missing the tag', () => {+ const plan = planRetag([+ { uid: '1', name: 'x', tags: [tag('a')] },+ { uid: '2', name: 'y', tags: [tag(AI_TAG)] },+ { uid: '3', name: 'z', tags: [] },+ ]);+ expect(plan.total).toBe(3);+ expect(plan.compliant).toBe(1);+ expect(plan.changes.map((c) => c.uid)).toEqual(['1', '3']);+ });++ it('waits Retry-After on 429 then succeeds', async () => {+ const waits = [];+ let n = 0;+ const f = async () =>+ n++ === 0+ ? { status: 429, headers: new Headers({ 'retry-after': '3' }) }+ : { status: 200, headers: new Headers() };+ const res = await sfFetch('u', {}, f, async (ms) => waits.push(ms));+ expect(res.status).toBe(200);+ expect(waits).toEqual([3000]);+ });++ it('follows pagination and sends an authenticated PATCH with a tags-only body', async () => {+ const calls = [];+ const f = async (url, init = {}) => {+ calls.push({ url, init });+ if (url.includes('cursor=2'))+ return { ok: true, status: 200, headers: new Headers(), json: async () => ({ results: [{ uid: '2' }], next: null }) };+ if (init.method === 'PATCH') return { ok: true, status: 204, headers: new Headers() };+ return { ok: true, status: 200, headers: new Headers(), json: async () => ({ results: [{ uid: '1' }], next: 'https://api.sketchfab.com/v3/me/models?cursor=2' }) };+ };+ const models = await listModels({ token: 't' }, f);+ expect(models.map((m) => m.uid)).toEqual(['1', '2']);+ expect(calls[0].url).toContain('/me/models');+ await applyChange({ uid: 'abc', body: { tags: ['x', AI_TAG] } }, 't', f);+ const patch = calls.at(-1);+ expect(patch.init.method).toBe('PATCH');+ expect(patch.url).toBe('https://api.sketchfab.com/v3/models/abc');+ expect(patch.init.headers.authorization).toBe('Token t');+ expect(JSON.parse(patch.init.body)).toEqual({ tags: ['x', AI_TAG] });+ });+});