@clarionhq/core 0.0.1 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clarion
+
+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/lib/emitter.d.ts

@@ -0,0 +1,9 @@
+import type { ClarionEvent, Listener, Unsubscribe } from './events';
+export declare class ClarionEmitter {
+    private listeners;
+    on(listener: Listener<ClarionEvent>): Unsubscribe;
+    emit(event: ClarionEvent): void;
+    removeAll(): void;
+    get listenerCount(): number;
+}
+//# sourceMappingURL=emitter.d.ts.map

package/lib/emitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emitter.d.ts","sourceRoot":"","sources":["../src/emitter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAEpE,qBAAa,cAAc;IACzB,OAAO,CAAC,SAAS,CAAqC;IAEtD,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,YAAY,CAAC,GAAG,WAAW;IAOjD,IAAI,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;IAU/B,SAAS,IAAI,IAAI;IAIjB,IAAI,aAAa,IAAI,MAAM,CAE1B;CACF"}

package/lib/emitter.js

@@ -0,0 +1,26 @@
+export class ClarionEmitter {
+    listeners = new Set();
+    on(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    emit(event) {
+        for (const listener of this.listeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // Listener errors must not break the emit loop or other listeners.
+            }
+        }
+    }
+    removeAll() {
+        this.listeners.clear();
+    }
+    get listenerCount() {
+        return this.listeners.size;
+    }
+}
+//# sourceMappingURL=emitter.js.map

package/lib/emitter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emitter.js","sourceRoot":"","sources":["../src/emitter.ts"],"names":[],"mappings":"AAEA,MAAM,OAAO,cAAc;IACjB,SAAS,GAAG,IAAI,GAAG,EAA0B,CAAC;IAEtD,EAAE,CAAC,QAAgC;QACjC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC7B,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAClC,CAAC,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,KAAmB;QACtB,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACtC,IAAI,CAAC;gBACH,QAAQ,CAAC,KAAK,CAAC,CAAC;YAClB,CAAC;YAAC,MAAM,CAAC;gBACP,mEAAmE;YACrE,CAAC;QACH,CAAC;IACH,CAAC;IAED,SAAS;QACP,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;IACzB,CAAC;IAED,IAAI,aAAa;QACf,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;IAC7B,CAAC;CACF"}

package/lib/engine.d.ts

@@ -0,0 +1,39 @@
+import type { ClarionEvent, Listener, Unsubscribe } from './events';
+import type { EngineKind, EngineState } from './state';
+export interface ClarionEngine {
+    readonly kind: EngineKind;
+    readonly state: EngineState;
+    prepare(): Promise<void>;
+    start(): Promise<void>;
+    pause(): Promise<void>;
+    resume(): Promise<void>;
+    stop(): Promise<void>;
+    discard(): Promise<void>;
+    release(): Promise<void>;
+    on(listener: Listener<ClarionEvent>): Unsubscribe;
+}
+export interface RecorderEngineConfig {
+    outputDirectory?: string;
+    filenamePrefix?: string;
+    rotateAfterMs?: number;
+    emitAudioLevel?: boolean;
+    audioLevelIntervalMs?: number;
+}
+export interface RecognizerEngineConfig {
+    language: string;
+    emitPartials?: boolean;
+    maxAlternatives?: number;
+}
+export interface AzureEngineConfig extends RecognizerEngineConfig {
+    subscriptionKey?: string;
+    region?: string;
+    authToken?: string;
+    endpoint?: string;
+}
+export interface HybridEngineConfig {
+    online: AzureEngineConfig;
+    offline: RecorderEngineConfig;
+    preferAzureWhen: 'always-if-online' | 'on-good-network';
+    retainOfflineCopy?: boolean;
+}
+//# sourceMappingURL=engine.d.ts.map

package/lib/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACpE,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEvD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAE5B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzB,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,YAAY,CAAC,GAAG,WAAW,CAAC;CACnD;AAED,MAAM,WAAW,oBAAoB;IACnC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAkB,SAAQ,sBAAsB;IAC/D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,OAAO,EAAE,oBAAoB,CAAC;IAC9B,eAAe,EAAE,kBAAkB,GAAG,iBAAiB,CAAC;IACxD,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B"}

package/lib/engine.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=engine.js.map

package/lib/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":""}

package/lib/errors.d.ts

