{"_id":"@aphrody/xai","_rev":"9-371b1ecddd5d81b5376fefe49293cfe9","name":"@aphrody/xai","dist-tags":{"latest":"1.1.5"},"versions":{"1.0.1":{"name":"@aphrody/xai","version":"1.0.1","license":"Apache-2.0","_id":"@aphrody/xai@1.0.1","maintainers":[{"name":"yohan971","email":"yohanpierre@live.fr"}],"dist":{"shasum":"191d61df0ceef6e4c5f21f36f2954423a06f6d86","tarball":"https://registry.npmjs.org/@aphrody/xai/-/xai-1.0.1.tgz","fileCount":7,"integrity":"sha512-VHn2rSPrTVXKrJ4hqXaNX2yIteGI9tmeNVWxO20b6I9jfxNmmxFyr8e3oOTt878+rjOUJNoTT1mPSkLPg++o1g==","signatures":[{"sig":"MEUCIQCpELxTTak6/hNdMdyqcnQ7ehRef07XU192saiNh9fo9QIgRXJQf93k5NMY5RrMiQmJyyVHU15Nk0is/MpFRMjwQFg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":12479},"main":"./src/index.ts","type":"module","types":"./src/index.ts","exports":{".":"./src/index.ts"},"gitHead":"7409bb65fef1c022208151a69304547bf9a4e516","scripts":{"test":"bun test","typecheck":"tsc --noEmit"},"_npmUser":{"name":"yohan971","email":"yohanpierre@live.fr"},"_npmVersion":"9.2.0","description":"Headless xAI Grok API client for Bun — OIDC session (~/.grok/auth.json) or XAI_API_KEY, OpenAI-compatible REST.","directories":{},"_nodeVersion":"24.3.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"^1.3.14","typescript":"^6.0.3"},"_npmOperationalInternal":{"tmp":"tmp/xai_1.0.1_1780527305612_0.038071844952848544","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@aphrody/xai","version":"1.0.3","license":"Apache-2.0","_id":"@aphrody/xai@1.0.3","maintainers":[{"name":"yohan971","email":"yohanpierre@live.fr"}],"dist":{"shasum":"5327bf153d3f7da1661def87e66fb5e635274423","tarball":"https://registry.npmjs.org/@aphrody/xai/-/xai-1.0.3.tgz","fileCount":10,"integrity":"sha512-JfIFvQ0WaMA8tUqcy5YC2o3JUAHRdBsH71C2ICOg77ix5NLwvnqOcW16VStZeK6NEROlSN8gcyrxiH/Ep1Wh6A==","signatures":[{"sig":"MEUCIQDLwar4ROxW0FVFMvbR3TaJXqzuRf0lcoDJfcXVyTya7gIgRYR5Pw6myHwpX+dW9fbNxCsaNTMQIzDR/54/oUIOwwk=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":61319},"main":"./src/index.ts","type":"module","types":"./src/index.ts","shasum":"5327bf153d3f7da1661def87e66fb5e635274423","exports":{".":"./src/index.ts"},"scripts":{"test":"bun test","typecheck":"tsc --noEmit"},"_npmUser":{"name":"yohan971","email":"yohanpierre@live.fr"},"_integrity":"sha512-JfIFvQ0WaMA8tUqcy5YC2o3JUAHRdBsH71C2ICOg77ix5NLwvnqOcW16VStZeK6NEROlSN8gcyrxiH/Ep1Wh6A==","_npmVersion":"10.8.3","description":"Headless xAI Grok API client for Bun — high-level fluent Chat API (createChat/append/sample/stream/executeToolCalls/sampleStructured, reasoning, structured, XTools for native X tool fulfillment) + SUPER_GROK_TOKEN keyless + OIDC. OpenAI-compatible REST, d","directories":{},"_nodeVersion":"24.3.0","dependencies":{"@aphrody/x":"1.0.8"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"^1.3.14","typescript":"^6.0.3"},"_npmOperationalInternal":{"tmp":"tmp/xai_1.0.3_1780586729387_0.6030128198725064","host":"s3://npm-registry-packages-npm-production"}},"1.0.5":{"name":"@aphrody/xai","version":"1.0.5","license":"Apache-2.0","_id":"@aphrody/xai@1.0.5","maintainers":[{"name":"yohan971","email":"yohanpierre@live.fr"}],"dist":{"shasum":"2221ea40ed382d924c87b7b6548196d6130bee4b","tarball":"https://registry.npmjs.org/@aphrody/xai/-/xai-1.0.5.tgz","fileCount":10,"integrity":"sha512-FSrJFXd02XqyawSQyMEFZmAFHQR0U5LwY6x8pSlBUXt/WnGDGumsOknl1hvjO2LqFQJybSEUSEyH11GwzdoWng==","signatures":[{"sig":"MEYCIQDKnLzw6IoKZ18iXIOTogDeg/7J4C+GS3BxqfMWDHaDNQIhALlML+3Dtf/EA9HJ/XURWu0OSIXzK4rD5P7A+9jz0fP1","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":61320},"main":"./src/index.ts","type":"module","types":"./src/index.ts","shasum":"2221ea40ed382d924c87b7b6548196d6130bee4b","exports":{".":"./src/index.ts"},"scripts":{"test":"bun test","typecheck":"tsc --noEmit"},"_npmUser":{"name":"yohan971","email":"yohanpierre@live.fr"},"_integrity":"sha512-FSrJFXd02XqyawSQyMEFZmAFHQR0U5LwY6x8pSlBUXt/WnGDGumsOknl1hvjO2LqFQJybSEUSEyH11GwzdoWng==","_npmVersion":"10.8.3","description":"Headless xAI Grok API client for Bun — high-level fluent Chat API (createChat/append/sample/stream/executeToolCalls/sampleStructured, reasoning, structured, XTools for native X tool fulfillment) + SUPER_GROK_TOKEN keyless + OIDC. OpenAI-compatible REST, d","directories":{},"_nodeVersion":"24.3.0","dependencies":{"@aphrody/x":"1.0.10"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"^1.3.14","typescript":"^6.0.3"},"_npmOperationalInternal":{"tmp":"tmp/xai_1.0.5_1786525426728_0.23869202125681954","host":"s3://npm-registry-packages-npm-production"}},"1.0.6":{"name":"@aphrody/xai","version":"1.0.6","license":"Apache-2.0","_id":"@aphrody/xai@1.0.6","maintainers":[{"name":"yohan971","email":"yohanpierre@live.fr"}],"dist":{"shasum":"fa36ad0cb7e2fdd97c080b27429df60de9c92e7f","tarball":"https://registry.npmjs.org/@aphrody/xai/-/xai-1.0.6.tgz","fileCount":10,"integrity":"sha512-MM53qjKahecwpaiWk277MvpwBDWD9QVK63imBYHVYbOj0Fni2FKHKcWeMpyuY2nkosZb6YJ4HUFFdQEp9GKLzg==","signatures":[{"sig":"MEUCIQCJnTCpx7dgE37CGefnZZKBsF6nzY6HXFFQVtu0mVUeEAIgYuxmd+nI531ybNWWkov/ek2WMph4CR2m6ZfxRsSfB3o=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":61319},"main":"./src/index.ts","type":"module","types":"./src/index.ts","shasum":"fa36ad0cb7e2fdd97c080b27429df60de9c92e7f","exports":{".":"./src/index.ts"},"scripts":{"test":"bun test","typecheck":"tsc --noEmit"},"_npmUser":{"name":"yohan971","email":"yohanpierre@live.fr"},"_integrity":"sha512-MM53qjKahecwpaiWk277MvpwBDWD9QVK63imBYHVYbOj0Fni2FKHKcWeMpyuY2nkosZb6YJ4HUFFdQEp9GKLzg==","_npmVersion":"10.8.3","description":"Headless xAI Grok API client for Bun — high-level fluent Chat API (createChat/append/sample/stream/executeToolCalls/sampleStructured, reasoning, structured, XTools for native X tool fulfillment) + SUPER_GROK_TOKEN keyless + OIDC. OpenAI-compatible REST, d","directories":{},"_nodeVersion":"24.3.0","dependencies":{"@aphrody/x":"1.1.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"^1.3.14","typescript":"^6.0.3"},"_npmOperationalInternal":{"tmp":"tmp/xai_1.0.6_1788311213579_0.515078721826902","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@aphrody/xai","version":"1.1.0","license":"Apache-2.0","_id":"@aphrody/xai@1.1.0","maintainers":[{"name":"yohan971","email":"yohanpierre@live.fr"}],"dist":{"shasum":"2ca89d6e52c3174b4c5f988616d68824024e1617","tarball":"https://registry.npmjs.org/@aphrody/xai/-/xai-1.1.0.tgz","fileCount":7,"integrity":"sha512-qhPPYPJ7MygGLT6HjxQMgx1QjKqoQSFZula2MpqppjCteaA5tOPXjanxlCyUjvhrCdPytxFbvUsRb5diO3ixIA==","signatures":[{"sig":"MEUCIQCd9hyg+2qRfmH2EsME4+9Kj1CHU9+rIiRtB5ZePZfRuQIgaU6fmJJYVuv8qXjpEr22yEmYmRFn8cqO7a8EuDSQJkI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":42559},"main":"./src/index.ts","type":"module","types":"./src/index.ts","shasum":"2ca89d6e52c3174b4c5f988616d68824024e1617","engines":{"bun":">=1.3.14"},"exports":{".":"./src/index.ts"},"scripts":{"test":"bun test","typecheck":"tsc --noEmit"},"_npmUser":{"name":"yohan971","email":"yohanpierre@live.fr"},"_integrity":"sha512-qhPPYPJ7MygGLT6HjxQMgx1QjKqoQSFZula2MpqppjCteaA5tOPXjanxlCyUjvhrCdPytxFbvUsRb5diO3ixIA==","_npmVersion":"10.8.3","description":"Headless xAI Grok API client for Bun — high-level fluent Chat API (createChat/append/sample/stream/executeToolCalls/sampleStructured, reasoning, structured, XTools for native X tool fulfillment) + SUPER_GROK_TOKEN keyless + OIDC. OpenAI-compatible REST, d","directories":{},"_nodeVersion":"24.3.0","dependencies":{"@aphrody/x":"1.2.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"^1.3.14","typescript":"^6.0.3"},"_npmOperationalInternal":{"tmp":"tmp/xai_1.1.0_1788431553207_0.011873579259984224","host":"s3://npm-registry-packages-npm-production"}},"1.1.1":{"name":"@aphrody/xai","version":"1.1.1","license":"Apache-2.0","_id":"@aphrody/xai@1.1.1","maintainers":[{"name":"yohan971","email":"yohanpierre@live.fr"}],"dist":{"shasum":"0f7bbd5f3891b1ca3164567b4c0f581383fdf7ae","tarball":"https://registry.npmjs.org/@aphrody/xai/-/xai-1.1.1.tgz","fileCount":7,"integrity":"sha512-nnncgBF3dUKNC8jXsNfcqn0b/X1zmIGOVV8B5PL8hYD3xuw1chiU0eJf87mKWSgKwjcFC3dKvYlFpq33MD6raw==","signatures":[{"sig":"MEYCIQClBmLAOyewjOVtaY1AKQ9T9ofrcuGliKEVDsO249rlmQIhANVR0uM6d+dAWjgZOy7sMuU4ajY90mn0SQIf32Q5485J","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":42559},"main":"./src/index.ts","type":"module","types":"./src/index.ts","shasum":"0f7bbd5f3891b1ca3164567b4c0f581383fdf7ae","engines":{"bun":">=1.3.14"},"exports":{".":"./src/index.ts"},"scripts":{"test":"bun test","typecheck":"tsc --noEmit"},"_npmUser":{"name":"yohan971","email":"yohanpierre@live.fr"},"_integrity":"sha512-nnncgBF3dUKNC8jXsNfcqn0b/X1zmIGOVV8B5PL8hYD3xuw1chiU0eJf87mKWSgKwjcFC3dKvYlFpq33MD6raw==","_npmVersion":"10.8.3","description":"Headless xAI Grok API client for Bun — high-level fluent Chat API (createChat/append/sample/stream/executeToolCalls/sampleStructured, reasoning, structured, XTools for native X tool fulfillment) + SUPER_GROK_TOKEN keyless + OIDC. OpenAI-compatible REST, d","directories":{},"_nodeVersion":"24.3.0","dependencies":{"@aphrody/x":"1.2.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"^1.3.14","typescript":"^6.0.3"},"_npmOperationalInternal":{"tmp":"tmp/xai_1.1.1_1788681509123_0.6674439396907559","host":"s3://npm-registry-packages-npm-production"}},"1.1.3":{"name":"@aphrody/xai","version":"1.1.3","license":"Apache-2.0","_id":"@aphrody/xai@1.1.3","maintainers":[{"name":"yohan971","email":"yohanpierre@live.fr"}],"bugs":{"url":"https://github.com/aphrody-code/xai/issues"},"dist":{"shasum":"615743f6fe743644757197fe61a6354493764a43","tarball":"https://registry.npmjs.org/@aphrody/xai/-/xai-1.1.3.tgz","fileCount":7,"integrity":"sha512-qcySn95kul9hiSYlpkSMthY3Qm/ZqQlq2v6Sl5r6xLmU/M9D+fb6D9CkEZHtYRCIvscBQBWpIGDeOXzs3LDJUw==","signatures":[{"sig":"MEQCIAkPTyCyMnbuQa46IAiHRqdNnkrACeKrdESqFV9xo/CZAiBF8GFIdyi03pVIE64jPxh//sPJ01cXxfvTi/X0nLvotw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":43967},"main":"./src/index.ts","type":"module","types":"./src/index.ts","shasum":"615743f6fe743644757197fe61a6354493764a43","engines":{"bun":">=1.3.14"},"exports":{".":"./src/index.ts"},"scripts":{"test":"bun test","typecheck":"tsc --noEmit"},"_npmUser":{"name":"yohan971","email":"yohanpierre@live.fr"},"_integrity":"sha512-qcySn95kul9hiSYlpkSMthY3Qm/ZqQlq2v6Sl5r6xLmU/M9D+fb6D9CkEZHtYRCIvscBQBWpIGDeOXzs3LDJUw==","repository":{"url":"https://github.com/aphrody-code/xai.git","type":"git"},"_npmVersion":"10.8.3","description":"Headless xAI Grok API client for Bun — high-level fluent Chat API (createChat/append/sample/stream/executeToolCalls/sampleStructured, reasoning, structured, XTools for native X tool fulfillment) + SUPER_GROK_TOKEN keyless + OIDC. OpenAI-compatible REST, d","directories":{},"_nodeVersion":"26.3.0","dependencies":{"@aphrody/x":"1.2.3"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"^1.3.14","typescript":"^6.0.3"},"_npmOperationalInternal":{"tmp":"tmp/xai_1.1.3_1788770715357_0.8190287209368665","host":"s3://npm-registry-packages-npm-production"}},"1.1.4":{"name":"@aphrody/xai","version":"1.1.4","license":"Apache-2.0","_id":"@aphrody/xai@1.1.4","maintainers":[{"name":"yohan971","email":"yohanpierre@live.fr"}],"homepage":"https://github.com/aphrody-code/xai#readme","bugs":{"url":"https://github.com/aphrody-code/xai/issues"},"dist":{"shasum":"dced49cd0e3793e89a9add1a288ddd0b0b14b476","tarball":"https://registry.npmjs.org/@aphrody/xai/-/xai-1.1.4.tgz","fileCount":7,"integrity":"sha512-sQGM5VxYt/jc1KqUEBJdp4kcwXw+pjV1kA49o7B/tLoUPnUJ+oN46rrvP35DItUOFjUtNOYuVzWwq3SOi30pCA==","signatures":[{"sig":"MEYCIQDcKJU2rOrFBG5+UlaqiWsm8E6liSitnZLFdlmYnfUn1AIhAJSYMCfYpV6bTWkXfL/uTFXBppiTGopiV7yPJYv992F1","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":42730},"main":"./src/index.ts","type":"module","types":"./src/index.ts","engines":{"bun":">=1.3.14"},"exports":{".":"./src/index.ts"},"gitHead":"b586f114f810d55b9e1b2aea63c0cd1378f76a8c","scripts":{"test":"bun test","typecheck":"tsc --noEmit"},"_npmUser":{"name":"yohan971","email":"yohanpierre@live.fr"},"repository":{"url":"git+https://github.com/aphrody-code/xai.git","type":"git"},"_npmVersion":"9.2.0","description":"Headless xAI Grok API client for Bun — high-level fluent Chat API (createChat/append/sample/stream/executeToolCalls/sampleStructured, reasoning, structured, XTools for native X tool fulfillment) + SUPER_GROK_TOKEN keyless + OIDC. OpenAI-compatible REST, d","directories":{},"_nodeVersion":"24.3.0","dependencies":{"@aphrody/x":"1.2.3"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"^1.3.14","typescript":"^6.0.3"},"_npmOperationalInternal":{"tmp":"tmp/xai_1.1.4_1789022212248_0.8671686210066858","host":"s3://npm-registry-packages-npm-production"}},"1.1.5":{"name":"@aphrody/xai","version":"1.1.5","repository":{"type":"git","url":"https://github.com/aphrody-code/xai.git"},"bugs":{"url":"https://github.com/aphrody-code/xai/issues"},"publishConfig":{"access":"public"},"description":"Headless xAI Grok API client for Bun — high-level fluent Chat API (createChat/append/sample/stream/executeToolCalls/sampleStructured, reasoning, structured, XTools for native X tool fulfillment) + SUPER_GROK_TOKEN keyless + OIDC. OpenAI-compatible REST, d","engines":{"bun":">=1.4.2"},"license":"Apache-2.0","type":"module","main":"./src/index.ts","types":"./src/index.ts","exports":{".":"./src/index.ts"},"scripts":{"typecheck":"tsc --noEmit","test":"bun test"},"dependencies":{"@aphrody/x":"1.2.5"},"devDependencies":{"@types/bun":"^1.3.14","typescript":"^6.0.3"},"_id":"@aphrody/xai@1.1.5","_integrity":"sha512-cpiCvVwgikE2qxzvGxLWlf/J6uOkODBqbPMlDyqF1qnKc0mEEUMgm0eIs9W9dGX2kmUiHvqsYxaMHsuWTaoFlA==","_nodeVersion":"24.3.0","_npmVersion":"10.8.3","shasum":"c6c4373be0cba0574b4c970e802b9daa7c88280d","dist":{"integrity":"sha512-cpiCvVwgikE2qxzvGxLWlf/J6uOkODBqbPMlDyqF1qnKc0mEEUMgm0eIs9W9dGX2kmUiHvqsYxaMHsuWTaoFlA==","shasum":"c6c4373be0cba0574b4c970e802b9daa7c88280d","tarball":"https://registry.npmjs.org/@aphrody/xai/-/xai-1.1.5.tgz","fileCount":7,"unpackedSize":42726,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDLxvZTcthC9aJC902poR7k5suZPXKEuJu0+iK38SkOvAIhAO2NEog/nDf4sN+scuYVgj8f5EYXIpB4pAwwuJVlTc7y"}]},"_npmUser":{"name":"yohan971","email":"yohanpierre@live.fr"},"directories":{},"maintainers":[{"name":"yohan971","email":"yohanpierre@live.fr"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/xai_1.1.5_1789648650705_0.07117281942061715"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-03T22:55:05.419Z","modified":"2026-09-17T12:37:31.032Z","1.0.1":"2026-06-03T22:55:05.752Z","1.0.3":"2026-06-04T15:25:29.525Z","1.0.5":"2026-08-12T09:03:46.879Z","1.0.6":"2026-09-02T01:06:53.700Z","1.1.0":"2026-09-03T10:32:33.344Z","1.1.1":"2026-09-06T07:58:29.255Z","1.1.3":"2026-09-07T08:45:15.493Z","1.1.4":"2026-09-10T06:36:52.415Z","1.1.5":"2026-09-17T12:37:30.849Z"},"bugs":{"url":"https://github.com/aphrody-code/xai/issues"},"license":"Apache-2.0","repository":{"type":"git","url":"https://github.com/aphrody-code/xai.git"},"description":"Headless xAI Grok API client for Bun — high-level fluent Chat API (createChat/append/sample/stream/executeToolCalls/sampleStructured, reasoning, structured, XTools for native X tool fulfillment) + SUPER_GROK_TOKEN keyless + OIDC. OpenAI-compatible REST, d","maintainers":[{"name":"yohan971","email":"yohanpierre@live.fr"}],"readme":"# @aphrody/xai\n\nHeadless **xAI Grok** client for Bun — OpenAI-compatible `https://api.x.ai/v1`.\n\n**Table of Contents**\n\n- [Auth (keyless / gratuite)](#auth-no-xai_api_key-required)\n- [CLI (`bxc grok`)](#cli-bxc-grok)\n- [High-level Library API (fluent Chat, Python SDK parity)](#library-high-level-fluent-chat-like-xai-sdk-python)\n- [Native X + Grok Integration (XTools for agentic use)](#native-x--grok-integration)\n- [Low-level API](#low-level-still-supported)\n- [MCP Tools](#mcp)\n- [Production-grade Notes](#production-grade-grok--native-x)\n\n## Auth (no `XAI_API_KEY` required)\n\nAfter `grok login`, Grok Build stores an OIDC JWT in `~/.grok/auth.json`. This package uses that token as `Authorization: Bearer …` (same as the Grok CLI).\n\nResolution order:\n\n1. Explicit `bearer` option / `--bearer`\n2. `XAI_API_KEY` environment variable (metered `xai-…` key)\n3. `~/.grok/auth.json` → `key` field (OIDC)\n\n**SuperGrok / free access (gratuite)**: set `SUPER_GROK_TOKEN` (or `GROK_SUPER_TOKEN`) env or use `~/.grok/auth.json` (from `grok login`). No paid `xai-` key needed. Full compatibility: explicit non-`xai-` bearer or SUPER_* env forces `supergrok` mode (preferred before falling back to auth file). The client detects non-`xai-` tokens as `supergrok` / `grok_oidc` mode. Use for agent flows without metered billing.\n\n## CLI (`bxc grok`)\n\n```bash\nbxc grok whoami\nbxc grok models\nbxc grok chat \"Hello\"\nbxc grok chat \"Hi\" --model grok-4 --stream\nbxc grok tts \"Hello\" --output /tmp/out.mp3\nbxc grok stt recording.wav\nbxc grok raw GET /models\n```\n\n## Library (high-level fluent Chat like xai-sdk-python)\n\nThe high-level API provides a stateful `Chat` session for multi-turn conversations, tool calling, streaming, structured outputs, and reasoning — directly inspired by the Python xai-sdk.\n\n```ts\nimport { XaiClient, system, user } from \"@aphrody/xai\"; // (add helpers if you want)\n\nconst client = new XaiClient(); // keyless via ~/.grok/auth.json (SuperGrok / Grok OIDC) or SUPER_GROK_TOKEN\n\n// High-level multi-turn (append + sample/stream)\nconst chat = client.createChat(\"grok-3\", {\n  messages: [system(\"You are a helpful pirate.\")],\n});\nchat.append(user(\"Hello!\"));\nconst res = await chat.sample();\nconsole.log(res.choices[0]?.message?.content);\nchat.append(res); // continue conversation\n\n// Streaming\nfor await (const { content, done } of chat.stream()) {\n  if (!done) process.stdout.write(content);\n}\n\n// Advanced: reasoning, structured (zod or simple json), tool-calling (see Native X section below)\nconst chatAdv = client.createChat(\"grok-4\", {\n  reasoning_effort: \"high\",\n  response_format: { type: \"json_object\" },\n});\nconst structured = await chatAdv.sampleStructured(); // basic zod/.parse or json auto\nconsole.log(structured.parsed);\n```\n\nSee the full `Chat` API in the Quick Reference below and source `src/core/client.ts`. Tool-calling with native X fulfillment is shown in the \"Native X + Grok integration\" section.\n\n## Native X + Grok integration\n\nAnalyse of our stack:\n- `packages/x`: full native cookie-auth X/Twitter client (GraphQL + REST, queryId catalog sync, sqlite store, X Pro/Radar, media, archive, stealth profiles). Zero official API key.\n- `packages/xai`: this package, now with high-level fluent Chat (create/append/sample/stream) + low-level OpenAI compat, using the same keyless SuperGrok token.\n\nUse them together for agentic Grok: let Grok decide to call an `x_search` tool, then fulfill it with the native `XClient` from `@aphrody/x` (no extra keys, fully local/native).\n\nExample tool handler (user code):\n```ts\nimport { XClient } from \"@aphrody/x\";\nconst x = new XClient(session);\nif (tool.name === \"x_search\") {\n  const results = await x.search(args.query, args.count);\n  // feed back as tool result to chat.append( tool_result(...) )\n}\n```\n\nUsing built-in XTools (recommended):\n```ts\nimport { XaiClient, XTools, xSearchToolDef, xWhoamiToolDef, xTweetsToolDef, xNewsToolDef } from \"@aphrody/xai\";\nconst grok = new XaiClient();\nconst xTools = new XTools(); // reuses our native packages/x (cookie, store, stealth)\n\nconst chat = grok.createChat(\"grok-3\", { tools: [xSearchToolDef, xWhoamiToolDef, xTweetsToolDef, xNewsToolDef] });\n// after Grok returns a tool_call e.g. for x_tweets or x_news:\nconst toolRes = await xTools.tweets({ handle: \"aphrody\", count: 5 });\n// or await xTools.news({count:3}); await xTools.whoami();\nchat.append({ role: \"tool\", tool_call_id: toolCall.id, content: JSON.stringify(toolRes) });\nconst final = await chat.sample();\n```\n\nXTools now covers key X actions for Grok agentic use (all use the native @aphrody/x XClient under the hood for zero extra keys, full stealth, and local SQLite state):\n\n- `search({query, count?, mode?})`: Latest/Top search.\n- `profile({handle})`: User profile.\n- `whoami()`: Authenticated viewer.\n- `tweets({handle, count?})`: User timeline.\n- `news({count?})`: Explore/trending news.\n\n**Testability**: XTools constructor accepts an optional pre-built (or mocked) XClient instance for unit testing without real network or auth:\n\n```ts\nconst mockX = { search: async (q) => ({tweets: [...]}) /* etc */ };\nconst xTools = new XTools(mockX);\n```\n\nCorresponding tool defs (`xSearchToolDef`, etc.) and the `xNativeTools` array are exported for easy use in `createChat({ tools: xNativeTools })`.\n\nSee `src/tools/x.ts` for full signatures and simplified return shapes suitable for tool results.\n\nSimple agent loop with native X tools:\n```ts\nconst grok = new XaiClient();\nconst xTools = new XTools();\nconst chat = grok.createChat(\"grok-3\", { tools: xNativeTools as any });\n\nchat.append(user(\"What's the latest on bxc or xai on X?\"));\nlet res = await chat.sample();\n\nwhile (res.choices[0]?.message?.tool_calls?.length) {\n  const n = await chat.executeToolCalls({\n    x_search: (a) => xTools.search(a),\n    x_profile: (a) => xTools.profile(a),\n    x_whoami: () => xTools.whoami(),\n    x_tweets: (a) => xTools.tweets(a),\n    x_news: (a) => xTools.news(a),\n  });\n  if (n === 0) break;\n  res = await chat.sample();\n}\nconsole.log(res.choices[0]?.message?.content);\n```\n\n## Low-level (still supported)\n\n```ts\nimport { XaiClient } from \"@aphrody/xai\";\n\nconst client = new XaiClient();\nconst models = await client.listModels();\nconst reply = await client.complete(\"Explain Rust in one line\", \"grok-3-mini\");\n```\n\n## MCP\n\n- `bxc_grok_whoami`\n- `bxc_grok_models`\n- `bxc_grok_chat` (now also supports high-level via the package)\n\n## API Quick Reference (high-level)\n\n```ts\n// Chat session\nconst chat = client.createChat(model, { messages?, tools?, reasoning_effort?, response_format?, ... });\nchat.append(msgOrStringOrResponse);\nconst res = await chat.sample();\nconst stream = chat.stream(); // yields {content?, toolCallDeltas?, toolCalls?, done, response?}\nconst n = await chat.executeToolCalls({ toolName: (args) => impl(args) }); // returns #executed\nconst structured = await chat.sampleStructured<T>(schema?); // { ...res, parsed? }\n\n// XTools (for Grok tool fulfillment or direct use)\nconst xTools = new XTools(sessionOrMockClient?);\nawait xTools.search({query, count?, mode?});\nawait xTools.profile({handle});\nawait xTools.whoami();\nawait xTools.tweets({handle, count?});\nawait xTools.news({count?});\n```\n\nSee `src/core/client.ts` (Chat + XaiClient), `src/tools/x.ts` (XTools + all *ToolDef), `src/index.ts` (exports + `xNativeTools` array).\n\nRunnable example: [packages/xai/examples/grok-x-agent.ts](examples/grok-x-agent.ts) (full agent loop with native X fulfillment).\n\n## Production-grade Grok + native X\n\nThe combo `@aphrody/xai` (Chat + XTools) + `@aphrody/x` (XClient) enables fully keyless, native, agentic Grok flows inside bxc: Grok can call x_search / x_tweets / x_news / x_whoami / x_profile tools; fulfillment is done locally with stealth cookies + sqlite, results fed back as tool messages. Improved Chat error handling, reasoning_effort/search_params/response_format parity, and basic structured (zod-if-present or json simple) make it robust for autonomous agents. All verified unit-only (30 pass + 2 skip live, 32 total, no live API required by default).\n\nSee also: packages/x/docs/* (including the new top-level README.md), src/cli/{grok,x}.ts , MEGA-PLAN.md (shipped milestone for native clients), tests in `packages/*/index.test.ts`.\n\n## Contributing & Notes\n\n- Keep packages light (dynamic zod for structured if present at runtime).\n- Prefer tools + XTools for agentic X access over legacy search_parameters.\n- Update catalog/surfaces via the scripts in root bxc when X changes.\n- Tests: `bun test packages/xai packages/x` (unit-only by default; live opt-in via env flags). Now includes comprehensive units for new high-level features: Chat (multi-turn, stream with toolCallDeltas, executeToolCalls, sampleStructured, error handling, param forwarding like reasoning_effort), XTools (instantiation, methods with injectable mocks, defs), tool calling sims, structured outputs, x + xai synergy, full agentic loop with auto-dispatch. 30 pass + 2 live-skipped (32 total across x+xai, 120 expect() calls).\n\nSee `index.test.ts` for details (all mocks, no live required for core coverage). Also `packages/x/index.test.ts` for algo + client units + cross synergy.","readmeFilename":"README.md"}