@getopencrawl/sdk 0.0.0-stage → 0.2.0

package/examples/letter-customer-research.mjs

@@ -0,0 +1,194 @@
+/** Server-only Node24 recipe. The host supplies actual customer authorization,
+ * a private SQLite store, and an encrypted secret-store adapter. It does not
+ * install itself into Letter, provision tenants automatically, or run timers.
+ */
+import {clientForCustomer} from './letter-service-tenants.mjs';
+import {validateAgentInput,validateAgentFeedbackInput} from '../dist/agents.js';
+import {CustomerResearchError} from './letter-customer-research-store.mjs';
+import {OpenCrawlAPIError} from '../dist/errors.js';
+const fail=code=>{throw new CustomerResearchError(code)};
+const clone=value=>JSON.parse(JSON.stringify(value));
+
+/** A confirmed HTTP refusal, with finite local codes only. Never expose server
+ * prose, request IDs, response bodies, transport causes or credentials.
+ * An admission intent still needs its original receipt; this permits no replay.
+ */
+export class CustomerResearchRemoteError extends CustomerResearchError {
+ constructor(code,status){super(code);this.name='CustomerResearchRemoteError';this.status=status;}
+}
+function knownRemote(error){
+ if(!(error instanceof OpenCrawlAPIError))return null;
+ const code={400:'request_rejected',401:'authentication_required',403:'access_denied',
+  404:error.code==='source_not_retained'?'source_not_retained':'not_found',409:'conflict',
+  422:'request_rejected',429:'rate_limited'}[error.status];
+ return code?new CustomerResearchRemoteError(code,error.status):null;
+}
+
+export function createLetterCustomerResearch({store,baseUrl,authorize,secrets,fetch}){
+ if(typeof authorize!=='function'||typeof secrets?.get!=='function')fail('host_adapters_required');
+ // Each operation has a bounded lease; no lock is held across network IO.
+ async function operation(context,customerId,options,fn){
+  const timeoutMs=options?.timeoutMs??30000;
+  if(!Number.isSafeInteger(timeoutMs)||timeoutMs<1||timeoutMs>60000)fail('invalid_timeout');
+  const signal=AbortSignal.any([AbortSignal.timeout(timeoutMs),...(options?.signal?[options.signal]:[])]);
+  let claim;
+  const alive=()=>{if(signal.aborted)fail('deadline_or_abort')};
+  const bounded=promise=>new Promise((resolve,reject)=>{
+   const abort=()=>reject(new CustomerResearchError('deadline_or_abort'));
+   if(signal.aborted)return abort();signal.addEventListener('abort',abort,{once:true});
+   Promise.resolve(promise).then(resolve,reject).finally(()=>signal.removeEventListener('abort',abort));
+  });
+  async function allowed(){alive();if(await bounded(authorize(context,customerId))!==true)fail('customer_denied');alive();if(claim)store.check(claim)}
+  try{
+   await allowed();claim=store.claim(customerId,timeoutMs+5000);await allowed();
+   const mapping=claim.mapping;
+   // The mapping's secret reference is selected by trusted server setup. The
+   // request cannot choose a tenant or key. Recheck after asynchronous vault IO.
+   const key=await bounded(secrets.get(mapping.secretRef));await allowed();
+   if(typeof key!=='string'||key.length<8)fail('customer_key_unavailable');
+   const client=await clientForCustomer({baseUrl,authorizedTenantId:mapping.tenantId,secrets:{get:async()=>key},fetch});await allowed();
+   const safe=value=>{if(JSON.stringify(value).includes(key))fail('credential_in_data');return value};
+   const read=async fn=>{await allowed();const value=await bounded(fn({signal,timeoutMs}));await allowed();return safe(value)};
+   return await fn({claim,client,allowed,read,safe,bounded,signal,timeoutMs});
+  }catch(error){if(error instanceof CustomerResearchError)throw error;throw knownRemote(error)??new CustomerResearchError('operation_unconfirmed')}
+  finally{if(claim)store.release(claim)}
+ }
+ return {
+  /** Exactly one initial create per mapping. An intent is committed before POST,
+   * even if the process dies before sending. Never call start to recover it.
+   */
+  async start(context,customerId,input,options={}){
+   // Snapshot caller input before awaits; use this exact SDK's normalization.
+   let brief;try{brief=clone(validateAgentInput(input))}catch{fail('invalid_brief')}
+   return operation(context,customerId,options,async({claim,client,allowed,safe,bounded,signal,timeoutMs})=>{
+    safe(brief);await allowed();const intent=store.begin(claim,brief);
+    try{await allowed();const value=await bounded(client.agents.create(intent.brief,{idempotencyKey:intent.key,signal,timeoutMs}));await allowed();safe(value);return store.accept(claim,value)}
+    catch(error){const known=knownRemote(error);if(known)throw known;fail('admission_unconfirmed_use_recovery')}
+   });
+  },
+  /** GET only. Missing/denied/malformed receipts leave the original intent intact.
+   * A recovered receipt is historical; read its exact run for current status.
+   */
+  async recover(context,customerId,options={}){
+   return operation(context,customerId,options,async({claim,client,read})=>{
+    const intent=store.intent(customerId);if(!intent)fail('missing_intent');
+    const value=await read(opts=>client.agents.receipt('create',{...opts,idempotencyKey:intent.key}));
+    return store.accept(claim,value);
+   });
+  },
+  /** One deliberate repeat of the known latest terminal run. Its ID anchors
+   * duplicate actions. A witnessed refusal needs explicit recovery before a
+   * new deliberate repeat can use the same predecessor.
+   */
+  async rerun(context,customerId,previousRunId,options={}){
+   if(typeof previousRunId!=='string'||!/^job_[0-9a-f]{32}$/.test(previousRunId))fail('unknown_run');
+   return operation(context,customerId,options,async({claim,client,allowed,read,safe,bounded,signal,timeoutMs})=>{
+    const agentId=store.mapping(customerId).agentId;
+    if(!agentId||!store.knowsRun(customerId,previousRunId))fail('unknown_run');
+    if(store.rerunIntent(customerId,previousRunId))fail('rerun_exists_use_recovery');
+    const agent=await read(opts=>client.agents.get(agentId,opts));
+    const intent=store.beginRerun(claim,previousRunId,agent);
+    try{await allowed();const value=await bounded(client.agents.runs.create(agentId,{expected_revision:intent.expectedRevision},{idempotencyKey:intent.key,signal,timeoutMs}));await allowed();safe(value);return store.acceptRerun(claim,previousRunId,value)}
+    catch(error){const known=knownRemote(error);if(known){if([409,429].includes(known.status)){await allowed();store.refuseRerun(claim,previousRunId,intent.key,known.status)}throw known}fail('rerun_unconfirmed_use_recovery')}
+   });
+  },
+  /** Recover the original receipt, or explicitly retire a witnessed refusal
+   * after a 404 and a fresh authorized agent read. No POST or replacement key.
+   */
+  async recoverRerun(context,customerId,previousRunId,options={}){
+   if(typeof previousRunId!=='string'||!/^job_[0-9a-f]{32}$/.test(previousRunId))fail('unknown_run');
+   return operation(context,customerId,options,async({claim,client,read})=>{
+    const intent=store.rerunIntent(customerId,previousRunId)??store.retiredRerun(customerId,previousRunId);
+    if(!intent)fail('missing_rerun_intent');
+    if(intent.agentId!==store.mapping(customerId).agentId||!store.knowsRun(customerId,previousRunId))fail('rerun_scope_mismatch');
+    let value;
+    try{value=await read(opts=>client.agents.receipt('run:'+intent.agentId,{...opts,idempotencyKey:intent.key}))}
+    catch(error){
+     if(!(error instanceof OpenCrawlAPIError)||error.status!==404||![409,429].includes(intent.refusalStatus)||intent.receiptHash||intent.runId)throw error;
+     const agent=await read(opts=>client.agents.get(intent.agentId,opts));
+     return store.retireRerun(claim,previousRunId,intent.key,agent);
+    }
+    return store.acceptRerun(claim,previousRunId,value);
+   });
+  },
+  /** Current remote authority, never cached evidence on failure. The caller can
+   * select only an exact run already admitted/discovered for this mapped agent.
+   */
+  async read(context,customerId,runId,options={}){
+   return operation(context,customerId,options,async({claim,client,read})=>{
+    const agentId=store.mapping(customerId).agentId;
+    if(!agentId||!store.knowsRun(customerId,runId))fail('unknown_run');
+    const run=await read(opts=>client.agents.runs.get(agentId,runId,opts));store.saveRun(claim,run);return run;
+   });
+  },
+  /** One current-access read of retained context for a known run. The SDK
+   * validates source identity and text hash; no source text is cached locally.
+   */
+  async source(context,customerId,runId,sourceId,options={}){
+   return operation(context,customerId,options,async({client,read})=>{
+    const agentId=store.mapping(customerId).agentId;
+    if(!agentId||!store.knowsRun(customerId,runId))fail('unknown_run');
+    return read(opts=>client.agents.runs.source(agentId,runId,sourceId,opts));
+   });
+  },
+  /** Current schedule for this mapping's agent; no caller-selected agent ID. */
+  async schedule(context,customerId,options={}){
+   return operation(context,customerId,options,async({client,read})=>{
+    const agentId=store.mapping(customerId).agentId;if(!agentId)fail('missing_agent');
+    return read(opts=>client.agents.schedule.get(agentId,opts));
+   });
+  },
+  /** One explicit revision-checked write. On conflict or uncertainty, call
+   * schedule() to reconcile; never replay this mutation automatically.
+   */
+  async setSchedule(context,customerId,input,options={}){
+   if(!input||typeof input!=='object'||Array.isArray(input)||Object.keys(input).some(key=>!['expected_revision','enabled'].includes(key)))fail('invalid_schedule');
+   const body={expected_revision:input.expected_revision,enabled:input.enabled};
+   if(!Number.isSafeInteger(body.expected_revision)||body.expected_revision<0||typeof body.enabled!=='boolean')fail('invalid_schedule');
+   return operation(context,customerId,options,async({client,read})=>{
+    const agentId=store.mapping(customerId).agentId;if(!agentId)fail('missing_agent');
+    return read(opts=>client.agents.schedule.update(agentId,body,opts));
+   });
+  },
+  /** Current authorized feedback for one finding; never a cached preference. */
+  async feedback(context,customerId,runId,findingId,options={}){
+   return operation(context,customerId,options,async({client,read})=>{
+    const agentId=store.mapping(customerId).agentId;
+    if(!agentId||!store.knowsRun(customerId,runId))fail('unknown_run');
+    return read(opts=>client.agents.runs.feedback.get(agentId,runId,findingId,opts));
+   });
+  },
+  /** One CAS write, no replay. On uncertainty read feedback before deciding. */
+  async setFeedback(context,customerId,runId,findingId,input,options={}){
+   let body;try{body=validateAgentFeedbackInput(input)}catch{fail('invalid_feedback')}
+   return operation(context,customerId,options,async({client,read,safe})=>{
+    const agentId=store.mapping(customerId).agentId;
+    if(!agentId||!store.knowsRun(customerId,runId))fail('unknown_run');
+    safe(body);
+    return read(opts=>client.agents.runs.feedback.set(agentId,runId,findingId,body,opts));
+   });
+  },
+  async deleteFeedback(context,customerId,runId,findingId,expectedRevision,options={}){
+   return operation(context,customerId,options,async({client,read})=>{
+    const agentId=store.mapping(customerId).agentId;
+    if(!agentId||!store.knowsRun(customerId,runId))fail('unknown_run');
+    return read(opts=>client.agents.runs.feedback.delete(agentId,runId,findingId,expectedRevision,opts));
+   });
+  },
+  /** One page + up to25 pending reads, no auto-pagination/admission/recurrence.
+   * Atomic rows+pending+cursor, then atomic exact updates. A failed read retains
+   * its pending ID. A page failure never advances its checkpoint.
+   */
+  async poll(context,customerId,options={}){
+   return operation(context,customerId,options,async({claim,client,read})=>{
+    const agentId=store.mapping(customerId).agentId;if(!agentId)fail('missing_agent');
+    const cursor=store.cursor(customerId);
+    const page=await read(opts=>client.agents.runs.list(agentId,{...opts,limit:25,...(cursor===undefined?{}:{cursor})}));
+    store.commitPage(claim,page);
+    let checked=0;const observed=new Set(page.items.map(run=>run.id));
+    for(const runId of store.pending(customerId)){const run=await read(opts=>client.agents.runs.get(agentId,runId,opts));store.saveRun(claim,run);observed.add(run.id);checked++}
+    return {received:page.items.length,checkedPending:checked,hasMoreAdmissions:page.has_more,pending:store.pendingCount(customerId),observedRunIds:[...observed]};
+   });
+  },
+ };
+}