@@ -0,0 +1,15 @@
+export type ErrorCode = 'PERMISSION_DENIED' | 'AUDIO_BUSY' | 'NETWORK_UNAVAILABLE' | 'NETWORK_TIMEOUT' | 'AUTH_FAILED' | 'QUOTA_EXCEEDED' | 'UNSUPPORTED_LANGUAGE' | 'UNSUPPORTED_FORMAT' | 'NO_SPEECH' | 'INTERRUPTED' | 'CANCELLED' | 'ENGINE_NOT_READY' | 'INVALID_STATE' | 'IO_ERROR' | 'INTERNAL_ERROR' | 'UNKNOWN';
+export interface ClarionErrorOptions {
+    code: ErrorCode;
+    message: string;
+    cause?: unknown;
+    recoverable?: boolean;
+}
+export declare class ClarionError extends Error {
+    readonly code: ErrorCode;
+    readonly recoverable: boolean;
+    readonly cause?: unknown;
+    constructor(opts: ClarionErrorOptions);
+}
+export declare const isClarionError: (e: unknown) => e is ClarionError;
+//# sourceMappingURL=errors.d.ts.map

package/lib/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GACjB,mBAAmB,GACnB,YAAY,GACZ,qBAAqB,GACrB,iBAAiB,GACjB,aAAa,GACb,gBAAgB,GAChB,sBAAsB,GACtB,oBAAoB,GACpB,WAAW,GACX,aAAa,GACb,WAAW,GACX,kBAAkB,GAClB,eAAe,GACf,UAAU,GACV,gBAAgB,GAChB,SAAS,CAAC;AAEd,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,SAAkB,KAAK,CAAC,EAAE,OAAO,CAAC;gBAEtB,IAAI,EAAE,mBAAmB;CAOtC;AAED,eAAO,MAAM,cAAc,GAAI,GAAG,OAAO,KAAG,CAAC,IAAI,YACtB,CAAC"}

package/lib/errors.js

@@ -0,0 +1,15 @@
+export class ClarionError extends Error {
+    code;
+    recoverable;
+    cause;
+    constructor(opts) {
+        super(opts.message);
+        this.name = 'ClarionError';
+        this.code = opts.code;
+        this.recoverable = opts.recoverable ?? false;
+        if (opts.cause !== undefined)
+            this.cause = opts.cause;
+    }
+}
+export const isClarionError = (e) => e instanceof ClarionError;
+//# sourceMappingURL=errors.js.map

package/lib/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAyBA,MAAM,OAAO,YAAa,SAAQ,KAAK;IAC5B,IAAI,CAAY;IAChB,WAAW,CAAU;IACZ,KAAK,CAAW;IAElC,YAAY,IAAyB;QACnC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACpB,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,KAAK,CAAC;QAC7C,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS;YAAE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;IACxD,CAAC;CACF;AAED,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAU,EAAqB,EAAE,CAC9D,CAAC,YAAY,YAAY,CAAC"}

package/lib/events.d.ts

@@ -0,0 +1,33 @@
+import type { ClarionError } from './errors';
+import type { RecorderResult, TranscriptResult } from './results';
+import type { EngineState } from './state';
+export type ClarionEvent = {
+    type: 'state';
+    state: EngineState;
+} | {
+    type: 'audio-level';
+    rms: number;
+    peak: number;
+} | {
+    type: 'partial';
+    result: TranscriptResult;
+} | {
+    type: 'final';
+    result: TranscriptResult;
+} | {
+    type: 'chunk';
+    uri: string;
+    startMs: number;
+    endMs: number;
+    sizeBytes: number;
+} | {
+    type: 'recording-complete';
+    result: RecorderResult;
+} | {
+    type: 'error';
+    error: ClarionError;
+};
+export type ClarionEventType = ClarionEvent['type'];
+export type Listener<T> = (event: T) => void;
+export type Unsubscribe = () => void;
+//# sourceMappingURL=events.d.ts.map

package/lib/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAClE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,WAAW,CAAA;CAAE,GACrC;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAClD;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,gBAAgB,CAAA;CAAE,GAC7C;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,gBAAgB,CAAA;CAAE,GAC3C;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACjF;IAAE,IAAI,EAAE,oBAAoB,CAAC;IAAC,MAAM,EAAE,cAAc,CAAA;CAAE,GACtD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,YAAY,CAAA;CAAE,CAAC;AAE3C,MAAM,MAAM,gBAAgB,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;AAEpD,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;AAC7C,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC"}

