llm-messages 0.5.0 → 0.5.2

package/docs/conformance-fixtures.md

@@ -1,12 +1,26 @@
-# Conformance fixtures plan
+# Conformance fixtures
 
 `llm-messages` keeps OpenAI Chat Completions-compatible messages as its hub
-shape. Provider-backed conformance fixtures are the next layer for proving that
-the conversions stay correct as OpenAI, Anthropic and Gemini payloads evolve.
+shape. Committed offline conformance fixtures prove that conversions stay
+stable. Provider-backed fixture refreshes are intentionally maintainer-run:
+this guide defines how refreshed payloads become deterministic offline fixtures,
+while the roadmap tracks automation for generating new provider payloads.
 
-The fixture workflow should be safe to run in public CI without secrets, while
-still allowing maintainers to refresh source payloads with API credits when
-needed.
+The fixture workflow is safe to run in public CI without secrets, while still
+allowing maintainers to refresh source payloads with API credits when needed.
+
+Committed fixtures live in `test/fixtures/*.json` as repository test assets;
+they are not included in the npm package tarball. The public Vitest harness in
+`test/conformance.test.ts` discovers those files in sorted order and runs them
+offline as part of `npm test`. It currently routes `source: "anthropic"`
+fixtures through `fromAnthropic(...)`, `source: "gemini"` fixtures through
+`fromGemini(...)`, `source: "openai"` fixtures through
+`responseFromOpenAI(...)`, and `source: "openai-responses"` fixtures through
+`responseFromOpenAIResponses(...)`. Response-level fixtures use
+`source: "anthropic-response"` for `responseFromAnthropic(...)` and
+`source: "gemini-response"` for `responseFromGemini(...)`; add explicit routing
+before committing fixtures for another provider or API family. The harness fails
+fast if no JSON fixtures are present.
 
 ## Fixture classes
 
@@ -20,6 +34,75 @@ needed.
 | Responses API shape | OpenAI Responses API output can be mapped or rejected with explicit warnings.  |
 | Lossy conversion    | Unsupported or ambiguous provider data emits stable warning codes.             |
 
