@mediaviz/sdk 1.8.0-dev.92 → 1.8.0-dev.95

package/dist/sdk.umd.js

@@ -465,6 +465,448 @@
 		return types;
 	}
 
+	var src$1;
+	var hasRequiredSrc$1;
+
+	function requireSrc$1 () {
+		if (hasRequiredSrc$1) return src$1;
+		hasRequiredSrc$1 = 1;
+
+		const { OAuthClient } = requireClient();
+		const { OAuthError } = requireErrors();
+		const { OAuthErrorCode } = requireTypes();
+
+		src$1 = { OAuthClient, OAuthError, OAuthErrorCode };
+		return src$1;
+	}
+
+	var srcExports$1 = requireSrc$1();
+	var _oauth = /*@__PURE__*/getDefaultExportFromCjs(srcExports$1);
+
+	// Auto-generated — do not edit
+	const { OAuthClient, OAuthError, OAuthErrorCode } = _oauth;
+
+	var signing;
+	var hasRequiredSigning;
+
+	function requireSigning () {
+		if (hasRequiredSigning) return signing;
+		hasRequiredSigning = 1;
+
+		// HMAC scheme shared with the MediaViz producer: X-Signature = 'sha256=' +
+		// hex(HMAC-SHA256(secret, `${X-Timestamp}.` + rawBody)). The signing string is
+		// the timestamp joined to the *raw request body bytes* — never re-serialized
+		// JSON. Verification accepts the current and (during rotation) previous
+		// secret, rejects timestamps outside the skew window, and compares digests in
+		// constant time. Web Crypto only, so the same code runs in Node >= 18 and
+		// browsers.
+
+		const _encoder = new TextEncoder();
+
+		async function signWebhookPayload(secret, timestamp, rawBody) {
+		  const key = await globalThis.crypto.subtle.importKey(
+		    'raw', _encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+		  const payload = _concat(_encoder.encode(`${timestamp}.`), toBytes(rawBody));
+		  const digest = await globalThis.crypto.subtle.sign('HMAC', key, payload);
+		  return 'sha256=' + _hex(new Uint8Array(digest));
+		}
+
+		async function verifyWebhookSignature(secretCurrent, secretPrevious, headers, rawBody, options = {}) {
+		  const h = lowerHeaders(headers);
+		  const timestamp = h['x-timestamp'];
+		  const signature = h['x-signature'];
+		  if (!timestamp || !signature) return false;
+		  if (!/^-?\d+$/.test(String(timestamp))) return false;
+		  const skewToleranceS = options.skewToleranceS ?? 300;
+		  const now = options.now ?? Math.floor(Date.now() / 1000);
+		  if (Math.abs(now - Number(timestamp)) > skewToleranceS) return false;
+		  for (const secret of [secretCurrent, secretPrevious]) {
+		    if (!secret) continue;
+		    const expected = await signWebhookPayload(secret, String(timestamp), rawBody);
+		    if (_constantTimeEqual(expected, String(signature))) return true;
+		  }
+		  return false;
+		}
+
+		// helpers
+		function toBytes(rawBody) {
+		  if (typeof rawBody === 'string') return _encoder.encode(rawBody);
+		  if (rawBody instanceof Uint8Array) return rawBody;
+		  if (rawBody instanceof ArrayBuffer) return new Uint8Array(rawBody);
+		  throw new TypeError('rawBody must be a string, Uint8Array, or ArrayBuffer');
+		}
+
+		function lowerHeaders(headers) {
+		  const out = {};
+		  const entries = typeof headers?.entries === 'function' ? headers.entries() : Object.entries(headers ?? {});
+		  for (const [k, v] of entries) out[String(k).toLowerCase()] = v;
+		  return out;
+		}
+
+		function _concat(a, b) {
+		  const out = new Uint8Array(a.length + b.length);
+		  out.set(a, 0);
+		  out.set(b, a.length);
+		  return out;
+		}
+
+		function _hex(bytes) {
+		  return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+		}
+
+		function _constantTimeEqual(a, b) {
+		  if (a.length !== b.length) return false;
+		  let diff = 0;
+		  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+		  return diff === 0;
+		}
+
+		signing = { signWebhookPayload, verifyWebhookSignature, toBytes, lowerHeaders };
+		return signing;
+	}
+
+	var store;
+	var hasRequiredStore;
+
+	function requireStore () {
+		if (hasRequiredStore) return store;
+		hasRequiredStore = 1;
+
+		// Persistence seam for the webhook consumer: dedupe ledger, signing secrets,
+		// and pull cursors. The default in-memory store suits a single long-lived
+		// process (worker, dev server); multi-process consumers supply an object with
+		// the same shape backed by Redis or a database.
+
+		const MAX_SEEN_ENTRIES = 100000;
+
+		class InMemoryWebhookStore {
+		  constructor() {
+		    this._seen = new Map();     // eventId -> expiresAt (ms)
+		    this._secrets = new Map();  // subscriptionId -> {current, previous, previousExpiresAt}
+		    this._cursors = new Map();  // subscriptionId -> cursor
+		  }
+
+		  markSeen(eventId, ttlS) {
+		    const now = Date.now();
+		    const expiresAt = this._seen.get(eventId);
+		    if (expiresAt !== undefined && expiresAt > now) return false;
+		    this._seen.delete(eventId);
+		    this._seen.set(eventId, now + ttlS * 1000);
+		    this._prune(now);
+		    return true;
+		  }
+
+		  unmarkSeen(eventId) {
+		    this._seen.delete(eventId);
+		  }
+
+		  saveSecret(subscriptionId, secret) {
+		    this._secrets.set(subscriptionId, { current: secret, previous: null, previousExpiresAt: 0 });
+		  }
+
+		  rotateSecret(subscriptionId, newSecret, windowS) {
+		    const entry = this._secrets.get(subscriptionId);
+		    this._secrets.set(subscriptionId, {
+		      current: newSecret,
+		      previous: entry?.current ?? null,
+		      previousExpiresAt: Date.now() + windowS * 1000,
+		    });
+		  }
+
+		  getSecrets(subscriptionId) {
+		    const entry = this._secrets.get(subscriptionId);
+		    if (!entry) return [null, null];
+		    const previous = entry.previous && entry.previousExpiresAt > Date.now() ? entry.previous : null;
+		    return [entry.current, previous];
+		  }
+
+		  getCursor(subscriptionId) {
+		    return this._cursors.get(subscriptionId) ?? null;
+		  }
+
+		  setCursor(subscriptionId, cursor) {
+		    this._cursors.set(subscriptionId, cursor);
+		  }
+
+		  _prune(now) {
+		    if (this._seen.size <= MAX_SEEN_ENTRIES) return;
+		    for (const [id, expiresAt] of this._seen) {
+		      if (expiresAt <= now) this._seen.delete(id);
+		      if (this._seen.size <= MAX_SEEN_ENTRIES) return;
+		    }
+		    // still over the cap: evict oldest insertions
+		    for (const id of this._seen.keys()) {
+		      this._seen.delete(id);
+		      if (this._seen.size <= MAX_SEEN_ENTRIES) return;
+		    }
+		  }
+		}
+
+		store = { InMemoryWebhookStore };
+		return store;
+	}
+
+	var consumer;
+	var hasRequiredConsumer;
+
+	function requireConsumer () {
+		if (hasRequiredConsumer) return consumer;
+		hasRequiredConsumer = 1;
+
+		const { verifyWebhookSignature, toBytes, lowerHeaders } = requireSigning();
+		const { InMemoryWebhookStore } = requireStore();
+
+		// Photo columns each producer model writes — used to select a model's results
+		// out of a fetched PhotoDisplay. Mirrors the producer vocabulary; personhood is
+		// predicate-based and writes no columns.
+		const WEBHOOK_MODEL_COLUMNS = {
+		  blur: ['blur_value'],
+		  colors: ['main_color_palette', 'color_averages', 'hue_values', 'light_values', 'saturation_values'],
+		  face_recognition: ['number_of_faces', 'bounding_boxes_from_faces_model'],
+		  image_classification: ['labels_from_classifications_model', 'feature_extraction_output'],
+		  image_comparison: ['average_hash'],
+		  image_describe: ['topic'],
+		  ocr: ['ocr_output'],
+		  similarity: ['similar_photo_ids_high', 'similar_photo_ids_medium', 'similar_photo_ids_low'],
+		  evidence: ['evidence_score', 'aesthetic_score', 'face_score', 'content_score', 'similarity_set_ranking'],
+		  personhood: [],
+		};
+
+		const WEBHOOK_OUTCOME_MODELS = {
+		  curation: ['blur', 'colors', 'face_recognition', 'image_classification', 'image_comparison', 'similarity', 'evidence'],
+		  similarity: ['image_classification', 'image_comparison', 'similarity'],
+		  persons: ['face_recognition', 'personhood'],
+		};
+
+		// Client-side counterpart of the MediaViz webhook producer, giving photo-by-photo
+		// progress as a project upload is analyzed.
+		//
+		// Receiver half (no auth needed): classify inbound POSTs, echo the subscription
+		// verification challenge, verify signed `target.completed` deliveries (HMAC +
+		// timestamp skew), dedupe on event_id, and dispatch each new event to a single
+		// onEvent callback. `handleRequest` is framework-agnostic glue — adapt it to
+		// express/lambda/etc. in a few lines by feeding it the raw body and headers.
+		//
+		// API half (requires an authenticated client): subscription lifecycle
+		// orchestration — register/confirm/rotate store the signing secret the moment
+		// the producer issues it — plus history pulls that share the push dedupe
+		// ledger, and out-of-band result fetches (webhooks carry a pointer, never the
+		// result itself).
+		class WebhookConsumer {
+		  constructor(ctx, subscriptionApi, options = {}) {
+		    this._ctx = ctx;
+		    this._api = subscriptionApi;
+		    this.store = options.store ?? new InMemoryWebhookStore();
+		    this.skewToleranceS = options.skewToleranceS ?? 300;
+		    this.rotationWindowS = options.rotationWindowS ?? 86400;
+		    this.dedupeTtlS = options.dedupeTtlS ?? 604800;
+		    this.pageLimit = options.pageLimit ?? 100;
+		    this._onEvent = options.onEvent ?? null;
+		  }
+
+		  // ── receiver half ─────────────────────────────────────────────────────────
+
+		  onEvent(fn) {
+		    this._onEvent = fn;
+		    return fn;
+		  }
+
+		  useStore(store) {
+		    this.store = store;
+		  }
+
+		  classifyMessage(body) {
+		    const type = body?.event_type;
+		    if (type === 'subscription.verification') return 'verification';
+		    if (type === 'target.completed') return 'delivery';
+		    return 'unknown';
+		  }
+
+		  handleChallenge(body) {
+		    return { challenge: body.challenge };
+		  }
+
+		  async handleDelivery(headers, rawBody) {
+		    let event;
+		    try {
+		      event = this._parseDelivery(rawBody);
+		    } catch {
+		      return 'bad_signature';
+		    }
+		    const [current, previous] = this.store.getSecrets(String(event.subscription_id));
+		    const ok = await verifyWebhookSignature(current, previous, headers, rawBody, { skewToleranceS: this.skewToleranceS });
+		    if (!ok) return 'bad_signature';
+		    return this._dispatch(event);
+		  }
+
+		  async handleRequest(headers, rawBody) {
+		    let body;
+		    try {
+		      body = JSON.parse(_text(rawBody));
+		    } catch {
+		      return { status: 400, body: { detail: 'invalid JSON' } };
+		    }
+		    switch (this.classifyMessage(body)) {
+		      case 'verification':
+		        return { status: 200, body: this.handleChallenge(body) };
+		      case 'delivery': {
+		        const ack = await this.handleDelivery(lowerHeaders(headers), rawBody);
+		        if (ack === 'bad_signature') return { status: 401, body: { detail: 'bad signature' } };
+		        return { status: 200, body: { status: ack } };
+		      }
+		      default:
+		        return { status: 400, body: { detail: 'unrecognized event_type' } };
+		    }
+		  }
+
+		  // ── API half ──────────────────────────────────────────────────────────────
+
+		  async register(projectTableName, callbackUrl, targets) {
+		    const res = await this._api.createSubscription(projectTableName, callbackUrl, targets);
+		    this._saveSecretFrom(res);
+		    return res;
+		  }
+
+		  async confirm(subscriptionId) {
+		    const res = await this._api.verifySubscription(subscriptionId);
+		    this._saveSecretFrom(res);
+		    return res;
+		  }
+
+		  async rotateSecret(subscriptionId) {
+		    const res = await this._api.rotateSubscriptionSecret(subscriptionId);
+		    this.store.rotateSecret(String(subscriptionId), res.signing_secret, this.rotationWindowS);
+		    return res.signing_secret;
+		  }
+
+		  async updateCallback(subscriptionId, callbackUrl) {
+		    // A callback change resets the subscription to pending_verification and
+		    // pauses push until the new URL passes the challenge — confirm right away.
+		    await this._api.updateSubscription(subscriptionId, { callbackUrl });
+		    return this.confirm(subscriptionId);
+		  }
+
+		  async disable(subscriptionId) {
+		    return this._api.deleteSubscription(subscriptionId);
+		  }
+
+		  async listSubscriptions() {
+		    return this._api.listSubscriptions();
+		  }
+
+		  async pullEvents(subscriptionId, { since, limit } = {}) {
+		    return this._api.listSubscriptionEvents(subscriptionId, { since, limit: limit ?? this.pageLimit });
+		  }
+
+		  async reconcile(subscriptionId, projectTableName) {
+		    const id = String(subscriptionId);
+		    let cursor = this.store.getCursor(id);
+		    let pulled = 0;
+		    let dispatched = 0;
+		    for (;;) {
+		      const page = await this._api.listSubscriptionEvents(id, { since: cursor ?? undefined, limit: this.pageLimit });
+		      const events = page?.events ?? [];
+		      pulled += events.length;
+		      for (const ev of events) {
+		        const ack = await this._dispatch({
+		          event_id: ev.event_id,
+		          event_type: 'target.completed',
+		          schema_version: '1',
+		          subscription_id: id,
+		          project_table_name: projectTableName,
+		          photo_id: ev.photo_id,
+		          target: ev.target,
+		          completed_at: ev.completed_at,
+		          result_location: this._ctx.baseUrl + _photoPath(projectTableName, ev.photo_id),
+		        });
+		        if (ack === 'handled') dispatched += 1;
+		      }
+		      if (page?.next_cursor && page.next_cursor !== cursor) {
+		        cursor = page.next_cursor;
+		        this.store.setCursor(id, cursor);
+		      }
+		      if (!events.length || events.length < this.pageLimit) break;
+		    }
+		    return { pulled, dispatched };
+		  }
+
+		  async fetchResult(event) {
+		    this._ctx.requireTokens();
+		    const path = _photoPath(event.project_table_name, event.photo_id);
+		    const { data } = await this._ctx.client.request(path, 'GET', this._ctx.accessToken, this._ctx.refreshToken);
+		    return { photo: data, selected: selectResultColumns(data, event.target) };
+		  }
+
+		  saveSecret(subscriptionId, secret) {
+		    this.store.saveSecret(String(subscriptionId), secret);
+		  }
+
+		  // ── internal ──────────────────────────────────────────────────────────────
+
+		  _saveSecretFrom(res) {
+		    if (res?.signing_secret && res?.subscription_id != null) {
+		      this.store.saveSecret(String(res.subscription_id), res.signing_secret);
+		    }
+		  }
+
+		  _parseDelivery(rawBody) {
+		    const event = JSON.parse(_text(rawBody));
+		    for (const key of ['event_id', 'subscription_id', 'target']) {
+		      if (typeof event?.[key] !== 'string' || !event[key]) throw new Error(`missing ${key}`);
+		    }
+		    if (!Number.isInteger(event.photo_id)) throw new Error('photo_id must be an integer');
+		    return event;
+		  }
+
+		  async _dispatch(event) {
+		    if (!this.store.markSeen(String(event.event_id), this.dedupeTtlS)) return 'duplicate';
+		    if (this._onEvent) {
+		      try {
+		        await this._onEvent(event);
+		      } catch (e) {
+		        // release the dedupe claim so the producer's retry redelivers
+		        this.store.unmarkSeen(String(event.event_id));
+		        throw e;
+		      }
+		    }
+		    return 'handled';
+		  }
+		}
+
+		// helpers
+		function selectResultColumns(photo, target) {
+		  if (target === 'all') return null;
+		  const sep = String(target).indexOf(':');
+		  const kind = sep === -1 ? String(target) : String(target).slice(0, sep);
+		  const name = sep === -1 ? '' : String(target).slice(sep + 1);
+		  let columns;
+		  if (kind === 'model') {
+		    columns = WEBHOOK_MODEL_COLUMNS[name];
+		    if (!columns) throw new Error(`unknown model '${name}'`);
+		  } else if (kind === 'outcome') {
+		    const models = WEBHOOK_OUTCOME_MODELS[name];
+		    if (!models) throw new Error(`unknown outcome '${name}'`);
+		    columns = [...new Set(models.flatMap((m) => WEBHOOK_MODEL_COLUMNS[m]))];
+		  } else {
+		    throw new Error(`unknown target grammar '${target}' (expected 'model:<name>', 'outcome:<name>', or 'all')`);
+		  }
+		  const selected = {};
+		  for (const c of columns) selected[c] = photo?.[c] ?? null;
+		  return selected;
+		}
+
+		function _photoPath(projectTableName, photoId) {
+		  return `/api/v1/photos/${encodeURIComponent(projectTableName)}/${encodeURIComponent(String(photoId))}`;
+		}
+
+		function _text(rawBody) {
+		  return typeof rawBody === 'string' ? rawBody : new TextDecoder().decode(toBytes(rawBody));
+		}
+
+		consumer = { WebhookConsumer, selectResultColumns, WEBHOOK_MODEL_COLUMNS, WEBHOOK_OUTCOME_MODELS };
+		return consumer;
+	}
+
 	var src;
 	var hasRequiredSrc;
 
@@ -472,19 +914,19 @@
 		if (hasRequiredSrc) return src;
 		hasRequiredSrc = 1;
 
-		const { OAuthClient } = requireClient();
-		const { OAuthError } = requireErrors();
-		const { OAuthErrorCode } = requireTypes();
+		const { WebhookConsumer, selectResultColumns, WEBHOOK_MODEL_COLUMNS, WEBHOOK_OUTCOME_MODELS } = requireConsumer();
+		const { InMemoryWebhookStore } = requireStore();
+		const { signWebhookPayload, verifyWebhookSignature } = requireSigning();
 
-		src = { OAuthClient, OAuthError, OAuthErrorCode };
+		src = { WebhookConsumer, InMemoryWebhookStore, signWebhookPayload, verifyWebhookSignature, selectResultColumns, WEBHOOK_MODEL_COLUMNS, WEBHOOK_OUTCOME_MODELS };
 		return src;
 	}
 
 	var srcExports = requireSrc();