package/lib/events.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=events.js.map

package/lib/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":""}

package/lib/format.d.ts

@@ -0,0 +1,10 @@
+export type SampleRate = 8000 | 16000 | 22050 | 44100 | 48000;
+export type ChannelCount = 1 | 2;
+export type BitDepth = 16 | 24 | 32;
+export interface AudioFormat {
+    sampleRate: SampleRate;
+    channels: ChannelCount;
+    bitDepth: BitDepth;
+}
+export declare const DEFAULT_AUDIO_FORMAT: AudioFormat;
+//# sourceMappingURL=format.d.ts.map

package/lib/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC;AAC9D,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,CAAC,CAAC;AACjC,MAAM,MAAM,QAAQ,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;AAEpC,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,UAAU,CAAC;IACvB,QAAQ,EAAE,YAAY,CAAC;IACvB,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED,eAAO,MAAM,oBAAoB,EAAE,WAIlC,CAAC"}

package/lib/format.js

@@ -0,0 +1,6 @@
+export const DEFAULT_AUDIO_FORMAT = {
+    sampleRate: 16000,
+    channels: 1,
+    bitDepth: 16,
+};
+//# sourceMappingURL=format.js.map

package/lib/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAUA,MAAM,CAAC,MAAM,oBAAoB,GAAgB;IAC/C,UAAU,EAAE,KAAK;IACjB,QAAQ,EAAE,CAAC;IACX,QAAQ,EAAE,EAAE;CACb,CAAC"}

package/lib/index.d.ts

@@ -0,0 +1,11 @@
+export * from './state';
+export * from './format';
+export * from './results';
+export * from './errors';
+export * from './events';
+export * from './permissions';
+export * from './engine';
+export * from './emitter';
+export * from './transitions';
+export declare const CLARION_CORE_VERSION = "0.0.1";
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAE9B,eAAO,MAAM,oBAAoB,UAAU,CAAC"}

package/lib/index.js

@@ -0,0 +1,11 @@
+export * from './state';
+export * from './format';
+export * from './results';
+export * from './errors';
+export * from './events';
+export * from './permissions';
+export * from './engine';
+export * from './emitter';
+export * from './transitions';
+export const CLARION_CORE_VERSION = '0.0.1';
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAE9B,MAAM,CAAC,MAAM,oBAAoB,GAAG,OAAO,CAAC"}

package/lib/permissions.d.ts

@@ -0,0 +1,6 @@
+export type PermissionStatus = 'granted' | 'denied' | 'undetermined' | 'restricted' | 'blocked';
+export interface PermissionsApi {
+    check(): Promise<PermissionStatus>;
+    request(): Promise<PermissionStatus>;
+}
+//# sourceMappingURL=permissions.d.ts.map

package/lib/permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../src/permissions.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GACxB,SAAS,GACT,QAAQ,GACR,cAAc,GACd,YAAY,GACZ,SAAS,CAAC;AAEd,MAAM,WAAW,cAAc;IAC7B,KAAK,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACnC,OAAO,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAC;CACtC"}

package/lib/permissions.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=permissions.js.map

package/lib/permissions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.js","sourceRoot":"","sources":["../src/permissions.ts"],"names":[],"mappings":""}

package/lib/results.d.ts

@@ -0,0 +1,22 @@
+import type { AudioFormat } from './format';
+export interface RecorderResult {
+    uri: string;
+    durationMs: number;
+    sizeBytes: number;
+    container: 'm4a';
+    audioFormat: AudioFormat;
+}
+export interface TranscriptAlternative {
+    text: string;
+    confidence: number;
+}
+export interface TranscriptResult {
+    text: string;
+    isFinal: boolean;
+    confidence?: number;
+    language?: string;
+    alternatives?: TranscriptAlternative[];
+    offsetMs?: number;
+    durationMs?: number;
+}
+//# sourceMappingURL=results.d.ts.map

package/lib/results.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"results.d.ts","sourceRoot":"","sources":["../src/results.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,KAAK,CAAC;IACjB,WAAW,EAAE,WAAW,CAAC;CAC1B;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,qBAAqB,EAAE,CAAC;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB"}

package/lib/results.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=results.js.map

package/lib/results.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"results.js","sourceRoot":"","sources":["../src/results.ts"],"names":[],"mappings":""}

package/lib/state.d.ts