+## Current fixture inventory
+
+Use this inventory as a release-review index for the committed offline fixtures;
+the JSON files remain the source of truth for exact inputs and expected output.
+Each fixture id below maps to `test/fixtures/<fixture>.json`.
+Update this table in the same change that adds or removes a fixture.
+
+| Fixture                                                       | Source               | Contract                                                                                                                                                              | Warning codes                            |
+| ------------------------------------------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
+| `anthropic-response-tool-use-duplicate-provider-id`           | `anthropic-response` | Anthropic response-level tool_use blocks with duplicate provider ids keep the first id and regenerate later duplicates.                                               | `generated-id`                           |
+| `anthropic-response-tool-use-generated-id`                    | `anthropic-response` | Anthropic response-level tool_use blocks without usable ids generate deterministic canonical tool call ids and warnings.                                              | 2x `generated-id`                        |
+| `anthropic-response-tool-use-id-reservation`                  | `anthropic-response` | Anthropic response-level id-less tool_use blocks skip generated ids reserved by later provider-supplied ids.                                                          | `generated-id`                           |
+| `anthropic-response-tool-use-invalid-arguments`               | `anthropic-response` | Response-level Anthropic tool_use blocks with non-object input fall back to empty canonical arguments and warn.                                                       | `invalid-json-arguments`                 |
+| `anthropic-response-tool-use-malformed-name`                  | `anthropic-response` | Anthropic response-level tool_use blocks with malformed names use the stable fallback function name and warning.                                                      | `dropped-metadata`                       |
+| `anthropic-response-unsupported-content-block`                | `anthropic-response` | Anthropic response-level unsupported content blocks are dropped with explicit warnings while supported text remains.                                                  | `dropped-content`                        |
+| `anthropic-tool-result-duplicate-provider-id`                 | `anthropic`          | Anthropic tool_result blocks with repeated provider ids map to duplicate tool_use ids in occurrence order after regeneration.                                         | `generated-id`                           |
+| `anthropic-tool-result-generated-id`                          | `anthropic`          | Anthropic tool_result blocks without usable tool_use_id generate deterministic canonical tool message ids and warnings.                                               | `unmapped-tool-result`                   |
+| `anthropic-tool-result-id-reservation`                        | `anthropic`          | Anthropic tool_result references reserve provider-supplied ids before earlier id-less tool_use blocks generate canonical ids and warn when no prior tool_use matches. | `generated-id`, `unmapped-tool-result`   |
+| `anthropic-tool-result-unmapped-id`                           | `anthropic`          | Anthropic tool_result ids that do not match prior tool_use blocks stay orphaned and warn.                                                                             | `unmapped-tool-result`                   |
+| `anthropic-tool-use-duplicate-provider-id`                    | `anthropic`          | Anthropic tool_use blocks with duplicate provider ids keep the first id and regenerate later duplicates.                                                              | `generated-id`                           |
+| `anthropic-tool-use-generated-id`                             | `anthropic`          | Anthropic tool_use blocks without usable ids generate deterministic canonical tool call ids and warnings.                                                             | 2x `generated-id`                        |
+| `anthropic-tool-use-invalid-arguments`                        | `anthropic`          | Anthropic tool_use blocks with non-object input fall back to empty canonical arguments and warn.                                                                      | `invalid-json-arguments`                 |
+| `anthropic-tool-use-malformed-name`                           | `anthropic`          | Anthropic tool_use blocks with malformed names use the stable fallback function name and warning.                                                                     | `dropped-metadata`                       |
+| `gemini-function-call-duplicate-provider-id`                  | `gemini`             | Gemini functionCall blocks with duplicate provider ids keep the first id and regenerate later duplicates.                                                             | `generated-id`                           |
+| `gemini-function-call-generated-id`                           | `gemini`             | Gemini functionCall blocks without usable ids generate deterministic canonical tool call ids and warnings.                                                            | `generated-id`                           |
+| `gemini-function-call-generated-id-reservation`               | `gemini`             | Gemini id-less functionCall blocks skip generated ids that are reserved by later provider-supplied ids.                                                               | `generated-id`                           |
+| `gemini-function-call-invalid-arguments`                      | `gemini`             | Gemini functionCall parts with non-object args fall back to empty canonical arguments and warn.                                                                       | `invalid-json-arguments`                 |
+| `gemini-function-call-malformed-name`                         | `gemini`             | Gemini functionCall blocks with malformed names use the stable fallback function name and warning.                                                                    | `dropped-metadata`                       |
+| `gemini-function-response-duplicate-provider-id`              | `gemini`             | Gemini functionResponse blocks with repeated provider ids map to duplicate functionCall ids in occurrence order after regeneration.                                   | `generated-id`                           |
+| `gemini-function-response-duplicate-provider-id-omitted-name` | `gemini`             | Gemini functionResponse blocks with repeated provider ids can omit names and still resolve in occurrence order after regeneration.                                    | `generated-id`                           |
+| `gemini-function-response-generated-id`                       | `gemini`             | Gemini functionResponse blocks without a matching call or id generate deterministic canonical tool-message ids.                                                       | `unmapped-tool-result`                   |
+| `gemini-function-response-id-precedence`                      | `gemini`             | Gemini functionResponse.id is resolved before falling back to same-name pending function calls.                                                                       | `dropped-metadata`                       |
+| `gemini-function-response-non-string-id`                      | `gemini`             | Gemini functionResponse ids that are not strings are ignored before matching by function name.                                                                        | `dropped-metadata`                       |
+| `gemini-function-response-null-response`                      | `gemini`             | Gemini functionResponse null response payloads serialize into canonical tool-message content instead of collapsing to an omitted response.                            | none                                     |
+| `gemini-function-response-omitted-name-id-match`              | `gemini`             | Gemini functionResponse blocks with a matching id can omit name and still resolve to the pending function call.                                                       | none                                     |
+| `gemini-function-response-order`                              | `gemini`             | Gemini user text around a functionResponse preserves canonical message ordering.                                                                                      | none                                     |
+| `gemini-function-response-scalar-response`                    | `gemini`             | Gemini functionResponse scalar response payloads serialize into canonical tool-message content without crashing.                                                      | none                                     |
+| `gemini-function-response-unmapped-id`                        | `gemini`             | Gemini functionResponse ids that do not match pending calls stay orphaned and do not consume same-name pending calls.                                                 | `unmapped-tool-result`                   |
+| `gemini-response-function-call-duplicate-provider-id`         | `gemini-response`    | Gemini response-level functionCall blocks with duplicate provider ids keep the first id and regenerate later duplicates.                                              | `generated-id`                           |
+| `gemini-response-function-call-generated-id`                  | `gemini-response`    | Gemini response-level functionCall blocks without usable ids generate deterministic canonical tool call ids and warnings.                                             | `generated-id`                           |
+| `gemini-response-function-call-id-reservation`                | `gemini-response`    | Gemini response-level id-less functionCall blocks skip generated ids reserved by later provider-supplied ids.                                                         | `generated-id`                           |
+| `gemini-response-function-call-invalid-arguments`             | `gemini-response`    | Response-level Gemini functionCall parts with non-object args fall back to empty canonical arguments and warn.                                                        | `invalid-json-arguments`                 |
+| `gemini-response-function-call-malformed-name`                | `gemini-response`    | Gemini response-level functionCall blocks with malformed names use the stable fallback function name and warning.                                                     | `dropped-metadata`                       |
+| `gemini-response-unsupported-content-part`                    | `gemini-response`    | Gemini response-level unsupported content parts are dropped with explicit warnings while supported text remains.                                                      | `dropped-content`                        |
+| `openai-chat-duplicate-provider-id`                           | `openai`             | OpenAI Chat Completions tool_calls with duplicate provider ids keep the first id and regenerate later duplicates.                                                     | `generated-id`                           |
+| `openai-chat-generated-id-reservation`                        | `openai`             | OpenAI Chat Completions id-less tool_calls skip generated ids that are reserved by later provider-supplied ids.                                                       | `generated-id`                           |
+| `openai-chat-generated-id-warning`                            | `openai`             | OpenAI Chat Completions tool_calls without ids generate deterministic canonical tool call ids and warnings.                                                           | `generated-id`                           |
+| `openai-chat-invalid-argument-string`                         | `openai`             | OpenAI Chat Completions tool_call argument strings that decode to non-objects fall back to empty canonical arguments.                                                 | `invalid-json-arguments`                 |
+| `openai-chat-invalid-arguments`                               | `openai`             | OpenAI Chat Completions tool_call arguments that are explicit non-object values fall back to empty canonical arguments.                                               | `invalid-json-arguments`                 |
+| `openai-chat-legacy-function-call`                            | `openai`             | Legacy OpenAI Chat Completions function_call responses normalize to canonical tool_calls with a generated id.                                                         | `generated-id`                           |
+| `openai-chat-legacy-function-call-invalid-arguments`          | `openai`             | Legacy OpenAI Chat Completions function_call argument strings that decode to non-objects fall back to empty canonical arguments.                                      | `generated-id`, `invalid-json-arguments` |
+| `openai-chat-legacy-function-call-malformed-name`             | `openai`             | Legacy OpenAI Chat Completions function_call responses with malformed names fall back before generating canonical ids.                                                | `dropped-metadata`, `generated-id`       |
+| `openai-chat-malformed-function-name`                         | `openai`             | OpenAI Chat Completions tool_calls with malformed function names use the stable fallback function name and warning.                                                   | `dropped-metadata`                       |
+| `openai-chat-malformed-tool-call`                             | `openai`             | OpenAI Chat Completions malformed tool_calls[] entries are dropped with explicit warnings while supported function calls remain.                                      | `dropped-content`                        |
+| `openai-chat-object-arguments`                                | `openai`             | OpenAI Chat Completions tool_call argument objects serialize to canonical JSON strings without warning.                                                               | none                                     |
+| `openai-chat-refusal-content-part`                            | `openai`             | OpenAI Chat Completions refusal content parts flatten into canonical assistant text without warning.                                                                  | none                                     |
+| `openai-chat-unsupported-content-part`                        | `openai`             | OpenAI Chat Completions unsupported response content parts are dropped with explicit warnings while supported text remains.                                           | `dropped-content`                        |
+| `openai-chat-unsupported-tool-call-type`                      | `openai`             | OpenAI Chat Completions unsupported tool_calls[] types are dropped while supported function calls remain.                                                             | `dropped-content`                        |
+| `openai-responses-call-id-precedence`                         | `openai-responses`   | OpenAI Responses API function_call items with both call_id and id preserve call_id as the canonical tool-call id.                                                     | none                                     |
+| `openai-responses-duplicate-provider-id`                      | `openai-responses`   | OpenAI Responses API function_call items with duplicate provider ids keep the first id and regenerate later duplicates.                                               | `generated-id`                           |
+| `openai-responses-generated-id-reservation`                   | `openai-responses`   | OpenAI Responses API id-less function_call items skip generated ids that are reserved by later provider-supplied ids.                                                 | `generated-id`                           |
+| `openai-responses-generated-id-warning`                       | `openai-responses`   | OpenAI Responses API function_call items without call_id or id generate a deterministic tool call id and warning.                                                     | `generated-id`                           |
+| `openai-responses-invalid-argument-string`                    | `openai-responses`   | OpenAI Responses API function_call argument strings that decode to non-objects fall back to empty canonical arguments.                                                | `invalid-json-arguments`                 |
+| `openai-responses-invalid-arguments`                          | `openai-responses`   | OpenAI Responses API function_call arguments that are explicit non-object values fall back to empty canonical arguments.                                              | `invalid-json-arguments`                 |
+| `openai-responses-malformed-function-name`                    | `openai-responses`   | OpenAI Responses API function_call items with malformed names use the stable fallback function name and warning.                                                      | `dropped-metadata`                       |
+| `openai-responses-refusal-content-part`                       | `openai-responses`   | OpenAI Responses API refusal content parts flatten into canonical assistant text without warning.                                                                     | none                                     |
+| `openai-responses-unsupported-content-part`                   | `openai-responses`   | OpenAI Responses API unsupported message content parts are dropped with explicit warnings while supported text remains.                                               | `dropped-content`                        |
+| `openai-responses-unsupported-output-item`                    | `openai-responses`   | OpenAI Responses API unsupported top-level output items are dropped with explicit warnings while supported message output remains.                                    | `dropped-content`                        |
+
 ## Refresh flow
 
 1. Generate provider payloads locally with maintainer-controlled API keys.
