@talqing/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Talqing
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,193 @@
+# Talqing TypeScript SDK
+
+The TypeScript client for the Talqing `/v1` API, generated from
+`openapi/openapi.json`. It is the same set of operations, under the same names,
+as the Python SDK — both come from the surface `backend/api/sdk_surface.py`
+declares.
+
+Two entrypoints:
+
+- `@talqing/sdk` — the API. Dependency-free, `fetch`-based.
+- `@talqing/sdk/browser` — the LiveKit layer for web calls, so a
+  tenant never types `livekit-client` themselves.
+
+```bash
+npm install @talqing/sdk
+```
+
+Node 20 or newer. `react` and `react-dom` are peer dependencies of the
+`/browser` entrypoint only — a server-side consumer never installs them.
+
+## Authentication
+
+```ts
+import { TalqingClient } from "@talqing/sdk";
+
+const talqing = new TalqingClient({
+  baseUrl: "https://api.in.talqing.com",
+  token: process.env.TALQING_API_TOKEN,
+});
+
+const me = await talqing.auth.me();
+```
+
+`baseUrl` is required and has no default. Bundlers inline `NEXT_PUBLIC_*` at
+build time, so a missing value cannot be caught at runtime — a localhost
+fallback would silently ship a production bundle calling a server that is not
+there.
+
+In the dashboard, pass `credentials: "include"` to send the cookie session
+instead of a token, and `onUnauthorized` to handle a dead session in one place:
+
+```ts
+const baseUrl = process.env.NEXT_PUBLIC_API_URL;
+if (!baseUrl) throw new Error("NEXT_PUBLIC_API_URL is required");
+
+const talqing = new TalqingClient({
+  baseUrl,
+  credentials: "include",
+  onUnauthorized: () => router.push("/login"),
+});
+```
+
+## The shape of it
+
+Operations are reached by resource, exactly as the API names them. Path and
+query parameters are one flat object; a request body is keyed by its schema
+name.
+
+```ts
+await talqing.agents.list({ limit: 50 });
+await talqing.agents.get({ agent_id });
+await talqing.agents.versions.rollback({ agent_id, version: 3 });
+await talqing.calls.batches.pause({ batch_id });
+await talqing.telephony.phoneNumbers.assign({
+  number_id,
+  assignPhoneNumberRequest: { agent_id },
+});
+
+const agent = await talqing.agents.create({
+  createAgentRequest: { config: { name: "Support bot", channel: "text" } },
+});
+await talqing.agents.publish({ agent_id: agent.id });
+```
+
+The body key is the generator's one ergonomic cost — hey-api has no `body`
+option — and it is uniform, so it is the same shape at every write call site.
+
+## Errors
+
+Every non-2xx throws `TalqingApiError`. There is one error shape, so there is
+nothing to branch on:
+
+```ts
+import { TalqingApiError } from "@talqing/sdk";
+
+try {
+  await talqing.agents.publish({ agent_id });
+} catch (error) {
+  if (error instanceof TalqingApiError) {
+    console.error(error.status, error.message); // 400 config is invalid
+    error.errors.forEach(console.error);        // ["llm: unknown model gpt-4.9"]
+  }
+}
+```
+
+## Pagination
+
+Every list endpoint pages the same way, so one helper covers all of them:
+
+```ts
+import { paginate } from "@talqing/sdk";
+
+for await (const agent of paginate((q) => talqing.agents.list(q))) {
+  console.log(agent.config.name);
+}
+```
+
+## Live streams
+
+Six endpoints stay open and push events. Each frame is typed, and repeats its
+own name in `event`, which is what narrows the union:
+
+```ts
+const { stream } = await talqing.conversations.events({ conversation_id });
+
+for await (const event of stream) {
+  if (event.event === "assistant.delta") process.stdout.write(event.text);
+  if (event.event === "turn" && event.status === "done") break;
+}
+```
+
+`talqing.copilot.agents.stream`, `copilot.tools.stream`,
+`copilot.knowledge.stream`, `copilot.tasks.stream` and `knowledge.events` work
+the same way.
+
+## Text conversations
+
+Text agents never create or join a LiveKit room. Open the conversation, then
+send turns — both addressed by your own `contact_key`, so the same key always
+reaches the same thread — and watch it happen on the stream above.
+
+```ts
+const conversation = await talqing.conversations.create({
+  createTextConversationRequest: { contact_key: "user-42", agent_id },
+});
+
+await talqing.conversations.messages.create({
+  textMessageRequest: {
+    contact_key: "user-42",
+    message: "Hello",
+    client_message_id: crypto.randomUUID(),
+  },
+});
+```
+
+## Web calls
+
+Voice and video agents take a LiveKit room token. The `/browser` entrypoint
+wraps the whole join — installing this package is all a tenant needs.
+
+```tsx
+import { TalqingSessionProvider, useTalqingSession } from "@talqing/sdk/browser";
+
+function App({ agentId }: { agentId: string }) {
+  const session = useTalqingSession({ client: talqing, agentId });
+  return (
+    <TalqingSessionProvider session={session}>
+      <Call />
+    </TalqingSessionProvider>
+  );
+}
+```
+
+It also carries `useTalqingImages` for attaching a photo mid-call,
+`useTalqingFrontendRpcs` for tools that call back into your page,
+`useTalqingUserdata`, `useTalqingAvatarTrack` and `TalqingVideoTrack` for a
+video agent, and audio capture defaults with echo cancellation on — without
+which the agent hears its own speech through the microphone.
+
+## Types
+
+Every request and response shape is exported, named as the API names it:
+
+```ts
+import type { AgentConfig, AgentResponse, CallOutcome, OperationRequest } from "@talqing/sdk";
+```
+
+`Page<T>` is the shape every list endpoint returns. OpenAPI has no generics, so
+the document spells each instantiation out (`PageAgentResponse`); TypeScript is
+structural, so those satisfy `Page<AgentResponse>` and generic helpers work.
+
+## Regenerating
+
+`src/gen` is generated and checked in. After re-running `openapi/export.py`:
+
+```bash
+npm run generate         # rewrite it
+npm run generate:check   # or just assert it is current
+npm run build            # dist/, which the dashboard resolves through
+```
+
+Everything else in `src` is hand-written: the client, the error, the pagination
+helper and the LiveKit layer — what the document cannot say.

