Sync from diffio-ui

Author: nmharmon8

AGENTS.md

@@ -0,0 +1,26 @@
+# Repository Guidelines
+
+## Project Structure and Module Organization
+Source lives in `src/`, with API resource clients and serialization under `src/api/`, shared helpers in `src/core/`, errors in `src/errors/`, and shared types in `src/types/`. Entry points are `src/index.ts` and `src/Client.ts`. Tests live in `tests/` with unit coverage in `tests/unit/` and wire level coverage in `tests/wire/`. Mock server utilities for wire tests live in `tests/mock-server/`.
+
+## Build, Test, and Development Commands
+1. `npm run build` compiles TypeScript to `dist/` using `tsc`.
+2. `npm test` runs all Jest projects.
+3. `npm run test:unit` runs the unit test project only.
+4. `npm run test:wire` runs the wire test project with MSW based mocks.
+
+## Coding Style and Naming Conventions
+Use TypeScript with strict typing, avoid `any` unless there is no alternative. Indentation is two spaces, and semicolons are used. Use `camelCase` for variables and methods, `PascalCase` for classes and exported types. Follow existing filename patterns, `PascalCase` for class files and lowercase for small utilities. Keep public client options and request payloads in `camelCase`.
+
+## Testing Guidelines
+Tests use Jest with project separation for unit and wire suites. Test files follow the `*.test.ts` pattern, for example `tests/unit/client/Client.test.ts`. Prefer adding unit coverage for helper logic and wire tests for client request and response behavior. Run the smallest relevant suite while iterating, then run `npm test` before submitting changes.
+
+## Commit and Pull Request Guidelines
+Recent history shows short, descriptive subjects without strict prefixes, so keep commit messages concise and clear about the change. For pull requests, include a summary, the test commands you ran, and any API surface changes. If you add or change a public method, update `README.md` usage examples.
+
+## SDK Documentation Sync
+Whenever you change the SDK, update the website API documentation in `app/components/docs/` to match the new behavior. Before finishing any SDK update, use a sub agent to review and apply the documentation updates in `app/components/docs/`, and do not exit until that review is complete.
+Before finishing any SDK update, use a sub agent to review `README.md`, apply any updates needed to match the code, and do not exit until that review is complete.
+
+## Configuration Tips
+Set `DIFFIO_API_KEY` for authentication and `DIFFIO_API_BASE_URL` to target emulators or alternate environments. Use Node 18 or later so the built in `fetch` API is available.

LICENSE

@@ -1,11 +1,11 @@
 MIT License
 
-Copyright (c) 2026 Diffio AI
+Copyright (c) 2026 Diffio
 
 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
+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:
 

README.md

