@302ai/media-studio-core 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 302.AI
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,213 @@
+# @302ai/media-studio-core
+
+Outbound client and isomorphic core SDK for 302.AI Media Studio services. Provides high-level client management (`MediaStudioClient`), session lifecycle and prewarming (`client.sessions`), and low-level streaming chat completions transport (`sendChatUpstream`).
+
+## Install
+
+```bash
+bun add @302ai/media-studio-core
+```
+
+## Usage
+
+### High-level client & sessions
+
+```ts
+import { createMediaStudioClient } from "@302ai/media-studio-core";
+
+const client = createMediaStudioClient({
+  baseUrl: "https://media.302.ai",
+  apiKey: process.env.API_302_KEY,
+});
+
+// List sessions from server
+const { sessions } = await client.sessions.list({ limit: 20 });
+
+// Provision a new session via prewarm
+const outcome = await client.sessions.prewarm({
+  sessionId: crypto.randomUUID(),
+  source: "cli", // "web" | "cli"
+  note: "CLI Session",
+  onStageChange: (stage) => console.log(`Stage: ${stage}`),
+  onSessionReady: (session) => {
+    // Upstream commit point: safe to save pointer
+    saveSessionId(session.id);
+  },
+});
+
+// Delete a session
+await client.sessions.remove(sessionId);
+```
+
+### Low-level raw stream transport
+
+```ts
+import { sendChatUpstream, ChatUpstreamError } from "@302ai/media-studio-core";
+
+try {
+  const response = await sendChatUpstream({
+    apiBaseUrl: "https://api.302.ai",
+    apiKey: process.env.API_302_KEY,
+    sessionId: "your-stable-session-id",
+    messages: [{ role: "user", content: "Draw me a cat" }],
+  });
+
+  for await (const chunk of response.body) {
+    // Your own SSE handling. No pipeline is applied for you.
+  }
+} catch (error) {
+  if (error instanceof ChatUpstreamError) {
+    console.error(error.status, error.message);
+  }
+}
+```
+
+## API
+
+### `client.sessions`
+
+Session management against the Media Studio gateway (`MediaStudioClient.prototype.sessions`).
+
+#### `client.sessions.list(query?): Promise<ListSessionsResponse>`
+
+Lists sessions stored upstream on the server (the single source of truth).
+
+| Query Field | Type | Notes |
+| --- | --- | --- |
+| `limit` | `number` | Optional maximum count of sessions to return. |
+| `offset` | `number` | Optional offset for pagination. |
+| `note` | `string` | Optional substring filter on session notes. |
+
+Returns `{ sessions: SessionItem[], total?: number }`. Each `SessionItem` contains `id`, `note`, `source` (`"web"` | `"cli"`), `createdAt`, and `updatedAt`.
+
+#### `client.sessions.remove(sessionId): Promise<void>`
+
+Deletes a session server-side. Destroys upstream conversation memory irreversibly. Throws `ChatUpstreamError` on HTTP failure.
+
+#### `client.sessions.prewarm(options): Promise<SessionPrewarmOutcome>`
+
+Provisions a session via the prewarm SSE endpoint (`/api/sessions/prewarm`) — the same preparation flow used by the web app.
+
+**Options**:
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `sessionId` | `string` | Client-generated UUID for the session. |
+| `source` | `"web" \| "cli"` | Session creation provenance (`SessionSource`). |
+| `note` | `string` | Optional human-readable note/title. |
+| `installUserSkills` | `boolean` | Whether to install user library skills during prewarm. |
+| `signal` | `AbortSignal` | Request abort signal. |
+| `onStageChange` | `(stage) => void` | Stage progress callback: `"creating"` → `"sandbox"` → `"skills"` → `"finishing"`. |
+| `onSessionReady` | `(session) => void` | Fired once when `session_ready` arrives (upstream commit point). |
+
+**Outcome**:
+Returns a discriminated union `SessionPrewarmOutcome`:
+- `{ status: "ready", session: PrewarmSessionReady }` — Full provisioning completed (sandbox + skills ready).
+- `{ status: "fallback", session: PrewarmSessionReady }` — Session persisted upstream, but sandbox/skills provisioning failed or stream ended early; plain-text chat remains usable.
+- `{ status: "failed" }` — Failed before session creation; no session exists upstream.
+
+#### Prewarm Commit-Point Invariant (`session_ready`)
+
+The `session_ready` event is the upstream commit point:
+- **Before `session_ready`**: The session has not been committed to server storage. If the request fails or is aborted before this event, no session exists upstream; callers must NOT persist or store this `sessionId`.
+- **After `session_ready`**: The session is durably committed upstream. `onSessionReady` fires exactly once. Even if subsequent sandbox or skill stages fail (`status === "fallback"`), callers must KEEP this session ID and continue to chat with plain-text fallback. Calling `prewarm` again with a new ID after `onSessionReady` fired would abandon the previous session and leak orphan sessions on the server.
+
+### `sendChatUpstream(request): Promise<Response>`
+
+Resolves with the upstream streaming response. Throws `ChatUpstreamError` when the upstream status is not ok.
+
+**Required**
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `apiBaseUrl` | `string` | API origin. Trailing slash tolerated. |
+| `apiKey` | `string` | Sent as a bearer token. |
+| `sessionId` | `string` | Stable client session id. |
+| `messages` | `ChatUpstreamMessage[]` | OpenAI-format messages. |
+
+**Optional**
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `locale` | `string` | Forwarded so upstream can localize error text. |
+| `modelParams` | `string \| Record<string, unknown>` | Objects are JSON-serialized. |
+| `skillUrls` | `string[]` | Skill packages to load for this turn. |
+| `chatTaskId` | `string` | Switches upstream into poll/resume mode. |
+| `sinceSeq` | `number` | Incremental cursor; only meaningful with `chatTaskId`. |
+| `structuredOutput` | `boolean` | Defaults to `false` (AI SDK event stream). Set `true` for raw claude-code stream-json. |
+| `signal` | `AbortSignal` | Ties upstream request lifetime to your connection. |
+
+Streaming is always on and the endpoint path is fixed, so neither is caller-controllable.
+
+### `ChatUpstreamError`
+
+Extends `Error` with `status` (the upstream HTTP status) and `body` (the raw response text). Its `message` is the human-readable upstream text.
+
+### `extractUpstreamErrorMessage(body): string | null`
+
+Pulls a readable message out of an upstream error body, checking in order: `error.message_cn`, `error.message`, `message_cn`, `message`, `error`.
+
+## Development & Testing
+
+### In-repo iteration
+
+The app and vitest alias `@302ai/media-studio-core` to `src/index.ts`
+(tsconfig `paths` + `vitest.config.ts`), so **no build step is needed** while
+developing — edits are picked up directly. Unit tests are co-located
+(`*.test.ts` next to source) and run from the repo root:
+
+```bash
+bun run test                  # full suite (vitest resolves core to src)
+```
+
+### Build
+
+```bash
+bun run package:build         # tsc -> dist/ + fix-dist.ts (.js specifier repair)
+```
+
+`exports` points at `dist/` unconditionally — the published artifact and the
+in-repo source are two different files.
+
+### Publishing gates (required before every publish)
+
+```bash
+bun run package:check         # = build + publint + attw + smoke, chained
+```
+
+| Script | What it catches |
+| --- | --- |
+| `package:build` | Compile errors; emits ESM + `.d.ts` |
+| `package:lint` | `publint` manifest/packaging defects |
+| `package:types` | `attw --profile esm-only` type-resolution defects |
+| `package:smoke` | The only check that runs the **published artifact** |
+
+**Why the smoke test matters:** because local tooling aliases to `src`, the
+app NEVER executes `dist` — every in-repo gate can pass while `dist` is
+broken. `package:smoke` packs the real tarball, installs it outside the repo,
+imports it under real Node ESM, and type-checks the shipped `.d.ts` under
+`nodenext`. It has already caught two real defects (extensionless relative
+specifiers; a `publishConfig.exports` map only pnpm honours). See
+`docs/adr/0004-chat-upstream-client-package.md`.
+
+Run `package:check` whenever you touch `packages/**`, `bunfig.toml`,
+`bun.lock`, `tsconfig.json`, or the root manifest — and always before a
+publish.
+
+### Notes learned the hard way
+
+- `bun pm pack` does NOT run publish lifecycle scripts; the smoke script
+  builds explicitly first. Don't assume pack produces a fresh dist.
+- Publishing is manual by design (`bun publish --dry-run` first; version
+  numbers are burned by hand and never reused).
+- `attw` node10-resolution failure and the CJS warning are intrinsic to an
+  ESM-only package — the `esm-only` profile records that intent, don't
+  "fix" them with a CJS build.
+
+## Notes
+
+No logging, no retries, no AI SDK dependency. Observability and retry policy are the caller's to own.
+
+## License
+
+Apache-2.0. Copyright 2026 302.AI. See [LICENSE](./LICENSE).

