@sorisdk/web-audio 0.6.4 → 0.6.7

package/dist/index.js

@@ -181,6 +181,18 @@ function getBrowserMediaDevices() {
 }
 
 // src/match-window.ts
+var FINGERPRINT_LEVEL_BYTE_LENGTH = 8;
+function getTypedArrayByteLengthGetter() {
+  const getter = Object.getOwnPropertyDescriptor(
+    Object.getPrototypeOf(Uint8Array.prototype),
+    "byteLength"
+  )?.get;
+  if (!getter) {
+    throw new Error("Uint8Array byteLength intrinsic is unavailable");
+  }
+  return getter;
+}
+var typedArrayByteLengthGetter = getTypedArrayByteLengthGetter();
 var cachedBindings = null;
 var initPromise = null;
 var testInjectedWasmModule = null;
@@ -197,18 +209,46 @@ var defaultLoader = async () => {
   const loaderModule = await import("./default-loader.js");
   return loaderModule.default();
 };
+function calculateMaxAppendFingerprintByteLength(options) {
+  const hopSize = options.afpgenConfig.hopSize ?? 1e3;
+  const levelCount = options.afpgenConfig.levelCount ?? 2;
+  const hopDurationMs = hopSize / options.sampleRate * 1e3;
+  const hopsInWindow = Math.ceil(options.matchWindowMs / hopDurationMs);
+  return Math.max(1, hopsInWindow) * levelCount * FINGERPRINT_LEVEL_BYTE_LENGTH;
+}
+function appendLimitError(byteLength, maxByteLength) {
+  return new RangeError(
+    `Fingerprint append byteLength ${byteLength} exceeds the per-instance limit of ${maxByteLength} bytes`
+  );
+}
+function intrinsicUint8ArrayByteLength(bytes) {
+  return typedArrayByteLengthGetter.call(bytes);
+}
 var WrappedFingerprintMatchWindow = class {
-  constructor(inner) {
+  constructor(inner, options) {
     this.inner = inner;
+    const maxLengthFn = getCallable(this.inner, [
+      "maxAppendFingerprintByteLength",
+      "max_append_fingerprint_byte_length"
+    ]);
+    this.maxAppendByteLength = maxLengthFn ? Number(maxLengthFn.call(this.inner)) : calculateMaxAppendFingerprintByteLength(options);
   }
   inner;
+  maxAppendByteLength;
   appendFingerprint(bytes) {
+    const byteLength = intrinsicUint8ArrayByteLength(bytes);
+    if (byteLength > this.maxAppendByteLength) {
+      throw appendLimitError(byteLength, this.maxAppendByteLength);
+    }
     const fn = getCallable(this.inner, ["appendFingerprint", "append_fingerprint"]);
     if (!fn) {
       throw new Error("web-audio wasm window is missing appendFingerprint");
     }
     fn.call(this.inner, bytes);
   }
+  maxAppendFingerprintByteLength() {
+    return this.maxAppendByteLength;
+  }
   hasReadyQuery() {
     const fn = getCallable(this.inner, ["hasReadyQuery", "has_ready_query"]);
     if (!fn) {
@@ -261,7 +301,8 @@ function createBindingsFromModule(moduleLike) {
           options.afpgenConfig,
           options.matchWindowMs,
           options.matchStrideMs
-        )
+        ),
+        options
       );
     }
   };
@@ -314,6 +355,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;
 }