-	var _oauth = /*@__PURE__*/getDefaultExportFromCjs(srcExports);
+	var _webhooks = /*@__PURE__*/getDefaultExportFromCjs(srcExports);
 
 	// Auto-generated — do not edit
-	const { OAuthClient, OAuthError, OAuthErrorCode } = _oauth;
+	const { WebhookConsumer, InMemoryWebhookStore, signWebhookPayload, verifyWebhookSignature, selectResultColumns, WEBHOOK_MODEL_COLUMNS, WEBHOOK_OUTCOME_MODELS } = _webhooks;
 
 	class AiModelCredits {
 	  constructor(ctx) { this._ctx = ctx; }
@@ -1214,7 +1656,7 @@
 	class Projects {
 	  constructor(ctx) { this._ctx = ctx; }
 
-	  async createProjectAndRun(name, private_ = undefined, type = undefined, description = undefined, directory = undefined, photoUploadVector = undefined, thumbnail = undefined, runName = undefined, { outcomes, models } = {}) {
+	  async createProjectAndRun(name, type, private_ = undefined, description = undefined, directory = undefined, photoUploadVector = undefined, thumbnail = undefined, runName = undefined, { outcomes, models } = {}) {
 	    this._ctx.requireTokens();
 	    let path = `/api/v1/project_outcome/`;
 	    const query = new URLSearchParams();
@@ -1907,6 +2349,7 @@
 	    this.search = new Search(_ctx);
 	    this.subscription = new Subscription(_ctx);
 	    this.users = new Users(_ctx);
+	    this.webhooks = new WebhookConsumer(_ctx, this.subscription);
 	  }
 
 	  async authenticate() {
@@ -1944,6 +2387,7 @@
 	exports.CustomAlbums = CustomAlbums;
 	exports.EmailTokens = EmailTokens;
 	exports.Health = Health;
+	exports.InMemoryWebhookStore = InMemoryWebhookStore;
 	exports.Keywords = Keywords;
 	exports.MediaViz = MediaViz;
 	exports.NotFoundError = NotFoundError;
@@ -1963,6 +2407,12 @@
 	exports.Subscription = Subscription;
 	exports.Users = Users;
 	exports.ValidationError = ValidationError;
+	exports.WEBHOOK_MODEL_COLUMNS = WEBHOOK_MODEL_COLUMNS;
+	exports.WEBHOOK_OUTCOME_MODELS = WEBHOOK_OUTCOME_MODELS;
+	exports.WebhookConsumer = WebhookConsumer;
 	exports.handleResponse = handleResponse;
+	exports.selectResultColumns = selectResultColumns;
+	exports.signWebhookPayload = signWebhookPayload;
+	exports.verifyWebhookSignature = verifyWebhookSignature;
 
 }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mediaviz/sdk",
-  "version": "1.8.0-dev.92",
+  "version": "1.8.0-dev.95",
   "description": "MediaViz JavaScript SDK \u2014 auto-generated public endpoint client.",
   "license": "MIT",
   "repository": {