@@ -0,0 +1,3 @@
+export type EngineState = 'idle' | 'preparing' | 'ready' | 'starting' | 'recording' | 'paused' | 'stopping' | 'error' | 'released';
+export type EngineKind = 'recorder' | 'native-recognizer' | 'azure-recognizer' | 'hybrid';
+//# sourceMappingURL=state.d.ts.map

package/lib/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GACnB,MAAM,GACN,WAAW,GACX,OAAO,GACP,UAAU,GACV,WAAW,GACX,QAAQ,GACR,UAAU,GACV,OAAO,GACP,UAAU,CAAC;AAEf,MAAM,MAAM,UAAU,GAClB,UAAU,GACV,mBAAmB,GACnB,kBAAkB,GAClB,QAAQ,CAAC"}

package/lib/state.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=state.js.map

package/lib/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":""}

package/lib/transitions.d.ts

@@ -0,0 +1,4 @@
+import type { EngineState } from './state';
+export declare const canTransition: (from: EngineState, to: EngineState) => boolean;
+export declare const assertTransition: (from: EngineState, to: EngineState) => void;
+//# sourceMappingURL=transitions.d.ts.map

package/lib/transitions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transitions.d.ts","sourceRoot":"","sources":["../src/transitions.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAc3C,eAAO,MAAM,aAAa,GAAI,MAAM,WAAW,EAAE,IAAI,WAAW,KAAG,OACnC,CAAC;AAEjC,eAAO,MAAM,gBAAgB,GAAI,MAAM,WAAW,EAAE,IAAI,WAAW,KAAG,IAOrE,CAAC"}

package/lib/transitions.js

@@ -0,0 +1,22 @@
+import { ClarionError } from './errors';
+const TRANSITIONS = {
+    idle: ['preparing', 'released'],
+    preparing: ['ready', 'error', 'released'],
+    ready: ['starting', 'released', 'error'],
+    starting: ['recording', 'error', 'released'],
+    recording: ['paused', 'stopping', 'error', 'released'],
+    paused: ['recording', 'stopping', 'error', 'released'],
+    stopping: ['ready', 'idle', 'error', 'released'],
+    error: ['idle', 'released'],
+    released: [],
+};
+export const canTransition = (from, to) => TRANSITIONS[from].includes(to);
+export const assertTransition = (from, to) => {
+    if (!canTransition(from, to)) {
+        throw new ClarionError({
+            code: 'INVALID_STATE',
+            message: `Illegal state transition: ${from} → ${to}`,
+        });
+    }
+};
+//# sourceMappingURL=transitions.js.map

package/lib/transitions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transitions.js","sourceRoot":"","sources":["../src/transitions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAGxC,MAAM,WAAW,GAAgD;IAC/D,IAAI,EAAE,CAAC,WAAW,EAAE,UAAU,CAAC;IAC/B,SAAS,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,UAAU,CAAC;IACzC,KAAK,EAAE,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,CAAC;IACxC,QAAQ,EAAE,CAAC,WAAW,EAAE,OAAO,EAAE,UAAU,CAAC;IAC5C,SAAS,EAAE,CAAC,QAAQ,EAAE,UAAU,EAAE,OAAO,EAAE,UAAU,CAAC;IACtD,MAAM,EAAE,CAAC,WAAW,EAAE,UAAU,EAAE,OAAO,EAAE,UAAU,CAAC;IACtD,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,CAAC;IAChD,KAAK,EAAE,CAAC,MAAM,EAAE,UAAU,CAAC;IAC3B,QAAQ,EAAE,EAAE;CACb,CAAC;AAEF,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,IAAiB,EAAE,EAAe,EAAW,EAAE,CAC3E,WAAW,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;AAEjC,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,IAAiB,EAAE,EAAe,EAAQ,EAAE;IAC3E,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,YAAY,CAAC;YACrB,IAAI,EAAE,eAAe;YACrB,OAAO,EAAE,6BAA6B,IAAI,MAAM,EAAE,EAAE;SACrD,CAAC,CAAC;IACL,CAAC;AACH,CAAC,CAAC"}

package/package.json