package/examples/letter-event-receiver.d.mts

@@ -0,0 +1,10 @@
+import type {Fetch} from '@getopencrawl/sdk';
+import type {LetterEvidenceStore} from './letter-event-store.mjs';
+
+/** Choose mappingId from server routing, not a request body/customer-supplied key. */
+export function createLetterEventReceiver(options:{
+ store:LetterEvidenceStore;mappingId:string;baseUrl:string;
+ secrets:{get:(tenantId:string)=>Promise<string|null|undefined>};
+ webhookSecrets:{get:(signingSecretRef:string)=>Promise<string|null|undefined>};
+ fetch?:Fetch;
+}):(request:Request)=>Promise<Response>;

package/examples/letter-event-receiver.mjs

@@ -0,0 +1,55 @@
+/** Server-only qualified evidence handoff. The optional SQLite adapter requires Node24. */
+import {createHash} from 'node:crypto';
+import {createResearchWebhookReceiver} from './research-webhook-receiver.mjs';
+import {clientForCustomer} from './letter-service-tenants.mjs';
+
+const kinds=['baseline','changed','unavailable','recovered'];
+const id=value=>typeof value==='string'&&value.length>0&&value.length<=200;
+const stamp=value=>typeof value==='string'&&value.length<=128&&Number.isFinite(Date.parse(value));
+const canonical=value=>JSON.stringify(value,(_key,v)=>v&&typeof v==='object'&&!Array.isArray(v)?Object.fromEntries(Object.keys(v).sort().map(k=>[k,v[k]])):v);
+const digest=value=>createHash('sha256').update(canonical(value)).digest('hex');
+function observation(event){
+ if(event.type==='webhook.test')return null;
+ const kind=event.type.slice('research.'.length),data=event.data;
+ if(!kinds.includes(kind)||data.observation_id!==event.id||!stamp(event.created_at)||data.observed_at!==event.created_at||!(data.previous_observed_at===null||stamp(data.previous_observed_at))||typeof data.gap!=='boolean'||![data.before_version_id,data.after_version_id].every(v=>v===null||id(v)))throw new Error('Invalid observation identity.');
+ return {id:event.id,collectionId:event.collection_id,kind,observedAt:data.observed_at,previousObservedAt:data.previous_observed_at,gap:data.gap,beforeVersionId:data.before_version_id,afterVersionId:data.after_version_id};
+}
+function bind(detail,event){
+ if(detail.id!==event.id||detail.collection_id!==event.collectionId||detail.kind!==event.kind||detail.observed_at!==event.observedAt||detail.previous_observed_at!==event.previousObservedAt||detail.gap!==event.gap||(detail.before?.version_id??null)!==event.beforeVersionId||(detail.after?.version_id??null)!==event.afterVersionId)throw new Error('Retained observation does not match its notification.');
+ return detail;
+}
+/**
+ * The mapping ID is chosen by server routing, never from the request body.
+ * secrets.get(tenantId) supplies only that customer's child key. webhookSecrets
+ * resolves the mapping's signing-secret reference. Neither secret is persisted
+ * in inbox/evidence rows or included in responses. No parent-key fallback.
+ */
+export function createLetterEventReceiver({store,mappingId,baseUrl,secrets,webhookSecrets,fetch}){
+ if(!id(mappingId)||!store||typeof secrets?.get!=='function'||typeof webhookSecrets?.get!=='function')throw new Error('A durable store and server-owned mapping are required.');
+ return async request=>{
+  if(request.method!=='POST')return new Response(null,{status:405,headers:{Allow:'POST'}});
+  let mapping,secret;
+  try{mapping=store.mapping(mappingId);if(!mapping?.active)return new Response(null,{status:404});secret=await webhookSecrets.get(mapping.signingSecretRef);if(!secret)throw new Error('Unavailable signing secret.');}catch{return new Response(null,{status:503});}
+  return createResearchWebhookReceiver({secret,collectionId:mapping.collectionId,processOnce:async({deliveryId,event})=>{
+   const selected=observation(event),claim=store.claim(mapping,deliveryId,event.id,digest(event),selected);
+   if(claim.state==='duplicate')return;
+   if(claim.state!=='claimed')throw new Error('Observation processing is not ready.');
+   try{
+    if(selected===null){store.commit(claim,{type:'connection_test',signalClassification:'not_assessed'});return;}
+    const child=await clientForCustomer({baseUrl,authorizedTenantId:mapping.tenantId,secrets,fetch});
+    if(!store.same(mapping))throw new Error('Customer mapping changed before the evidence read.');
+    const detail=bind(await child.collections.event(mapping.collectionId,event.id,{budget:16000}),selected);
+    store.commit(claim,{type:'retained_observation',signalClassification:'not_assessed',coverage:'bounded_window',
+     interpretation:'Source observation only; no independently verified business event, buying intent or capability change.',
+     evidence:detail});
+   }catch(error){
+    // A lost commit acknowledgement may already have a durable record. Reconcile
+    // its exact claim before any retry, never issue a replacement record/read.
+    if(store.committed(claim))return;
+    const unavailable=[401,403,404].includes(error?.status);
+    const terminal=store.fail(claim,unavailable?'unavailable':'retryable');
+    if(!unavailable||!terminal)throw new Error('Observation processing could not be confirmed.');
+   }
+  }})(request);
+ };
+}

