@volley/recognition-client-sdk 0.1.211 → 0.1.254

package/dist/index.d.ts

@@ -1,7 +1,573 @@
-import { A as ASRRequestConfig, G as GameContextV1, R as RecognitionCallbackUrl, T as TranscriptionResultV1, M as MetadataResultV1, E as ErrorResultV1, a as RealTimeTwoWayWebSocketRecognitionClientConfig, I as IRecognitionClient, C as ClientState, b as IRecognitionClientConfig } from './browser-C4ZssGoU.js';
-export { k as ASRRequestV1, f as AudioEncoding, h as ControlSignal, h as ControlSignalTypeV1, D as DeepgramModel, F as FunctionCallResultV1, m as GoogleModel, e as IRecognitionClientStats, L as Language, c as RealTimeTwoWayWebSocketRecognitionClient, g as RecognitionContextTypeV1, l as RecognitionProvider, j as RecognitionResultTypeV1, S as SampleRate, d as TranscriptionResult, i as isNormalDisconnection } from './browser-C4ZssGoU.js';
+import { R as RecognitionProvider, E as ErrorTypeV1, S as Stage, A as ASRRequestConfig, G as GameContextV1, a as RecognitionCallbackUrl, T as TranscriptionResultV1, M as MetadataResultV1, b as ErrorResultV1, c as RealTimeTwoWayWebSocketRecognitionClientConfig, I as IRecognitionClient, C as ClientState, d as IRecognitionClientConfig } from './browser-BZs4BL_w.js';
+export { m as ASRRequestV1, h as AudioEncoding, k as ControlSignal, k as ControlSignalTypeV1, D as DeepgramModel, F as FunctionCallResultV1, n as GoogleModel, g as IRecognitionClientStats, L as Language, e as RealTimeTwoWayWebSocketRecognitionClient, j as RecognitionContextTypeV1, l as RecognitionResultTypeV1, p as STAGES, o as SampleRate, f as TranscriptionResult, i as isNormalDisconnection } from './browser-BZs4BL_w.js';
 import { z } from 'zod';
 