@@ -333,11 +390,23 @@ 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 captureActivityRecognitionTiming(match) {
+  const recognizedAtMillis = Date.now();
+  const position = match.position;
+  return Object.freeze({
+    recognizedAt: new Date(recognizedAtMillis).toISOString(),
+    position
+  });
+}
+function validateRequestPayload(payload) {
   if (payload === null) {
     return null;
   }
@@ -346,6 +415,40 @@ 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 {
+    position: _ignoredPosition,
+    recognized_at: _ignoredRecognizedAt,
+    refinement_expected: _ignoredRefinementExpected,
+    ...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 {
+    position: _ignoredPosition,
+    recognized_at: _ignoredRecognizedAt,
+    refinement_expected: _ignoredRefinementExpected,
+    ...requestPayload
+  } = payload;
+  return requestPayload;
+}
 function defaultCampaignMapper(payload, match) {
   const campaign = payload.campaign;
   if (!isRecord2(campaign)) {
@@ -358,42 +461,608 @@ 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,
+      creationAttempted: true,
+      refinementExpected
+    };
+  }
+  const campaign = reporter.mapResponseToCampaign ? await reporter.mapResponseToCampaign(data, match) : defaultCampaignMapper(data, match);
+  return {
+    activityId: responseActivityId(data, campaign),
+    campaign,
+    creationAttempted: true,
+    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, recognitionTiming = captureActivityRecognitionTiming(match)) {
+  const payload = await resolveCreateRequestPayload(reporter, match);
+  if (!payload) {
+    return {
+      activityId: null,
+      campaign: null,
+      creationAttempted: false,
+      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 = {
+    ...payload,
+    recognized_at: recognitionTiming.recognizedAt,
+    position: recognitionTiming.position,
+    ...requestRefinementExpected ? { refinement_expected: true } : {}
+  };
   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 ACTIVITY_CONTINUITY_GAP_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;
+    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);
+    }
+    if (refinement && this.activeLifecycle) {
+      const now = this.now();
+      const activeLifecycle = this.activeLifecycle;
+      if (this.isContinuousMatch(activeLifecycle, match, captureGeneration, now)) {
+        this.renewContinuity(activeLifecycle, now);
+        if (requestId !== null) {
+          if (requestCanRefine && this.canAcceptMarker(activeLifecycle)) {
+            this.requestLifecycles.set(requestId, activeLifecycle);
+          } else {
+            this.requestLifecycles.delete(requestId);
+          }
+        }
+        if (pendingMarker) {
+          this.claimMarker(activeLifecycle, pendingMarker);
+        }
+        if (hasMarker && match.audioMarker) {
+          this.claimMarker(activeLifecycle, match.audioMarker);
+        }
+        return;
+      }
+      this.sealLifecycle(activeLifecycle);
+    }
+    const refinementExpected = Boolean(refinement && !hasMarker && requestCanRefine);
+    let lifecycle = null;
+    if (refinement) {
+      const now = this.now();
+      lifecycle = {
+        recognitionId,
+        captureGeneration,
+        match,
+        deadline: now + ACTIVITY_REFINEMENT_WINDOW_MS,
+        lastObservedAt: now,
+        activityId: null,
+        markerMatch: hasMarker ? match : null,
+        markerCode: hasMarker ? match.audioMarker?.code ?? null : null,
+        refinementTimer: null,
+        continuityTimer: null,
+        createSettled: false,
+        refinementStarted: false,
+        refinementInFlight: false,
+        refinementClosed: !refinementExpected,
+        sealed: false
+      };
+      const createdLifecycle = lifecycle;
+      if (refinementExpected) {
+        lifecycle.refinementTimer = setTimeout(() => {
+          this.closeRefinement(createdLifecycle);
+        }, ACTIVITY_REFINEMENT_WINDOW_MS);
+      }
+      this.scheduleContinuityExpiry(lifecycle);
+      this.lifecycles.set(recognitionId, lifecycle);
+      if (requestId !== null && refinementExpected) {
+        this.requestLifecycles.set(requestId, lifecycle);
+      }
+      this.activeLifecycle = lifecycle;
+      if (pendingMarker && refinementExpected) {
+        this.claimMarker(lifecycle, pendingMarker);
+      }
+    }
+    const recognitionTiming = captureActivityRecognitionTiming(match);
+    void createMatchedMaterialActivity(
+      this.reporter,
+      match,
+      () => Boolean(lifecycle && this.isRefinementActive(lifecycle)),
+      recognitionTiming
+    ).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;
+        }
+        lifecycle.createSettled = true;
+        lifecycle.activityId = result.activityId;
+        if (!result.creationAttempted) {
+          this.deleteLifecycle(lifecycle);
+          return;
+        }
+        if (!result.refinementExpected) {
+          this.closeRefinement(lifecycle);
+          this.maybeDeleteSealed(lifecycle);
+          return;
+        }
+        if (lifecycle.markerMatch) {
+          if (lifecycle.activityId) {
+            this.startRefinement(lifecycle);
+          } else {
+            this.failMissingActivityId(lifecycle);
+          }
+        }
+        this.maybeDeleteSealed(lifecycle);
+      },
+      (error) => {
+        if (lifecycle) {
+          lifecycle.createSettled = true;
+          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) {
+      return false;
+    }
+    const now = this.now();
+    if (!this.isContinuousMatch(lifecycle, match, captureGeneration, now)) {
+      this.sealLifecycle(lifecycle);
+      return false;
+    }
+    this.renewContinuity(lifecycle, now);
+    const pendingMarker = this.pendingMarkers.get(requestId);
+    if (this.canAcceptMarker(lifecycle)) {
+      this.requestLifecycles.set(requestId, lifecycle);
+    } else {
+      this.requestLifecycles.delete(requestId);
+    }
+    if (pendingMarker && this.canAcceptMarker(lifecycle)) {
+      this.pendingMarkers.delete(requestId);
+      this.claimMarker(lifecycle, pendingMarker);
+    } else if (pendingMarker) {
+      this.pendingMarkers.delete(requestId);
+    }
+    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);
+    this.requestLifecycles.delete(requestId);
+    if (awaitingAssociation) {
+      this.settledRequests.add(requestId);
+    }
   }