@@ -1,11 +1,36 @@
 {
   "name": "@clarionhq/core",
-  "version": "0.0.1",
-  "description": "Clarion core — placeholder, full release coming soon",
-  "main": "index.js",
+  "version": "0.1.0",
+  "description": "Clarion core — shared types, interfaces, errors, and state machine",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "source": "src/index.ts",
+  "react-native": "src/index.ts",
+  "files": [
+    "lib",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "react-native",
+    "audio",
+    "speech",
+    "voice",
+    "types"
+  ],
   "license": "MIT",
-  "publishConfig": { "access": "public" },
-  "repository": { "type": "git", "url": "https://github.com/clarionhq/clarion" },
-  "homepage": "https://github.com/clarionhq/clarion",
-  "keywords": ["react-native", "audio", "speech", "voice"]
-}
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Th4nderG0d/clarion",
+    "directory": "packages/core"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "clean": "rm -rf lib"
+  }
+}

package/src/emitter.ts

@@ -0,0 +1,30 @@
+import type { ClarionEvent, Listener, Unsubscribe } from './events';
+
+export class ClarionEmitter {
+  private listeners = new Set<Listener<ClarionEvent>>();
+
+  on(listener: Listener<ClarionEvent>): Unsubscribe {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  emit(event: ClarionEvent): void {
+    for (const listener of this.listeners) {
+      try {
+        listener(event);
+      } catch {
+        // Listener errors must not break the emit loop or other listeners.
+      }
+    }
+  }
+
+  removeAll(): void {
+    this.listeners.clear();
+  }
+
+  get listenerCount(): number {
+    return this.listeners.size;
+  }
+}

package/src/engine.ts

@@ -0,0 +1,45 @@
+import type { ClarionEvent, Listener, Unsubscribe } from './events';
+import type { EngineKind, EngineState } from './state';
+
+export interface ClarionEngine {
+  readonly kind: EngineKind;
+  readonly state: EngineState;
+
+  prepare(): Promise<void>;
+  start(): Promise<void>;
+  pause(): Promise<void>;
+  resume(): Promise<void>;
+  stop(): Promise<void>;
+  discard(): Promise<void>;
+  release(): Promise<void>;
+
+  on(listener: Listener<ClarionEvent>): Unsubscribe;
+}
+
+export interface RecorderEngineConfig {
+  outputDirectory?: string;
+  filenamePrefix?: string;
+  rotateAfterMs?: number;
+  emitAudioLevel?: boolean;
+  audioLevelIntervalMs?: number;
+}
+
+export interface RecognizerEngineConfig {
+  language: string;
+  emitPartials?: boolean;
+  maxAlternatives?: number;
+}
+
+export interface AzureEngineConfig extends RecognizerEngineConfig {
+  subscriptionKey?: string;
+  region?: string;
+  authToken?: string;
+  endpoint?: string;
+}
+
+export interface HybridEngineConfig {
+  online: AzureEngineConfig;
+  offline: RecorderEngineConfig;
+  preferAzureWhen: 'always-if-online' | 'on-good-network';
+  retainOfflineCopy?: boolean;
+}

package/src/errors.ts

@@ -0,0 +1,41 @@
+export type ErrorCode =
+  | 'PERMISSION_DENIED'
+  | 'AUDIO_BUSY'
+  | 'NETWORK_UNAVAILABLE'
+  | 'NETWORK_TIMEOUT'
+  | 'AUTH_FAILED'
+  | 'QUOTA_EXCEEDED'
+  | 'UNSUPPORTED_LANGUAGE'
+  | 'UNSUPPORTED_FORMAT'
+  | 'NO_SPEECH'
+  | 'INTERRUPTED'
+  | 'CANCELLED'
+  | 'ENGINE_NOT_READY'
+  | 'INVALID_STATE'
+  | 'IO_ERROR'
+  | 'INTERNAL_ERROR'
+  | 'UNKNOWN';
+
+export interface ClarionErrorOptions {
+  code: ErrorCode;
+  message: string;
+  cause?: unknown;
+  recoverable?: boolean;
+}
+
+export class ClarionError extends Error {
+  readonly code: ErrorCode;
+  readonly recoverable: boolean;
+  override readonly cause?: unknown;
+
+  constructor(opts: ClarionErrorOptions) {
+    super(opts.message);
+    this.name = 'ClarionError';
+    this.code = opts.code;
+    this.recoverable = opts.recoverable ?? false;
+    if (opts.cause !== undefined) this.cause = opts.cause;
+  }
+}
+
+export const isClarionError = (e: unknown): e is ClarionError =>
+  e instanceof ClarionError;

package/src/events.ts

@@ -0,0 +1,17 @@
+import type { ClarionError } from './errors';
+import type { RecorderResult, TranscriptResult } from './results';
+import type { EngineState } from './state';
+
+export type ClarionEvent =
+  | { type: 'state'; state: EngineState }
+  | { type: 'audio-level'; rms: number; peak: number }
+  | { type: 'partial'; result: TranscriptResult }
+  | { type: 'final'; result: TranscriptResult }
+  | { type: 'chunk'; uri: string; startMs: number; endMs: number; sizeBytes: number }
+  | { type: 'recording-complete'; result: RecorderResult }
+  | { type: 'error'; error: ClarionError };
+
+export type ClarionEventType = ClarionEvent['type'];
+
+export type Listener<T> = (event: T) => void;
+export type Unsubscribe = () => void;

package/src/format.ts

@@ -0,0 +1,15 @@
+export type SampleRate = 8000 | 16000 | 22050 | 44100 | 48000;
+export type ChannelCount = 1 | 2;
+export type BitDepth = 16 | 24 | 32;
+
+export interface AudioFormat {
+  sampleRate: SampleRate;
+  channels: ChannelCount;
+  bitDepth: BitDepth;
+}
+
+export const DEFAULT_AUDIO_FORMAT: AudioFormat = {
+  sampleRate: 16000,
+  channels: 1,
+  bitDepth: 16,
+};

package/src/index.ts

@@ -0,0 +1,11 @@
+export * from './state';
+export * from './format';
+export * from './results';
+export * from './errors';
+export * from './events';
+export * from './permissions';
+export * from './engine';
+export * from './emitter';
+export * from './transitions';
+
+export const CLARION_CORE_VERSION = '0.0.1';

package/src/permissions.ts

@@ -0,0 +1,11 @@
+export type PermissionStatus =
+  | 'granted'
+  | 'denied'
+  | 'undetermined'
+  | 'restricted'
+  | 'blocked';
+
+export interface PermissionsApi {
+  check(): Promise<PermissionStatus>;
+  request(): Promise<PermissionStatus>;
+}

package/src/results.ts

@@ -0,0 +1,24 @@
+import type { AudioFormat } from './format';
+
+export interface RecorderResult {
+  uri: string;
+  durationMs: number;
+  sizeBytes: number;
+  container: 'm4a';
+  audioFormat: AudioFormat;
+}
+
+export interface TranscriptAlternative {
+  text: string;
+  confidence: number;
+}
+
+export interface TranscriptResult {
+  text: string;
+  isFinal: boolean;
+  confidence?: number;
+  language?: string;
+  alternatives?: TranscriptAlternative[];
+  offsetMs?: number;
+  durationMs?: number;
+}

package/src/state.ts

@@ -0,0 +1,16 @@
+export type EngineState =
+  | 'idle'
+  | 'preparing'
+  | 'ready'
+  | 'starting'
+  | 'recording'
+  | 'paused'
+  | 'stopping'
+  | 'error'
+  | 'released';
+
+export type EngineKind =
+  | 'recorder'
+  | 'native-recognizer'
+  | 'azure-recognizer'
+  | 'hybrid';

package/src/transitions.ts

@@ -0,0 +1,26 @@
+import { ClarionError } from './errors';
+import type { EngineState } from './state';
+
+const TRANSITIONS: Record<EngineState, readonly EngineState[]> = {
+  idle: ['preparing', 'released'],
+  preparing: ['ready', 'error', 'released'],
+  ready: ['starting', 'released', 'error'],
+  starting: ['recording', 'error', 'released'],
+  recording: ['paused', 'stopping', 'error', 'released'],
+  paused: ['recording', 'stopping', 'error', 'released'],
+  stopping: ['ready', 'idle', 'error', 'released'],
+  error: ['idle', 'released'],
+  released: [],
+};
+
+export const canTransition = (from: EngineState, to: EngineState): boolean =>
+  TRANSITIONS[from].includes(to);
+
+export const assertTransition = (from: EngineState, to: EngineState): void => {
+  if (!canTransition(from, to)) {
+    throw new ClarionError({
+      code: 'INVALID_STATE',
+      message: `Illegal state transition: ${from} → ${to}`,
+    });
+  }
+};

package/index.js

@@ -1 +0,0 @@
-// @clarionhq/core — placeholder. See https://github.com/clarionhq/clarion