@sorisdk/web-audio 0.6.3 → 0.6.5

package/README.md

@@ -22,7 +22,7 @@ configuration, or Node-based asset server is required:
 ```html
 <script type="module">
   import { AudioRecognizer } from
-    "https://cdn.iplateia.com/web/sorisdk/v0.6.3/sori-web-audio.mjs";
+    "https://cdn.iplateia.com/web/sorisdk/v0.6.5/sori-web-audio.mjs";
 
   const recognizer = new AudioRecognizer({
     appId: "YOUR_APP_ID",
@@ -49,7 +49,7 @@ configuration, or Node-based asset server is required:
 ```
 
 Static URL imports are valid inside `<script type="module">`. Dynamic
-`await import("https://cdn.iplateia.com/web/sorisdk/v0.6.3/sori-web-audio.mjs")`
+`await import("https://cdn.iplateia.com/web/sorisdk/v0.6.5/sori-web-audio.mjs")`
 is an optional alternative when the SDK should be loaded conditionally.
 
 Pin an exact version in production. Do not construct a mutable `latest` URL.
@@ -93,7 +93,7 @@ An import map can give the standalone URL the npm package name:
 <script type="importmap">
 {
   "imports": {
-    "@sorisdk/web-audio": "https://cdn.iplateia.com/web/sorisdk/v0.6.3/sori-web-audio.mjs"
+    "@sorisdk/web-audio": "https://cdn.iplateia.com/web/sorisdk/v0.6.5/sori-web-audio.mjs"
   }
 }
 </script>
