{"_id":"@authoritas-ace/ace-sdk","_rev":"3-e9d22567f004597be8f5fc36da2d9c95","name":"@authoritas-ace/ace-sdk","dist-tags":{"latest":"2.0.0"},"versions":{"1.0.0":{"name":"@authoritas-ace/ace-sdk","version":"1.0.0","keywords":["ace","authoritas","feed","enrichment","content","api","sdk","commerce"],"license":"MIT","_id":"@authoritas-ace/ace-sdk@1.0.0","maintainers":[{"name":"authoritas-ace","email":"marketing@authoritas.com"}],"dist":{"shasum":"21a97199b71e34bc610cfa8a6c3aee4db8f80813","tarball":"https://registry.npmjs.org/@authoritas-ace/ace-sdk/-/ace-sdk-1.0.0.tgz","fileCount":11,"integrity":"sha512-VDbmHWTxzzk1zyBNBEo151cJuMiAy7keygbkGV8+aNKbouFmQl/usr+vxpXpFoSIMf5FvhFxe7wR6ZDtyIJ+vQ==","signatures":[{"sig":"MEQCIDajNqkFdzI6rKVG3zkFmbXx+QqHdx16jgYN5FmFUKmWAiBUjwRiliqdTqhuUdZYe6pgtdhDpWfGvE900tayvp7GmQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":18451},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"}},"gitHead":"7ed7c68608db74af71ede90ee73bef7f39d52a18","scripts":{"build":"tsc","prepare":"npm run build"},"_npmUser":{"name":"authoritas-ace","email":"marketing@authoritas.com"},"_npmVersion":"10.9.3","description":"TypeScript client for ACE (Agentic Commerce Engine) API: feed enrichment, content generation, context rules, language detection","directories":{},"_nodeVersion":"22.20.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5","@types/node":"^20"},"_npmOperationalInternal":{"tmp":"tmp/ace-sdk_1.0.0_1772465661303_0.7309069533074464","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@authoritas-ace/ace-sdk","version":"1.0.1","keywords":["ace","authoritas","feed","enrichment","content","api","sdk","commerce"],"license":"MIT","_id":"@authoritas-ace/ace-sdk@1.0.1","maintainers":[{"name":"authoritas-ace","email":"marketing@authoritas.com"}],"dist":{"shasum":"db270e531490d9133f1c527b3de84f185b8feaab","tarball":"https://registry.npmjs.org/@authoritas-ace/ace-sdk/-/ace-sdk-1.0.1.tgz","fileCount":11,"integrity":"sha512-ZpubJZ9sqBrl7zNb8SG4yDeh7061d6RjkT6oe4XW25BH8EyPMipjoAah6E+9TDOcZr500z4BIJOmcSvmhRs0LQ==","signatures":[{"sig":"MEUCIQCc781QTUydQ5YC8hFjZnZffh1fa3mRYztE3q24VjXJmAIgcFhi2f1Sh5ed6CgWdEdDiNtchTyrCUIcrxdfdrXxcYM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":19971},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"}},"gitHead":"7ed7c68608db74af71ede90ee73bef7f39d52a18","scripts":{"build":"tsc","prepare":"npm run build"},"_npmUser":{"name":"authoritas-ace","email":"marketing@authoritas.com"},"_npmVersion":"10.9.3","description":"TypeScript client for ACE (Agentic Commerce Engine) API: feed enrichment, content generation, context rules, language detection","directories":{},"_nodeVersion":"22.20.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5","@types/node":"^20"},"_npmOperationalInternal":{"tmp":"tmp/ace-sdk_1.0.1_1772465796893_0.26301753130247785","host":"s3://npm-registry-packages-npm-production"}},"2.0.0":{"name":"@authoritas-ace/ace-sdk","version":"2.0.0","description":"TypeScript client for the ACE (Agentic Commerce Engine) v1 API: contextual enrichment, durable jobs, projects, experiments, webhooks","type":"module","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"}},"scripts":{"build":"tsc","prepare":"npm run build"},"keywords":["ace","authoritas","feed","enrichment","content","api","sdk","commerce"],"license":"MIT","engines":{"node":">=18"},"publishConfig":{"access":"public"},"devDependencies":{"@types/node":"^20","typescript":"^5"},"_id":"@authoritas-ace/ace-sdk@2.0.0","_nodeVersion":"22.22.3","_npmVersion":"10.9.8","dist":{"integrity":"sha512-lyLMxpb3vRCiiJzDtJEAya4YLRswQv9KsNpgYXe8ddNIoSdbvVlWZzlcIsbN6/0HnrCxmnzU5IVpO2Kn5sHvGA==","shasum":"33e573bcd7441a2abcb923d98d2ebc773152a577","tarball":"https://registry.npmjs.org/@authoritas-ace/ace-sdk/-/ace-sdk-2.0.0.tgz","fileCount":11,"unpackedSize":50640,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCID+3vXUxXrxGCHrcAC6qlF3CfiI3KD0N4fidrxYs71fIAiAEhcDaT6dTglMGP+nXzLSgCu7oqdMex71QGLIqvRpqsw=="}]},"_npmUser":{"name":"authoritas-ace","email":"marketing@authoritas.com"},"directories":{},"maintainers":[{"name":"authoritas-ace","email":"marketing@authoritas.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ace-sdk_2.0.0_1785483763446_0.5413649813503556"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-02T15:34:21.223Z","modified":"2026-07-31T07:42:43.732Z","1.0.0":"2026-03-02T15:34:21.490Z","1.0.1":"2026-03-02T15:36:37.036Z","2.0.0":"2026-07-31T07:42:43.592Z"},"license":"MIT","keywords":["ace","authoritas","feed","enrichment","content","api","sdk","commerce"],"description":"TypeScript client for the ACE (Agentic Commerce Engine) v1 API: contextual enrichment, durable jobs, projects, experiments, webhooks","maintainers":[{"name":"authoritas-ace","email":"marketing@authoritas.com"}],"readme":"# ACE SDK\n\nThe official JavaScript and TypeScript client for **ACE** (Agentic Commerce Engine). Use it in Node.js apps, scripts, or serverless functions to run the Contextual Enrichment Engine, track durable jobs, and manage your projects, experiments and webhooks.\n\n**New to ACE?** Start at [ace.authoritas.com](https://ace.authoritas.com), or read the [SDK guide](https://ace.authoritas.com/docs/sdk) for the long-form version of this page.\n\n## Install\n\n```bash\nnpm install @authoritas-ace/ace-sdk\n```\n\nNode 18 or newer. ESM only.\n\n## Create a client\n\n```ts\nimport { createClient } from \"@authoritas-ace/ace-sdk\";\n\nconst ace = createClient({\n  baseUrl: \"https://ace.authoritas.com\",\n  apiKey: process.env.ACE_API_KEY, // ace_live_... or ace_test_...\n});\n```\n\nCreate a key under **Settings, Developer console, Keys**. `health()` is the only method that works without one.\n\n## How results are shaped\n\nEvery method resolves to an `ApiResult<T>`. Nothing throws on an API error, so you get `error` instead of `data`, plus the HTTP status:\n\n```ts\ninterface ApiResult<T> {\n  data?: T;\n  error?: { code: string; message: string; details?: unknown };\n  status: number;\n  meta?: { pagination?: { page: number; pageSize: number; total: number; totalPages: number } };\n}\n```\n\nCheck `error` yourself, or use `assertOk` to turn a failure into a thrown `AceApiError`:\n\n```ts\nimport { assertOk, AceApiError } from \"@authoritas-ace/ace-sdk\";\n\ntry {\n  const res = await ace.usage();\n  assertOk(res);\n  console.log(res.data.credits.balance); // res.data is defined past this point\n} catch (err) {\n  if (err instanceof AceApiError) console.error(err.code, err.status, err.message);\n}\n```\n\n## Contextual Enrichment Engine\n\nThree methods, matching the three engine endpoints. Each takes a `source`, which is either inline products or a connected store.\n\n```ts\n// 1. Generate the contextual rules for a product set.\nconst rules = await ace.enrichment.rules({\n  source: {\n    type: \"inline\",\n    products: [{ id: \"sku-1\", title: \"Merino base layer\", category: \"Outdoor\" }],\n  },\n  creativityLevel: 3,\n});\n\n// 2. Generate content grounded in those rules.\nconst content = await ace.enrichment.content({\n  source: { type: \"inline\", products: [{ id: \"sku-1\", title: \"Merino base layer\" }] },\n  contentTypes: [\"product-description\", \"meta-tags\", \"jsonld-schema\"],\n  rules: rules.data,\n});\n\n// 3. Or run both steps in one call.\nconst pipeline = await ace.enrichment.pipeline({\n  source: { type: \"inline\", products: [{ id: \"sku-1\", title: \"Merino base layer\" }] },\n  contentTypes: [\"product-description\", \"meta-tags\"],\n});\n```\n\nA product needs only `id` and `title`. Extra keys you pass through (brand, price, tags, attributes) become grounding signal.\n\nWrite methods take an idempotency key, so a retried request reuses the original job instead of starting a second one:\n\n```ts\nawait ace.enrichment.pipeline(body, { idempotencyKey: \"nightly-2026-07-29\" });\n```\n\n## Jobs\n\nA large `content` or `pipeline` request runs asynchronously and returns a job envelope. Poll it, or let the SDK poll for you.\n\n```ts\nconst started = await ace.enrichment.pipeline({ source, contentTypes: [\"product-description\"] });\nassertOk(started);\n\nconst finished = await ace.jobs.wait(started.data.id, { pollMs: 2000, timeoutMs: 300_000 });\nconst results = await ace.jobs.results(started.data.id, { page: 1, pageSize: 50 });\n```\n\n| Method | What it does |\n|--------|--------------|\n| `ace.jobs.list({ kind, status, storeId, page, pageSize })` | List jobs, newest first |\n| `ace.jobs.get(id)` | One job with its status and result |\n| `ace.jobs.results(id, { page, pageSize })` | Paginated per-product results |\n| `ace.jobs.cancel(id)` | Cancel a queued or running job |\n| `ace.jobs.wait(id, { pollMs, timeoutMs })` | Poll until terminal. Returns a `TIMEOUT` error if the cap elapses |\n\n## Projects\n\n```ts\nawait ace.projects.list();                                 // scoped keys see only their project\nawait ace.projects.get(id);\nawait ace.projects.create({ name: \"Autumn catalogue\" });    // integration_type defaults to \"feeds\"\nawait ace.projects.update(id, { description: \"Q4 push\" });\nawait ace.projects.remove(id);\n```\n\n## Experiments\n\nEvery experiments call is project-scoped, so `projectId` is required throughout. On `create` it travels in the body; everywhere else it is a scope argument.\n\n```ts\nawait ace.experiments.list({ projectId });\nawait ace.experiments.get(id, { projectId });\nawait ace.experiments.create({ projectId, name: \"PDP copy A/B\" });\nawait ace.experiments.update(id, { status: \"running\" }, { projectId });\nawait ace.experiments.remove(id, { projectId });\n```\n\n## Webhooks\n\n```ts\nconst hook = await ace.webhooks.create({\n  url: \"https://example.com/hooks/ace\",  // https is required\n  events: [\"enrichment.job.succeeded\", \"enrichment.job.failed\"],\n});\n\nawait ace.webhooks.list();\nawait ace.webhooks.update(id, { is_active: false });\nawait ace.webhooks.remove(id);\n\n// Delivery log. Page counts arrive in result.meta.pagination.\nconst log = await ace.webhooks.deliveries(id, { status: \"failed\", pageSize: 50 });\n```\n\nEach subscription carries a `secret`. Verify the signature header on your endpoint against it before trusting a payload.\n\n## Utilities, usage and feeds\n\nLanguage detection is unbilled and the scorers are pure functions, so none of these consume credits.\n\n```ts\nawait ace.utils.language({ products });          // dominant locale + confidence\nawait ace.utils.agenticReadiness({ products });  // per-product readiness + summary\nawait ace.utils.reviewQuality({ items });        // weighted overall score per item\n\nawait ace.usage();                               // credits, rate limit, job counts, test quota\nawait ace.feeds.list({ projectId });\nawait ace.feeds.get(feedId);\n```\n\n`testQuota` is present only for `ace_test_` keys.\n\n## Escape hatch\n\nAny endpoint without a typed wrapper is still reachable, with auth and error handling applied:\n\n```ts\nawait ace.get(\"/api/v1/openapi\");\nawait ace.post(\"/api/v1/some/endpoint\", body);\nawait ace.put(\"/api/v1/some/endpoint/id\", body);\nawait ace.del(\"/api/v1/some/endpoint/id\");\n```\n\n## Also available\n\n- [ACE CLI](https://www.npmjs.com/package/@authoritas-ace/ace-cli) drives the same API from your terminal.\n- The [MCP server](https://ace.authoritas.com/docs/mcp-tools) lets an AI assistant call ACE for you.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}