package/dist/client/auth.d.ts

@@ -0,0 +1,13 @@
+import { type MeResponse } from "./types.js";
+export declare class ClientAuth {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly customFetch;
+    constructor(baseUrl: string, apiKey: string, customFetch?: typeof fetch);
+    /**
+     * Fetches current authentication status and user details from /api/auth/me.
+     *
+     * @throws {ChatUpstreamError} on HTTP failure or invalid token (401).
+     */
+    getMe(): Promise<MeResponse>;
+}

package/dist/client/auth.js

@@ -0,0 +1,34 @@
+import { ChatUpstreamError, extractUpstreamErrorMessage, } from "../transport/errors.js";
+import { MeResponseSchema } from "./types.js";
+export class ClientAuth {
+    baseUrl;
+    apiKey;
+    customFetch;
+    constructor(baseUrl, apiKey, customFetch) {
+        this.baseUrl = baseUrl;
+        this.apiKey = apiKey;
+        this.customFetch = customFetch ?? fetch;
+    }
+    /**
+     * Fetches current authentication status and user details from /api/auth/me.
+     *
+     * @throws {ChatUpstreamError} on HTTP failure or invalid token (401).
+     */
+    async getMe() {
+        const url = `${this.baseUrl}/api/auth/me`;
+        const response = await this.customFetch(url, {
+            method: "GET",
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+            },
+        });
+        if (!response.ok) {
+            const rawBody = await response.text();
+            const message = extractUpstreamErrorMessage(rawBody) ||
+                `Authentication verification failed with status ${response.status}`;
+            throw new ChatUpstreamError(message, response.status, rawBody);
+        }
+        const rawJson = await response.json();
+        return MeResponseSchema.parse(rawJson);
+    }
+}