package/examples/letter-event-store.d.mts

@@ -0,0 +1,35 @@
+import type {ResearchEventDetail} from '@getopencrawl/sdk';
+
+export type LetterMappingInput={id:string;customerId:string;tenantId:string;collectionId:string;signingSecretRef:string;active:boolean};
+export type LetterMapping=LetterMappingInput&{revision:number};
+export type LetterObservation={id:string;collectionId:string;kind:ResearchEventDetail['kind'];observedAt:string;previousObservedAt:string|null;gap:boolean;beforeVersionId:string|null;afterVersionId:string|null};
+export type LetterEvidenceRecord=
+ |{type:'connection_test';signalClassification:'not_assessed'}
+ |{type:'retained_observation';signalClassification:'not_assessed';coverage:'bounded_window';interpretation:string;evidence:ResearchEventDetail};
+export type LetterClaim={state:'claimed';mapping:LetterMapping;deliveryId:string;eventId:string;payloadHash:string;token:string;observation:LetterObservation|null};
+export type LetterClaimResult=LetterClaim|{state:'duplicate'|'busy'};
+export type LetterStoredRecord={state:'processing'|'committed'|'unavailable'|'retryable';record:LetterEvidenceRecord|null;updatedAt:number};
+/** Synchronous transactions; never hold a transaction across remote I/O. */
+export interface LetterEvidenceStore{
+ mapping(id:string):LetterMapping|null;
+ same(mapping:LetterMapping):boolean;
+ claim(mapping:LetterMapping,deliveryId:string,eventId:string,payloadHash:string,observation:LetterObservation|null):LetterClaimResult;
+ committed(claim:LetterClaim):boolean;
+ commit(claim:LetterClaim,record:LetterEvidenceRecord):void;
+ /** True only when an exact terminal unavailable receipt is durably confirmed. */
+ fail(claim:LetterClaim,state:'unavailable'|'retryable'):boolean;
+}
+/** Optional server-only adapter, Node24+. Use private directory0700/file0600. */
+export class LetterEventStore implements LetterEvidenceStore{
+ constructor(filename:string,options?:{maxRecords?:number;leaseMs?:number;clock?:()=>number});
+ close():void;
+ putMapping(mapping:LetterMappingInput):LetterMapping;
+ mapping(id:string):LetterMapping|null;
+ same(mapping:LetterMapping):boolean;
+ claim(mapping:LetterMapping,deliveryId:string,eventId:string,payloadHash:string,observation:LetterObservation|null):LetterClaimResult;
+ committed(claim:LetterClaim):boolean;
+ commit(claim:LetterClaim,record:LetterEvidenceRecord):void;
+ fail(claim:LetterClaim,state:'unavailable'|'retryable'):boolean;
+ /** The host application must check its current customer authorization first. */
+ getRecord(customerId:string,collectionId:string,eventId:string):LetterStoredRecord|null;
+}

