@autoark-ai/eva-client-sdk-ts 0.0.2-dev

package/dist/spi.d.ts

@@ -0,0 +1,130 @@
+// Generated by dts-bundle-generator v9.5.1
+
+/** Encoded audio sample format. The built-in browser implementation currently uses `pcm_s16le`. */
+export type AudioFormat = "pcm_s16le" | (string & {});
+/** One interleaved audio chunk exchanged through the media SPI. */
+export interface AudioChunk {
+	/** Encoded audio bytes. */
+	data: Uint8Array;
+	/** Sample rate in Hz. */
+	sampleRate: number;
+	/** Number of interleaved channels. */
+	channels: number;
+	/** Encoding used by `data`. */
+	format: AudioFormat;
+}
+/**
+ * Pull-based audio input owned by the dialogue runtime after agent construction.
+ * Consumers implementing this SPI must support sequential start/stop sessions and
+ * must not drive the lifecycle concurrently with the agent.
+ */
+export interface AudioInputSource {
+	/** Acquires the input resource and resolves only after it is ready to produce frames. */
+	start(): Promise<void>;
+	/**
+	 * Produces frames for the current started session.
+	 * Only one active consumer is allowed; abort must stop production promptly.
+	 */
+	frames(signal?: AbortSignal): AsyncIterable<AudioChunk>;
+	/** Idempotently releases the current input resource and waits for teardown to finish. */
+	stop(): Promise<void>;
+}
+/**
+ * Push-based audio output owned by the dialogue runtime after agent construction.
+ * The implementation may initialize lazily on the first `enqueue()` call.
+ */
+export interface AudioOutputSink {
+	/** Queues one audio chunk for playback. */
+	enqueue(chunk: AudioChunk): Promise<void> | void;
+	/** Immediately discards queued/current playback while keeping the sink reusable. */
+	flush(): Promise<void> | void;
+	/** Resolves after all audio accepted before the call has finished playing. */
+	drain(): Promise<void> | void;
+	/** Idempotently releases output resources and prevents further playback. */
+	stop(): Promise<void> | void;
+}
+/** One validated still image captured through the environment-neutral camera SPI. */
+export interface CameraSnapshot {
+	/** Encoded image bytes. The runtime never persists these bytes in events or conversation history. */
+	readonly data: Uint8Array;
+	/** Actual encoded MIME type, such as `image/png` or `image/jpeg`. */
+	readonly mimeType: string;
+	/** Actual captured frame width in pixels. */
+	readonly width: number;
+	/** Actual captured frame height in pixels. */
+	readonly height: number;
+}
+/**
+ * Pull-based still-camera source owned exclusively by the dialogue runtime.
+ *
+ * @remarks
+ * `start()` resolves only when one continuously held camera session is ready for capture.
+ * `capture()` returns one snapshot from that session. Both operations require an
+ * `AbortSignal`; an implementation must reject promptly on cancellation while retaining
+ * ownership of any pending acquisition/encode continuation. A stream acquired late must be
+ * released immediately, and a snapshot encoded late must be discarded. At most one started
+ * session and one in-flight capture are allowed. `stop()` must cancel or settle pending work,
+ * release both pending and already-acquired resources, and be idempotent. After a successful
+ * stop, a later sequential start is allowed.
+ *
+ * The runtime allows a cancelled `start()` or `capture()` a fixed 1500ms settlement deadline.
+ * If it still cannot settle, or `stop()` cannot confirm release, the runtime marks this camera
+ * role faulted; subsequent camera capture/control calls reject deterministically, while other
+ * agent capabilities remain usable. Callers must not drive this lifecycle concurrently with
+ * the agent.
+ */
+export interface CameraSnapshotSource {
+	/**
+	 * Acquires one camera session and resolves only after permission, acquisition, and frame readiness.
+	 * @param signal - Required cancellation signal owned by the runtime for this start attempt.
+	 */
+	start(signal: AbortSignal): Promise<void>;
+	/**
+	 * Captures one still image from the ready session and rejects promptly when cancelled.
+	 * @param signal - Required cancellation signal scoped to this single capture attempt.
+	 * @returns A validated, environment-neutral encoded snapshot descriptor.
+	 */
+	capture(signal: AbortSignal): Promise<CameraSnapshot>;
+	/** Idempotently waits for pending acquisition/capture and confirms all owned resources are released. */
+	stop(): Promise<void>;
+}
+/** Stable identity and optional capability metadata for an AEC implementation. */
+export interface AecDescriptor {
+	id: string;
+	supportedPlatforms?: readonly string[];
+	metadata?: Record<string, unknown>;
+}
+/** Reserved AEC configuration surface; no public options are defined in the alpha. */
+export type AecProcessorConfiguration = Record<string, never>;
+/** Acoustic echo cancellation role in the media transport pipeline. */
+export interface AecProcessor {
+	readonly descriptor: AecDescriptor;
+	configure?(config: AecProcessorConfiguration): Promise<void> | void;
+	pushFarEnd(chunk: AudioChunk): Promise<void> | void;
+	processNearEnd(chunk: AudioChunk): Promise<AudioChunk> | AudioChunk;
+	reset(reason?: string): Promise<void> | void;
+	release(): Promise<void> | void;
+}
+/**
+ * Complete media transport set accepted by the agent.
+ * The three audio roles are required and the camera role is optional. After construction,
+ * the dialogue runtime exclusively
+ * drives their lifecycle; callers should not invoke lifecycle methods concurrently.
+ */
+export interface MediaTransportsConfig {
+	/** Audio capture implementation. */
+	input: AudioInputSource;
+	/** Audio playback implementation. */
+	output: AudioOutputSink;
+	/** Echo cancellation implementation, including the SDK passthrough default. */
+	aec: AecProcessor;
+	/**
+	 * Optional still-camera implementation used for one snapshot at each eligible `speech.started`.
+	 * @remarks Merely configuring this field does not acquire a device: camera capture remains
+	 * disabled until `setCameraCaptureEnabled(true)` succeeds. Manual text and greeting turns do
+	 * not capture images.
+	 */
+	camera?: CameraSnapshotSource;
+}
+
+export {};

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@autoark-ai/eva-client-sdk-ts",
+  "version": "0.0.2-dev",
+  "description": "Eva 端侧 TypeScript SDK（契约驱动、浏览器优先）。",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./spi": {
+      "types": "./dist/spi.d.ts",
+      "import": "./dist/spi.js",
+      "default": "./dist/spi.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "import": "./dist/browser.js",
+      "default": "./dist/browser.js"
+    }
+  },
+  "files": [
+    "LICENSE",
+    "GATEWAY_TERMS.md",
+    "THIRD_PARTY_NOTICES.md",
+    "dist/index.js",
+    "dist/index.d.ts",
+    "dist/spi.js",
+    "dist/spi.d.ts",
+    "dist/browser.js",
+    "dist/browser.d.ts",
+    "dist/assets/silero_vad_v6.onnx"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "check": "npm run build && npm run typecheck && npm run typecheck:test && npm run depcruise && npm test && npm run test:browser && npm run verify:pack",
+    "depcruise": "depcruise src --config .dependency-cruiser.cjs",
+    "quickstart:prepare": "npm run version:sync && npm run build && node scripts/prepare-browser-quickstart.mjs",
+    "test": "vitest run",
+    "test:browser": "vitest run --config vitest.browser.config.ts",
+    "verify:consumer": "node scripts/verify-clean-consumer.mjs",
+    "verify:consumer:browser": "node scripts/verify-clean-browser.mjs",
+    "verify:consumer:gateway": "tsx test/e2e/direct-gateway/cli.ts",
+    "verify:pack": "node scripts/verify-pack.mjs",
+    "verify:release-candidate": "node scripts/verify-release-candidate.mjs",
+    "version:sync": "node scripts/sync-package-version.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "typecheck:test": "tsc -p tsconfig.test.json"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.1",
+    "@vitest/browser": "^4.1.10",
+    "@vitest/browser-playwright": "^4.1.10",
+    "dependency-cruiser": "^16.0.0",
+    "dts-bundle-generator": "^9.5.1",
+    "esbuild": "^0.28.1",
+    "playwright": "^1.48.0",
+    "tsx": "^4.23.0",
+    "typescript": "^5.6.0",
+    "vite": "^8.1.4",
+    "vitest": "^4.1.10"
+  },
+  "dependencies": {
+    "@alexanderolsen/libsamplerate-js": "2.1.2",
+    "onnxruntime-web": "1.26.0"
+  }
+}