@sorisdk/matcher 0.6.10 → 0.6.11

package/dist/generated/core.d.ts

@@ -22,6 +22,7 @@ export class WasmMatcherEngine {
     free(): void;
     [Symbol.dispose](): void;
     bestMatch(database: WasmMatcherDatabase, query: Uint8Array, config?: any | null): any;
+    bestMatchChecked(database: WasmMatcherDatabase, query: Uint8Array, config?: any | null): any;
     bestMatchWithVariants(database: WasmMatcherDatabase, query: Uint8Array, pitch_query: any, config?: any | null, variant_config?: any | null): any;
     detectAudioMarker(pcm16_le: Uint8Array, sample_rate: number, config?: any | null): any;
     detectAudioMarkerWithLimits(pcm16_le: Uint8Array, sample_rate: number, config?: any | null, limits?: any | null): any;
@@ -33,6 +34,7 @@ export class WasmMatcherEngine {
     extractPitchReference(pcm16_le: Uint8Array, sample_rate: number): any;
     extractSpectralShiftReference(pcm16_le: Uint8Array, sample_rate: number): any;
     matchQuery(database: WasmMatcherDatabase, query: Uint8Array, config?: any | null): any;
+    matchQueryChecked(database: WasmMatcherDatabase, query: Uint8Array, config?: any | null): any;
     matchQueryWithVariants(database: WasmMatcherDatabase, query: Uint8Array, pitch_query: any, config?: any | null, variant_config?: any | null): any;
     constructor();
     /**

package/dist/generated/core_bg.js

@@ -170,6 +170,22 @@ export class WasmMatcherEngine {
         }
         return takeFromExternrefTable0(ret[0]);
     }
+    /**
+     * @param {WasmMatcherDatabase} database
+     * @param {Uint8Array} query
+     * @param {any | null} [config]
+     * @returns {any}
+     */
+    bestMatchChecked(database, query, config) {
+        _assertClass(database, WasmMatcherDatabase);
+        const ptr0 = passArray8ToWasm0(query, wasm.__wbindgen_malloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.wasmmatcherengine_bestMatchChecked(this.__wbg_ptr, database.__wbg_ptr, ptr0, len0, isLikeNone(config) ? 0 : addToExternrefTable0(config));
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
     /**
      * @param {WasmMatcherDatabase} database
      * @param {Uint8Array} query
@@ -335,6 +351,22 @@ export class WasmMatcherEngine {
         }
         return takeFromExternrefTable0(ret[0]);
     }
+    /**
+     * @param {WasmMatcherDatabase} database
+     * @param {Uint8Array} query
+     * @param {any | null} [config]
+     * @returns {any}
+     */
+    matchQueryChecked(database, query, config) {
+        _assertClass(database, WasmMatcherDatabase);
+        const ptr0 = passArray8ToWasm0(query, wasm.__wbindgen_malloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.wasmmatcherengine_matchQueryChecked(this.__wbg_ptr, database.__wbg_ptr, ptr0, len0, isLikeNone(config) ? 0 : addToExternrefTable0(config));
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
     /**
      * @param {WasmMatcherDatabase} database
      * @param {Uint8Array} query

package/dist/generated/core_bg.wasm.d.ts

@@ -25,6 +25,7 @@ export const wasmmatcherdatabase_new: () => number;
 export const wasmmatcherdatabase_removeEntry: (a: number, b: number, c: number) => [number, number];
 export const wasmmatcherdatabase_setEntryVariantMetadata: (a: number, b: number, c: number, d: number, e: number) => [number, number];
 export const wasmmatcherengine_bestMatch: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
+export const wasmmatcherengine_bestMatchChecked: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
 export const wasmmatcherengine_bestMatchWithVariants: (a: number, b: number, c: number, d: number, e: any, f: number, g: number) => [number, number, number];
 export const wasmmatcherengine_detectAudioMarker: (a: number, b: any, c: number, d: number) => [number, number, number];
 export const wasmmatcherengine_detectAudioMarkerWithLimits: (a: number, b: any, c: number, d: number, e: number) => [number, number, number];
@@ -35,9 +36,10 @@ export const wasmmatcherengine_estimatePitchRatioAgainstSpectralFeatures: (a: nu
 export const wasmmatcherengine_extractPitchReference: (a: number, b: number, c: number, d: number) => [number, number, number];
 export const wasmmatcherengine_extractSpectralShiftReference: (a: number, b: number, c: number, d: number) => [number, number, number];
 export const wasmmatcherengine_matchQuery: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
+export const wasmmatcherengine_matchQueryChecked: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
 export const wasmmatcherengine_matchQueryWithVariants: (a: number, b: number, c: number, d: number, e: any, f: number, g: number) => [number, number, number];
-export const wasmmatcherengine_resetDistinctMatchState: (a: number) => void;
 export const wasmmatcherengine_new: () => number;
+export const wasmmatcherengine_resetDistinctMatchState: (a: number) => void;
 export const init_matcher_wasm: () => void;
 export const detectPatternMark: (a: any, b: number, c: number) => [number, number, number];
 export const wasmmatcherengine_detectPatternMark: (a: number, b: any, c: number, d: number) => [number, number, number];

package/dist/index.d.ts

@@ -142,6 +142,24 @@ interface MatchResult {
     durationMillis?: number;
     afpType: AudioFingerprintType;
 }
+type TimingCoordinateSpace = "entry_local" | "segment_local" | "unavailable";
+type TimingUnavailableReason = "rejected_metadata" | "invalidated_metadata" | "incompatible_geometry" | "ambiguous_clock" | "out_of_range" | "window_origin_underflow" | "inconsistent_windows";
+interface MatchTiming {
+    coordinateSpace: TimingCoordinateSpace;
+    /** Null when timing normalization failed. */
+    positionMillis: number | null;
+    durationMillis: number | null;
+    segmentIndex: number | null;
+    reason: TimingUnavailableReason | null;
+}
+interface CheckedMatchResult {
+    name: string;
+    score: number;
+    afpType: AudioFingerprintType;
+    /** Diagnostic entry offset only; consumers should use timing. */
+    rawPositionMillis: number;
+    timing: MatchTiming;
+}
 interface VariantMatch {
     matchResult: MatchResult;
     variant: VariantDecision;
@@ -273,6 +291,11 @@ declare class MatcherSession {
     clear(): Promise<void>;
     getEntryMetadata(name: string): Promise<EntryMetadata | null>;
     match(query: Uint8Array, config?: MatchConfig): Promise<MatchResult[]>;
+    /**
+     * Read one observation with explicit timing coordinates. This direct accessor
+     * does not emit legacy match events or update recognition deduplication state.
+     */
+    bestMatchChecked(query: Uint8Array, config?: MatchConfig): Promise<CheckedMatchResult | null>;
     bestMatch(query: Uint8Array, config?: MatchConfig): Promise<MatchResult | null>;
     estimatePitchRatio(pcm16Le: Uint8Array, sampleRate: number): Promise<PitchRatioEstimate>;
     extractPitchReference(pcm16Le: Uint8Array, sampleRate: number): Promise<PitchReferenceEstimate>;
@@ -304,4 +327,4 @@ declare function __resetMatcherWasmForTests(): void;
 /** Maximum gap between successful observations in one continuous material run. */
 declare const MATCH_CONTINUITY_GAP_MS = 30000;
 
-export { AUDIO_MARKER_INPUT_BUDGET_EXCEEDED_REASON, AUDIO_MARKER_WORK_BUDGET_EXCEEDED_REASON, AUDIO_MARKER_WORK_OVERFLOW_REASON, AudioFingerprintType, type AudioMarkerCode, type AudioMarkerConfig, type AudioMarkerDetection, type AudioMarkerLevelDiagnostics, type AudioMarkerLevelPolicy, type AudioMarkerLimits, DEFAULT_MAX_AUDIO_MARKER_DURATION_MILLIS, DEFAULT_MAX_AUDIO_MARKER_PCM_BYTES, DEFAULT_MAX_AUDIO_MARKER_SAMPLES, DEFAULT_MAX_AUDIO_MARKER_WORK_UNITS, DEFAULT_MAX_PACK_BYTES, type EntryMetadata, type InitMatcherOptions, type InitMatcherResult, MATCH_CONTINUITY_GAP_MS, type MatchConfig, type MatchResult, type MatcherEphemeralAuthOptions, type MatcherEphemeralAuthResult, type MatcherEphemeralKeyExchangeMetadata, type MatcherEphemeralKeyExchangeOptions, MatcherSession, type MatcherSessionEventMap, type MatcherSessionEventName, type MatcherSessionListener, type MatcherSessionOptions, type PackSource, type PitchRatioEstimate, type PitchReferenceEstimate, type VariantDecision, type VariantDecisionStatus, type VariantMatch, type VariantMatchConfig, type VariantMatchQuery, __resetMatcherWasmForTests, __setMatcherEmbeddedPackForTests, __setMatcherWasmModuleForTests, initMatcher };
+export { AUDIO_MARKER_INPUT_BUDGET_EXCEEDED_REASON, AUDIO_MARKER_WORK_BUDGET_EXCEEDED_REASON, AUDIO_MARKER_WORK_OVERFLOW_REASON, AudioFingerprintType, type AudioMarkerCode, type AudioMarkerConfig, type AudioMarkerDetection, type AudioMarkerLevelDiagnostics, type AudioMarkerLevelPolicy, type AudioMarkerLimits, type CheckedMatchResult, DEFAULT_MAX_AUDIO_MARKER_DURATION_MILLIS, DEFAULT_MAX_AUDIO_MARKER_PCM_BYTES, DEFAULT_MAX_AUDIO_MARKER_SAMPLES, DEFAULT_MAX_AUDIO_MARKER_WORK_UNITS, DEFAULT_MAX_PACK_BYTES, type EntryMetadata, type InitMatcherOptions, type InitMatcherResult, MATCH_CONTINUITY_GAP_MS, type MatchConfig, type MatchResult, type MatchTiming, type MatcherEphemeralAuthOptions, type MatcherEphemeralAuthResult, type MatcherEphemeralKeyExchangeMetadata, type MatcherEphemeralKeyExchangeOptions, MatcherSession, type MatcherSessionEventMap, type MatcherSessionEventName, type MatcherSessionListener, type MatcherSessionOptions, type PackSource, type PitchRatioEstimate, type PitchReferenceEstimate, type TimingCoordinateSpace, type TimingUnavailableReason, type VariantDecision, type VariantDecisionStatus, type VariantMatch, type VariantMatchConfig, type VariantMatchQuery, __resetMatcherWasmForTests, __setMatcherEmbeddedPackForTests, __setMatcherWasmModuleForTests, initMatcher };

package/dist/index.js

@@ -478,6 +478,28 @@ var WrappedDatabase = class {
 var WrappedMatcher = class {
   constructor(inner) {
     this.inner = inner;
+    const findMatchesCheckedFn = getCallable(this.inner, [
+      "findMatchesChecked",
+      "find_matches_checked",
+      "matchQueryChecked",
+      "match_query_checked"
+    ]);
+    if (findMatchesCheckedFn) {
+      this.findMatchesChecked = (database, query, config) => {
+        const dbRecord = typeof database.raw === "function" ? database.raw() : database;
+        const raw = findMatchesCheckedFn.call(this.inner, dbRecord, query, config);
+        if (!Array.isArray(raw)) throw new Error("Invalid checked match results");
+        return raw.map(normalizeCheckedResult);
+      };
+    }
+    const bestMatchCheckedFn = getCallable(this.inner, ["bestMatchChecked", "best_match_checked"]);
+    if (bestMatchCheckedFn) {
+      this.bestMatchChecked = (database, query, config) => {
+        const dbRecord = typeof database.raw === "function" ? database.raw() : database;
+        const raw = bestMatchCheckedFn.call(this.inner, dbRecord, query, config);
+        return raw == null ? null : normalizeCheckedResult(raw);
+      };
+    }
     const estimatePitchRatioFn = getCallable(this.inner, [
       "estimatePitchRatio",
       "estimate_pitch_ratio"
@@ -555,6 +577,8 @@ var WrappedMatcher = class {
     }
   }
   inner;
+  findMatchesChecked;
+  bestMatchChecked;
   estimatePitchRatio;
   extractPitchReference;
   estimatePitchRatioAgainstReference;
@@ -645,6 +669,56 @@ function normalizeResult(raw) {
   }
   return result;
 }
+var TIMING_UNAVAILABLE_REASONS = /* @__PURE__ */ new Set([
+  "rejected_metadata",
+  "invalidated_metadata",
+  "incompatible_geometry",
+  "ambiguous_clock",
+  "out_of_range",
+  "window_origin_underflow",
+  "inconsistent_windows"
+]);
+function normalizeCheckedResult(raw) {
+  const invalid = () => new Error("Invalid checked match result");
+  if (!raw || typeof raw !== "object") {
+    throw invalid();
+  }
+  const record = raw;
+  if (!record.timing || typeof record.timing !== "object") {
+    throw invalid();
+  }
+  const source = record.timing;
+  const integer = (camel, snake) => {
+    const value = camel ?? snake;
+    if (value == null) return null;
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+      throw invalid();
+    }
+    return value;
+  };
+  const coordinateSpace = source.coordinateSpace ?? source.coordinate_space;
+  const timing = {
+    coordinateSpace,
+    positionMillis: integer(source.positionMillis, source.position_millis),
+    durationMillis: integer(source.durationMillis, source.duration_millis),
+    segmentIndex: integer(source.segmentIndex, source.segment_index),
+    reason: source.reason ?? null
+  };
+  const available = timing.reason === null && timing.positionMillis !== null;
+  const validTiming = coordinateSpace === "unavailable" ? timing.positionMillis === null && timing.durationMillis === null && timing.segmentIndex === null && TIMING_UNAVAILABLE_REASONS.has(timing.reason) : coordinateSpace === "entry_local" ? available && timing.durationMillis === null && timing.segmentIndex === null : coordinateSpace === "segment_local" && available && timing.durationMillis !== null && timing.segmentIndex !== null && timing.positionMillis < timing.durationMillis;
+  const rawPositionMillis = integer(record.rawPositionMillis, record.raw_position_millis);
+  const afpType = record.afpType ?? record.afp_type;
+  if (!validTiming || typeof record.name !== "string" || record.name.length === 0 || typeof record.score !== "number" || !Number.isFinite(record.score) || record.score < 0 || ![1, 2, 4].includes(afpType) || rawPositionMillis === null) {
+    throw invalid();
+  }
+  return {
+    name: record.name,
+    score: record.score,
+    afpType,
+    rawPositionMillis,
+    timing
+  };
+}
 function normalizeVariantMatch(raw) {
   const rawMatch = raw.matchResult ?? raw.match;
   const rawVariant = raw.variant ?? {};
@@ -1265,6 +1339,26 @@ var MatcherSession = class {
       handleError(this.events, "match", error);
     }
   }
+  /**
+   * Read one observation with explicit timing coordinates. This direct accessor
+   * does not emit legacy match events or update recognition deduplication state.
+   */
+  async bestMatchChecked(query, config) {
+    const generation = this.recognitionGeneration;
+    try {
+      await this.ensureLiveReady();
+      if (generation !== this.recognitionGeneration) return null;
+      const safeQuery = toUint8ArrayCopy(query);
+      const matcher = this.matcherOrThrow();
+      if (!matcher.bestMatchChecked) {
+        throw new Error("WASM matcher is missing bestMatchChecked; upgrade the WASM assets");
+      }
+      if (generation !== this.recognitionGeneration || this.destroyed) return null;
+      return matcher.bestMatchChecked(this.databaseOrThrow(), safeQuery, config);
+    } catch (error) {
+      handleError(this.events, "bestMatchChecked", error);
+    }
+  }
   async bestMatch(query, config) {
     const generation = this.recognitionGeneration;
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sorisdk/matcher",
-  "version": "0.6.10",
+  "version": "0.6.11",
   "description": "Browser WASM SDK for audio fingerprint matching",
   "type": "module",
   "main": "./dist/index.js",