package/examples/letter-event-store.mjs

@@ -0,0 +1,84 @@
+/** Node24-only concrete customer-side SQLite adapter. Not an OpenCrawl platform database. */
+import {DatabaseSync} from 'node:sqlite';
+import {randomUUID} from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+const id=value=>typeof value==='string'&&/^[A-Za-z0-9_-]{1,200}$/.test(value);
+const bounded=(value,max)=>Number.isSafeInteger(value)&&value>0&&value<=max;
+export class LetterEventStore{
+ constructor(filename,{maxRecords=10000,leaseMs=60000,clock=()=>Date.now()}={}){
+  if(Number(process.versions.node.split('.')[0])<24)throw new Error('This SQLite example requires Node24.');
+  if(!path.isAbsolute(filename)||!bounded(maxRecords,100000)||!bounded(leaseMs,300000))throw new Error('Use a bounded private absolute SQLite path.');
+  const parent=fs.lstatSync(path.dirname(filename));if(!parent.isDirectory()||parent.isSymbolicLink()||(parent.mode&0o077)!==0)throw new Error('Use a private directory.');
+  try{const fd=fs.openSync(filename,'wx',0o600);fs.closeSync(fd);}catch(error){if(error.code!=='EEXIST')throw error;}
+  const stat=fs.lstatSync(filename);if(!stat.isFile()||stat.isSymbolicLink()||(stat.mode&0o077)!==0)throw new Error('Use a private SQLite file.');
+  this.db=new DatabaseSync(filename);this.clock=clock;this.maxRecords=maxRecords;this.leaseMs=leaseMs;
+  this.db.exec(`PRAGMA foreign_keys=ON; PRAGMA busy_timeout=1000;
+   CREATE TABLE IF NOT EXISTS letter_mappings(id TEXT PRIMARY KEY,customer_id TEXT NOT NULL,tenant_id TEXT NOT NULL,collection_id TEXT NOT NULL,signing_secret_ref TEXT NOT NULL,revision INTEGER NOT NULL,active INTEGER NOT NULL);
+   CREATE TABLE IF NOT EXISTS letter_events(customer_id TEXT NOT NULL,collection_id TEXT NOT NULL,event_id TEXT NOT NULL,mapping_id TEXT NOT NULL,revision INTEGER NOT NULL,payload_hash TEXT NOT NULL,state TEXT NOT NULL,claim TEXT,lease_until INTEGER,record TEXT,updated_at INTEGER NOT NULL,PRIMARY KEY(customer_id,collection_id,event_id));
+   CREATE TABLE IF NOT EXISTS letter_deliveries(mapping_id TEXT NOT NULL,delivery_id TEXT NOT NULL,customer_id TEXT NOT NULL,collection_id TEXT NOT NULL,event_id TEXT NOT NULL,payload_hash TEXT NOT NULL,PRIMARY KEY(mapping_id,delivery_id));`);
+ }
+ close(){this.db.close()}
+ transaction(fn){this.db.exec('BEGIN IMMEDIATE');try{const value=fn();this.db.exec('COMMIT');return value}catch(error){this.db.exec('ROLLBACK');throw error}}
+ /** Local administrative configuration only; never accept a webhook's mapping. */
+ putMapping(value){
+  for(const key of ['id','customerId','tenantId','collectionId','signingSecretRef'])if(!id(value[key]))throw new Error('Invalid server mapping.');
+  if(typeof value.active!=='boolean')throw new Error('Choose an explicit mapping state.');
+  return this.transaction(()=>{
+   const old=this.mapping(value.id);
+   if(old&&['customerId','tenantId','collectionId'].some(key=>old[key]!==value[key]))throw new Error('Mapping identity cannot be reassigned.');
+   const revision=(old?.revision??0)+1;
+   this.db.prepare('INSERT INTO letter_mappings VALUES(?,?,?,?,?,?,?) ON CONFLICT(id) DO UPDATE SET signing_secret_ref=excluded.signing_secret_ref,revision=excluded.revision,active=excluded.active').run(value.id,value.customerId,value.tenantId,value.collectionId,value.signingSecretRef,revision,Number(value.active));
+   return this.mapping(value.id);
+  });
+ }
+ mapping(identity){const row=this.db.prepare('SELECT * FROM letter_mappings WHERE id=?').get(identity);return row?{id:row.id,customerId:row.customer_id,tenantId:row.tenant_id,collectionId:row.collection_id,signingSecretRef:row.signing_secret_ref,revision:row.revision,active:Boolean(row.active)}:null}
+ same(mapping){const current=this.mapping(mapping.id);return Boolean(current?.active&&['customerId','tenantId','collectionId','signingSecretRef','revision'].every(key=>current[key]===mapping[key]))}
+ claim(mapping,deliveryId,eventId,payloadHash,observation){
+  if(!id(deliveryId)||!id(eventId)||!/^[a-f0-9]{64}$/.test(payloadHash))throw new Error('Invalid receipt identity.');
+  return this.transaction(()=>{
+   if(!this.same(mapping))throw new Error('Customer mapping changed.');
+   const args=[mapping.customerId,mapping.collectionId,eventId],existing=this.db.prepare('SELECT * FROM letter_events WHERE customer_id=? AND collection_id=? AND event_id=?').get(...args);
+   const delivery=this.db.prepare('SELECT * FROM letter_deliveries WHERE mapping_id=? AND delivery_id=?').get(mapping.id,deliveryId);
+   if(delivery&&(delivery.customer_id!==mapping.customerId||delivery.collection_id!==mapping.collectionId||delivery.event_id!==eventId||delivery.payload_hash!==payloadHash))throw new Error('Conflicting delivery identity.');
+   if(existing&&existing.payload_hash!==payloadHash)throw new Error('Conflicting event identity.');
+   if(!delivery){
+    if(this.db.prepare('SELECT COUNT(*) n FROM letter_deliveries').get().n>=this.maxRecords)throw new Error('Inbox capacity reached.');
+    this.db.prepare('INSERT INTO letter_deliveries VALUES(?,?,?,?,?,?)').run(mapping.id,deliveryId,...args,payloadHash);
+   }
+   if(existing&&['committed','unavailable'].includes(existing.state))return {state:'duplicate'};
+   const stamp=this.clock();
+   if(existing?.state==='processing'&&existing.lease_until>stamp)return {state:'busy'};
+   // Lease expiry only retries an idempotent retained read. Publication always
+   // requires the new claim; an earlier reader cannot commit after takeover.
+   if(!existing&&this.db.prepare('SELECT COUNT(*) n FROM letter_events').get().n>=this.maxRecords)throw new Error('Evidence capacity reached.');
+   const token=randomUUID();
+   this.db.prepare(`INSERT INTO letter_events VALUES(?,?,?,?,?,?,'processing',?,?,NULL,?)
+    ON CONFLICT(customer_id,collection_id,event_id) DO UPDATE SET mapping_id=excluded.mapping_id,revision=excluded.revision,state='processing',claim=excluded.claim,lease_until=excluded.lease_until,updated_at=excluded.updated_at`).run(...args,mapping.id,mapping.revision,payloadHash,token,stamp+this.leaseMs,stamp);
+   return {state:'claimed',mapping,deliveryId,eventId,payloadHash,token,observation};
+  });
+ }
+ row(claim){return this.db.prepare('SELECT * FROM letter_events WHERE customer_id=? AND collection_id=? AND event_id=?').get(claim.mapping.customerId,claim.mapping.collectionId,claim.eventId)}
+ committed(claim){const row=this.row(claim);return row?.payload_hash===claim.payloadHash&&row.state==='committed'}
+ commit(claim,record){
+  const encoded=JSON.stringify(record);if(Buffer.byteLength(encoded)>262144)throw new Error('Evidence record exceeds the bound.');
+  return this.transaction(()=>{
+   const row=this.row(claim);if(row?.state==='committed'&&row.payload_hash===claim.payloadHash)return;
+   if(!this.same(claim.mapping)||row?.state!=='processing'||row.claim!==claim.token||row.lease_until<=this.clock())throw new Error('Publication claim is no longer current.');
+   this.db.prepare("UPDATE letter_events SET state='committed',record=?,claim=NULL,lease_until=NULL,updated_at=? WHERE customer_id=? AND collection_id=? AND event_id=?").run(encoded,this.clock(),claim.mapping.customerId,claim.mapping.collectionId,claim.eventId);
+  });
+ }
+ fail(claim,state){
+  if(!['unavailable','retryable'].includes(state))throw new Error('Invalid failure state.');
+  return this.transaction(()=>{
+   const row=this.row(claim);
+   if(row?.state==='unavailable'&&row.payload_hash===claim.payloadHash)return true;
+   if(row?.state!=='processing'||row.claim!==claim.token)return false;
+   const next=this.same(claim.mapping)?state:'unavailable';
+   this.db.prepare('UPDATE letter_events SET state=?,record=NULL,claim=NULL,lease_until=NULL,updated_at=? WHERE customer_id=? AND collection_id=? AND event_id=?').run(next,this.clock(),claim.mapping.customerId,claim.mapping.collectionId,claim.eventId);
+   return next==='unavailable';
+  });
+ }
+ /** Caller must enforce its application's current customer access before reading. */
+ getRecord(customerId,collectionId,eventId){const row=this.db.prepare('SELECT state,record,updated_at FROM letter_events WHERE customer_id=? AND collection_id=? AND event_id=?').get(customerId,collectionId,eventId);return row?{state:row.state,record:row.record?JSON.parse(row.record):null,updatedAt:row.updated_at}:null}
+}