+/**
+ * Error Exception Types
+ *
+ * Defines structured exception types for each ErrorTypeV1 category.
+ * Each exception type has metadata about whether it's immediately available
+ * (can be shown to user right away vs needs investigation/retry).
+ */
+
+/**
+ * Authentication/Authorization Error
+ * isImmediatelyAvailable: false
+ * These are system configuration issues, not user-facing
+ */
+declare const AuthenticationExceptionSchema: z.ZodObject<{
+    message: z.ZodString;
+    code: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+    description: z.ZodOptional<z.ZodString>;
+    provider: z.ZodOptional<z.ZodNativeEnum<typeof RecognitionProvider>>;
+    audioUtteranceId: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodOptional<z.ZodNumber>;
+} & {
+    errorType: z.ZodLiteral<ErrorTypeV1.AUTHENTICATION_ERROR>;
+    isImmediatelyAvailable: z.ZodLiteral<false>;
+    service: z.ZodOptional<z.ZodString>;
+    authMethod: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    message: string;
+    errorType: ErrorTypeV1.AUTHENTICATION_ERROR;
+    isImmediatelyAvailable: false;
+    provider?: RecognitionProvider | undefined;
+    code?: string | number | undefined;
+    audioUtteranceId?: string | undefined;
+    description?: string | undefined;
+    timestamp?: number | undefined;
+    service?: string | undefined;
+    authMethod?: string | undefined;
+}, {
+    message: string;
+    errorType: ErrorTypeV1.AUTHENTICATION_ERROR;
+    isImmediatelyAvailable: false;
+    provider?: RecognitionProvider | undefined;
+    code?: string | number | undefined;
+    audioUtteranceId?: string | undefined;
+    description?: string | undefined;
+    timestamp?: number | undefined;
+    service?: string | undefined;
+    authMethod?: string | undefined;
+}>;
+type AuthenticationException = z.infer<typeof AuthenticationExceptionSchema>;
+/**
+ * Validation Error
+ * isImmediatelyAvailable: true
+ * User provided invalid input - can show them what's wrong
+ */
+declare const ValidationExceptionSchema: z.ZodObject<{
+    message: z.ZodString;
+    code: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+    description: z.ZodOptional<z.ZodString>;
+    provider: z.ZodOptional<z.ZodNativeEnum<typeof RecognitionProvider>>;
+    audioUtteranceId: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodOptional<z.ZodNumber>;
+} & {
+    errorType: z.ZodLiteral<ErrorTypeV1.VALIDATION_ERROR>;
+    isImmediatelyAvailable: z.ZodLiteral<true>;
+    field: z.ZodOptional<z.ZodString>;
+    expected: z.ZodOptional<z.ZodString>;
+    received: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    message: string;
+    errorType: ErrorTypeV1.VALIDATION_ERROR;
+    isImmediatelyAvailable: true;
+    provider?: RecognitionProvider | undefined;
+    code?: string | number | undefined;
+    expected?: string | undefined;
+    received?: string | undefined;
+    audioUtteranceId?: string | undefined;
+    description?: string | undefined;
+    timestamp?: number | undefined;
+    field?: string | undefined;
+}, {
+    message: string;
+    errorType: ErrorTypeV1.VALIDATION_ERROR;
+    isImmediatelyAvailable: true;
+    provider?: RecognitionProvider | undefined;
+    code?: string | number | undefined;
+    expected?: string | undefined;
+    received?: string | undefined;
+    audioUtteranceId?: string | undefined;
+    description?: string | undefined;
+    timestamp?: number | undefined;
+    field?: string | undefined;
+}>;
+type ValidationException = z.infer<typeof ValidationExceptionSchema>;
+/**
+ * Provider Error
+ * isImmediatelyAvailable: false
+ * Error from ASR provider - usually transient or needs investigation
+ */
+declare const ProviderExceptionSchema: z.ZodObject<{
+    message: z.ZodString;
+    code: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+    description: z.ZodOptional<z.ZodString>;
+    audioUtteranceId: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodOptional<z.ZodNumber>;
+} & {
+    errorType: z.ZodLiteral<ErrorTypeV1.PROVIDER_ERROR>;
+    isImmediatelyAvailable: z.ZodLiteral<false>;
+    provider: z.ZodOptional<z.ZodString>;
+    providerErrorCode: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+    isTransient: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    message: string;
+    errorType: ErrorTypeV1.PROVIDER_ERROR;
+    isImmediatelyAvailable: false;
+    provider?: string | undefined;
+    code?: string | number | undefined;
+    audioUtteranceId?: string | undefined;
+    description?: string | undefined;
+    timestamp?: number | undefined;
+    providerErrorCode?: string | number | undefined;
+    isTransient?: boolean | undefined;
+}, {
+    message: string;
+    errorType: ErrorTypeV1.PROVIDER_ERROR;
+    isImmediatelyAvailable: false;
+    provider?: string | undefined;
+    code?: string | number | undefined;
+    audioUtteranceId?: string | undefined;
+    description?: string | undefined;
+    timestamp?: number | undefined;
+    providerErrorCode?: string | number | undefined;
+    isTransient?: boolean | undefined;
+}>;
+type ProviderException = z.infer<typeof ProviderExceptionSchema>;
+/**
+ * Timeout Error
+ * isImmediatelyAvailable: true
+ * Request took too long - user should try again
+ */
+declare const TimeoutExceptionSchema: z.ZodObject<{
+    message: z.ZodString;
+    code: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+    description: z.ZodOptional<z.ZodString>;
+    provider: z.ZodOptional<z.ZodNativeEnum<typeof RecognitionProvider>>;
+    audioUtteranceId: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodOptional<z.ZodNumber>;
+} & {
+    errorType: z.ZodLiteral<ErrorTypeV1.TIMEOUT_ERROR>;
+    isImmediatelyAvailable: z.ZodLiteral<true>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+    operation: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    message: string;
+    errorType: ErrorTypeV1.TIMEOUT_ERROR;
+    isImmediatelyAvailable: true;
+    provider?: RecognitionProvider | undefined;
+    code?: string | number | undefined;
+    audioUtteranceId?: string | undefined;
+    description?: string | undefined;
+    timestamp?: number | undefined;
+    timeoutMs?: number | undefined;
+    operation?: string | undefined;
+}, {
+    message: string;
+    errorType: ErrorTypeV1.TIMEOUT_ERROR;
+    isImmediatelyAvailable: true;
+    provider?: RecognitionProvider | undefined;
+    code?: string | number | undefined;
+    audioUtteranceId?: string | undefined;
+    description?: string | undefined;
+    timestamp?: number | undefined;
+    timeoutMs?: number | undefined;
+    operation?: string | undefined;
+}>;
+type TimeoutException = z.infer<typeof TimeoutExceptionSchema>;
+/**
+ * Quota Exceeded Error
+ * isImmediatelyAvailable: true
+ * Rate limit or quota exceeded - user should wait
+ */
+declare const QuotaExceededExceptionSchema: z.ZodObject<{
+    message: z.ZodString;
+    code: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+    description: z.ZodOptional<z.ZodString>;
+    provider: z.ZodOptional<z.ZodNativeEnum<typeof RecognitionProvider>>;
+    audioUtteranceId: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodOptional<z.ZodNumber>;
+} & {
+    errorType: z.ZodLiteral<ErrorTypeV1.QUOTA_EXCEEDED>;
+    isImmediatelyAvailable: z.ZodLiteral<true>;
+    quotaType: z.ZodOptional<z.ZodString>;
+    resetAt: z.ZodOptional<z.ZodNumber>;
+    retryAfterSeconds: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    message: string;
+    errorType: ErrorTypeV1.QUOTA_EXCEEDED;
+    isImmediatelyAvailable: true;
+    provider?: RecognitionProvider | undefined;
+    code?: string | number | undefined;
+    audioUtteranceId?: string | undefined;
+    description?: string | undefined;
+    timestamp?: number | undefined;
+    quotaType?: string | undefined;
+    resetAt?: number | undefined;
+    retryAfterSeconds?: number | undefined;
+}, {
+    message: string;
+    errorType: ErrorTypeV1.QUOTA_EXCEEDED;
+    isImmediatelyAvailable: true;
+    provider?: RecognitionProvider | undefined;
+    code?: string | number | undefined;
+    audioUtteranceId?: string | undefined;
+    description?: string | undefined;
+    timestamp?: number | undefined;
+    quotaType?: string | undefined;
+    resetAt?: number | undefined;
+    retryAfterSeconds?: number | undefined;
+}>;
+type QuotaExceededException = z.infer<typeof QuotaExceededExceptionSchema>;
+/**
+ * Connection Error
+ * isImmediatelyAvailable: true
+ * Connection establishment or network failure - user should check network or retry
+ */
+declare const ConnectionExceptionSchema: z.ZodObject<{
+    message: z.ZodString;
+    code: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+    description: z.ZodOptional<z.ZodString>;
+    provider: z.ZodOptional<z.ZodNativeEnum<typeof RecognitionProvider>>;
+    audioUtteranceId: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodOptional<z.ZodNumber>;
+} & {
+    errorType: z.ZodLiteral<ErrorTypeV1.CONNECTION_ERROR>;
+    isImmediatelyAvailable: z.ZodLiteral<true>;
+    attempts: z.ZodOptional<z.ZodNumber>;
+    url: z.ZodOptional<z.ZodString>;
+    underlyingError: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    message: string;
+    errorType: ErrorTypeV1.CONNECTION_ERROR;
+    isImmediatelyAvailable: true;
+    provider?: RecognitionProvider | undefined;
+    code?: string | number | undefined;
+    audioUtteranceId?: string | undefined;
+    description?: string | undefined;
+    timestamp?: number | undefined;
+    attempts?: number | undefined;
+    url?: string | undefined;
+    underlyingError?: string | undefined;
+}, {
+    message: string;
+    errorType: ErrorTypeV1.CONNECTION_ERROR;
+    isImmediatelyAvailable: true;
+    provider?: RecognitionProvider | undefined;
+    code?: string | number | undefined;
+    audioUtteranceId?: string | undefined;
+    description?: string | undefined;
+    timestamp?: number | undefined;
+    attempts?: number | undefined;
+    url?: string | undefined;
+    underlyingError?: string | undefined;
+}>;
+type ConnectionException = z.infer<typeof ConnectionExceptionSchema>;
+/**
+ * Unknown Error
+ * isImmediatelyAvailable: false
+ * Unexpected error - needs investigation
+ */
+declare const UnknownExceptionSchema: z.ZodObject<{
+    message: z.ZodString;
+    code: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+    description: z.ZodOptional<z.ZodString>;
+    provider: z.ZodOptional<z.ZodNativeEnum<typeof RecognitionProvider>>;
+    audioUtteranceId: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodOptional<z.ZodNumber>;
+} & {
+    errorType: z.ZodLiteral<ErrorTypeV1.UNKNOWN_ERROR>;
+    isImmediatelyAvailable: z.ZodLiteral<false>;
+    stack: z.ZodOptional<z.ZodString>;
+    context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    message: string;
+    errorType: ErrorTypeV1.UNKNOWN_ERROR;
+    isImmediatelyAvailable: false;
+    provider?: RecognitionProvider | undefined;
+    code?: string | number | undefined;
+    audioUtteranceId?: string | undefined;
+    description?: string | undefined;
+    timestamp?: number | undefined;
+    stack?: string | undefined;
+    context?: Record<string, unknown> | undefined;
+}, {
+    message: string;
+    errorType: ErrorTypeV1.UNKNOWN_ERROR;
+    isImmediatelyAvailable: false;
+    provider?: RecognitionProvider | undefined;
+    code?: string | number | undefined;
+    audioUtteranceId?: string | undefined;
+    description?: string | undefined;
+    timestamp?: number | undefined;
+    stack?: string | undefined;
+    context?: Record<string, unknown> | undefined;
+}>;
+type UnknownException = z.infer<typeof UnknownExceptionSchema>;
+/**
+ * Discriminated union of all exception types
+ * Use this for type-safe error handling
+ */
+declare const RecognitionExceptionSchema: z.ZodDiscriminatedUnion<"errorType", [z.ZodObject<{
+    message: z.ZodString;
+    code: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+    description: z.ZodOptional<z.ZodString>;
+    provider: z.ZodOptional<z.ZodNativeEnum<typeof RecognitionProvider>>;
+    audioUtteranceId: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodOptional<z.ZodNumber>;
+} & {
+    errorType: z.ZodLiteral<ErrorTypeV1.AUTHENTICATION_ERROR>;
+    isImmediatelyAvailable: z.ZodLiteral<false>;
+    service: z.ZodOptional<z.ZodString>;
+    authMethod: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    message: string;
+    errorType: ErrorTypeV1.AUTHENTICATION_ERROR;
+    isImmediatelyAvailable: false;
+    provider?: RecognitionProvider | undefined;
+    code?: string | number | undefined;
+    audioUtteranceId?: string | undefined;
+    description?: string | undefined;
+    timestamp?: number | undefined;
+    service?: string | undefined;
+    authMethod?: string | undefined;
+}, {
+    message: string;
+    errorType: ErrorTypeV1.AUTHENTICATION_ERROR;
+    isImmediatelyAvailable: false;
+    provider?: RecognitionProvider | undefined;
+    code?: string | number | undefined;
+    audioUtteranceId?: string | undefined;
+    description?: string | undefined;
+    timestamp?: number | undefined;
+    service?: string | undefined;
+    authMethod?: string | undefined;
+}>, z.ZodObject<{
+    message: z.ZodString;
+    code: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+    description: z.ZodOptional<z.ZodString>;
+    provider: z.ZodOptional<z.ZodNativeEnum<typeof RecognitionProvider>>;
+    audioUtteranceId: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodOptional<z.ZodNumber>;
+} & {
+    errorType: z.ZodLiteral<ErrorTypeV1.VALIDATION_ERROR>;
+    isImmediatelyAvailable: z.ZodLiteral<true>;
+    field: z.ZodOptional<z.ZodString>;
+    expected: z.ZodOptional<z.ZodString>;
+    received: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    message: string;
+    errorType: ErrorTypeV1.VALIDATION_ERROR;
+    isImmediatelyAvailable: true;
+    provider?: RecognitionProvider | undefined;
+    code?: string | number | undefined;
+    expected?: string | undefined;
+    received?: string | undefined;
+    audioUtteranceId?: string | undefined;
+    description?: string | undefined;
+    timestamp?: number | undefined;
+    field?: string | undefined;
+}, {
+    message: string;
+    errorType: ErrorTypeV1.VALIDATION_ERROR;
+    isImmediatelyAvailable: true;
+    provider?: RecognitionProvider | undefined;
+    code?: string | number | undefined;
+    expected?: string | undefined;
+    received?: string | undefined;
+    audioUtteranceId?: string | undefined;
+    description?: string | undefined;
+    timestamp?: number | undefined;
+    field?: string | undefined;
+}>, z.ZodObject<{
+    message: z.ZodString;
+    code: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+    description: z.ZodOptional<z.ZodString>;
+    audioUtteranceId: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodOptional<z.ZodNumber>;
+} & {
+    errorType: z.ZodLiteral<ErrorTypeV1.PROVIDER_ERROR>;
+    isImmediatelyAvailable: z.ZodLiteral<false>;
+    provider: z.ZodOptional<z.ZodString>;
+    providerErrorCode: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+    isTransient: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    message: string;
+    errorType: ErrorTypeV1.PROVIDER_ERROR;
+    isImmediatelyAvailable: false;
+    provider?: string | undefined;
+    code?: string | number | undefined;
+    audioUtteranceId?: string | undefined;
+    description?: string | undefined;
+    timestamp?: number | undefined;
+    providerErrorCode?: string | number | undefined;
+    isTransient?: boolean | undefined;
+}, {
+    message: string;
+    errorType: ErrorTypeV1.PROVIDER_ERROR;
+    isImmediatelyAvailable: false;
+    provider?: string | undefined;
+    code?: string | number | undefined;
+    audioUtteranceId?: string | undefined;
+    description?: string | undefined;
+    timestamp?: number | undefined;
+    providerErrorCode?: string | number | undefined;
+    isTransient?: boolean | undefined;
+}>, z.ZodObject<{
+    message: z.ZodString;
+    code: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+    description: z.ZodOptional<z.ZodString>;
+    provider: z.ZodOptional<z.ZodNativeEnum<typeof RecognitionProvider>>;
+    audioUtteranceId: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodOptional<z.ZodNumber>;
+} & {
+    errorType: z.ZodLiteral<ErrorTypeV1.TIMEOUT_ERROR>;
+    isImmediatelyAvailable: z.ZodLiteral<true>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+    operation: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    message: string;
+    errorType: ErrorTypeV1.TIMEOUT_ERROR;
+    isImmediatelyAvailable: true;
+    provider?: RecognitionProvider | undefined;
+    code?: string | number | undefined;
+    audioUtteranceId?: string | undefined;
+    description?: string | undefined;
+    timestamp?: number | undefined;
+    timeoutMs?: number | undefined;
+    operation?: string | undefined;
+}, {
+    message: string;
+    errorType: ErrorTypeV1.TIMEOUT_ERROR;
+    isImmediatelyAvailable: true;
+    provider?: RecognitionProvider | undefined;
+    code?: string | number | undefined;
+    audioUtteranceId?: string | undefined;
+    description?: string | undefined;
+    timestamp?: number | undefined;
+    timeoutMs?: number | undefined;
+    operation?: string | undefined;
+}>, z.ZodObject<{
+    message: z.ZodString;
+    code: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+    description: z.ZodOptional<z.ZodString>;
+    provider: z.ZodOptional<z.ZodNativeEnum<typeof RecognitionProvider>>;
+    audioUtteranceId: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodOptional<z.ZodNumber>;
+} & {
+    errorType: z.ZodLiteral<ErrorTypeV1.QUOTA_EXCEEDED>;
+    isImmediatelyAvailable: z.ZodLiteral<true>;
+    quotaType: z.ZodOptional<z.ZodString>;
+    resetAt: z.ZodOptional<z.ZodNumber>;
+    retryAfterSeconds: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    message: string;
+    errorType: ErrorTypeV1.QUOTA_EXCEEDED;
+    isImmediatelyAvailable: true;
+    provider?: RecognitionProvider | undefined;
+    code?: string | number | undefined;
+    audioUtteranceId?: string | undefined;
+    description?: string | undefined;
+    timestamp?: number | undefined;
+    quotaType?: string | undefined;
+    resetAt?: number | undefined;
+    retryAfterSeconds?: number | undefined;
+}, {
+    message: string;
+    errorType: ErrorTypeV1.QUOTA_EXCEEDED;
+    isImmediatelyAvailable: true;
+    provider?: RecognitionProvider | undefined;
+    code?: string | number | undefined;
+    audioUtteranceId?: string | undefined;
+    description?: string | undefined;
+    timestamp?: number | undefined;
+    quotaType?: string | undefined;
+    resetAt?: number | undefined;
+    retryAfterSeconds?: number | undefined;
+}>, z.ZodObject<{
+    message: z.ZodString;
+    code: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+    description: z.ZodOptional<z.ZodString>;
+    provider: z.ZodOptional<z.ZodNativeEnum<typeof RecognitionProvider>>;
+    audioUtteranceId: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodOptional<z.ZodNumber>;
+} & {
+    errorType: z.ZodLiteral<ErrorTypeV1.CONNECTION_ERROR>;
+    isImmediatelyAvailable: z.ZodLiteral<true>;
+    attempts: z.ZodOptional<z.ZodNumber>;
+    url: z.ZodOptional<z.ZodString>;
+    underlyingError: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    message: string;
+    errorType: ErrorTypeV1.CONNECTION_ERROR;
+    isImmediatelyAvailable: true;
+    provider?: RecognitionProvider | undefined;
+    code?: string | number | undefined;
+    audioUtteranceId?: string | undefined;
+    description?: string | undefined;
+    timestamp?: number | undefined;
+    attempts?: number | undefined;
+    url?: string | undefined;
+    underlyingError?: string | undefined;
+}, {
+    message: string;
+    errorType: ErrorTypeV1.CONNECTION_ERROR;
+    isImmediatelyAvailable: true;
+    provider?: RecognitionProvider | undefined;
+    code?: string | number | undefined;
+    audioUtteranceId?: string | undefined;
+    description?: string | undefined;
+    timestamp?: number | undefined;
+    attempts?: number | undefined;
+    url?: string | undefined;
+    underlyingError?: string | undefined;
+}>, z.ZodObject<{
+    message: z.ZodString;
+    code: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+    description: z.ZodOptional<z.ZodString>;
+    provider: z.ZodOptional<z.ZodNativeEnum<typeof RecognitionProvider>>;
+    audioUtteranceId: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodOptional<z.ZodNumber>;
+} & {
+    errorType: z.ZodLiteral<ErrorTypeV1.UNKNOWN_ERROR>;
+    isImmediatelyAvailable: z.ZodLiteral<false>;
+    stack: z.ZodOptional<z.ZodString>;
+    context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    message: string;
+    errorType: ErrorTypeV1.UNKNOWN_ERROR;
+    isImmediatelyAvailable: false;
+    provider?: RecognitionProvider | undefined;
+    code?: string | number | undefined;
+    audioUtteranceId?: string | undefined;
+    description?: string | undefined;
+    timestamp?: number | undefined;
+    stack?: string | undefined;
+    context?: Record<string, unknown> | undefined;
+}, {
+    message: string;
+    errorType: ErrorTypeV1.UNKNOWN_ERROR;
+    isImmediatelyAvailable: false;
+    provider?: RecognitionProvider | undefined;
+    code?: string | number | undefined;
+    audioUtteranceId?: string | undefined;
+    description?: string | undefined;
+    timestamp?: number | undefined;
+    stack?: string | undefined;
+    context?: Record<string, unknown> | undefined;
+}>]>;
+type RecognitionException = z.infer<typeof RecognitionExceptionSchema>;
+/**
+ * Check if an exception should be shown to the user immediately
+ */
+declare function isExceptionImmediatelyAvailable(exception: RecognitionException): boolean;
+/**
+ * Get user-friendly error message for exceptions
+ */
+declare function getUserFriendlyMessage(exception: RecognitionException): string;
+
 /**
  * Gemini Model Types
  * Based on available models as of January 2025
@@ -32,17 +598,6 @@ declare enum OpenAIModel {
     WHISPER_1 = "whisper-1"
 }
 
-/**
- * Standard stage/environment constants used across all services
- */
-declare const STAGES: {
-    readonly LOCAL: "local";
-    readonly DEV: "dev";
-    readonly STAGING: "staging";
-    readonly PRODUCTION: "production";
-};
-type Stage = typeof STAGES[keyof typeof STAGES];
-
 /**
  * Configuration Builder for Recognition Client
  *
@@ -56,8 +611,10 @@ type Stage = typeof STAGES[keyof typeof STAGES];
  *
  * Example:
  * ```typescript
+ * import { STAGES } from '@recog/shared-types';
+ *
  * const config = new ConfigBuilder()
- *   .url('ws://localhost:3101/ws/v1/recognize')
+ *   .stage(STAGES.STAGING)  // Recommended: automatic environment selection
  *   .asrRequestConfig({
  *     provider: RecognitionProvider.DEEPGRAM,
  *     model: 'nova-2-general'
@@ -69,9 +626,20 @@ type Stage = typeof STAGES[keyof typeof STAGES];
 declare class ConfigBuilder {
     private config;
     /**
-     * Set the WebSocket URL
+     * Set the WebSocket URL (advanced usage)
+     * For standard environments, use stage() instead
      */
     url(url: string): this;