-  return defaultCampaignMapper(data, match);
-}
+  clearActive(captureGeneration) {
+    if (this.activeLifecycle?.captureGeneration === captureGeneration) {
+      this.sealLifecycle(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;
+    }
+    if (!this.canAcceptMarker(lifecycle)) {
+      return;
+    }
+    this.claimMarker(lifecycle, marker);
+  }
+  reset() {
+    this.generation += 1;
+    for (const lifecycle of this.lifecycles.values()) {
+      if (lifecycle.refinementTimer) {
+        clearTimeout(lifecycle.refinementTimer);
+      }
+      if (lifecycle.continuityTimer) {
+        clearTimeout(lifecycle.continuityTimer);
+      }
+    }
+    this.lifecycles.clear();
+    this.requestLifecycles.clear();
+    this.pendingMarkers.clear();
+    this.registeredRequests.clear();
+    this.settledRequests.clear();
+    this.activeLifecycle = null;
+  }
+  startRefinement(lifecycle) {
+    if (lifecycle.refinementStarted || lifecycle.refinementClosed || !lifecycle.activityId || !lifecycle.markerMatch) {
+      return;
+    }
+    lifecycle.refinementStarted = true;
+    lifecycle.refinementInFlight = true;
+    void this.runRefinement(lifecycle).finally(() => {
+      lifecycle.refinementInFlight = false;
+      this.maybeDeleteSealed(lifecycle);
+    });
+  }
+  failMissingActivityId(lifecycle) {
+    if (!this.isRefinementActive(lifecycle)) {
+      return;
+    }
+    this.closeRefinement(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.closeRefinement(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.isRefinementActive(lifecycle)) {
+        return;
+      }
+      const now = this.now();
+      if (now > lifecycle.deadline) {
+        this.closeRefinement(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.closeRefinement(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.closeRefinement(lifecycle);
+          this.callbacks.emitError("activity-refinement", policyError);
+          return;
+        }
+        if (!this.isRefinementActive(lifecycle)) {
+          return;
+        }
+        if (retry) {
+          continue;
+        }
+        this.closeRefinement(lifecycle);
+        this.callbacks.emitError("activity-refinement", error);
+        return;
+      }
+    }
+  }
+  isTransportActive(lifecycle) {
+    return this.lifecycles.get(lifecycle.recognitionId) === lifecycle && this.callbacks.isCurrentCapture(lifecycle.captureGeneration);
+  }
+  isRefinementActive(lifecycle) {
+    if (!this.isTransportActive(lifecycle) || lifecycle.refinementClosed) {
+      return false;
+    }
+    const now = this.now();
+    if (now > lifecycle.deadline) {
+      this.closeRefinement(lifecycle);
+      return false;
+    }
+    return true;
+  }
+  canAcceptMarker(lifecycle) {
+    return lifecycle.markerCode === null && this.isRefinementActive(lifecycle);
+  }
+  claimMarker(lifecycle, marker) {
+    const markerCode = marker.code;
+    if (typeof markerCode !== "string" || markerCode.length === 0 || !this.canAcceptMarker(lifecycle)) {
+      return;
+    }
+    lifecycle.markerCode = markerCode;
+    lifecycle.markerMatch = { ...lifecycle.match, audioMarker: marker };
+    if (lifecycle.activityId) {
+      this.startRefinement(lifecycle);
+    } else if (lifecycle.createSettled) {
+      this.failMissingActivityId(lifecycle);
+    }
+  }
+  isContinuousMatch(lifecycle, match, captureGeneration, now) {
+    return !lifecycle.sealed && this.activeLifecycle === lifecycle && lifecycle.captureGeneration === captureGeneration && lifecycle.match.name === match.name && lifecycle.match.afpType === match.afpType && this.isTransportActive(lifecycle) && now - lifecycle.lastObservedAt <= ACTIVITY_CONTINUITY_GAP_MS;
+  }
+  renewContinuity(lifecycle, now) {
+    lifecycle.lastObservedAt = now;
+    this.scheduleContinuityExpiry(lifecycle);
+  }
+  scheduleContinuityExpiry(lifecycle) {
+    if (lifecycle.continuityTimer) {
+      clearTimeout(lifecycle.continuityTimer);
+    }
+    const remainingMs = lifecycle.lastObservedAt + ACTIVITY_CONTINUITY_GAP_MS - this.now();
+    lifecycle.continuityTimer = setTimeout(() => {
+      lifecycle.continuityTimer = null;
+      if (this.activeLifecycle !== lifecycle || lifecycle.sealed) {
+        return;
+      }
+      const now = this.now();
+      if (now - lifecycle.lastObservedAt <= ACTIVITY_CONTINUITY_GAP_MS) {
+        this.scheduleContinuityExpiry(lifecycle);
+        return;
+      }
+      this.sealLifecycle(lifecycle);
+    }, Math.max(1, remainingMs + 1));
+  }
+  sealLifecycle(lifecycle) {
+    if (lifecycle.sealed) {
+      return;
+    }
+    lifecycle.sealed = true;
+    if (lifecycle.continuityTimer) {
+      clearTimeout(lifecycle.continuityTimer);
+      lifecycle.continuityTimer = null;
+    }
+    if (this.activeLifecycle === lifecycle) {
+      this.activeLifecycle = null;
+    }
+    this.removeRequestAssociations(lifecycle);
+    this.maybeDeleteSealed(lifecycle);
+  }
+  closeRefinement(lifecycle) {
+    if (lifecycle.refinementClosed) {
+      return;
+    }
+    lifecycle.refinementClosed = true;
+    if (lifecycle.refinementTimer) {
+      clearTimeout(lifecycle.refinementTimer);
+      lifecycle.refinementTimer = null;
+    }
+    this.removeRequestAssociations(lifecycle);
+    this.maybeDeleteSealed(lifecycle);
+  }
+  removeRequestAssociations(lifecycle) {
+    for (const [requestId, requestLifecycle] of this.requestLifecycles) {
+      if (requestLifecycle === lifecycle) {
+        this.requestLifecycles.delete(requestId);
+        this.pendingMarkers.delete(requestId);
+        this.registeredRequests.delete(requestId);
+      }
+    }
+  }
+  maybeDeleteSealed(lifecycle) {
+    if (lifecycle.sealed && lifecycle.createSettled && !lifecycle.refinementInFlight) {
+      this.deleteLifecycle(lifecycle);
+    }
+  }
+  now() {
+    return this.reporter.refinement && this.reporter.refinement.now ? this.reporter.refinement.now() : Date.now();
+  }
+  deleteLifecycle(lifecycle) {
+    if (lifecycle.refinementTimer) {
+      clearTimeout(lifecycle.refinementTimer);
+      lifecycle.refinementTimer = null;
+    }
+    if (lifecycle.continuityTimer) {
+      clearTimeout(lifecycle.continuityTimer);
+      lifecycle.continuityTimer = null;
+    }
+    if (this.lifecycles.get(lifecycle.recognitionId) === lifecycle) {
+      this.lifecycles.delete(lifecycle.recognitionId);
+    }
+    this.removeRequestAssociations(lifecycle);
+    if (this.activeLifecycle === lifecycle) {
+      this.activeLifecycle = null;
+    }
+  }
+};
 
 // src/microphone.ts
 var WORKLET_PROCESSOR_NAME = "sori-microphone-capture";
@@ -518,11 +1187,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;
 }