package/examples/letter-seer.d.mts

@@ -0,0 +1,31 @@
+import type {OpenCrawl,ChangeHunk,CollectionReceipt,ResearchJob,ResearchEvent,ResearchSearchResponse,SearchResult} from '@getopencrawl/sdk';
+
+export type SeerPassage=Pick<SearchResult,'document_id'|'source_id'|'title'|'url'|'kind'|'metadata'|'source_created_at'|'source_updated_at'|'indexed_at'|'freshness'|'research_observation'>&{
+  citation:string;chunk_id?:string;content:string;
+  location:Record<string,unknown>&{start_char:number;end_char:number};
+};
+export type SeerPassagePack={
+  kind:'whole_returned_passages';source_text_is_untrusted:true;
+  budget_bytes:32768;utf8_bytes:number;returned_passage_count:number;
+  all_returned_passages_included:boolean;omitted_citations:string[];passages:SeerPassage[];
+};
+/** Fixed total serialized UTF-8 cap; completeness refers only to returned passages. */
+export function packSeerPassages(evidence:ResearchSearchResponse):SeerPassagePack;
+
+export type SeerPreparation = {
+  name:string;brief?:string;seedUrls:string[];allowedOrigins?:string[];
+  pageLimit?:number;scheduleMinutes?:number;includeMedia?:boolean;
+  idempotencyKey:string;signal?:AbortSignal;
+};
+export type SeerRunSelection = {collectionId:string;jobId:string;query:string;cursor?:string;includeVolatile?:boolean;signal?:AbortSignal};
+export type SeerEvent = {
+  id:string;kind:ResearchEvent['kind'];url:string;observedAt:string;previousObservedAt:string|null;
+  before:ResearchEvent['before'];after:ResearchEvent['after'];changeSummary:ResearchEvent['change_summary'];gap:boolean;
+  changes:ChangeHunk[]|null;substance:'content'|'volatile_only'|null;
+};
+export type SeerRun = {
+  state:'processing'|'empty'|'review'|'needs_attention';job:ResearchJob;
+  events?:SeerEvent[];nextCursor?:string|null;evidence?:ResearchSearchResponse;interpretation?:string;
+};
+export function prepareSeer(client:OpenCrawl,input:SeerPreparation):Promise<CollectionReceipt>;
+export function readSeerRun(client:OpenCrawl,input:SeerRunSelection):Promise<SeerRun>;