@@ -29,7 +112,7 @@ needed.
 4. Commit only deterministic JSON fixtures and expected normalized output.
 5. Run public CI without any API keys.
 
-## OpenAI API credit use
+## Provider API credit use
 
 Credits should be used only for fixture refreshes that improve public coverage:
 
@@ -45,12 +128,29 @@ that require secrets in public CI.
 
 Every committed fixture should include:
 
-- Provider name and source API family.
-- Input payload.
-- Expected canonical OpenAI-compatible message.
-- Expected provider output when round-tripping is supported.
-- Expected warning codes for lossy or unsupported conversions.
-- A short note explaining why the case matters.
+- `name`: a stable, unique test title that matches the JSON filename without
+  `.json`.
+- `description`: a short note explaining why the case matters.
+- `source`: the source provider or API family. The current public harness
+  accepts `anthropic`, `anthropic-response`, `gemini`, `gemini-response`,
+  `openai` and `openai-responses`.
+- `input`: the minimized provider payload. Anthropic fixtures must include a
+  `messages` array, Anthropic response fixtures must include a `content` array,
+  Gemini fixtures must include a `contents` array, Gemini response fixtures must
+  include a `candidates` array, OpenAI Chat Completions fixtures must include a
+  `choices` array, and OpenAI Responses fixtures must include an `output` array.
+- `expectedOpenAI`: the expected canonical OpenAI-compatible messages.
+- `expectedWarningCodes`: expected warning codes for lossy or unsupported
+  conversions. Values must match the package's exported `warningCodes` list.
+- `expectedResponse`: required only for response-body fixtures
+  (`anthropic-response`, `gemini-response`, `openai`, `openai-responses`).
+  It records the normalized `finishReason` and `usage` so response fixtures
+  catch metadata regressions as well as message-shape regressions.
+
+Future fixture classes may add provider round-trip expectations, but the current
+public harness intentionally stays offline and asserts normalized output,
+response metadata and warning codes. Duplicate fixture names and names that do
+not match their filenames fail fast so test output remains unambiguous.
 
 ## Public CI rule
 