+    /**
+     * Set the stage for automatic environment selection (recommended)
+     * @param stage - STAGES.LOCAL | STAGES.DEV | STAGES.STAGING | STAGES.PRODUCTION
+     * @example
+     * ```typescript
+     * import { STAGES } from '@recog/shared-types';
+     * builder.stage(STAGES.STAGING)
+     * ```
+     */
+    stage(stage: Stage | string): this;
     /**
      * Set ASR request configuration
      */
@@ -193,6 +761,47 @@ declare function createClient(config: RealTimeTwoWayWebSocketRecognitionClientCo
  */
 declare function createClientWithBuilder(configure: (builder: ConfigBuilder) => ConfigBuilder): IRecognitionClient;
 
+/**
+ * SDK Error Classes
+ *
+ * Typed error classes that extend native Error with recognition-specific metadata
+ */
+
+/**
+ * Base class for all recognition SDK errors
+ */
+declare class RecognitionError extends Error {
+    readonly errorType: ErrorTypeV1;
+    readonly timestamp: number;
+    constructor(errorType: ErrorTypeV1, message: string);
+}
+/**
+ * Connection error - thrown when WebSocket connection fails after all retry attempts
+ */
+declare class ConnectionError extends RecognitionError {
+    readonly attempts: number;
+    readonly url: string;
+    readonly underlyingError?: Error;
+    constructor(message: string, attempts: number, url: string, underlyingError?: Error);
+}
+/**
+ * Timeout error - thrown when operations exceed timeout limits
+ */
+declare class TimeoutError extends RecognitionError {
+    readonly timeoutMs: number;
+    readonly operation: string;
+    constructor(message: string, timeoutMs: number, operation: string);
+}
+/**
+ * Validation error - thrown when invalid configuration or input is provided
+ */
+declare class ValidationError extends RecognitionError {
+    readonly field?: string;
+    readonly expected?: string;
+    readonly received?: string;
+    constructor(message: string, field?: string, expected?: string, received?: string);
+}
+
 /**
  * VGF-style state schema for game-side recognition state/results management.
  *
@@ -349,6 +958,10 @@ interface ISimplifiedVGFRecognitionClient {
      * Get the audio utterance ID for this session
      */
     getAudioUtteranceId(): string;
+    /**
+     * Get the WebSocket URL being used
+     */
+    getUrl(): string;
     /**
      * Get the underlying client state (for advanced usage)
      */
@@ -368,6 +981,7 @@ declare class SimplifiedVGFRecognitionClient implements ISimplifiedVGFRecognitio
     sendAudio(audioData: ArrayBuffer | ArrayBufferView | Blob): void;
     stopRecording(): Promise<void>;
     getAudioUtteranceId(): string;
+    getUrl(): string;
     getState(): ClientState;
     isConnected(): boolean;
     isConnecting(): boolean;
@@ -462,4 +1076,4 @@ declare function getRecognitionConductorHttpBase(stage?: Stage | string | null |
 declare function getRecognitionConductorWsBase(stage?: Stage | string | null | undefined): string;
 declare function getRecognitionConductorHost(stage?: Stage | string | null | undefined): string;
 
-export { ASRRequestConfig, ClientState, ConfigBuilder, ErrorResultV1, GameContextV1, GeminiModel, IRecognitionClient, IRecognitionClientConfig, type ISimplifiedVGFRecognitionClient, MetadataResultV1, OpenAIModel, RECOGNITION_CONDUCTOR_BASES, RECOGNITION_SERVICE_BASES, RealTimeTwoWayWebSocketRecognitionClientConfig, RecognitionCallbackUrl, type RecognitionState, RecognitionVGFStateSchema, RecordingStatus, type RecordingStatusType, type SimplifiedVGFClientConfig, SimplifiedVGFRecognitionClient, TranscriptionResultV1, TranscriptionStatus, type TranscriptionStatusType, createClient, createClientWithBuilder, createInitialRecognitionState, createSimplifiedVGFClient, getRecognitionConductorBase, getRecognitionConductorHost, getRecognitionConductorHttpBase, getRecognitionConductorWsBase, getRecognitionServiceBase, getRecognitionServiceHost, getRecognitionServiceHttpBase, getRecognitionServiceWsBase, isValidRecordingStatusTransition, normalizeStage };
+export { ASRRequestConfig, type AuthenticationException, ClientState, ConfigBuilder, ConnectionError, type ConnectionException, ErrorResultV1, ErrorTypeV1, GameContextV1, GeminiModel, IRecognitionClient, IRecognitionClientConfig, type ISimplifiedVGFRecognitionClient, MetadataResultV1, OpenAIModel, type ProviderException, type QuotaExceededException, RECOGNITION_CONDUCTOR_BASES, RECOGNITION_SERVICE_BASES, RealTimeTwoWayWebSocketRecognitionClientConfig, RecognitionCallbackUrl, RecognitionError, type RecognitionException, RecognitionProvider, type RecognitionState, RecognitionVGFStateSchema, RecordingStatus, type RecordingStatusType, type SimplifiedVGFClientConfig, SimplifiedVGFRecognitionClient, Stage, TimeoutError, type TimeoutException, TranscriptionResultV1, TranscriptionStatus, type TranscriptionStatusType, type UnknownException, ValidationError, type ValidationException, createClient, createClientWithBuilder, createInitialRecognitionState, createSimplifiedVGFClient, getRecognitionConductorBase, getRecognitionConductorHost, getRecognitionConductorHttpBase, getRecognitionConductorWsBase, getRecognitionServiceBase, getRecognitionServiceHost, getRecognitionServiceHttpBase, getRecognitionServiceWsBase, getUserFriendlyMessage, isExceptionImmediatelyAvailable, isValidRecordingStatusTransition, normalizeStage };