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

package/dist/sdk.cjs

@@ -461,6 +461,448 @@ function requireTypes () {
 	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;
 
@@ -468,19 +910,19 @@ function requireSrc () {
 	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; }
@@ -1210,7 +1652,7 @@ function stripUndef$3(o) { const r = {}; for (const k in o) if (o[k] !== undefin
 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();
@@ -1903,6 +2345,7 @@ class MediaViz {
     this.search = new Search(_ctx);
     this.subscription = new Subscription(_ctx);
     this.users = new Users(_ctx);
+    this.webhooks = new WebhookConsumer(_ctx, this.subscription);
   }
 
   async authenticate() {
@@ -1940,6 +2383,7 @@ exports.CuratedAlbums = CuratedAlbums;
 exports.CustomAlbums = CustomAlbums;
 exports.EmailTokens = EmailTokens;
 exports.Health = Health;
+exports.InMemoryWebhookStore = InMemoryWebhookStore;
 exports.Keywords = Keywords;
 exports.MediaViz = MediaViz;
 exports.NotFoundError = NotFoundError;
@@ -1959,4 +2403,10 @@ exports.ServerError = ServerError;
 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/dist/sdk.d.cts

@@ -60,6 +60,79 @@ export class ServerError extends ApiError {
 
 export function handleResponse(response: Response): Promise<any>;
 
+export type WebhookAck = 'handled' | 'duplicate' | 'bad_signature';
+
+export interface WebhookDeliveryEvent {
+  event_id: string;
+  event_type: string;
+  schema_version?: string;
+  subscription_id: string;
+  project_table_name: string;
+  photo_id: number;
+  target: string;
+  completed_at?: string;
+  result_location?: string;
+  [key: string]: any;
+}
+
+export interface WebhookStoreLike {
+  markSeen(eventId: string, ttlS: number): boolean;
+  unmarkSeen(eventId: string): void;
+  saveSecret(subscriptionId: string, secret: string): void;
+  rotateSecret(subscriptionId: string, newSecret: string, windowS: number): void;
+  getSecrets(subscriptionId: string): [string | null, string | null];
+  getCursor(subscriptionId: string): string | null;
+  setCursor(subscriptionId: string, cursor: string): void;
+}
+
+export class InMemoryWebhookStore implements WebhookStoreLike {
+  markSeen(eventId: string, ttlS: number): boolean;
+  unmarkSeen(eventId: string): void;
+  saveSecret(subscriptionId: string, secret: string): void;
+  rotateSecret(subscriptionId: string, newSecret: string, windowS: number): void;
+  getSecrets(subscriptionId: string): [string | null, string | null];
+  getCursor(subscriptionId: string): string | null;
+  setCursor(subscriptionId: string, cursor: string): void;
+}
+
+export class WebhookConsumer {
+  constructor(ctx: any, subscriptionApi: any, options?: {
+    store?: WebhookStoreLike;
+    onEvent?: (event: WebhookDeliveryEvent) => void | Promise<void>;
+    skewToleranceS?: number;
+    rotationWindowS?: number;
+    dedupeTtlS?: number;
+    pageLimit?: number;
+  });
+  store: WebhookStoreLike;
+  skewToleranceS: number;
+  rotationWindowS: number;
+  dedupeTtlS: number;
+  pageLimit: number;
+  onEvent(fn: (event: WebhookDeliveryEvent) => void | Promise<void>): (event: WebhookDeliveryEvent) => void | Promise<void>;
+  useStore(store: WebhookStoreLike): void;
+  classifyMessage(body: any): 'verification' | 'delivery' | 'unknown';
+  handleChallenge(body: any): { challenge: string };
+  handleDelivery(headers: any, rawBody: string | Uint8Array | ArrayBuffer): Promise<WebhookAck>;
+  handleRequest(headers: any, rawBody: string | Uint8Array | ArrayBuffer): Promise<{ status: number; body: any }>;
+  register(projectTableName: string, callbackUrl: string, targets: string[]): Promise<any>;
+  confirm(subscriptionId: string): Promise<any>;
+  rotateSecret(subscriptionId: string): Promise<string>;
+  updateCallback(subscriptionId: string, callbackUrl: string): Promise<any>;
+  disable(subscriptionId: string): Promise<any>;
+  listSubscriptions(): Promise<any>;
+  pullEvents(subscriptionId: string, options?: { since?: string; limit?: number }): Promise<any>;
+  reconcile(subscriptionId: string, projectTableName: string): Promise<{ pulled: number; dispatched: number }>;
+  fetchResult(event: WebhookDeliveryEvent): Promise<{ photo: any; selected: Record<string, any> | null }>;
+  saveSecret(subscriptionId: string, secret: string): void;
+}
+
+export function signWebhookPayload(secret: string, timestamp: string, rawBody: string | Uint8Array | ArrayBuffer): Promise<string>;
+export function verifyWebhookSignature(secretCurrent: string | null, secretPrevious: string | null, headers: any, rawBody: string | Uint8Array | ArrayBuffer, options?: { skewToleranceS?: number; now?: number }): Promise<boolean>;
+export function selectResultColumns(photo: any, target: string): Record<string, any> | null;
+export const WEBHOOK_MODEL_COLUMNS: Record<string, string[]>;
+export const WEBHOOK_OUTCOME_MODELS: Record<string, string[]>;
+
 // ── response schemas ──
 export interface AlbumDisplay {
   name?: string;
@@ -255,7 +328,7 @@ export interface PhotoPersonWithS3Link {
 export interface ProjectRunDisplay {
   name: string;
   private?: boolean;
-  type?: number;
+  type: number;
   description?: string;
   directory?: string;
   photo_upload_vector?: number;
@@ -290,6 +363,7 @@ export interface ProjectRunDisplay {
   evidence_model?: boolean;
   insights_model?: boolean;
   normalize?: boolean;
+  is_continuous_upload?: boolean;
 }
 
 export interface PullEvent {
@@ -430,7 +504,7 @@ export class OauthAuthorization {
 export class OauthToken {
   token(body: { grantType: string, code: string, redirectUri: string, clientId: string, codeVerifier: string, refreshToken: string, clientSecret: string }): Promise<Record<string, any>>;
   adminRevokeUserTokens(userId: number): Promise<Record<string, any>>;
-  revoke(body: { token: string, tokenTypeHint: string, clientId: string }): Promise<any>;
+  revoke(body: { token: string, tokenTypeHint: string, clientId: string }): Promise<Record<string, any>>;
 }
 
 export class OauthLogin {
@@ -467,7 +541,7 @@ export class Photos {
 }
 
 export class Projects {
-  createProjectAndRun(name: string, private_?: boolean, type?: number, description?: string, directory?: string, photoUploadVector?: number, thumbnail?: string, runName?: string, options?: { outcomes?: any, models?: any }): Promise<ProjectRunDisplay>;
+  createProjectAndRun(name: string, type: number, private_?: boolean, description?: string, directory?: string, photoUploadVector?: number, thumbnail?: string, runName?: string, options?: { outcomes?: any, models?: any }): Promise<ProjectRunDisplay>;
   markProjectUploadComplete(projectTableName: string, options?: { skippedFileCount?: number | number[] }): Promise<any>;
   checkProjectStatus(projectTableName: string): Promise<any>;
   getProjectPrelimModelRequestTemplate(projectTableName: string): Promise<Record<string, any>>;
@@ -500,8 +574,8 @@ export class Search {
 }
 
 export class Subscription {
-  createSubscription(projectTableName: string, callbackUrl: string, targets: string[]): Promise<any>;
-  verifySubscription(subscriptionId: string): Promise<any>;
+  createSubscription(projectTableName: string, callbackUrl: string, targets: string[]): Promise<SubscriptionActivated>;
+  verifySubscription(subscriptionId: string): Promise<SubscriptionActivated>;
   listSubscriptions(): Promise<SubscriptionDisplay[]>;
   listSubscriptionEvents(subscriptionId: string, options?: { since?: string | string[], limit?: number | number[] }): Promise<EventPage>;
   updateSubscription(subscriptionId: string, body?: { callbackUrl?: string, targets?: string[] }): Promise<SubscriptionDisplay>;
@@ -546,5 +620,6 @@ export class MediaViz {
   readonly search: Search;
   readonly subscription: Subscription;
   readonly users: Users;
+  readonly webhooks: WebhookConsumer;
 }