package/examples/letter-seer.mjs

@@ -0,0 +1,78 @@
+/** Server-only integration boundary for Letter's Seer runner. No emails or webhooks are sent. */
+import {OpenCrawlValidationError} from '@getopencrawl/sdk';
+
+const PASSAGE_BUDGET=32_768;
+const encoder=new TextEncoder();
+const PASSAGE_FIELDS=['citation','document_id','chunk_id','source_id','title','url','kind','content','location','metadata','source_created_at','source_updated_at','indexed_at','freshness','research_observation'];
+
+/** Package already-returned source passages, never another query or a summary.
+ * The fixed cap covers the complete serialized JSON, including provenance and
+ * omission metadata. Source strings remain untrusted data, not instructions.
+ */
+export function packSeerPassages(evidence){
+ const results=evidence?.results;
+ if(!Array.isArray(results)||results.length>50)throw new OpenCrawlValidationError('Pass an existing search response with at most 50 returned passages.');
+ const seen=new Set(),passages=[];
+ for(const result of results){
+  const {citation,content,document_id,location}=result??{};
+  if(typeof citation!=='string'||!/^S[1-9]\d{0,2}$/.test(citation)||seen.has(citation)||typeof document_id!=='string'||!document_id||typeof content!=='string'||!location||!Number.isSafeInteger(location.start_char)||!Number.isSafeInteger(location.end_char)||location.start_char<0||location.end_char-location.start_char!==Array.from(content).length)throw new OpenCrawlValidationError('Each passage needs a unique citation, document identity and exact codepoint source range.');
+  seen.add(citation);
+  // Select evidence/provenance fields only. Preview and compact-context offsets
+  // describe different slices and must never be relabeled as full-passage spans.
+  passages.push(Object.fromEntries(PASSAGE_FIELDS.filter(key=>Object.hasOwn(result,key)).map(key=>[key,result[key]])));
+ }
+ const build=(included,omitted)=>{
+  const value={kind:'whole_returned_passages',source_text_is_untrusted:true,budget_bytes:PASSAGE_BUDGET,utf8_bytes:0,returned_passage_count:passages.length,all_returned_passages_included:omitted.length===0,omitted_citations:omitted,passages:included};
+  let serialized;
+  for(let step=0;step<4;step++){serialized=JSON.stringify(value);const size=encoder.encode(serialized).length;if(size===value.utf8_bytes)return {value,serialized};value.utf8_bytes=size;}
+  throw new OpenCrawlValidationError('Could not account for the evidence envelope.');
+ };
+ let included=[],omitted=passages.map(p=>p.citation),packed=build(included,omitted);
+ for(const passage of passages){
+  const nextOmitted=omitted.filter(label=>label!==passage.citation),candidate=build([...included,passage],nextOmitted);
+  if(candidate.value.utf8_bytes<=PASSAGE_BUDGET){included=candidate.value.passages;omitted=nextOmitted;packed=candidate;}
+ }
+ // A detached JSON value prevents later mutation of the response from changing
+ // retained evidence; no source text is normalized, interpreted or executed.
+ return JSON.parse(packed.serialized);
+}
+
+/** Save the exact input/key before calling, then persist the accepted collection/job IDs.
+ * Pilot defaults are one page, manual checks and no media; opt into ongoing work explicitly.
+ */
+export async function prepareSeer(client,{name,brief,seedUrls,allowedOrigins,pageLimit=1,scheduleMinutes=0,includeMedia=false,idempotencyKey,signal}){
+ return client.collections.create({name,brief,seed_urls:seedUrls,allowed_origins:allowedOrigins,page_limit:pageLimit,schedule_minutes:scheduleMinutes,include_media:includeMedia},{idempotencyKey,signal});
+}
+
+/** Resume the same accepted job after a process restart; never create a replacement blindly.
+ * By default, changes whose only differences are dates, clock times, relative
+ * ages or whitespace are omitted; they remain in the collection's history.
+ */
+export async function readSeerRun(client,{collectionId,jobId,query,cursor,includeVolatile=false,signal}){
+ const job=await client.jobs.get(jobId,{signal});
+ if(job.collection_id!==collectionId)throw new OpenCrawlValidationError('The job belongs to a different research collection.');
+ if(job.status==='queued'||job.status==='running')return {state:'processing',job};
+ // A terminal receipt is not proof of usable evidence. Do not turn an empty
+ // failed first run into an apparently ready search of unrelated older pages.
+ if(job.progress.indexed===0)return {state:['failed','cancelled'].includes(job.status)?'needs_attention':'empty',job};
+ const [events,evidence]=await Promise.all([
+  client.collections.events(collectionId,{limit:25,cursor,includeVolatile,signal}),
+  client.search({query,collection_ids:[collectionId],freshness:'indexed',limit:10,budget:6000},{signal}),
+ ]);
+ return {
+  state:job.status==='completed'?'review':'needs_attention',
+  job,
+  events:events.items.map(event=>({
+   // Baseline is not a newly occurring business event. Unavailable is not a deletion.
+   id:event.id,kind:event.kind,url:event.url,observedAt:event.observed_at,
+   previousObservedAt:event.previous_observed_at,before:event.before,after:event.after,
+   changeSummary:event.change_summary,gap:event.gap,
+   // Removed/added lines for the host's positioning rule; absent on older observations.
+   changes:event.change_summary.changes??null,substance:event.change_summary.substance??null,
+  })),
+  nextCursor:events.next_cursor,
+  evidence,
+  // The host may apply a reviewed positioning rule, but must retain this evidence boundary.
+  interpretation:'Observed source changes; not independently verified purchase intent or business outcomes.',
+ };
+}