package/examples/commonjs.cjs

@@ -0,0 +1,34 @@
+/* eslint-disable @typescript-eslint/no-require-imports */
+// Run from the repo root after `npm run build`:
+//   node examples/commonjs.cjs
+const assert = require('node:assert/strict');
+const { normalizeResponse, toAnthropic, warningCodes } = require('../dist/index.cjs');
+
+const anthropic = toAnthropic([
+  { role: 'system', content: 'You are concise.' },
+  { role: 'user', content: 'Ping' },
+]);
+
+assert.deepEqual(anthropic, {
+  system: 'You are concise.',
+  messages: [{ role: 'user', content: 'Ping' }],
+});
+
+const normalized = normalizeResponse(
+  {
+    choices: [
+      {
+        finish_reason: 'stop',
+        message: { role: 'assistant', content: 'Pong' },
+      },
+    ],
+    usage: { prompt_tokens: 2, completion_tokens: 1 },
+  },
+  { from: 'openai' },
+);
+
+assert.equal(normalized.message.content, 'Pong');
+assert.equal(normalized.finishReason, 'stop');
+assert.equal(Object.isFrozen(warningCodes), true);
+
+console.log('CommonJS smoke check passed.');

package/examples/usage.mjs

@@ -1,7 +1,10 @@
 // Run from the repo root after `npm run build`:
 //   node examples/usage.mjs
