{"_id":"@curator1/sommelier-sdk","name":"@curator1/sommelier-sdk","dist-tags":{"latest":"0.2.0"},"versions":{"0.2.0":{"name":"@curator1/sommelier-sdk","version":"0.2.0","description":"Typed client for the Joy of Wine AI Sommelier API. Wraps /v1/sommelier/query and /v1/sommelier/identity.","license":"Apache-2.0","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/Joy-of-Wine-Company/ai-sommelier.git","directory":"partner-sdk"},"homepage":"https://github.com/Joy-of-Wine-Company/ai-sommelier/tree/main/partner-sdk#readme","bugs":{"url":"https://github.com/Joy-of-Wine-Company/ai-sommelier/issues"},"scripts":{"build":"tsc","typecheck":"tsc --noEmit","test":"vitest run","lint":"eslint src tests"},"devDependencies":{"typescript":"^5.9.3","vitest":"^2.1.8"},"gitHead":"a1ac00fae0756fcd63ff8ef456cddb49766a128f","_id":"@curator1/sommelier-sdk@0.2.0","_nodeVersion":"25.3.0","_npmVersion":"11.7.0","dist":{"integrity":"sha512-t4mHH4OLrKMRZqsd5zkr3umUT8mmvjFdvwMzFviL0Cy5ekJ0LRzR2+vvMmZIuIJXh4S8/FJp4YQ57zUWOW51Mg==","shasum":"52fb0c73805721afe3c53e70eaa013e48cab5f42","tarball":"https://registry.npmjs.org/@curator1/sommelier-sdk/-/sommelier-sdk-0.2.0.tgz","fileCount":11,"unpackedSize":17787,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIEu/tF9YSiJkgWGmD66rCl2nf3NCtP+gCJDMaX3GwOeqAiAhU786YebMh8Qzlgw2MNZjzpUNvKsO3SrbhtxwpyhMyQ=="}]},"_npmUser":{"name":"curator1","email":"curator@joyofwine.co"},"directories":{},"maintainers":[{"name":"curator1","email":"curator@joyofwine.co"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sommelier-sdk_0.2.0_1779230141743_0.2630349077558649"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-19T22:35:41.647Z","0.2.0":"2026-05-19T22:35:41.896Z","modified":"2026-05-19T22:35:42.067Z"},"maintainers":[{"name":"curator1","email":"curator@joyofwine.co"}],"description":"Typed client for the Joy of Wine AI Sommelier API. Wraps /v1/sommelier/query and /v1/sommelier/identity.","homepage":"https://github.com/Joy-of-Wine-Company/ai-sommelier/tree/main/partner-sdk#readme","repository":{"type":"git","url":"git+https://github.com/Joy-of-Wine-Company/ai-sommelier.git","directory":"partner-sdk"},"bugs":{"url":"https://github.com/Joy-of-Wine-Company/ai-sommelier/issues"},"license":"Apache-2.0","readme":"# @curator1/sommelier-sdk\n\nTyped TypeScript client for the Joy of Wine AI Sommelier API. Wraps `POST /v1/sommelier/query` and `POST /v1/sommelier/identity` with full request/response typings.\n\n## Install\n\n```bash\nnpm install @curator1/sommelier-sdk\n```\n\n## Quickstart\n\n```ts\nimport { createSommelierClient } from '@curator1/sommelier-sdk';\n\nconst client = createSommelierClient({\n  baseUrl: 'https://api.joyofwine.co',\n  apiKey: process.env.SOMMELIER_API_KEY!,\n});\n\nconst response = await client.query({\n  query: 'bright red for grilled salmon under $40',\n  context: {\n    ship_to: { state: 'PA' },\n  },\n});\n\nconsole.log(response.answer);                    // gpt-4o sommelier prose\nconsole.log(response.recommendations.length);    // up to 5 ranked wines\nconsole.log(response.thread_id);                 // persist for follow-up turns\n```\n\n## Multi-turn conversations\n\nThe sommelier uses OpenAI Assistants threads for multi-turn memory. Persist `response.thread_id` from the first turn and pass it back as `context.thread_id` on follow-ups:\n\n```ts\nconst turn1 = await client.query({\n  query: 'bright red for grilled salmon under $40',\n  context: { ship_to: { state: 'PA' } },\n});\n\nconst turn2 = await client.query({\n  query: 'make it low-tannin',\n  context: {\n    ship_to: { state: 'PA' },\n    thread_id: turn1.thread_id,    // round-trip the thread\n  },\n});\n// turn2.answer references the salmon + budget context from turn 1.\n```\n\nA `thread_id` is returned on every successful response. If you don't pass one, a fresh thread is created server-side and returned for you to persist.\n\n## Response shape\n\n`SommelierQueryResponse`:\n\n| Field | Type | Notes |\n|---|---|---|\n| `answer` | `string` | LLM-generated prose. Refusals included for out-of-scope queries. |\n| `recommendations` | `Recommendation[]` | Up to 5 wines, ranked. Empty when no matches passed compliance. |\n| `producer_message` | `string \\| null` | Optional producer-controlled override. |\n| `affiliate_disclosure` | `string \\| null` | Required when any recommendation carries an affiliate vendor. |\n| `retrieval_source` | `'vertex_ai_search' \\| 'sql_fallback' \\| 'unavailable' \\| null` | Which retrieval path served the candidates. Surface as a degraded-quality hint if not `vertex_ai_search`. |\n| `thread_id` | `string \\| null` | OpenAI Assistants thread id. Round-trip on follow-ups. |\n| `request_id` | `string` | Use in support tickets. |\n\n`Recommendation`:\n\n| Field | Type | Notes |\n|---|---|---|\n| `wine_id` | `string` | Stable id (LWIN where available). |\n| `name`, `producer` | `string` | |\n| `vintage` | `number \\| null` | |\n| `tasting_notes` | `string \\| null` | |\n| `compliance` | `{ can_ship: boolean \\| null, carriers: string[], notes: string \\| null }` | `can_ship === null` means \"unknown\" — surfaces should not assert shippability. |\n| `affiliate` | `{ vendor, url, commission_pct } \\| null` | Present when an affiliate match exists. |\n| `rank` | `number` | 1-based. |\n\n## Authentication\n\nPass your partner API key via the `apiKey` option (sent as `X-API-Key`). Issue keys through the Joy of Wine partner dashboard.\n\n## License\n\nApache-2.0.\n","readmeFilename":"README.md","_rev":"1-cbaf4a779518a88ba508c0b8e13f0276"}