package/dist/browser.d.ts

@@ -0,0 +1,153 @@
+import React from "react";
+import { Room, type RoomOptions } from "livekit-client";
+import { type ReceivedMessage, type TrackReference, type UseSessionReturn } from "@livekit/components-react";
+import type { JsonObject, JsonValue, TalqingClient } from "./client.js";
+import type { ScreenShareCaptureOptions, TrackPublishOptions } from "livekit-client";
+import type { CallTokenResponse, TokenRequest } from "./gen/types.gen.js";
+/** Everything about one web call except which agent runs it. Wire-shaped, like
+ *  every other request type in this SDK. */
+export type TalqingCallOptions = Omit<TokenRequest, "agent_id">;
+export interface TalqingBrowserSessionOptions {
+    client: TalqingClient;
+    agentId: string | null;
+    roomOptions?: RoomOptions;
+    callOptions?: TalqingCallOptions;
+    onTokenDetails?: (details: CallTokenResponse) => void;
+}
+export interface TalqingRpcInvocation {
+    payload: string;
+    responseTimeout?: number;
+    callerIdentity?: string;
+}
+export type TalqingRpcHandler = (data: TalqingRpcInvocation) => string | Promise<string>;
+export type TalqingRpcHandlers = Record<string, TalqingRpcHandler>;
+export interface TalqingFrontendRpcEnvelope {
+    method: string;
+    payload?: JsonValue;
+}
+export declare class TalqingRpcError extends Error {
+    readonly code: number;
+    readonly data?: string;
+    constructor(code: number, message: string, data?: string);
+}
+export type TalqingSession = UseSessionReturn;
+export type TalqingMessage = ReceivedMessage;
+export type TalqingVideoTrackRef = TrackReference;
+export declare function createTalqingTokenSource(client: TalqingClient, agentId: string | null, options?: TalqingCallOptions, onTokenDetails?: (details: CallTokenResponse) => void): import("livekit-client").TokenSourceLiteral;
+export declare const TALQING_AUDIO_CAPTURE_DEFAULTS: {
+    readonly echoCancellation: true;
+    readonly noiseSuppression: true;
+    readonly autoGainControl: true;
+};
+export declare function useTalqingSession({ client, agentId, roomOptions, callOptions, onTokenDetails, }: TalqingBrowserSessionOptions): TalqingSession;
+export declare function TalqingSessionProvider({ session, children, audio, }: {
+    session: TalqingSession;
+    children: React.ReactNode;
+    audio?: boolean;
+}): React.JSX.Element;
+export declare function useTalqingConnection(): {
+    isConnected: boolean;
+    connectionState: import("livekit-client").ConnectionState;
+    room: Room;
+    start: (options?: import("@livekit/components-react").SessionConnectOptions) => Promise<void>;
+    end: () => Promise<void>;
+};
+export declare function setTalqingUserdata(room: Room, patch: JsonObject, responseTimeout?: number): Promise<{
+    ok: boolean;
+    error?: string;
+}>;
+export declare function getTalqingUserdata(room: Room, keys?: string[], responseTimeout?: number): Promise<JsonObject>;
+export declare function useTalqingUserdata(): {
+    get: (keys?: string[], responseTimeout?: number) => Promise<JsonObject>;
+    set: (patch: JsonObject, responseTimeout?: number) => Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+};
+export declare const TALQING_IMAGE_TOPIC = "talqing.images";
+/** Decoded size the server refuses above. The downscale below keeps a phone
+ *  photo far under it; this is the belt for a file that is not a photo. */
+export declare const TALQING_IMAGE_MAX_BYTES: number;
+/** Longest side the server stores. Downscaling to it before sending is a
+ *  courtesy to the data channel, which is ordered and reliable and will
+ *  happily spend a minute pushing 10 MB past a call's audio. */
+export declare const TALQING_IMAGE_MAX_EDGE_PX = 1568;
+export type TalqingImageStatus = "sending" | "sent" | "failed" | "unknown";
+export interface TalqingSentImage {
+    /** The stream id `sendFile` returned, which the ack comes back under. */
+    streamId: string;
+    name: string;
+    /** An object URL for the downscaled image, for rendering the thumbnail.
+     *  Revoked when the hook unmounts. */
+    previewUrl: string;
+    status: TalqingImageStatus;
+    /** Set when `status` is "failed" or "unknown" — a sentence, shown as-is. */
+    error?: string;
+}
+/** Refuse what the browser can see is wrong, instantly and with no round trip.
+ *  Returns the sentence to show, or null when the file is fine. The server
+ *  re-validates everything regardless — this exists so the common mistakes cost
+ *  nothing to catch. */
+export declare function talqingImageRejection(file: File): string | null;
+/** Downscale to the longest edge the server keeps, re-encoding as JPEG or PNG.
+ *
+ *  Also what normalizes whatever the OS handed the file input — this is how a
+ *  Safari HEIC becomes a JPEG. Throws if the image cannot be decoded, which is
+ *  the third dropzone check. */
+export declare function talqingDownscaleImage(file: File): Promise<Blob>;
+/** Validate and downscale a file into the `data:` URL a text message carries.
+ *
+ *  `createTextMessage` takes `images: [{data_url, filename}]`; this produces the
+ *  `data_url`. It doubles as the thumbnail's `src`, so there is no object URL to
+ *  create and revoke. Throws the sentence to show if the file is refused. */
+export declare function talqingImageDataUrl(file: File): Promise<string>;
+/** Send images to the agent on this call, and follow what became of each.
+ *
+ *  `send` resolves once the bytes are on their way; the outcome arrives on the
+ *  returned list, which is what a thumbnail should render.
+ *
+ *  Takes the `Room` rather than reading it from the session context: a byte
+ *  stream and an RPC handler are room-level things, and passing the room keeps
+ *  this usable from a surface that manages its own connection —
+ *  `useTalqingConnection().room` inside a provider, or the Room you built. */
+export declare function useTalqingImages(room: Room | null | undefined): {
+    send: (file: File) => Promise<TalqingSentImage>;
+    sent: TalqingSentImage[];
+    clear: () => void;
+};
+export declare function useTalqingAgent(): {
+    state: "failed" | "idle" | "connecting" | "disconnected" | "listening" | "thinking" | "speaking" | "pre-connect-buffering" | "initializing";
+    isFinished: boolean;
+};
+export declare function useTalqingMessages(): {
+    messages: ReceivedMessage[];
+    send: (message: string, options?: import("livekit-client").SendTextOptions) => Promise<import("@livekit/components-react").ReceivedChatMessage>;
+    isSending: boolean;
+};
+export declare const TALQING_SCREEN_SHARE_CAPTURE: ScreenShareCaptureOptions;
+export declare const TALQING_SCREEN_SHARE_PUBLISH: TrackPublishOptions;
+export declare function useTalqingScreenShare(): {
+    /** Whether a screen is being shared right now. */
+    enabled: boolean;
+    /** True while the browser picker is open or the track is publishing. */
+    pending: boolean;
+    /** Opens the browser's share picker. Must be called from a user gesture. */
+    start: () => Promise<void> | Promise<boolean | undefined>;
+    /** Stops sharing. The agent is told it can no longer see on the next turn. */
+    stop: () => Promise<void> | Promise<boolean | undefined>;
+};
+export declare function useTalqingAvatarTrack(): TalqingVideoTrackRef | undefined;
+export declare function TalqingVideoTrack({ track, className, }: {
+    track: TalqingVideoTrackRef;
+    className?: string;
+}): React.JSX.Element;
+export declare function useTalqingRpcHandlers(handlers: TalqingRpcHandlers, enabled?: boolean): void;
+export declare function useTalqingFrontendRpcs(enabled?: boolean): {
+    actions: Record<string, {
+        payload?: JsonValue;
+        at: number;
+    }>;
+    clear: () => void;
+};
+export declare function setTalqingBrowserLogLevel(level: "debug" | "info" | "warn" | "error" | "silent"): void;
+//# sourceMappingURL=browser.d.ts.map

package/dist/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.tsx"],"names":[],"mappings":"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"}