@@ -540,6 +1209,7 @@ var MicrophoneMatcher = class {
   captureSampleRate;
   audioGraphFactory;
   packSource;
+  activityRefinement;
   options;
   extractor = null;
   graphController = null;
@@ -558,6 +1228,7 @@ var MicrophoneMatcher = class {
   latestAudioMarker = null;
   latestAudioMarkerDetection = null;
   audioMarkerRequestId = 0;
+  activityRecognitionId = 0;
   hopSize = 0;
   diagnostics = {
     sampleCallbacks: 0,
@@ -579,6 +1250,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);
@@ -662,6 +1338,7 @@ var MicrophoneMatcher = class {
     try {
       this.ensureNotDestroyed();
       await this.prepare();
+      this.activityRefinement?.reset();
       this.matchWindowOrThrow().reset();
       await this.matcherSession.clear();
     } catch (error) {
@@ -799,6 +1476,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;
@@ -815,8 +1494,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 {
@@ -828,9 +1522,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) {
@@ -850,6 +1556,7 @@ var MicrophoneMatcher = class {
     this.latestAudioMarker = null;
     this.latestAudioMarkerDetection = null;
     this.audioMarkerRequestId += 1;
+    this.activityRefinement?.reset();
     this.matchWindowOrThrow().reset();
     await this.extractor?.reset();
   }
@@ -867,6 +1574,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;
@@ -882,8 +1590,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;
     }
@@ -976,19 +1686,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) {
@@ -1073,6 +1781,8 @@ function createLocalStorageSessionManager(options) {
 
 // src/audio-recognizer.ts
 var DEFAULT_SORI_API_ENDPOINT = "https://console.soriapi.com/api";
+var MAX_API_ENDPOINT_LENGTH = 32 * 1024;
+var ASCII_SLASH_CODE_UNIT = 47;
 var FORWARDED_EVENTS = [
   "ready",
   "microphoneready",
@@ -1100,12 +1810,24 @@ function ensureNonEmptyString(name, value) {
   }
   return value;
 }
-function normalizeEndpointPrefix(endpoint) {
-  const value = String(endpoint).replace(/\/+$/, "");
+function stringifyAndValidateApiEndpoint(endpoint) {
+  const value = String(endpoint);
+  if (value.length > MAX_API_ENDPOINT_LENGTH) {
+    throw new Error(
+      `AudioRecognizer apiEndpoint exceeds maximum length of ${MAX_API_ENDPOINT_LENGTH} UTF-16 code units`
+    );
+  }
   return value;
 }
+function normalizeValidatedEndpointPrefix(value) {
+  let end = value.length;
+  while (end > 0 && value.charCodeAt(end - 1) === ASCII_SLASH_CODE_UNIT) {
+    end -= 1;
+  }
+  return end === value.length ? value : value.slice(0, end);
+}
 function joinEndpoint(prefix, path) {
-  return `${normalizeEndpointPrefix(prefix)}${path.startsWith("/") ? path : `/${path}`}`;
+  return `${prefix}${path.startsWith("/") ? path : `/${path}`}`;
 }
 function createEphemeralKeyResolver(endpoint, fetcher, requestInit) {
   return async () => {
@@ -1133,8 +1855,15 @@ function resolveRecognizerOptions(options) {
   const activityReportingDisabled = options.activityReporter === false;
   const customActivityReporter = activityReportingDisabled ? void 0 : options.activityReporter;
   const appId = legacyAuth?.appId ?? options.appId;
-  const authEndpoint = legacyAuth?.endpoint ?? options.authEndpoint ?? joinEndpoint(apiEndpoint, "/auth");
-  const activityEndpoint = activityReportingDisabled ? void 0 : customActivityReporter?.endpoint ?? options.activityEndpoint ?? joinEndpoint(apiEndpoint, "/activity/");
+  const configuredAuthEndpoint = legacyAuth?.endpoint ?? options.authEndpoint;
+  const configuredActivityEndpoint = activityReportingDisabled ? void 0 : customActivityReporter?.endpoint ?? options.activityEndpoint;
+  const derivesAuthEndpoint = configuredAuthEndpoint == null;
+  const derivesActivityEndpoint = !activityReportingDisabled && configuredActivityEndpoint == null;
+  const derivesApiEndpoint = derivesAuthEndpoint || derivesActivityEndpoint;
+  const validatedApiEndpoint = options.apiEndpoint !== void 0 || derivesApiEndpoint ? stringifyAndValidateApiEndpoint(apiEndpoint) : void 0;
+  const normalizedApiEndpoint = derivesApiEndpoint ? normalizeValidatedEndpointPrefix(validatedApiEndpoint) : void 0;
+  const authEndpoint = configuredAuthEndpoint ?? joinEndpoint(normalizedApiEndpoint, "/auth");
+  const activityEndpoint = activityReportingDisabled ? void 0 : configuredActivityEndpoint ?? joinEndpoint(normalizedApiEndpoint, "/activity/");
   const ephemeralKey = legacyAuth?.ephemeralKey ?? options.ephemeralKey ?? options.ephemeraKey ?? (legacyAuth?.ephemeralKeyEndpoint ?? options.ephemeralKeyEndpoint ? createEphemeralKeyResolver(
     legacyAuth?.ephemeralKeyEndpoint ?? options.ephemeralKeyEndpoint,
     legacyAuth?.ephemeralKeyFetch ?? options.ephemeralKeyFetch ?? legacyAuth?.fetch ?? sharedFetch,
@@ -1143,7 +1872,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,
@@ -1316,10 +2046,12 @@ 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,
   DEFAULT_SORI_API_ENDPOINT,
+  MAX_API_ENDPOINT_LENGTH,
   MicrophoneMatcher,
   authenticateAndLoadAudioPack,
   createLocalStorageAudioPackStore,