package/examples/letter-service-tenants.d.mts

@@ -0,0 +1,12 @@
+import type {OpenCrawl,Fetch,ServiceTenant,ServiceTenantReceipt,ServiceTenantOperation} from '@getopencrawl/sdk';
+
+export type CustomerSecrets = {put:(tenantId:string,key:string)=>Promise<void>;get:(tenantId:string)=>Promise<string|null|undefined>};
+export type CustomerReceiptWriter = (record:{tenant:ServiceTenant;receipt:ServiceTenantReceipt['receipt']})=>Promise<void>;
+export type CustomerProvisionResult = {tenant:ServiceTenant;state:'key_stored'|'review_key_storage'};
+export function provisionCustomer(parent:OpenCrawl,input:{customerId:string;name:string;createKey:string;
+  secrets:Pick<CustomerSecrets,'put'>;recordReceipt:CustomerReceiptWriter;signal?:AbortSignal}):Promise<CustomerProvisionResult>;
+export function recoverProvisioning(parent:OpenCrawl,input:{operation:ServiceTenantOperation;idempotencyKey:string;
+  recordReceipt:CustomerReceiptWriter;signal?:AbortSignal}):Promise<{tenant:ServiceTenant;state:'revoked'|'review_key_storage'}>;
+export function rotateCustomerKey(parent:OpenCrawl,input:{tenantId:string;expectedRevision:number;rotationKey:string;
+  secrets:Pick<CustomerSecrets,'put'>;recordReceipt:CustomerReceiptWriter;signal?:AbortSignal}):Promise<CustomerProvisionResult>;
+export function clientForCustomer(input:{baseUrl:string;authorizedTenantId:string;secrets:Pick<CustomerSecrets,'get'>;fetch?:Fetch}):Promise<OpenCrawl>;

package/examples/letter-service-tenants.mjs