@@ -142,7 +142,7 @@ const recognizer = new AudioRecognizer({
 });
 
 recognizer.on("campaign", (event) => {
-  console.log(event.campaign);
+  console.log(event.activityId, event.campaign);
 });
 
 recognizer.on("error", ({ error }) => {
@@ -159,6 +159,119 @@ await recognizer.stop();
 await recognizer.destroy();
 ```
 
+## Activity refinement
+
+The default `AudioRecognizer` activity reporter represents one fingerprint
+recognition and its later audio-marker enrichment as one server activity:
+
+1. A marker-free match with an active marker-scan request is created with
+   `POST /api/activity/` and top-level `refinement_expected: true`.
+2. The returned `activity_id` is retained for 30 seconds.
+3. If the same recognition gains `audioMarker.code`, the SDK sends
+   `PUT /api/activity/{activity_id}` with the same material and
+   `trait.marker`.
+4. The refined `campaign` event keeps the same non-empty `activityId`, so an
+   application can replace the earlier campaign row deterministically.
+
+A marker present on the first match is included in the POST and does not cause
+a PUT or include `refinement_expected`. Recognition without an active marker
+scan, plus legacy/custom POST-only reporters, also omit the opt-in flag.
+Marker-state `audiomarker` events remain independently observable; they do not
+mean that server activity refinement completed.
+
+Network and 5xx PUT failures are retried at most twice within the original
+30-second deadline. Server responses 404, 409, and 410 are terminal. An
+expired or failed refinement is dropped and never becomes a second POST.
+Stopping, clearing, destroying, or replacing the authenticated capture clears
+pending refinement identity.
+
+Custom `activityReporter` configurations remain POST-only by default. Enable
+refinement explicitly and, if needed, provide operation-specific transport or
+mapping hooks:
+
+```ts
+const recognizer = new AudioRecognizer({
+  appId: "YOUR_APP_ID",
+  ephemeralKey: fetchEphemeralKeyFromYourServer,
+  activityReporter: {
+    endpoint: "https://example.com/activity/",
+    refinement: {
+      endpoint: (activityId) =>
+        `https://example.com/activity/${encodeURIComponent(activityId)}`,
+      maxAttempts: 2,
+      shouldRetry: ({ status }) => status === null || status >= 500
+    }
+  }
+});
+```
+
+Existing `mapMatchToRequest` and `mapResponseToCampaign` hooks continue to
+handle POST. Additive refinement hooks can override the PUT payload, response
+mapping, endpoint, headers, fetcher, and retry policy. The stable terminal
+statuses 404, 409, and 410 are never retried even if a custom policy returns
+`true`.
+
+## Session identifiers
+
+`AudioRecognizer` creates one pseudonymous session identifier per application
+and stores it in `localStorage` under
+`sorisdk:web-audio:session:<appId>`. The value persists until the origin's
+storage is cleared or the session manager's `clear()` method is called. An
+upgrade does not rotate an existing non-empty value, including identifiers
+created by older SDK versions.
+
+New identifiers use `crypto.randomUUID()`. Browsers without `randomUUID()` use
+`crypto.getRandomValues()` to create an RFC 4122 UUID v4. If neither secure API
+is available, session creation fails instead of falling back to predictable
+randomness. A host for such an environment must provide a cryptographically
+secure generator explicitly:
+
+```ts
+import {
+  AudioRecognizer,
+  createLocalStorageSessionManager
+} from "@sorisdk/web-audio";
+
+const sessionManager = createLocalStorageSessionManager({
+  key: "sorisdk:web-audio:session:YOUR_APP_ID",
+  generateSessionId: () => secureSessionIdFromYourRuntime()
+});
+
+const recognizer = new AudioRecognizer({
+  appId: "YOUR_APP_ID",
+  ephemeralKey: fetchEphemeralKeyFromYourServer,
+  sessionManager
+});
+
+// Stop recognition before intentionally rotating the identifier.
+await recognizer.destroy();
+await sessionManager.clear?.();
+```
+
+Treat the identifier as persistent pseudonymous data: do not include personal
+information in a custom value, and do not log or expose it unnecessarily.
+Clearing it breaks device and activity continuity; the next authentication
+creates a new server-side device identity.
+
+### SORI service contract
+
+The current SORI service uses the identifier at these boundaries:
+
+| Boundary | Use of `sessionId` | Security contract |
+| --- | --- | --- |
+| Authentication request | Debounces repeated requests and upserts an account-scoped device record | A valid application ID plus secret or ephemeral key is still required |
+| Session token | Stored as the signed device claim | Possession of the raw identifier does not create or validate a token |
+| Recognition activity | Attributes impressions, clicks, campaign links, and campaign webhooks to a device | Authorization comes from the signed token, not the identifier |
+| Monitoring | Binds stored health and transition data to the token's device claim | A submitted device ID must match the signed claim |
+| Authentication webhook | Populates the webhook `device_id` | The value is correlation data, not a webhook credential |
+| Quota and throttling | Selects the authentication debounce bucket only | It is not a standalone billing or usage quota key |
+| AudioPack caching | Not used as a cache partition | The browser cache remains application-scoped |
+| Replay protection | No use | The stable identifier provides neither freshness nor replay protection |
+
+Authorization, quota enforcement, cache isolation, and replay controls must
+remain bound to authenticated server-side state rather than possession or
+unpredictability of `sessionId`.
+
 ## Advanced wasm loading overrides
 
 If you need to pin explicit generated modules, use the nested `wasm` options:

package/dist/index.d.ts

@@ -62,6 +62,11 @@ interface AudioMarkerEvent {
 interface MaterialActivityRequestPayload {
     type: "material";
     material_id: string;
+    refinement_expected?: true;
+    trait?: {
+        marker?: string;
+        [key: string]: unknown;
+    };
     metadata?: unknown;
 }
 interface MicrophoneMatcherCampaignEvent {
@@ -70,6 +75,27 @@ interface MicrophoneMatcherCampaignEvent {
     activityId: string | null;
     raw: Record<string, unknown>;
 }
+interface ActivityRefinementRequestContext {
+    operation: "refine";
+    activityId: string;
+    attempt: number;
+    deadline: number;
+}
+interface ActivityRefinementFailureContext extends ActivityRefinementRequestContext {
+    error: Error;
+    status: number | null;
+    detail: string | null;
+}
+interface MicrophoneMatcherActivityRefinementOptions {
+    endpoint?: string | URL | ((activityId: string) => string | URL | Promise<string | URL>);
+    fetch?: typeof fetch;
+    headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+    mapMatchToRequest?: (match: DetectedMatch, context: ActivityRefinementRequestContext) => MaterialActivityRequestPayload | null | Promise<MaterialActivityRequestPayload | null>;
+    mapResponseToCampaign?: (response: Record<string, unknown>, match: DetectedMatch, context: ActivityRefinementRequestContext) => MicrophoneMatcherCampaignEvent | null | Promise<MicrophoneMatcherCampaignEvent | null>;
+    shouldRetry?: (context: ActivityRefinementFailureContext) => boolean | Promise<boolean>;
+    maxAttempts?: number;
+    now?: () => number;
+}
 interface MicrophoneMatcherActivityReporterOptions {
     endpoint: string | URL;
     token: string | (() => string | Promise<string>);
@@ -77,6 +103,7 @@ interface MicrophoneMatcherActivityReporterOptions {
     headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
     mapMatchToRequest?: (match: DetectedMatch) => MaterialActivityRequestPayload | null | Promise<MaterialActivityRequestPayload | null>;
     mapResponseToCampaign?: (response: Record<string, unknown>, match: DetectedMatch) => MicrophoneMatcherCampaignEvent | null | Promise<MicrophoneMatcherCampaignEvent | null>;
+    refinement?: false | MicrophoneMatcherActivityRefinementOptions;
 }
 interface CreateMicrophoneMatcherWasmOptions {
     afpgen?: InitAfpgenOptions;
@@ -182,6 +209,8 @@ declare class AudioRecognizer {
     private setAuthResult;
 }
 
+declare const ACTIVITY_REFINEMENT_WINDOW_MS = 30000;
+
 declare class MicrophoneMatcher {
     private readonly events;
     private readonly matcherSession;
@@ -193,6 +222,7 @@ declare class MicrophoneMatcher {
     private readonly captureSampleRate;
     private readonly audioGraphFactory;
     private readonly packSource;
+    private readonly activityRefinement;
     private readonly options;
     private extractor;
     private graphController;
@@ -211,6 +241,7 @@ declare class MicrophoneMatcher {
     private latestAudioMarker;
     private latestAudioMarkerDetection;
     private audioMarkerRequestId;
+    private activityRecognitionId;
     private hopSize;
     private diagnostics;
     constructor(options: CreateMicrophoneMatcherOptions);
@@ -260,4 +291,4 @@ declare function requestMicrophoneStream(mediaDevices: MediaDevices, mediaConstr
     preferredSampleRate?: number;
 }): Promise<MediaStream>;
 
-export { type AudioMarkerEvent, AudioRecognizer, type AudioRecognizerAuthOptions, type AudioRecognizerOptions, type AuthenticateAndLoadAudioPackOptions, type AuthenticateAndLoadAudioPackResult, type BrowserAudioPackLoader, type BrowserAudioPackState, type BrowserAudioPackStateStore, type BrowserSessionManager, type CreateLocalStorageAudioPackStoreOptions, type CreateLocalStorageSessionManagerOptions, type CreateMicrophoneMatcherOptions, type CreateMicrophoneMatcherWasmOptions, DEFAULT_BROWSER_AUDIOPACK_VERSION, DEFAULT_SORI_API_ENDPOINT, type DetectedMatch, type MaterialActivityRequestPayload, MicrophoneMatcher, type MicrophoneMatcherActivityReporterOptions, type MicrophoneMatcherCampaignEvent, type MicrophoneMatcherEventMap, type MicrophoneMatcherEventName, type MicrophoneMatcherListener, authenticateAndLoadAudioPack, createLocalStorageAudioPackStore, createLocalStorageSessionManager, createMicrophoneMatcher, requestMicrophoneStream };
+export { ACTIVITY_REFINEMENT_WINDOW_MS, type ActivityRefinementFailureContext, type ActivityRefinementRequestContext, type AudioMarkerEvent, AudioRecognizer, type AudioRecognizerAuthOptions, type AudioRecognizerOptions, type AuthenticateAndLoadAudioPackOptions, type AuthenticateAndLoadAudioPackResult, type BrowserAudioPackLoader, type BrowserAudioPackState, type BrowserAudioPackStateStore, type BrowserSessionManager, type CreateLocalStorageAudioPackStoreOptions, type CreateLocalStorageSessionManagerOptions, type CreateMicrophoneMatcherOptions, type CreateMicrophoneMatcherWasmOptions, DEFAULT_BROWSER_AUDIOPACK_VERSION, DEFAULT_SORI_API_ENDPOINT, type DetectedMatch, type MaterialActivityRequestPayload, MicrophoneMatcher, type MicrophoneMatcherActivityRefinementOptions, type MicrophoneMatcherActivityReporterOptions, type MicrophoneMatcherCampaignEvent, type MicrophoneMatcherEventMap, type MicrophoneMatcherEventName, type MicrophoneMatcherListener, authenticateAndLoadAudioPack, createLocalStorageAudioPackStore, createLocalStorageSessionManager, createMicrophoneMatcher, requestMicrophoneStream };

package/dist/index.js

@@ -201,6 +201,7 @@ var WrappedFingerprintMatchWindow = class {
   constructor(inner) {
     this.inner = inner;
   }
+  inner;
   appendFingerprint(bytes) {
     const fn = getCallable(this.inner, ["appendFingerprint", "append_fingerprint"]);
     if (!fn) {
@@ -313,6 +314,22 @@ var FingerprintMatchWindow = class {
 };
 
 // src/activity.ts
+var ActivityReportingError = class extends Error {
+  status;
+  detail;
+  constructor(message, status = null, detail = null) {
+    super(message);
+    this.name = "ActivityReportingError";
+    this.status = status;
+    this.detail = detail;
+  }
+};
+var ActivityReportingCancelledError = class extends Error {
+  constructor() {
+    super("Activity reporting was cancelled before transport");
+    this.name = "ActivityReportingCancelledError";
+  }
+};
 function isRecord2(value) {
   return typeof value === "object" && value !== null;
 }
@@ -332,11 +349,15 @@ async function resolveToken(token) {
   }
   return resolved;
 }
-async function resolveRequestPayload(reporter, match) {
-  const payload = reporter.mapMatchToRequest ? await reporter.mapMatchToRequest(match) : {
+function defaultRequestPayload(match) {
+  const marker = match.audioMarker?.code;
+  return {
     type: "material",
-    material_id: match.name
+    material_id: match.name,
+    ...typeof marker === "string" && marker.length > 0 ? { trait: { marker } } : {}
   };
+}
+function validateRequestPayload(payload) {
   if (payload === null) {
     return null;
   }
@@ -345,6 +366,30 @@ async function resolveRequestPayload(reporter, match) {
   }
   return payload;
 }
+async function resolveCreateRequestPayload(reporter, match) {
+  const payload = validateRequestPayload(
+    reporter.mapMatchToRequest ? await reporter.mapMatchToRequest(match) : defaultRequestPayload(match)
+  );
+  if (!payload) {
+    return null;
+  }
+  const { refinement_expected: _ignored, ...requestPayload } = payload;
+  return requestPayload;
+}
+async function resolveRefineRequestPayload(reporter, match, context) {
+  const refinement = reporter.refinement;
+  if (!refinement) {
+    return null;
+  }
+  const payload = validateRequestPayload(
+    refinement.mapMatchToRequest ? await refinement.mapMatchToRequest(match, context) : reporter.mapMatchToRequest ? await reporter.mapMatchToRequest(match) : defaultRequestPayload(match)
+  );
+  if (!payload) {
+    return null;
+  }
+  const { refinement_expected: _ignored, ...requestPayload } = payload;
+  return requestPayload;
+}
 function defaultCampaignMapper(payload, match) {
   const campaign = payload.campaign;
   if (!isRecord2(campaign)) {
@@ -357,42 +402,462 @@ function defaultCampaignMapper(payload, match) {
     raw: payload
   };
 }
-async function reportMatchedMaterialActivity(reporter, match) {
-  const payload = await resolveRequestPayload(reporter, match);
-  if (!payload) {
-    return null;
+async function resolveHeaders(reporter, refinement = false) {
+  const refinementHeaders = reporter.refinement && reporter.refinement.headers;
+  const baseHeaders = reporter.headers ? typeof reporter.headers === "function" ? await reporter.headers() : reporter.headers : void 0;
+  const headers = new Headers(baseHeaders);
+  if (refinement && refinementHeaders !== void 0) {
+    const overrides = new Headers(
+      typeof refinementHeaders === "function" ? await refinementHeaders() : refinementHeaders
+    );
+    overrides.forEach((value, name) => headers.set(name, value));
   }
-  const headers = new Headers(
-    reporter.headers ? typeof reporter.headers === "function" ? await reporter.headers() : reporter.headers : void 0
-  );
   headers.set("authorization", `Bearer ${await resolveToken(reporter.token)}`);
   headers.set("content-type", "application/json");
+  return headers;
+}
+async function parseActivityResponse(response, operation) {
+  const responseText = await response.text();
+  let data = null;
+  if (responseText.trim().length > 0) {
+    try {
+      data = JSON.parse(responseText);
+    } catch {
+      throw new ActivityReportingError(
+        `Activity ${operation} failed: invalid JSON response`,
+        response.status
+      );
+    }
+  }
+  const succeeded = operation === "refine" ? response.status === 200 : response.ok;
+  if (!succeeded) {
+    const detail = isRecord2(data) && typeof data.detail === "string" ? data.detail : null;
+    throw new ActivityReportingError(
+      `Activity ${operation} failed: HTTP ${response.status}${detail ? ` (${detail})` : ""}`,
+      response.status,
+      detail
+    );
+  }
+  if (data === null) {
+    return null;
+  }
+  if (!isRecord2(data)) {
+    throw new ActivityReportingError(
+      `Activity ${operation} failed: expected an object response`,
+      response.status
+    );
+  }
+  return data;
+}
+function responseActivityId(data, campaign) {
+  if (data && typeof data.activity_id === "string" && data.activity_id.length > 0) {
+    return data.activity_id;
+  }
+  return campaign?.activityId && campaign.activityId.length > 0 ? campaign.activityId : null;
+}
+async function mapCreateResponse(reporter, data, match, refinementExpected) {
+  if (!data) {
+    return { activityId: null, campaign: null, refinementExpected };
+  }
+  const campaign = reporter.mapResponseToCampaign ? await reporter.mapResponseToCampaign(data, match) : defaultCampaignMapper(data, match);
+  return { activityId: responseActivityId(data, campaign), campaign, refinementExpected };
+}
+async function resolveRefinementEndpoint(reporter, activityId) {
+  const configured = reporter.refinement && reporter.refinement.endpoint;
+  if (typeof configured === "function") {
+    return configured(activityId);
+  }
+  const prefix = String(configured ?? reporter.endpoint);
+  return `${prefix.endsWith("/") ? prefix : `${prefix}/`}${encodeURIComponent(activityId)}`;
+}
+async function createMatchedMaterialActivity(reporter, match, refinementExpected = false) {
+  const payload = await resolveCreateRequestPayload(reporter, match);
+  if (!payload) {
+    return { activityId: null, campaign: null, refinementExpected: false };
+  }
+  const headers = await resolveHeaders(reporter);
+  const actualMarker = match.audioMarker?.code;
+  const payloadMarker = payload.trait?.marker;
+  const hasMarker = typeof actualMarker === "string" && actualMarker.length > 0 || typeof payloadMarker === "string" && payloadMarker.length > 0;
+  const lifecycleOpen = typeof refinementExpected === "function" ? refinementExpected() : refinementExpected;
+  const requestRefinementExpected = Boolean(reporter.refinement && lifecycleOpen && !hasMarker);
+  const requestPayload = requestRefinementExpected ? { ...payload, refinement_expected: true } : payload;
   const response = await resolveFetch(reporter.fetch)(reporter.endpoint, {
     method: "POST",
     headers,
+    body: JSON.stringify(requestPayload)
+  });
+  return mapCreateResponse(
+    reporter,
+    await parseActivityResponse(response, "create"),
+    match,
+    requestRefinementExpected
+  );
+}
+async function refineMatchedMaterialActivity(reporter, match, context, isActive = () => true) {
+  const refinement = reporter.refinement;
+  if (!refinement) {
+    return { activityId: null, campaign: null };
+  }
+  const payload = await resolveRefineRequestPayload(reporter, match, context);
+  if (!payload) {
+    return { activityId: null, campaign: null };
+  }
+  const endpoint = await resolveRefinementEndpoint(reporter, context.activityId);
+  const headers = await resolveHeaders(reporter, true);
+  if (!isActive()) {
+    throw new ActivityReportingCancelledError();
+  }
+  const response = await resolveFetch(refinement.fetch ?? reporter.fetch)(endpoint, {
+    method: "PUT",
+    headers,
     body: JSON.stringify(payload)
   });
-  if (!response.ok) {
-    throw new Error(`Activity reporting failed: HTTP ${response.status}`);
+  const data = await parseActivityResponse(response, "refine");
+  if (!data) {
+    throw new ActivityReportingError("Activity refine failed: empty response", response.status);
+  }
+  const mappedCampaign = refinement.mapResponseToCampaign ? await refinement.mapResponseToCampaign(data, match, context) : reporter.mapResponseToCampaign ? await reporter.mapResponseToCampaign(data, match) : defaultCampaignMapper(data, match);
+  const activityId = responseActivityId(data, mappedCampaign);
+  if (activityId !== context.activityId) {
+    throw new ActivityReportingError(
+      "Activity refine failed: response activity_id does not match the requested activity",
+      response.status
+    );
   }
-  const responseText = await response.text();
-  if (responseText.trim().length === 0) {
-    return null;
+  const campaign = mappedCampaign ? { ...mappedCampaign, activityId: context.activityId } : null;
+  return { activityId, campaign };
+}
+
+// src/activity-refinement.ts
+var ACTIVITY_REFINEMENT_WINDOW_MS = 3e4;
+var DEFAULT_MAX_REFINEMENT_ATTEMPTS = 2;
+var MAX_REFINEMENT_ATTEMPTS = 10;
+function normalizeError(error) {
+  return error instanceof Error ? error : new Error(String(error));
+}
+function statusAndDetail(error) {
+  return error instanceof ActivityReportingError ? { status: error.status, detail: error.detail } : { status: null, detail: null };
+}
+function defaultShouldRetry(context) {
+  return context.status === null || context.status >= 500 && context.status <= 599;
+}
+function isStableTerminalStatus(status) {
+  return status === 404 || status === 409 || status === 410;
+}
+var ActivityRefinementCoordinator = class {
+  reporter;
+  callbacks;
+  lifecycles = /* @__PURE__ */ new Map();
+  requestLifecycles = /* @__PURE__ */ new Map();
+  pendingMarkers = /* @__PURE__ */ new Map();
+  registeredRequests = /* @__PURE__ */ new Set();
+  settledRequests = /* @__PURE__ */ new Set();
+  activeLifecycle = null;
+  generation = 0;
+  constructor(reporter, callbacks) {
+    this.reporter = reporter;
+    this.callbacks = callbacks;
+  }
+  registerRequest(requestId) {
+    if (this.reporter.refinement) {
+      this.registeredRequests.add(requestId);
+    }
   }
-  let data;
-  try {
-    data = JSON.parse(responseText);
-  } catch {
-    throw new Error("Activity reporting failed: invalid JSON response");
+  report(recognitionId, match, captureGeneration, requestId = null) {
+    const coordinatorGeneration = this.generation;
+    if (this.activeLifecycle && this.activeLifecycle.recognitionId !== recognitionId) {
+      this.deleteLifecycle(this.activeLifecycle);
+    }
+    const hasMarker = typeof match.audioMarker?.code === "string" && match.audioMarker.code.length > 0;
+    const refinement = this.reporter.refinement;
+    const requestCanRefine = requestId !== null && !this.settledRequests.has(requestId);
+    const pendingMarker = requestId === null ? void 0 : this.pendingMarkers.get(requestId);
+    if (requestId !== null) {
+      this.pendingMarkers.delete(requestId);
+      this.registeredRequests.delete(requestId);
+      this.settledRequests.delete(requestId);
+    }
+    const refinementExpected = Boolean(refinement && !hasMarker && requestCanRefine);
+    let lifecycle = null;
+    if (refinementExpected && refinement) {
+      const now = refinement.now?.() ?? Date.now();
+      lifecycle = {
+        recognitionId,
+        captureGeneration,
+        match,
+        deadline: now + ACTIVITY_REFINEMENT_WINDOW_MS,
+        activityId: null,
+        markerMatch: null,
+        markerCode: null,
+        timer: null,
+        createSettled: false,
+        refinementStarted: false
+      };
+      const createdLifecycle = lifecycle;
+      lifecycle.timer = setTimeout(() => {
+        this.deleteLifecycle(createdLifecycle);
+      }, ACTIVITY_REFINEMENT_WINDOW_MS);
+      this.lifecycles.set(recognitionId, lifecycle);
+      if (requestId !== null) {
+        this.requestLifecycles.set(requestId, lifecycle);
+      }
+      this.activeLifecycle = lifecycle;
+      if (pendingMarker) {
+        this.refine(requestId ?? recognitionId, pendingMarker, captureGeneration);
+      }
+    }
+    void createMatchedMaterialActivity(
+      this.reporter,
+      match,
+      () => Boolean(lifecycle && this.isRefinementActive(lifecycle))
+    ).then(
+      (result) => {
+        if (coordinatorGeneration === this.generation && result.campaign && this.callbacks.isCurrentCapture(captureGeneration)) {
+          this.callbacks.emitCampaign(result.campaign);
+        }
+        if (coordinatorGeneration !== this.generation || !lifecycle || this.lifecycles.get(recognitionId) !== lifecycle) {
+          return;
+        }
+        if (!result.refinementExpected) {
+          this.deleteLifecycle(lifecycle);
+          return;
+        }
+        lifecycle.createSettled = true;
+        lifecycle.activityId = result.activityId;
+        if (lifecycle.markerMatch) {
+          if (lifecycle.activityId) {
+            this.startRefinement(lifecycle);
+          } else {
+            this.failMissingActivityId(lifecycle);
+          }
+        }
+      },
+      (error) => {
+        if (lifecycle) {
+          this.deleteLifecycle(lifecycle);
+        }
+        if (coordinatorGeneration === this.generation && this.callbacks.isCurrentCapture(captureGeneration)) {
+          this.callbacks.emitError("activity", error);
+        }
+      }
+    );
   }
-  if (!isRecord2(data)) {
-    throw new Error("Activity reporting failed: expected an object response");
+  associate(requestId, match, captureGeneration) {
+    const lifecycle = this.activeLifecycle;
+    this.registeredRequests.delete(requestId);
+    if (!lifecycle || !match || lifecycle.captureGeneration !== captureGeneration || lifecycle.match.name !== match.name || lifecycle.match.afpType !== match.afpType || !this.isActive(lifecycle)) {
+      return false;
+    }
+    this.requestLifecycles.set(requestId, lifecycle);
+    const pendingMarker = this.pendingMarkers.get(requestId);
+    if (pendingMarker) {
+      this.pendingMarkers.delete(requestId);
+      this.refine(requestId, pendingMarker, captureGeneration);
+    }
+    return true;
   }
-  if (reporter.mapResponseToCampaign) {
-    return reporter.mapResponseToCampaign(data, match);
+  discardRequest(requestId) {
+    this.registeredRequests.delete(requestId);
+    this.pendingMarkers.delete(requestId);
+    this.requestLifecycles.delete(requestId);
+    this.settledRequests.delete(requestId);
+  }
+  settleRequest(requestId) {
+    const awaitingAssociation = this.registeredRequests.delete(requestId);
+    this.pendingMarkers.delete(requestId);
+    const lifecycle = this.requestLifecycles.get(requestId);
+    if (lifecycle) {
+      this.deleteLifecycle(lifecycle);
+      return;
+    }
+    if (awaitingAssociation) {
+      this.settledRequests.add(requestId);
+    }
   }
-  return defaultCampaignMapper(data, match);
-}
+  clearActive(captureGeneration) {
+    if (this.activeLifecycle?.captureGeneration === captureGeneration) {
+      this.deleteLifecycle(this.activeLifecycle);
+    }
+  }
+  refine(recognitionId, marker, captureGeneration) {
+    if (!this.reporter.refinement) {
+      return;
+    }
+    const lifecycle = this.requestLifecycles.get(recognitionId);
+    const markerCode = marker.code;
+    if (typeof markerCode !== "string" || markerCode.length === 0) {
+      this.settleRequest(recognitionId);
+      return;
+    }
+    if (!lifecycle || lifecycle.captureGeneration !== captureGeneration || lifecycle.markerCode !== null || !this.callbacks.isCurrentCapture(captureGeneration)) {
+      if (!lifecycle && this.registeredRequests.has(recognitionId) && typeof markerCode === "string" && markerCode.length > 0 && this.callbacks.isCurrentCapture(captureGeneration)) {
+        this.pendingMarkers.set(recognitionId, marker);
+      }
+      return;
+    }
+    const now = this.reporter.refinement?.now?.() ?? Date.now();
+    if (now > lifecycle.deadline) {
+      this.deleteLifecycle(lifecycle);
+      return;
+    }
+    lifecycle.markerCode = markerCode;
+    lifecycle.markerMatch = { ...lifecycle.match, audioMarker: marker };
+    if (lifecycle.activityId) {
+      this.startRefinement(lifecycle);
+    } else if (lifecycle.createSettled) {
+      this.failMissingActivityId(lifecycle);
+    }
+  }
+  reset() {
+    this.generation += 1;
+    for (const lifecycle of this.lifecycles.values()) {
+      if (lifecycle.timer) {
+        clearTimeout(lifecycle.timer);
+      }
+    }
+    this.lifecycles.clear();
+    this.requestLifecycles.clear();
+    this.pendingMarkers.clear();
+    this.registeredRequests.clear();
+    this.settledRequests.clear();
+    this.activeLifecycle = null;
+  }
+  startRefinement(lifecycle) {
+    if (lifecycle.refinementStarted || !lifecycle.activityId || !lifecycle.markerMatch) {
+      return;
+    }
+    lifecycle.refinementStarted = true;
+    void this.runRefinement(lifecycle);
+  }
+  failMissingActivityId(lifecycle) {
+    if (!this.isRefinementActive(lifecycle)) {
+      return;
+    }
+    this.deleteLifecycle(lifecycle);
+    this.callbacks.emitError(
+      "activity-refinement",
+      new Error("Activity refinement requires a non-empty activity_id from the create response")
+    );
+  }
+  async runRefinement(lifecycle) {
+    const refinement = this.reporter.refinement;
+    if (!refinement || !lifecycle.activityId || !lifecycle.markerMatch) {
+      this.deleteLifecycle(lifecycle);
+      return;
+    }
+    const maxAttempts = Math.min(
+      MAX_REFINEMENT_ATTEMPTS,
+      Math.max(
+        1,
+        Number.isSafeInteger(refinement.maxAttempts) ? refinement.maxAttempts ?? DEFAULT_MAX_REFINEMENT_ATTEMPTS : DEFAULT_MAX_REFINEMENT_ATTEMPTS
+      )
+    );
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+      if (!this.isActive(lifecycle)) {
+        return;
+      }
+      const now = refinement.now?.() ?? Date.now();
+      if (now > lifecycle.deadline) {
+        this.deleteLifecycle(lifecycle);
+        return;
+      }
+      try {
+        const result = await refineMatchedMaterialActivity(
+          this.reporter,
+          lifecycle.markerMatch,
+          {
+            operation: "refine",
+            activityId: lifecycle.activityId,
+            attempt,
+            deadline: lifecycle.deadline
+          },
+          () => this.isRefinementActive(lifecycle)
+        );
+        if (!this.isRefinementActive(lifecycle)) {
+          return;
+        }
+        this.deleteLifecycle(lifecycle);
+        if (result.campaign) {
+          this.callbacks.emitCampaign(result.campaign);
+        }
+        return;
+      } catch (caught) {
+        if (caught instanceof ActivityReportingCancelledError) {
+          return;
+        }
+        if (!this.isRefinementActive(lifecycle)) {
+          return;
+        }
+        const error = normalizeError(caught);
+        const { status, detail } = statusAndDetail(error);
+        const failureContext = {
+          operation: "refine",
+          activityId: lifecycle.activityId,
+          attempt,
+          deadline: lifecycle.deadline,
+          error,
+          status,
+          detail
+        };
+        let retry = false;
+        try {
+          retry = !isStableTerminalStatus(status) && attempt < maxAttempts && (refinement.now?.() ?? Date.now()) <= lifecycle.deadline && (refinement.shouldRetry ? await refinement.shouldRetry(failureContext) : defaultShouldRetry(failureContext));
+        } catch (policyError) {
+          if (!this.isRefinementActive(lifecycle)) {
+            return;
+          }
+          this.deleteLifecycle(lifecycle);
+          this.callbacks.emitError("activity-refinement", policyError);
+          return;
+        }
+        if (!this.isRefinementActive(lifecycle)) {
+          return;
+        }
+        if (retry) {
+          continue;
+        }
+        this.deleteLifecycle(lifecycle);
+        this.callbacks.emitError("activity-refinement", error);
+        return;
+      }
+    }
+  }
+  isActive(lifecycle) {
+    return this.lifecycles.get(lifecycle.recognitionId) === lifecycle && this.callbacks.isCurrentCapture(lifecycle.captureGeneration);
+  }
+  isRefinementActive(lifecycle) {
+    if (!this.isActive(lifecycle)) {
+      return false;
+    }
+    const refinement = this.reporter.refinement;
+    const now = refinement && refinement.now ? refinement.now() : Date.now();
+    if (now > lifecycle.deadline) {
+      this.deleteLifecycle(lifecycle);
+      return false;
+    }
+    return true;
+  }
+  deleteLifecycle(lifecycle) {
+    if (lifecycle.timer) {
+      clearTimeout(lifecycle.timer);
+      lifecycle.timer = null;
+    }
+    if (this.lifecycles.get(lifecycle.recognitionId) === lifecycle) {
+      this.lifecycles.delete(lifecycle.recognitionId);
+    }
+    for (const [requestId, requestLifecycle] of this.requestLifecycles) {
+      if (requestLifecycle === lifecycle) {
+        this.requestLifecycles.delete(requestId);
+        this.pendingMarkers.delete(requestId);
+        this.registeredRequests.delete(requestId);
+      }
+    }
+    if (this.activeLifecycle === lifecycle) {
+      this.activeLifecycle = null;
+    }
+  }
+};
 
 // src/microphone.ts
 var WORKLET_PROCESSOR_NAME = "sori-microphone-capture";
@@ -517,11 +982,11 @@ var defaultAudioGraphFactory = async (options) => {
 };
 
 // src/microphone-matcher.ts
-function normalizeError(error) {
+function normalizeError2(error) {
   return error instanceof Error ? error : new Error(String(error));
 }
 function emitError(emitter, phase, error) {
-  const normalized = normalizeError(error);
+  const normalized = normalizeError2(error);
   emitter.emit("error", { phase, error: normalized });
   return normalized;
 }
@@ -539,6 +1004,7 @@ var MicrophoneMatcher = class {
   captureSampleRate;
   audioGraphFactory;
   packSource;
+  activityRefinement;
   options;
   extractor = null;
   graphController = null;
@@ -557,6 +1023,7 @@ var MicrophoneMatcher = class {
   latestAudioMarker = null;
   latestAudioMarkerDetection = null;
   audioMarkerRequestId = 0;
+  activityRecognitionId = 0;
   hopSize = 0;
   diagnostics = {
     sampleCallbacks: 0,
@@ -578,6 +1045,11 @@ var MicrophoneMatcher = class {
     this.suspendContextOnStop = options.suspendContextOnStop ?? true;
     this.audioGraphFactory = defaultAudioGraphFactory;
     this.packSource = options.packSource;
+    this.activityRefinement = options.activityReporter ? new ActivityRefinementCoordinator(options.activityReporter, {
+      isCurrentCapture: (captureGeneration) => captureGeneration === this.captureGeneration && this.running,
+      emitCampaign: (campaign) => this.events.emit("campaign", campaign),
+      emitError: (phase, error) => emitError(this.events, phase, error)
+    }) : null;
   }
   on(eventName, listener) {
     this.events.on(eventName, listener);
@@ -661,6 +1133,7 @@ var MicrophoneMatcher = class {
     try {
       this.ensureNotDestroyed();
       await this.prepare();
+      this.activityRefinement?.reset();
       this.matchWindowOrThrow().reset();
       await this.matcherSession.clear();
     } catch (error) {
@@ -798,6 +1271,8 @@ var MicrophoneMatcher = class {
         this.diagnostics.readyQueries += 1;
         let matchedBest = null;
         let shouldEmitNoMatch = false;
+        let audioMarkerRequestId = null;
+        let associatedActivity = false;
         const handleMatch = (event) => {
           if (!event.best) {
             return;
@@ -814,8 +1289,23 @@ var MicrophoneMatcher = class {
         try {
           this.diagnostics.matchRequests += 1;
           const bestMatchPromise = this.matcherSession.bestMatch(query, this.matchConfig());
-          const audioMarkerRequestId = this.beginAudioMarkerDetection(captureGeneration);
-          await bestMatchPromise;
+          audioMarkerRequestId = this.beginAudioMarkerDetection(captureGeneration);
+          let observedBest;
+          try {
+            observedBest = await bestMatchPromise;
+          } catch (error) {
+            if (audioMarkerRequestId !== null) {
+              this.activityRefinement?.discardRequest(audioMarkerRequestId);
+            }
+            throw error;
+          }
+          if (audioMarkerRequestId !== null) {
+            associatedActivity = this.activityRefinement?.associate(
+              audioMarkerRequestId,
+              observedBest,
+              captureGeneration
+            ) ?? false;
+          }
           const distinctBest = this.withAudioMarkerForRequest(matchedBest, audioMarkerRequestId);
           matchedBest = distinctBest;
         } finally {
@@ -827,9 +1317,21 @@ var MicrophoneMatcher = class {
         }
         if (matchedBest) {
           this.events.emit("match", { best: matchedBest });
-          void this.reportCampaign(matchedBest, captureGeneration);
+          this.activityRecognitionId += 1;
+          this.reportCampaign(
+            this.activityRecognitionId,
+            matchedBest,
+            captureGeneration,
+            audioMarkerRequestId
+          );
         } else if (shouldEmitNoMatch) {
+          if (audioMarkerRequestId !== null && !associatedActivity) {
+            this.activityRefinement?.discardRequest(audioMarkerRequestId);
+          }
+          this.activityRefinement?.clearActive(captureGeneration);
           this.events.emit("nomatch", {});
+        } else if (audioMarkerRequestId !== null && !associatedActivity) {
+          this.activityRefinement?.discardRequest(audioMarkerRequestId);
         }
       } while (this.pendingMatch || this.matchWindowOrThrow().hasReadyQuery());
     } catch (error) {
@@ -849,6 +1351,7 @@ var MicrophoneMatcher = class {
     this.latestAudioMarker = null;
     this.latestAudioMarkerDetection = null;
     this.audioMarkerRequestId += 1;
+    this.activityRefinement?.reset();
     this.matchWindowOrThrow().reset();
     await this.extractor?.reset();
   }
@@ -866,6 +1369,7 @@ var MicrophoneMatcher = class {
     }
     const requestId = this.audioMarkerRequestId + 1;
     this.audioMarkerRequestId = requestId;
+    this.activityRefinement?.registerRequest(requestId);
     const markerPcm = float32ToPcm16Le(this.markerPcmBuffer);
     void this.detectAudioMarkerForRequest(captureGeneration, requestId, markerPcm);
     return requestId;
@@ -881,8 +1385,10 @@ var MicrophoneMatcher = class {
       }
       this.latestAudioMarkerDetection = { requestId, detection };
       this.emitAudioMarkerIfChanged(detection);
+      this.activityRefinement?.refine(requestId, detection, captureGeneration);
       return detection;
     } catch (error) {
+      this.activityRefinement?.settleRequest(requestId);
       emitError(this.events, "audiomarker", error);
       return null;
     }
@@ -975,19 +1481,17 @@ var MicrophoneMatcher = class {
     }
     return this.matchWindow;
   }
-  async reportCampaign(match, captureGeneration) {
+  reportCampaign(recognitionId, match, captureGeneration, audioMarkerRequestId) {
     const reporter = this.options.activityReporter;
     if (!reporter) {
       return;
     }
-    try {
-      const campaign = await reportMatchedMaterialActivity(reporter, match);
-      if (campaign && captureGeneration === this.captureGeneration && this.running) {
-        this.events.emit("campaign", campaign);
-      }
-    } catch (error) {
-      emitError(this.events, "activity", error);
-    }
+    this.activityRefinement?.report(
+      recognitionId,
+      match,
+      captureGeneration,
+      audioMarkerRequestId
+    );
   }
 };
 function appendFloat32(left, right) {
@@ -1025,11 +1529,31 @@ function resolveStorage2(storage) {
   }
   return globalThis.localStorage;
 }
+function formatUuidV4(bytes) {
+  bytes[6] = bytes[6] & 15 | 64;
+  bytes[8] = bytes[8] & 63 | 128;
+  const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+  return [
+    hex.slice(0, 8),
+    hex.slice(8, 12),
+    hex.slice(12, 16),
+    hex.slice(16, 20),
+    hex.slice(20)
+  ].join("-");
+}
 function defaultGenerateSessionId() {
-  if (typeof globalThis.crypto !== "undefined" && typeof globalThis.crypto.randomUUID === "function") {
-    return globalThis.crypto.randomUUID();
+  const crypto = globalThis.crypto;
+  if (typeof crypto !== "undefined") {
+    if (typeof crypto.randomUUID === "function") {
+      return crypto.randomUUID();
+    }
+    if (typeof crypto.getRandomValues === "function") {
+      return formatUuidV4(crypto.getRandomValues(new Uint8Array(16)));
+    }
   }
-  return `session-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+  throw new Error(
+    "Secure random number generation is unavailable; provide a cryptographically secure `generateSessionId`"
+  );
 }
 function createLocalStorageSessionManager(options) {
   const storage = resolveStorage2(options.storage);
@@ -1122,7 +1646,8 @@ function resolveRecognizerOptions(options) {
   const activityReporter = activityEndpoint === void 0 ? void 0 : {
     ...customActivityReporter,
     endpoint: activityEndpoint,
-    fetch: customActivityReporter?.fetch ?? sharedFetch
+    fetch: customActivityReporter?.fetch ?? sharedFetch,
+    refinement: customActivityReporter ? customActivityReporter.refinement : {}
   };
   return {
     ...options,
@@ -1295,6 +1820,7 @@ var AudioRecognizer = class {
 // src/index.ts
 import { AudioFingerprintType as AudioFingerprintType3 } from "@sorisdk/matcher";
 export {
+  ACTIVITY_REFINEMENT_WINDOW_MS,
   AudioFingerprintType3 as AudioFingerprintType,
   AudioRecognizer,
   DEFAULT_BROWSER_AUDIOPACK_VERSION,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sorisdk/web-audio",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "description": "Web SDK for browser-based audio recognition with SORI API",
   "type": "module",
   "main": "./dist/index.js",
@@ -34,13 +34,13 @@
   "license": "SEE LICENSE IN LICENSE.md",
   "homepage": "https://docs.soriapi.com/ko/integration/web",
   "dependencies": {
-    "@sorisdk/matcher": "0.6.3",
-    "@sorisdk/afpgen": "0.6.3"
+    "@sorisdk/afpgen": "0.6.5",
+    "@sorisdk/matcher": "0.6.5"
   },
   "devDependencies": {
     "tsup": "^8.5.1",
     "typescript": "^5.8.3",
-    "vitest": "^3.2.4"
+    "vitest": "^3.2.6"
   },
   "scripts": {
     "build:wasm": "node ../../scripts/build-wasm-package.mjs web-audio",