+import assert from 'node:assert/strict';
 import { toAnthropic, toGemini, convert } from '../dist/index.js';
 
+const checkMode = process.argv.includes('--check');
+
 const messages = [
   { role: 'system', content: 'You are a weather assistant.' },
   { role: 'user', content: "What's the weather in Paris?" },
@@ -15,12 +18,24 @@ const messages = [
   { role: 'tool', tool_call_id: 'call_abc', content: '15C partly cloudy' },
 ];
 
+const anthropic = toAnthropic(messages);
+const gemini = toGemini(messages);
+const converted = convert(anthropic, { from: 'anthropic', to: 'gemini' });
+
+if (checkMode) {
+  assert.equal(anthropic.system, 'You are a weather assistant.');
+  assert.ok(Array.isArray(anthropic.messages));
+  assert.ok(Array.isArray(gemini.contents));
+  assert.ok(Array.isArray(converted.contents));
+  console.log('ESM usage smoke check passed.');
+  process.exit(0);
+}
+
 console.log('--- OpenAI -> Anthropic ---');
-console.log(JSON.stringify(toAnthropic(messages), null, 2));
+console.log(JSON.stringify(anthropic, null, 2));
 
 console.log('\n--- OpenAI -> Gemini ---');
-console.log(JSON.stringify(toGemini(messages), null, 2));
+console.log(JSON.stringify(gemini, null, 2));
 
 console.log('\n--- Anthropic -> Gemini (via convert) ---');
-const anthropic = toAnthropic(messages);
-console.log(JSON.stringify(convert(anthropic, { from: 'anthropic', to: 'gemini' }), null, 2));
+console.log(JSON.stringify(converted, null, 2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-messages",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Convert chat conversations and responses between OpenAI, Anthropic and Gemini. Tool calls, images, audio, documents and roles handled. Zero dependencies.",
   "keywords": [
     "openai",
@@ -58,23 +58,31 @@
     "examples",
     "README.md",
     "ROADMAP.md",
+    "SECURITY.md",
     "LICENSE",
     "CHANGELOG.md"
   ],
   "engines": {
     "node": ">=18"
   },
+  "packageManager": "npm@10.9.8",
   "sideEffects": false,
   "scripts": {
     "build": "tsup",
+    "check": "npm run format:check && npm run typecheck && npm run lint && npm test && npm run build && npm run examples:check && npm run pack:check && npm run pack:smoke",
+    "examples:check": "node examples/usage.mjs --check && node examples/commonjs.cjs",
+    "pack:check": "npm pack --dry-run --foreground-scripts=false",
+    "pack:smoke": "node scripts/pack-smoke.mjs",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
     "lint": "eslint .",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
-    "prepublishOnly": "npm run build",
-    "prepare": "npm run build"
+    "prepublishOnly": "npm run check",
+    "prepare": "npm run build",
+    "badges:downloads": "node scripts/update-download-badge.mjs",
+    "badges:downloads:check": "node scripts/update-download-badge.mjs --check"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
@@ -82,7 +90,7 @@
     "eslint": "^10.4.1",
     "prettier": "^3.4.2",
     "tsup": "^8.3.5",
-    "typescript": "^5.7.2",
+    "typescript": "^6.0.3",
     "typescript-eslint": "^8.60.0",
     "vitest": "^4.1.8"
   }