package/dist/client/chat.d.ts

@@ -0,0 +1,14 @@
+import { ChatStream } from "../stream/stream.js";
+import type { ChatTurnOptions, QuickPromptOptions } from "./types.js";
+export declare class ClientChat {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly defaultLocale?;
+    private readonly customFetch;
+    constructor(baseUrl: string, apiKey: string, defaultLocale?: string, customFetch?: typeof fetch);
+    private executeTurn;
+    raw(prompt: string, options: QuickPromptOptions): Promise<Response>;
+    raw(options: ChatTurnOptions): Promise<Response>;
+    stream(prompt: string, options: QuickPromptOptions): Promise<ChatStream>;
+    stream(options: ChatTurnOptions): Promise<ChatStream>;
+}

package/dist/client/chat.js

@@ -0,0 +1,89 @@
+import { isNotNil, isString } from "es-toolkit/predicate";
+import { ChatStream } from "../stream/stream.js";
+export class ClientChat {
+    baseUrl;
+    apiKey;
+    defaultLocale;
+    customFetch;
+    constructor(baseUrl, apiKey, defaultLocale, customFetch) {
+        this.baseUrl = baseUrl;
+        this.apiKey = apiKey;
+        this.defaultLocale = defaultLocale;
+        this.customFetch = customFetch ?? fetch;
+    }
+    executeTurn(options) {
+        const base = this.baseUrl;
+        const url = `${base}/api/chat/claude-sse`;
+        const headers = {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${this.apiKey}`,
+            "X-User-Session-Id": options.sessionId,
+        };
+        if (this.defaultLocale) {
+            headers["X-UI-Locale"] = this.defaultLocale;
+        }
+        const body = {
+            session_id: options.sessionId,
+            messages: options.messages,
+            ...(options.chatTaskId ? { chat_task_id: options.chatTaskId } : {}),
+            ...(isNotNil(options.sinceSeq) ? { since_seq: options.sinceSeq } : {}),
+            ...(isNotNil(options.modelParams)
+                ? { model_params: options.modelParams }
+                : {}),
+            ...(isNotNil(options.skillUrls) ? { skill_urls: options.skillUrls } : {}),
+            ...(isNotNil(options.structuredOutput)
+                ? { structured_output: options.structuredOutput }
+                : {}),
+        };
+        // If single user turn with string content, also set prompt for gateway convenience
+        if (options.messages.length === 1 &&
+            options.messages[0].role === "user" &&
+            isString(options.messages[0].content)) {
+            body.prompt = options.messages[0].content;
+        }
+        return this.customFetch(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+            signal: options.signal,
+        });
+    }
+    async raw(promptOrOptions, maybeOptions) {
+        if (isString(promptOrOptions)) {
+            if (!maybeOptions) {
+                throw new Error("QuickPromptOptions including sessionId is required");
+            }
+            return this.executeTurn({
+                sessionId: maybeOptions.sessionId,
+                messages: [{ role: "user", content: promptOrOptions }],
+                chatTaskId: maybeOptions.chatTaskId,
+                signal: maybeOptions.signal,
+                maxRetries: maybeOptions.maxRetries,
+                initialRetryDelayMs: maybeOptions.initialRetryDelayMs,
+                onFinalResponse: maybeOptions.onFinalResponse,
+            });
+        }
+        return this.executeTurn(promptOrOptions);
+    }
+    async stream(promptOrOptions, maybeOptions) {
+        if (isString(promptOrOptions)) {
+            if (!maybeOptions) {
+                throw new Error("QuickPromptOptions including sessionId is required");
+            }
+            return new ChatStream(() => this.raw(promptOrOptions, maybeOptions), {
+                maxRetries: maybeOptions.maxRetries,
+                initialRetryDelayMs: maybeOptions.initialRetryDelayMs,
+                signal: maybeOptions.signal,
+                onFinalResponse: maybeOptions.onFinalResponse,
+                onError: maybeOptions.onError,
+            });
+        }
+        return new ChatStream(() => this.raw(promptOrOptions), {
+            maxRetries: promptOrOptions.maxRetries,
+            initialRetryDelayMs: promptOrOptions.initialRetryDelayMs,
+            signal: promptOrOptions.signal,
+            onFinalResponse: promptOrOptions.onFinalResponse,
+            onError: promptOrOptions.onError,
+        });
+    }
+}

package/dist/client/client.d.ts

@@ -0,0 +1,20 @@
+import { ClientAuth } from "./auth.js";
+import { ClientChat } from "./chat.js";
+import { ChatSession } from "./session.js";
+import { ClientSessions } from "./sessions.js";
+import type { ChatSessionOptions, MediaStudioClientOptions } from "./types.js";
+export declare class MediaStudioClient {
+    readonly baseUrl: string;
+    readonly apiKey: string;
+    readonly locale?: string;
+    readonly auth: ClientAuth;
+    readonly chat: ClientChat;
+    readonly sessions: ClientSessions;
+    constructor(options: MediaStudioClientOptions);
+    /**
+     * Creates a multi-turn conversation session that maintains `sessionId`
+     * and conversation history across turns.
+     */
+    createSession(options?: ChatSessionOptions): ChatSession;
+}
+export declare function createMediaStudioClient(options: MediaStudioClientOptions): MediaStudioClient;

package/dist/client/client.js

@@ -0,0 +1,34 @@
+import { ClientAuth } from "./auth.js";
+import { ClientChat } from "./chat.js";
+import { ChatSession } from "./session.js";
+import { ClientSessions } from "./sessions.js";
+export class MediaStudioClient {
+    baseUrl;
+    apiKey;
+    locale;
+    auth;
+    chat;
+    sessions;
+    constructor(options) {
+        const trimmedKey = options.apiKey.trim();
+        if (!trimmedKey) {
+            throw new Error("apiKey is required and cannot be empty");
+        }
+        this.apiKey = trimmedKey;
+        this.baseUrl = (options.baseUrl ?? "https://media.302.ai").replace(/\/+$/, "");
+        this.locale = options.locale;
+        this.auth = new ClientAuth(this.baseUrl, this.apiKey, options.fetch);
+        this.chat = new ClientChat(this.baseUrl, this.apiKey, this.locale, options.fetch);
+        this.sessions = new ClientSessions(this.baseUrl, this.apiKey, options.fetch);
+    }
+    /**
+     * Creates a multi-turn conversation session that maintains `sessionId`
+     * and conversation history across turns.
+     */
+    createSession(options) {
+        return new ChatSession(this.chat, options);
+    }
+}
+export function createMediaStudioClient(options) {
+    return new MediaStudioClient(options);
+}

package/dist/client/session.d.ts

@@ -0,0 +1,33 @@
+import type { ChatStream } from "../stream/stream.js";
+import type { ChatUpstreamMessage } from "../transport/types.js";
+import type { ClientChat } from "./chat.js";
+import type { ChatSessionOptions, QuickPromptOptions } from "./types.js";
+export declare class ChatSession {
+    readonly sessionId: string;
+    private readonly chat;
+    private messages;
+    private isTurnActive;
+    constructor(chat: ClientChat, options?: ChatSessionOptions);
+    /**
+     * Whether a message turn is currently in-flight.
+     */
+    get isBusy(): boolean;
+    /**
+     * Returns a copy of the current in-memory conversation history.
+     */
+    getMessages(): ChatUpstreamMessage[];
+    /**
+     * Clears accumulated turn history while preserving the session ID.
+     */
+    clearHistory(): void;
+    /**
+     * Sends a user turn within this session.
+     *
+     * Automatically appends the user message to history, dispatches the full
+     * history to the model, and asynchronously appends the assistant's reply
+     * to history once the stream completes.
+     *
+     * Throws an error if another turn is already active on this session.
+     */
+    sendMessage(prompt: string, options?: Omit<QuickPromptOptions, "sessionId">): Promise<ChatStream>;
+}