@@ -0,0 +1,49 @@
+/** Server-only: use the immutable SDK install command from Research → Use this search in your app.
+ * Without the UI, use packages.sdk.url from https://app.getopencrawl.com/downloads/manifest.json.
+ * Authorize the Letter customer before resolving its mapping; keep the parent key on your server.
+ * After provisioning, pass a separate child client to prepareSeer/readSeerRun in letter-seer.mjs.
+ * Create collections with that child client and retain their IDs; human-workspace collection IDs do not transfer.
+ * Keep the exact provisioning parent key: revoking/replacing it suspends its child credentials and jobs.
+ * Child-key rotation does not transfer this parent anchor.
+ * This adapter does not install itself into Letter or store credentials for the host product.
+ */
+import {OpenCrawl} from '@getopencrawl/sdk';
+
+/** Persist the exact descriptor + operation key before calling; use a durable encrypted secret store. */
+export async function provisionCustomer(parent,{customerId,name,createKey,secrets,recordReceipt,signal}){
+ return save(await parent.createServiceTenant({external_customer_id:customerId,name},{idempotencyKey:createKey,signal}),{secrets,recordReceipt});
+}
+export async function recoverProvisioning(parent,{operation,idempotencyKey,recordReceipt,signal}){
+ const result=await parent.getServiceTenantReceipt(operation,{idempotencyKey,signal});
+ await recordReceipt({tenant:result.tenant,receipt:result.receipt});
+ // No recoverable secret; check your store, then explicitly rotate if missing.
+ return {tenant:result.tenant,state:result.tenant.access_state==='revoked'?'revoked':'review_key_storage'};
+}
+export async function rotateCustomerKey(parent,{tenantId,expectedRevision,rotationKey,secrets,recordReceipt,signal}){
+ return save(await parent.rotateServiceTenantKey(tenantId,{expected_revision:expectedRevision},{idempotencyKey:rotationKey,signal}),{secrets,recordReceipt});
+}
+async function save(result,{secrets,recordReceipt}){
+ // Save the first-response secret first. A storage failure requires receipt recovery
+ // and an explicit rotation; never log this response or blindly repeat creation.
+ if(result.key!==null)await secrets.put(result.tenant.id,result.key);
+ await recordReceipt({tenant:result.tenant,receipt:result.receipt});
+ return {tenant:result.tenant,state:result.key!==null?'key_stored':'review_key_storage'};
+}
+export async function clientForCustomer({baseUrl,authorizedTenantId,secrets,fetch}){
+ const key=await secrets.get(authorizedTenantId);
+ if(!key)throw new Error('No stored customer credential. Recover its receipt and explicitly rotate if needed.');
+ return new OpenCrawl({baseUrl,apiKey:key,fetch,maxRetries:0}); // Explicit receipt recovery; never fall back to a parent key.
+}
+
+// Offline, runnable contract demonstration. In-memory storage is for this mock only.
+if(process.argv[1]?.endsWith('/letter-service-tenants.mjs')){
+ if(process.argv[2]!=='--mock')throw new Error('Run with --mock, or import these helpers into your server with durable storage.');
+ const id='stn_'+'1'.repeat(32),stamp='2026-01-01T00:00:00.000Z';
+ const tenant={id,external_customer_id:'customer-42',name:'Synthetic customer',workspace_id:'ws_synthetic',machine_user_id:'usr_synthetic',status:'active',access_state:'active',revision:1,provisioning_key_id:'key_parent',credential:null,created_at:stamp,updated_at:stamp,revoked_at:null};
+ const parent=new OpenCrawl({baseUrl:'https://example.invalid',apiKey:'synthetic-parent-key',fetch:async()=>new Response(JSON.stringify({tenant,receipt:{id:'streq_synthetic',operation:'create',tenant_id:id,target_revision:1,created_at:stamp},key:'synthetic-child-key',secret_available:true,replayed:false}))});
+ const vault=new Map(),records=[],secrets={put:async(id,key)=>{vault.set(id,key)},get:async(id)=>vault.get(id)};
+ const result=await provisionCustomer(parent,{customerId:'customer-42',name:'Synthetic customer',createKey:'synthetic-create-key-0001',secrets,recordReceipt:async value=>{records.push(value)}});
+ const child=await clientForCustomer({baseUrl:parent.baseUrl,authorizedTenantId:result.tenant.id,secrets,fetch:async(_url,init)=>{if(init.headers.Authorization!=='Bearer synthetic-child-key')throw new Error('Wrong customer credential');return new Response(JSON.stringify({items:[],next_cursor:null}))}});
+ const page=await child.collections.list();
+ console.log(JSON.stringify({mock:true,key_stored:result.state==='key_stored',metadata_receipts:records.length,child_collections:page.items.length,parent_credential_used_for_child:false}));
+}

package/examples/research-webhook-receiver.mjs

@@ -0,0 +1,29 @@
+/** Server-only Fetch API receiver. Mount this handler on one explicitly configured HTTPS path. */
+import {verifyResearchWebhook} from '@getopencrawl/sdk';
+
+/**
+ * processOnce must atomically deduplicate deliveryId and commit the event in your durable store.
+ * It resolves after that commit, including for a previously committed duplicate. Do not use
+ * a process-local Set: requests can be repeated after restarts or an unknown delivery outcome.
+ */
+export function createResearchWebhookReceiver({secret,collectionId,processOnce}){
+ if(typeof processOnce!=='function'||typeof collectionId!=='string'||!collectionId)throw new Error('A collection and durable processOnce handler are required.');
+ return async function receive(request){
+  if(request.method!=='POST')return new Response(null,{status:405,headers:{Allow:'POST'}});
+  if(!request.body)return new Response(null,{status:400});
+  if(Number(request.headers.get('Content-Length'))>16384)return new Response(null,{status:413});
+  const reader=request.body.getReader(),parts=[];let size=0,timer;
+  try{
+   const timeout=new Promise((_,reject)=>{timer=setTimeout(()=>{void reader.cancel().catch(()=>{});reject(new Error('body timeout'));},10000)});
+   while(true){const part=await Promise.race([reader.read(),timeout]);if(part.done)break;size+=part.value.byteLength;if(size>16384){void reader.cancel().catch(()=>{});return new Response(null,{status:413})}parts.push(part.value)}
+  }catch{return new Response(null,{status:400})}finally{clearTimeout(timer);reader.releaseLock()}
+  const body=new Uint8Array(size);let offset=0;for(const part of parts){body.set(part,offset);offset+=part.byteLength}
+  let verified;
+  try{verified=await verifyResearchWebhook({secret,body,headers:{'webhook-id':request.headers.get('Webhook-Id'),'webhook-timestamp':request.headers.get('Webhook-Timestamp'),'webhook-signature':request.headers.get('Webhook-Signature')}})}catch{return new Response(null,{status:503})}
+  if(!verified)return new Response(null,{status:401});
+  let event;try{event=JSON.parse(new TextDecoder('utf-8',{fatal:true}).decode(body))}catch{return new Response(null,{status:400})}
+  const kinds=['research.changed','research.recovered','research.baseline','research.unavailable','webhook.test'];
+  if(!event||typeof event!=='object'||Array.isArray(event)||typeof event.id!=='string'||event.id.length>200||!event.id||event.collection_id!==collectionId||!kinds.includes(event.type)||typeof event.created_at!=='string'||!event.data||typeof event.data!=='object'||Array.isArray(event.data))return new Response(null,{status:400});
+  try{await processOnce({deliveryId:verified.deliveryId,event});return new Response(null,{status:204})}catch{return new Response(null,{status:503})}
+ };
+}