@@ -0,0 +1,204 @@
+# Diffio JS SDK
+
+The Diffio JS SDK helps you call the Diffio API from Node. This version covers project creation, upload, generation, progress checks, and download URLs.
+
+## Install
+
+```bash
+npm install diffio-js
+```
+
+For local development:
+
+```bash
+cd diffio-js
+npm install
+```
+
+## Configuration
+
+Set the API key with `DIFFIO_API_KEY`. You can also override the base URL with `DIFFIO_API_BASE_URL`.
+
+```bash
+export DIFFIO_API_KEY="diffio_live_..."
+export DIFFIO_API_BASE_URL="https://us-central1-diffioai.cloudfunctions.net"
+```
+
+For emulators, set the base URL to the Functions emulator host.
+
+```bash
+export DIFFIO_API_BASE_URL="http://127.0.0.1:5001/diffioai/us-central1"
+```
+
+## Request options
+
+Use request options to override headers, timeouts, retries, or the API key per request.
+
+```ts
+import { DiffioClient } from "diffio-js";
+
+const client = new DiffioClient({ apiKey: "diffio_live_..." });
+const projects = await client.listProjects({
+  requestOptions: {
+    headers: { "X-Debug": "1" },
+    timeoutInSeconds: 30,
+    maxRetries: 2,
+    retryBackoff: 0.5
+  }
+});
+```
+
+## Create a project and generation
+
+`createProject` uploads the file and returns the project metadata.
+
+```ts
+import { DiffioClient } from "diffio-js";
+
+const client = new DiffioClient({ apiKey: "diffio_live_..." });
+const filePath = "sample.wav";
+
+const project = await client.createProject({
+  filePath
+});
+
+const generation = await client.createGeneration({
+  apiProjectId: project.apiProjectId,
+  model: "diffio-2",
+  sampling: { steps: 12, guidance: 1.5 }
+});
+
+console.log(generation.generationId);
+```
+
+## Audio isolation helper
+
+```ts
+import { DiffioClient } from "diffio-js";
+
+const client = new DiffioClient({ apiKey: "diffio_live_..." });
+const result = await client.audioIsolation.isolate({
+  filePath: "sample.wav",
+  model: "diffio-2",
+  sampling: { steps: 12, guidance: 1.5 }
+});
+
+console.log(result.generation.generationId);
+```
+
+## Restore audio in one call
+
+This helper runs the full flow and returns the downloaded bytes plus a metadata object.
+
+```ts
+import fs from "node:fs";
+import { DiffioClient } from "diffio-js";
+
+const client = new DiffioClient({ apiKey: "diffio_live_..." });
+const [audioBytes, info] = await client.restoreAudio({
+  filePath: "sample.wav",
+  model: "diffio-2",
+  sampling: { steps: 12, guidance: 1.5 },
+  onProgress: (progress) => console.log(progress.status)
+});
+
+if (info.error) {
+  console.log(info.error);
+} else if (audioBytes) {
+  fs.writeFileSync("restored.mp3", Buffer.from(audioBytes));
+}
+
+console.log(info.apiProjectId, info.generationId);
+```
+
+## Generation progress
+
+```ts
+import { DiffioClient } from "diffio-js";
+
+const client = new DiffioClient({ apiKey: "diffio_live_..." });
+const progress = await client.generations.getProgress({
+  generationId: "gen_123",
+  apiProjectId: "proj_123"
+});
+
+console.log(progress.status);
+```
+
+## Generation download
+
+```ts
+import { DiffioClient } from "diffio-js";
+
+const client = new DiffioClient({ apiKey: "diffio_live_..." });
+const download = await client.generations.getDownload({
+  generationId: "gen_123",
+  apiProjectId: "proj_123",
+  downloadType: "audio"
+});
+
+console.log(download.downloadUrl);
+```
+
+## List projects
+
+```ts
+import { DiffioClient } from "diffio-js";
+
+const client = new DiffioClient({ apiKey: "diffio_live_..." });
+const projects = await client.projects.list();
+
+for (const project of projects.projects) {
+  console.log(project.apiProjectId, project.status);
+}
+```
+
+## List project generations
+
+```ts
+import { DiffioClient } from "diffio-js";
+
+const client = new DiffioClient({ apiKey: "diffio_live_..." });
+const generations = await client.projects.listGenerations({ apiProjectId: "proj_123" });
+
+for (const generation of generations.generations) {
+  console.log(generation.generationId, generation.status);
+}
+```
+
+## Webhooks portal access
+
+```ts
+import { DiffioClient } from "diffio-js";
+
+const client = new DiffioClient({ apiKey: "diffio_live_..." });
+const portal = await client.webhooks.getPortalAccess({ mode: "test" });
+console.log(portal.portalUrl);
+```
+
+## Send a test webhook event
+
+```ts
+import { DiffioClient } from "diffio-js";
+
+const client = new DiffioClient({ apiKey: "diffio_live_..." });
+const event = await client.webhooks.sendTestEvent({
+  eventType: "generation.completed",
+  mode: "test",
+  samplePayload: { apiProjectId: "proj_123" }
+});
+
+console.log(event.svixMessageId);
+```
+
+## Runtime compatibility
+
+Use Node 18 or later so `fetch` is available without extra packages.
+Examples use ES modules. Save files with a `.mjs` extension or set `"type": "module"` in your package.json.
+
+## Tests
+
+```bash
+cd diffio-js
+npm run build
+```

jest.config.mjs

@@ -0,0 +1,37 @@
+/** @type {import("jest").Config} */
+export default {
+  preset: "ts-jest",
+  testEnvironment: "node",
+  projects: [
+    {
+      displayName: "unit",
+      preset: "ts-jest",
+      testEnvironment: "node",
+      moduleNameMapper: {
+        "^(\\.{1,2}/.*)\\.js$": "$1"
+      },
+      transform: {
+        "^.+\\.(ts|tsx|js|jsx)$": ["ts-jest", { tsconfig: { allowJs: true } }]
+      },
+      transformIgnorePatterns: ["/node_modules/(?!(msw|@mswjs|until-async)/)"],
+      roots: ["<rootDir>/tests/unit"],
+      setupFilesAfterEnv: ["<rootDir>/tests/setup.ts"]
+    },
+    {
+      displayName: "wire",
+      preset: "ts-jest",
+      testEnvironment: "node",
+      moduleNameMapper: {
+        "^(\\.{1,2}/.*)\\.js$": "$1"
+      },
+      transform: {
+        "^.+\\.(ts|tsx|js|jsx)$": ["ts-jest", { tsconfig: { allowJs: true } }]
+      },
+      transformIgnorePatterns: ["/node_modules/(?!(msw|@mswjs|until-async)/)"],
+      roots: ["<rootDir>/tests/wire"],
+      setupFilesAfterEnv: ["<rootDir>/tests/setup.ts", "<rootDir>/tests/mock-server/setup.ts"]
+    }
+  ],
+  workerThreads: false,
+  passWithNoTests: true
+};