![\"SocAIty](\"docs/socaity_icon.png\"){kind=icon}
\n\n \n
\n ![\"npm](\"https://badge.fury.io/js/socaity.svg\"){kind=icon}
\n ![\"License:](\"https://img.shields.io/badge/License-MIT-blue.svg\"){kind=icon}
\n ![\"Node](\"https://img.shields.io/badge/node-%E2%89%A520-brightgreen.svg\"){kind=icon}
\n ![\"socaity.ai\"](\"https://img.shields.io/badge/platform-socaity.ai-0A86BF\"){kind=icon}
\n socaity-js is the browser-first JavaScript client for socaity.ai and any APIPod service.
\n Connect by URL, submit a job, await the result or stream it live — same mental model as the Python stack.\n
\n Quickstart ·\n Why this ·\n Features ·\n Jobs & streaming ·\n Auth ·\n Ecosystem\n
\n\n---\n\n## Quickstart\n\nThree lines. Under five minutes. Any Socaity or APIPod endpoint.\n\n```typescript\nimport { socaity, connect } from 'socaity';\n\nsocaity.setApiKey('sk_...'); // free key at socaity.ai\nconst client = await connect('https://api.socaity.ai/services/v1/speechcraft');\n\nconst audio = await client.submitJob('/text2voice', { text: 'Welcome to generative AI' });\nawait audio.save('welcome.mp3');\n```\n\nThat is the whole pattern: **connect to a service, submit a job, save the result.**\n\nBrowse the model catalog at [socaity.ai/APIs/Overview](https://www.socaity.ai/APIs/Overview).\n\n---\n\n## Why socaity-js\n\nCalling AI services from the browser or Node sounds simple until you ship it: long-running jobs need polling, file uploads differ per content type, streaming SSE must be parsed, and every endpoint wants a different request shape.\n\n| | Raw `fetch` | Generic HTTP client | socaity-js |\n|---|---|---|---|\n| Call pattern | Hand-roll every endpoint | One client, no schema awareness | `connect()` → typed `submitJob()` |\n| Long-running jobs | Build your own poll loop | Not included | Built-in job handles + events |\n| Media I/O | Manual Blob/base64 juggling | Partial | [media-toolkit-js](https://github.com/SocAIty/media-toolkit-js) in and out |\n| Streaming | Parse SSE yourself | Varies | `job.stream().iterText()` / `iterBytes()` |\n| Socaity gateway | Wire envelope + links yourself | — | Normalized `SocaityJobResponse` polling |\n\n**Why not use the Python SDK?** Use it on the backend. socaity-js is the lightweight JS counterpart: Socaity/APIPod only, no multi-provider layer, pure web APIs (`fetch`, `FormData`, streams), ES + UMD builds for browser bundles.\n\n**Why not call the REST API directly?** You can. This package is the transport layer the Socaity frontend and your apps share — job envelopes, progress events, stream assembly, and media parsing already handled.\n\n---\n\n## Key features\n\n**Connect and call.** Point at a service URL; the SDK loads its OpenAPI spec and returns a client. Or pass a catalog `ServiceDefinition` you already have.\n\n**Job handles, not blocked HTTP.** Every submission returns a `Job` immediately. Await it, observe progress, stream live, or cancel — in parallel across many calls.\n\n```typescript\nconst tts = client.submitJob('/text2voice', { text: 'Hello' });\nconst img = client.submitJob('/text2img', { prompt: 'A robot at sunset' });\n// ... do other work ...\nconst [audio, images] = await Promise.all([tts, img]);\n```\n\n**Streaming built in.** Chat tokens, TTS chunks, and binary media streams share one API. Iterate live or let `getResult()` assemble the full payload.\n\n**Files just work.** Inputs accept paths (Node), URLs, base64, Blobs/Files (browser), or `MediaFile` instances. Results with media content arrive as typed `ImageFile` / `AudioFile` / `VideoFile` objects.\n\n**Browser-first, Node too.** No Node-only HTTP stack — the same bundle runs in Vite/Nuxt and in Node ≥ 20.\n\n---\n\n## Jobs and streaming\n\nCalls return a **job** handle, not a blocked connection. Poll when ready, cancel when not, run many in parallel.\n\n```typescript\nconst job = client.submitJob('/text2img', { prompt: 'A futuristic city at sunset' });\n\njob.onStatus((status) => console.log(status)); // QUEUED → PROCESSING → FINISHED\njob.onProgress(({ progress, message }) => console.log(progress, message));\n\n// await job; // same as job.getResult()\n// await job.cancel(); // abort locally + POST links.cancel when present\n// await job.interruptAndWait(); // graceful stop, then getResult()\n\nconst images = await job;\nawait images[0].save('city.jpg');\n```\n\n### Live streaming\n\nSchema endpoints (chat, TTS, video) accept `stream: true`. Iterate tokens or bytes as they arrive:\n\n```typescript\nconst job = client.submitJob('/chat', {\n messages: [{ role: 'user', content: 'Explain why an SDK beats raw HTTP.' }],\n stream: true,\n});\n\nfor await (const text of (await job.stream()).iterText()) {\n process.stdout.write(text); // OpenAI-style SSE deltas\n}\n```\n\nThree iterators on `StreamSession`:\n\n| Method | Returns |\n|---|---|\n| `iterText()` | Joined chat/token text |\n| `iterChunks()` | Decoded SSE JSON items |\n| `iterBytes()` | Raw network chunks |\n\nIf you never call `stream()`, `await job` drains the body and assembles the final result (text or typed media file).\n\n### Chat and LangChain.js\n\nFor chat services there are two purpose-built layers. `ChatServiceAdapter` speaks the OpenAI wire format (tools, tool_choice, logprobs, reasoning, streaming) without any framework:\n\n```typescript\nimport { ChatServiceAdapter } from 'socaity';\n\nconst chat = await ChatServiceAdapter.connect(serviceUrl);\nconst response = await chat.complete({ messages: [{ role: 'user', content: 'hi' }] });\n\nfor await (const chunk of chat.streamChunks({ messages })) {\n process.stdout.write(chunk.choices[0]?.delta?.content ?? '');\n}\n```\n\n`ChatSocaity` plugs the same service into LangChain.js (install `@langchain/core`, it is an optional peer dependency):\n\n```typescript\nimport { ChatSocaity } from 'socaity/langchain';\n\nconst model = new ChatSocaity({ model: serviceUrl });\nconst bound = model.bindTools([myTool], { tool_choice: 'auto' });\nconst answer = await bound.invoke([new HumanMessage('What is the weather in Boston?')]);\n```\n\nStreaming, tool calls, forced `tool_choice`, reasoning content (`additional_kwargs.reasoning_content`) and usage metadata all round-trip. The Python SDK ships the same pair (`socaity.integrations`).\n\n### Catalog service definitions\n\nWhen the Socaity frontend (or your backend) already provides a `ServiceDefinition`, skip OpenAPI discovery:\n\n```typescript\nimport { createClient } from 'socaity';\n\nconst client = createClient(serviceDefinition, {\n address: 'https://api.socaity.ai/services/v1/