@getopencrawl/sdk 0.0.0-stage → 0.2.0

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/webhooks.d.ts

@@ -0,0 +1,38 @@
+import { Transport, type MutationOptions, type RequestOptions } from './transport.js';
+import type { OffsetPage, Webhook, WebhookDelivery, WebhookDeliveryReceipt, WebhookInput, WebhookReplay, WebhookRevision, WebhookSecretReceipt, WebhookUpdate } from './types.js';
+export declare class ResearchWebhooks {
+    private readonly transport;
+    constructor(transport: Transport);
+    /** A repeated successful create returns secret:null. It never rotates implicitly. */
+    create(collectionId: string, input: WebhookInput, options: MutationOptions): Promise<WebhookSecretReceipt>;
+    list(collectionId: string, options?: RequestOptions): Promise<{
+        items: Webhook[];
+    }>;
+    get(id: string, options?: RequestOptions): Promise<Webhook>;
+    update(id: string, input: WebhookUpdate, options?: RequestOptions): Promise<Webhook>;
+    remove(id: string, input: WebhookRevision, options?: RequestOptions): Promise<Webhook>;
+    rotate(id: string, input: WebhookRevision, options: MutationOptions): Promise<WebhookSecretReceipt>;
+    test(id: string, input: WebhookRevision, options: MutationOptions): Promise<WebhookDeliveryReceipt>;
+    deliveries(id: string, options?: RequestOptions & {
+        limit?: number;
+        offset?: number;
+    }): Promise<OffsetPage<WebhookDelivery>>;
+    replay(id: string, deliveryId: string, input: WebhookReplay, options: MutationOptions): Promise<WebhookDeliveryReceipt>;
+}
+export type WebhookSignatureInput = {
+    secret: string;
+    body: Uint8Array;
+    headers: {
+        'webhook-id': string;
+        'webhook-timestamp': string;
+        'webhook-signature': string;
+    };
+    toleranceSeconds?: number;
+    nowSeconds?: number;
+};
+/** Verifies raw bytes before JSON parsing. Delivery-ID deduplication is the receiver's responsibility. */
+export declare function verifyResearchWebhook(input: WebhookSignatureInput): Promise<{
+    deliveryId: string;
+    timestamp: number;
+} | null>;
+//# sourceMappingURL=webhooks.d.ts.map

package/dist/webhooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,SAAS,EAAsC,KAAK,eAAe,EAAC,KAAK,cAAc,EAAC,MAAM,gBAAgB,CAAC;AACvH,OAAO,KAAK,EAAC,UAAU,EAAC,OAAO,EAAC,eAAe,EAAC,sBAAsB,EAAC,YAAY,EAAC,aAAa,EAAC,eAAe,EAAC,oBAAoB,EAAC,aAAa,EAAC,MAAM,YAAY,CAAC;AAGxK,qBAAa,gBAAgB;IAChB,OAAO,CAAC,QAAQ,CAAC,SAAS;gBAAT,SAAS,EAAC,SAAS;IAChD,qFAAqF;IACrF,MAAM,CAAC,YAAY,EAAC,MAAM,EAAC,KAAK,EAAC,YAAY,EAAC,OAAO,EAAC,eAAe,GAAE,OAAO,CAAC,oBAAoB,CAAC;IAM9F,IAAI,CAAC,YAAY,EAAC,MAAM,EAAC,OAAO,GAAC,cAAiB,GAAE,OAAO,CAAC;QAAC,KAAK,EAAC,OAAO,EAAE,CAAA;KAAC,CAAC;IACpF,GAAG,CAAC,EAAE,EAAC,MAAM,EAAC,OAAO,GAAC,cAAiB,GAAE,OAAO,CAAC,OAAO,CAAC;IACzD,MAAM,CAAC,EAAE,EAAC,MAAM,EAAC,KAAK,EAAC,aAAa,EAAC,OAAO,GAAC,cAAiB,GAAE,OAAO,CAAC,OAAO,CAAC;IAChF,MAAM,CAAC,EAAE,EAAC,MAAM,EAAC,KAAK,EAAC,eAAe,EAAC,OAAO,GAAC,cAAiB,GAAE,OAAO,CAAC,OAAO,CAAC;IAClF,MAAM,CAAC,EAAE,EAAC,MAAM,EAAC,KAAK,EAAC,eAAe,EAAC,OAAO,EAAC,eAAe,GAAE,OAAO,CAAC,oBAAoB,CAAC;IAC7F,IAAI,CAAC,EAAE,EAAC,MAAM,EAAC,KAAK,EAAC,eAAe,EAAC,OAAO,EAAC,eAAe,GAAE,OAAO,CAAC,sBAAsB,CAAC;IACvF,UAAU,CAAC,EAAE,EAAC,MAAM,EAAC,OAAO,GAAC,cAAc,GAAC;QAAC,KAAK,CAAC,EAAC,MAAM,CAAC;QAAA,MAAM,CAAC,EAAC,MAAM,CAAA;KAAI,GAAE,OAAO,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC;IACzH,MAAM,CAAC,EAAE,EAAC,MAAM,EAAC,UAAU,EAAC,MAAM,EAAC,KAAK,EAAC,aAAa,EAAC,OAAO,EAAC,eAAe,GAAE,OAAO,CAAC,sBAAsB,CAAC;CAC/G;AAED,MAAM,MAAM,qBAAqB,GAAC;IAAC,MAAM,EAAC,MAAM,CAAC;IAAA,IAAI,EAAC,UAAU,CAAC;IAAA,OAAO,EAAC;QAAC,YAAY,EAAC,MAAM,CAAC;QAAA,mBAAmB,EAAC,MAAM,CAAC;QAAA,mBAAmB,EAAC,MAAM,CAAA;KAAC,CAAC;IAAA,gBAAgB,CAAC,EAAC,MAAM,CAAC;IAAA,UAAU,CAAC,EAAC,MAAM,CAAA;CAAC,CAAC;AAElM,0GAA0G;AAC1G,wBAAsB,qBAAqB,CAAC,KAAK,EAAC,qBAAqB,GAAE,OAAO,CAAC;IAAC,UAAU,EAAC,MAAM,CAAC;IAAA,SAAS,EAAC,MAAM,CAAA;CAAC,GAAC,IAAI,CAAC,CAa1H"}

package/dist/webhooks.js

@@ -0,0 +1,73 @@
+import { OpenCrawlProtocolError, OpenCrawlValidationError } from './errors.js';
+import { boundedInteger, idPath, idempotencyKey } from './transport.js';
+function revision(value) { boundedInteger(value.expected_revision, 'expected_revision', 1, Number.MAX_SAFE_INTEGER); }
+export class ResearchWebhooks {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /** A repeated successful create returns secret:null. It never rotates implicitly. */
+    create(collectionId, input, options) {
+        idempotencyKey(options?.idempotencyKey);
+        boundedInteger(input.expected_collection_revision, 'expected_collection_revision', 1, Number.MAX_SAFE_INTEGER);
+        let endpoint;
+        try {
+            endpoint = new URL(input.endpoint);
+        }
+        catch {
+            throw new OpenCrawlValidationError('The webhook endpoint must be an HTTPS URL.');
+        }
+        if (endpoint.protocol !== 'https:' || endpoint.username || endpoint.password || endpoint.search || endpoint.hash)
+            throw new OpenCrawlValidationError('The webhook endpoint must use HTTPS without credentials, query or fragment.');
+        return this.transport.request(`/api/research/collections/${idPath(collectionId)}/webhooks`, { ...options, method: 'POST', body: input });
+    }
+    async list(collectionId, options = {}) { const value = await this.transport.request(`/api/research/collections/${idPath(collectionId)}/webhooks`, options); if (!value || !Array.isArray(value.items))
+        throw new OpenCrawlProtocolError('OpenCrawl returned an invalid webhook list.'); return value; }
+    get(id, options = {}) { return this.transport.request(`/api/research/webhooks/${idPath(id)}`, options); }
+    update(id, input, options = {}) { revision(input); if (!['active', 'paused'].includes(input.status))
+        throw new OpenCrawlValidationError('status must be active or paused.'); return this.transport.request(`/api/research/webhooks/${idPath(id)}`, { ...options, method: 'PATCH', body: input }); }
+    remove(id, input, options = {}) { revision(input); return this.transport.request(`/api/research/webhooks/${idPath(id)}`, { ...options, method: 'DELETE', body: input }); }
+    rotate(id, input, options) { revision(input); idempotencyKey(options?.idempotencyKey); return this.transport.request(`/api/research/webhooks/${idPath(id)}/rotate`, { ...options, method: 'POST', body: input }); }
+    test(id, input, options) { revision(input); idempotencyKey(options?.idempotencyKey); return this.transport.request(`/api/research/webhooks/${idPath(id)}/test`, { ...options, method: 'POST', body: input }); }
+    async deliveries(id, options = {}) { const limit = boundedInteger(options.limit ?? 20, 'limit', 1, 50), offset = boundedInteger(options.offset ?? 0, 'offset', 0, 1000000); const value = await this.transport.request(`/api/research/webhooks/${idPath(id)}/deliveries?${new URLSearchParams({ limit: String(limit), offset: String(offset) })}`, options); if (!value || !Array.isArray(value.items) || !Number.isSafeInteger(value.total) || !Number.isSafeInteger(value.offset) || !Number.isSafeInteger(value.limit) || typeof value.has_more !== 'boolean')
+        throw new OpenCrawlProtocolError('OpenCrawl returned an invalid delivery page.'); return value; }
+    replay(id, deliveryId, input, options) { revision(input); boundedInteger(input.expected_replay_count, 'expected_replay_count', 0, Number.MAX_SAFE_INTEGER); idempotencyKey(options?.idempotencyKey); return this.transport.request(`/api/research/webhooks/${idPath(id)}/deliveries/${idPath(deliveryId)}/replay`, { ...options, method: 'POST', body: input }); }
+}
+function decode(value) { try {
+    if (!/^[A-Za-z0-9+/]+={0,2}$/.test(value) || value.length % 4 !== 0)
+        return null;
+    const bytes = Uint8Array.from(atob(value), character => character.charCodeAt(0));
+    return bytes.length === 32 ? bytes : null;
+}
+catch {
+    return null;
+} }
+/** Verifies raw bytes before JSON parsing. Delivery-ID deduplication is the receiver's responsibility. */
+export async function verifyResearchWebhook(input) {
+    if ('window' in globalThis && 'document' in globalThis)
+        throw new OpenCrawlValidationError('Verify webhook signatures on your server.');
+    const tolerance = boundedInteger(input.toleranceSeconds ?? 300, 'toleranceSeconds', 0, 3600), current = boundedInteger(input.nowSeconds ?? Math.floor(Date.now() / 1000), 'nowSeconds', 0, Number.MAX_SAFE_INTEGER);
+    const secret = typeof input.secret === 'string' && input.secret.startsWith('whsec_') ? decode(input.secret.slice(6)) : null;
+    if (!secret)
+        throw new OpenCrawlValidationError('A webhook signing secret is required.');
+    const headers = input.headers, id = headers?.['webhook-id'], rawTime = headers?.['webhook-timestamp'], signatures = headers?.['webhook-signature'];
+    if (typeof id !== 'string' || !/^[A-Za-z0-9_-]{1,200}$/.test(id) || typeof rawTime !== 'string' || !/^\d{1,16}$/.test(rawTime) || typeof signatures !== 'string' || signatures.length > 1024 || !(input.body instanceof Uint8Array) || input.body.byteLength > 16384)
+        return null;
+    const timestamp = Number(rawTime);
+    if (!Number.isSafeInteger(timestamp) || Math.abs(current - timestamp) > tolerance)
+        return null;
+    const candidates = signatures.split(/\s+/);
+    if (candidates.length > 10)
+        return null;
+    const prefix = new TextEncoder().encode(`${id}.${rawTime}.`), bytes = new Uint8Array(prefix.length + input.body.length);
+    bytes.set(prefix);
+    bytes.set(input.body, prefix.length);
+    const key = await crypto.subtle.importKey('raw', secret, { name: 'HMAC', hash: 'SHA-256' }, false, ['verify']);
+    for (const candidate of candidates) {
+        const signature = candidate.startsWith('v1,') ? decode(candidate.slice(3)) : null;
+        if (signature && await crypto.subtle.verify('HMAC', key, signature, bytes))
+            return { deliveryId: id, timestamp };
+    }
+    return null;
+}
+//# sourceMappingURL=webhooks.js.map

package/dist/webhooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"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"}

package/examples/letter-customer-research-demo.mjs

@@ -0,0 +1,54 @@
+/** Runnable offline composition. Node24: node letter-customer-research-demo.mjs --mock
+ * This fake transport never reaches a provider or API. Replace the authorization,
+ * encrypted vault, and durable provisioning receipt adapters in YOUR server;
+ * do not use the mock's in-memory vault for customer credentials.
+ */
+import {OpenCrawl} from '@getopencrawl/sdk';
+import {provisionCustomer} from './letter-service-tenants.mjs';
+import {LetterCustomerResearchStore} from './letter-customer-research-store.mjs';
+import {createLetterCustomerResearch} from './letter-customer-research.mjs';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {pathToFileURL} from 'node:url';
+
+export async function runCustomerResearchMock(){
+ const directory=fs.mkdtempSync(path.join(os.tmpdir(),'letter-research-mock-'));fs.chmodSync(directory,0o700);
+ const store=new LetterCustomerResearchStore(path.join(directory,'research.sqlite')),vault=new Map();
+ const customerId='customer_demo',tenantId='stn_'+'c'.repeat(32),agentId='ragent_'+'a'.repeat(32),runId='job_'+'b'.repeat(32),stamp='2026-10-24T00:00:00.000Z';
+ const childKey='synthetic-child-key-not-a-credential',parentKey='synthetic-parent-key-not-a-credential';
+ const brief={customer:{name:'Demo customer',website:'https://customer.example/',context:''},goal:'Find a documented workflow and preserve restrictions.',collection_ids:[],schedule_minutes:0};
+ const queued={id:runId,agent_id:agentId,agent_revision:1,status:'queued',phase:'queued',created_at:stamp,started_at:null,finished_at:null,outcome:null,findings:[],gaps:[],usage:{},error:null};
+ const agent={id:agentId,...brief,revision:1,status:'active',created_at:stamp,updated_at:stamp,latest_run:queued};
+ const finished={...queued,status:'partial',phase:'finished',started_at:stamp,finished_at:stamp,outcome:'no_supported_findings',gaps:['No supported findings were returned in this synthetic example.']};
+ const tenant={id:tenantId,external_customer_id:customerId,name:'Demo customer',workspace_id:'ws_demo',machine_user_id:'usr_demo',status:'active',access_state:'active',revision:1,provisioning_key_id:'parent_demo',credential:null,created_at:stamp,updated_at:stamp,revoked_at:null};
+ let admissions=0,reads=0;
+ const json=value=>new Response(JSON.stringify(value));
+ try{
+  // Host production code persists its exact provisioning descriptor/key BEFORE
+  // provisionCustomer. Recover uncertain receipts; missing first-response secret
+  // needs explicit rotation, never automatic tenant recreation. This mock has
+  // no credential lifecycle/remote provisioning and demonstrates composition only.
+  const parent=new OpenCrawl({baseUrl:'https://api.example.invalid',apiKey:parentKey,maxRetries:0,fetch:async()=>json({tenant,receipt:{id:'streq_demo',operation:'create',tenant_id:tenantId,target_revision:1,created_at:stamp},key:childKey,secret_available:true,replayed:false})});
+  await provisionCustomer(parent,{customerId,name:'Demo customer',createKey:'mock-provision-key-00001',secrets:{put:async(id,key)=>vault.set(id,key)},recordReceipt:async({tenant})=>store.bindCustomer({customerId,tenantId:tenant.id,secretRef:tenant.id,active:true})});
+  const recipe=createLetterCustomerResearch({store,baseUrl:parent.baseUrl,
+   authorize:async(session,id)=>session?.authenticated===true&&session.customerIds.includes(id),
+   // A real implementation resolves this logical reference via an encrypted
+   // server vault. This Map contains only deliberately synthetic mock values.
+   secrets:{get:async ref=>vault.get(ref)},
+   fetch:async(url,init)=>{
+    if(init.headers.Authorization!==`Bearer ${childKey}`)throw Error('Mock child isolation failed');
+    if(init.method==='POST'&&new URL(url).pathname==='/api/research/agents'){admissions++;return json({agent,run:queued,replayed:false})}
+    if(init.method!=='GET')throw Error('Unexpected mock write');reads++;
+    return new URL(url).search?json({items:[finished],next_cursor:'checkpoint_demo',has_more:false}):json(finished);
+   },
+  });
+  const session={authenticated:true,customerIds:[customerId]},accepted=await recipe.start(session,customerId,brief);
+  const saved=await recipe.read(session,customerId,accepted.runId),polled=await recipe.poll(session,customerId);
+  return {mock:true,admissions,reads,terminalStatus:saved.status,findings:saved.findings.length,pending:polled.pending,checkpointSaved:store.snapshot(customerId).cursor!==null,credentialsPersisted:false};
+ }finally{vault.clear();store.close();fs.rmSync(directory,{recursive:true,force:true})}
+}
+if(process.argv[1]&&import.meta.url===pathToFileURL(path.resolve(process.argv[1])).href){
+ if(process.argv.length!==3||process.argv[2]!=='--mock')throw new Error('Only --mock is available; import the recipe into your authorized server.');
+ try{console.log(JSON.stringify(await runCustomerResearchMock()))}catch{console.error('Mock recipe did not complete.');process.exitCode=1}
+}

package/examples/letter-customer-research-store.d.mts

@@ -0,0 +1,38 @@
+import type {ResearchAgent,ResearchAgentInput,ResearchAgentReceipt,ResearchAgentRun,ResearchAgentRunPage} from '@getopencrawl/sdk';
+export class CustomerResearchError extends Error { readonly code:string }
+export type CustomerResearchMapping={customerId:string;tenantId:string;secretRef:string;revision:number;active:boolean;agentId:string|null};
+export type CustomerResearchClaim={mapping:CustomerResearchMapping;token:string;until:number};
+export type CustomerResearchIntent={key:string;brief:ResearchAgentInput;receipt:Omit<ResearchAgentReceipt,'replayed'>|null};
+export type CustomerResearchRerunIntent={key:string;agentId:string;previousRunId:string;expectedRevision:number;runId:string|null;receiptHash:string|null;refusalStatus:409|429|null;refusalMappingRevision:number|null};
+/** Private local metadata/results database; never store credentials here. */
+export class LetterCustomerResearchStore {
+ constructor(filename:string,options?:{maxRuns?:number;maxBytes?:number;clock?:()=>number});
+ close():void;
+ /** Server administration only, after provisioning/receipt recovery. Bump on key rotation. */
+ bindCustomer(input:{customerId:string;tenantId:string;secretRef:string;active:boolean}):CustomerResearchMapping;
+ mapping(customerId:string):CustomerResearchMapping|null;
+ claim(customerId:string,leaseMs:number):CustomerResearchClaim;
+ check(claim:CustomerResearchClaim):void;
+ release(claim:CustomerResearchClaim):void;
+ intent(customerId:string):CustomerResearchIntent|null;
+ begin(claim:CustomerResearchClaim,brief:ResearchAgentInput):{key:string;brief:ResearchAgentInput};
+ accept(claim:CustomerResearchClaim,receipt:ResearchAgentReceipt):{agentId:string;runId:string};
+ rerunIntent(customerId:string,previousRunId:string):CustomerResearchRerunIntent|null;
+ retiredRerun(customerId:string,previousRunId:string):CustomerResearchRerunIntent|null;
+ /** Trusted metadata for explicit recovery after a restart, not evidence. */
+ pendingRerun(customerId:string):CustomerResearchRerunIntent|null;
+ beginRerun(claim:CustomerResearchClaim,previousRunId:string,agent:ResearchAgent):CustomerResearchRerunIntent;
+ acceptRerun(claim:CustomerResearchClaim,previousRunId:string,receipt:ResearchAgentReceipt):{agentId:string;runId:string};
+ refuseRerun(claim:CustomerResearchClaim,previousRunId:string,key:string,status:409|429):void;
+ retireRerun(claim:CustomerResearchClaim,previousRunId:string,key:string,agent:ResearchAgent):{refused:true;previousRunId:string};
+ saveRun(claim:CustomerResearchClaim,run:ResearchAgentRun):void;
+ commitPage(claim:CustomerResearchClaim,page:ResearchAgentRunPage):void;
+ cursor(customerId:string):string|undefined;
+ /** Next bounded batch, at most25 IDs. */
+ pending(customerId:string):string[];
+ pendingCount(customerId:string):number;
+ storedRuns(customerId:string,options?:{offset?:number;limit?:number}):{items:Array<{runId:string;status:ResearchAgentRun['status']}>;hasMore:boolean};
+ knowsRun(customerId:string,runId:string):boolean;
+ /** Metadata only; use the recipe's exact authorized read to display evidence. */
+ snapshot(customerId:string):{mapping:CustomerResearchMapping|null;intent:{key:string;accepted:boolean;agentId:string|null;runId:string|null}|null;cursor:string|null;pendingIds:string[];pendingCount:number;savedRuns:number};
+}

package/examples/letter-customer-research-store.mjs

@@ -0,0 +1,186 @@
+/** Node24 customer-side example store, never the OpenCrawl service database.
+ * Use a private local directory. Results are private plaintext source data;
+ * credentials belong only in the host's encrypted secret adapter.
+ */
+import {DatabaseSync} from 'node:sqlite';
+import {randomUUID,createHash} from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import {readResearchCompletion} from '../dist/researchCompletion.js';
+export class CustomerResearchError extends Error {
+ constructor(code){super(`Customer research: ${code}.`);this.name='CustomerResearchError';this.code=code;}
+}
+const fail=code=>{throw new CustomerResearchError(code)};
+const id=value=>typeof value==='string'&&/^[A-Za-z0-9_-]{1,200}$/.test(value);
+const positive=(value,max)=>Number.isSafeInteger(value)&&value>0&&value<=max;
+const pending=run=>run.status==='queued'||run.status==='running';
+const encoded=value=>JSON.stringify(value);
+const canonical=value=>value!==null&&typeof value==='object'?(Array.isArray(value)?value.map(canonical):Object.fromEntries(Object.keys(value).sort().map(key=>[key,canonical(value[key])]))):value;
+const same=(a,b)=>encoded(canonical(a))===encoded(canonical(b));
+export class LetterCustomerResearchStore {
+ #db;#clock;#maxRuns;#maxBytes;
+ constructor(filename,{maxRuns=1000,maxBytes=33554432,clock=()=>Date.now()}={}){
+  if(Number(process.versions.node.split('.')[0])<24||!path.isAbsolute(filename)||!positive(maxRuns,10000)||!positive(maxBytes,134217728))fail('invalid_store');
+  const parent=fs.lstatSync(path.dirname(filename));
+  if(!parent.isDirectory()||parent.isSymbolicLink()||(parent.mode&0o077)||parent.uid!==process.getuid?.())fail('private_directory_required');
+  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)||stat.uid!==process.getuid?.())fail('private_file_required');
+  this.#db=new DatabaseSync(filename);this.#clock=clock;this.#maxRuns=maxRuns;this.#maxBytes=maxBytes;
+  this.#db.exec(`PRAGMA foreign_keys=ON; PRAGMA synchronous=FULL; PRAGMA busy_timeout=1000;
+   CREATE TABLE IF NOT EXISTS lcr_customers(customer_id TEXT PRIMARY KEY,tenant_id TEXT UNIQUE NOT NULL,secret_ref TEXT UNIQUE NOT NULL,revision INTEGER NOT NULL,active INTEGER NOT NULL,agent_id TEXT,lease TEXT,lease_until INTEGER);
+   CREATE TABLE IF NOT EXISTS lcr_intents(customer_id TEXT PRIMARY KEY REFERENCES lcr_customers(customer_id),request_key TEXT UNIQUE NOT NULL,brief TEXT NOT NULL,receipt TEXT);
+   CREATE TABLE IF NOT EXISTS lcr_runs(customer_id TEXT NOT NULL REFERENCES lcr_customers(customer_id),run_id TEXT NOT NULL,agent_id TEXT NOT NULL,record TEXT NOT NULL,bytes INTEGER NOT NULL,pending INTEGER NOT NULL,PRIMARY KEY(customer_id,run_id));
+   CREATE TABLE IF NOT EXISTS lcr_cursors(customer_id TEXT PRIMARY KEY REFERENCES lcr_customers(customer_id),cursor TEXT NOT NULL);
+   CREATE TABLE IF NOT EXISTS lcr_rerun_intents(customer_id TEXT NOT NULL REFERENCES lcr_customers(customer_id),previous_run_id TEXT NOT NULL,request_key TEXT UNIQUE NOT NULL,agent_id TEXT NOT NULL,expected_revision INTEGER NOT NULL,run_id TEXT,receipt_hash TEXT,refusal_status INTEGER,refusal_mapping_revision INTEGER,PRIMARY KEY(customer_id,previous_run_id));
+   CREATE TABLE IF NOT EXISTS lcr_rerun_refusals(customer_id TEXT NOT NULL REFERENCES lcr_customers(customer_id),previous_run_id TEXT NOT NULL,request_key TEXT PRIMARY KEY,agent_id TEXT NOT NULL,expected_revision INTEGER NOT NULL,refusal_status INTEGER NOT NULL,refusal_mapping_revision INTEGER NOT NULL);`);
+  // Older local intents have no refusal witness; never infer one from absence.
+  const columns=this.#db.prepare('PRAGMA table_info(lcr_rerun_intents)').all().map(row=>row.name);
+  for(const column of ['refusal_status','refusal_mapping_revision'])if(!columns.includes(column))this.#db.exec(`ALTER TABLE lcr_rerun_intents ADD COLUMN ${column} INTEGER`);
+ }
+ close(){this.#db.close()}
+ #tx(fn){this.#db.exec('BEGIN IMMEDIATE');try{const value=fn();this.#db.exec('COMMIT');return value}catch(error){this.#db.exec('ROLLBACK');throw error}}
+ /** Trusted local administrative binding, not a web request. Provision/recover
+  * with the existing service-tenant helper first. Bump this generation whenever
+  * replacing a stored key, even if the secret reference itself is unchanged.
+  */
+ bindCustomer({customerId,tenantId,secretRef,active}){
+  if(typeof customerId!=='string'||!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(customerId)||typeof tenantId!=='string'||!/^stn_[0-9a-f]{32}$/.test(tenantId)||!id(secretRef)||typeof active!=='boolean')fail('invalid_mapping');
+  return this.#tx(()=>{
+   const old=this.mapping(customerId);
+   if(old&&old.tenantId!==tenantId)fail('mapping_identity_changed');
+   if(!old&&this.#db.prepare('SELECT COUNT(*) n FROM lcr_customers').get().n>=1000)fail('capacity');
+   this.#db.prepare(`INSERT INTO lcr_customers VALUES(?,?,?,?,?,NULL,NULL,NULL)
+    ON CONFLICT(customer_id) DO UPDATE SET secret_ref=excluded.secret_ref,revision=excluded.revision,active=excluded.active,lease=NULL,lease_until=NULL`).run(customerId,tenantId,secretRef,(old?.revision??0)+1,Number(active));
+   return this.mapping(customerId);
+  });
+ }
+ mapping(customerId){const r=this.#db.prepare('SELECT * FROM lcr_customers WHERE customer_id=?').get(customerId);return r?{customerId:r.customer_id,tenantId:r.tenant_id,secretRef:r.secret_ref,revision:r.revision,active:!!r.active,agentId:r.agent_id}:null}
+ claim(customerId,leaseMs){
+  if(typeof customerId!=='string'||!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(customerId)||!positive(leaseMs,65000))fail('invalid_operation');
+  return this.#tx(()=>{
+   const row=this.#db.prepare('SELECT * FROM lcr_customers WHERE customer_id=?').get(customerId);
+   if(!row?.active)fail('customer_unavailable');
+   if(row.lease&&row.lease_until>this.#clock())fail('busy');
+   const claim={mapping:this.mapping(customerId),token:randomUUID(),until:this.#clock()+leaseMs};
+   this.#db.prepare('UPDATE lcr_customers SET lease=?,lease_until=? WHERE customer_id=?').run(claim.token,claim.until,customerId);return claim;
+  });
+ }
+ check(claim){
+  const row=this.#db.prepare('SELECT * FROM lcr_customers WHERE customer_id=?').get(claim.mapping.customerId);
+  if(!row?.active||row.revision!==claim.mapping.revision||row.tenant_id!==claim.mapping.tenantId||row.secret_ref!==claim.mapping.secretRef||row.lease!==claim.token||row.lease_until<=this.#clock())fail('mapping_or_lease_changed');
+ }
+ release(claim){this.#db.prepare('UPDATE lcr_customers SET lease=NULL,lease_until=NULL WHERE customer_id=? AND lease=?').run(claim.mapping.customerId,claim.token)}
+ intent(customerId){const r=this.#db.prepare('SELECT * FROM lcr_intents WHERE customer_id=?').get(customerId);return r?{key:r.request_key,brief:JSON.parse(r.brief),receipt:r.receipt?JSON.parse(r.receipt):null}:null}
+ begin(claim,brief){return this.#tx(()=>{
+  this.check(claim);
+  if(this.intent(claim.mapping.customerId)||this.mapping(claim.mapping.customerId).agentId)fail('intent_exists_use_recovery');
+  const value=encoded(brief);if(Buffer.byteLength(value)>32768)fail('brief_too_large');
+  const key=randomUUID();
+  this.#db.prepare('INSERT INTO lcr_intents VALUES(?,?,?,NULL)').run(claim.mapping.customerId,key,value);
+  return {key,brief:JSON.parse(value)};
+ })}
+ accept(claim,value){return this.#tx(()=>{
+  this.check(claim);const customer=claim.mapping.customerId,intent=this.intent(customer);
+  if(!intent)fail('missing_intent');
+  const {agent,run}=value,brief={customer:agent.customer,goal:agent.goal,collection_ids:agent.collection_ids,schedule_minutes:agent.schedule_minutes};
+  if(Object.hasOwn(intent.brief,'research_policy')){
+   // Policy is per run, not an agent field. The immutable create receipt carries
+   // admitted metadata on both run views; never certify policy from intent alone.
+   const completion=readResearchCompletion(run).completion,latest=readResearchCompletion(agent.latest_run).completion;
+   if(!['completion_v1','completion_v2','completion_v3'].includes(intent.brief.research_policy)||!completion||completion.policy!==intent.brief.research_policy||completion.reason!=='admitted'||!same(completion,latest))fail('receipt_mismatch');
+   brief.research_policy=completion.policy;
+  }
+  if(!same(brief,intent.brief)||agent.revision!==1||run.agent_id!==agent.id||agent.latest_run?.id!==run.id)fail('receipt_mismatch');
+  const receipt={agent,run};
+  if(intent.receipt&&!same(intent.receipt,receipt))fail('receipt_mismatch');
+  const old=this.mapping(customer).agentId;if(old&&old!==agent.id)fail('receipt_mismatch');
+  this.#db.prepare('UPDATE lcr_customers SET agent_id=? WHERE customer_id=?').run(agent.id,customer);
+  this.#db.prepare('UPDATE lcr_intents SET receipt=? WHERE customer_id=?').run(encoded(receipt),customer);
+  // Recovering an old queued receipt must never overwrite a newer saved result.
+  if(!this.#db.prepare('SELECT 1 FROM lcr_runs WHERE customer_id=? AND run_id=?').get(customer,run.id))this.#put(customer,agent.id,run);
+  return {agentId:agent.id,runId:run.id};
+ })}
+ /** Trusted metadata only. Each predecessor identifies one deliberate rerun. */
+ rerunIntent(customerId,previousRunId){const r=this.#db.prepare('SELECT * FROM lcr_rerun_intents WHERE customer_id=? AND previous_run_id=?').get(customerId,previousRunId);return r?{key:r.request_key,agentId:r.agent_id,previousRunId:r.previous_run_id,expectedRevision:r.expected_revision,runId:r.run_id,receiptHash:r.receipt_hash,refusalStatus:r.refusal_status,refusalMappingRevision:r.refusal_mapping_revision}:null}
+ retiredRerun(customerId,previousRunId){const r=this.#db.prepare('SELECT * FROM lcr_rerun_refusals WHERE customer_id=? AND previous_run_id=? ORDER BY rowid DESC LIMIT 1').get(customerId,previousRunId);return r?{key:r.request_key,agentId:r.agent_id,previousRunId:r.previous_run_id,expectedRevision:r.expected_revision,runId:null,receiptHash:null,refusalStatus:r.refusal_status,refusalMappingRevision:r.refusal_mapping_revision}:null}
+ pendingRerun(customerId){const r=this.#db.prepare('SELECT previous_run_id FROM lcr_rerun_intents WHERE customer_id=? AND receipt_hash IS NULL').get(customerId);return r?this.rerunIntent(customerId,r.previous_run_id):null}
+ #sameBrief(customer,agent){const original=this.intent(customer)?.receipt?.agent;return original&&same([agent.customer,agent.goal,agent.collection_ids],[original.customer,original.goal,original.collection_ids])}
+ beginRerun(claim,previousRunId,agent){return this.#tx(()=>{
+  this.check(claim);const customer=claim.mapping.customerId,agentId=this.mapping(customer).agentId;
+  if(!agentId||!this.knowsRun(customer,previousRunId))fail('unknown_run');
+  if(this.rerunIntent(customer,previousRunId)||this.pendingRerun(customer))fail('rerun_exists_use_recovery');
+  if(agent.id!==agentId||!this.#sameBrief(customer,agent))fail('rerun_scope_mismatch');
+  if(agent.status!=='active'||agent.latest_run?.id!==previousRunId||pending(agent.latest_run)||!positive(agent.revision,Number.MAX_SAFE_INTEGER))fail('rerun_predecessor_changed');
+  if(this.#db.prepare('SELECT (SELECT COUNT(*) FROM lcr_rerun_intents)+(SELECT COUNT(*) FROM lcr_rerun_refusals) n').get().n>=this.#maxRuns||this.#db.prepare('SELECT COUNT(*) n FROM lcr_runs').get().n>=this.#maxRuns)fail('capacity');
+  // Persist the fresh predecessor and new intent atomically before any POST.
+  this.#put(customer,agentId,agent.latest_run);
+  const key=randomUUID();
+  this.#db.prepare('INSERT INTO lcr_rerun_intents(customer_id,previous_run_id,request_key,agent_id,expected_revision) VALUES(?,?,?,?,?)').run(customer,previousRunId,key,agentId,agent.revision);
+  return this.rerunIntent(customer,previousRunId);
+ })}
+ acceptRerun(claim,previousRunId,value){return this.#tx(()=>{
+  this.check(claim);const customer=claim.mapping.customerId,intent=this.rerunIntent(customer,previousRunId);
+  if(!intent)fail('missing_rerun_intent');
+  const {agent,run}=value;
+  if(this.mapping(customer).agentId!==intent.agentId||agent.id!==intent.agentId||!this.#sameBrief(customer,agent)||agent.revision!==intent.expectedRevision||run.agent_id!==intent.agentId||run.agent_revision!==intent.expectedRevision||run.id===previousRunId||run.status!=='queued'||!same(agent.latest_run,run))fail('receipt_mismatch');
+  const digest=createHash('sha256').update(encoded(canonical({agent,run}))).digest('hex');
+  if(intent.receiptHash&&(intent.receiptHash!==digest||intent.runId!==run.id))fail('receipt_mismatch');
+  this.#db.prepare('UPDATE lcr_rerun_intents SET run_id=?,receipt_hash=? WHERE customer_id=? AND previous_run_id=?').run(run.id,digest,customer,previousRunId);
+  // A historical queued receipt must not replace a newer exact run read.
+  if(!this.knowsRun(customer,run.id))this.#put(customer,intent.agentId,run);
+  return {agentId:intent.agentId,runId:run.id};
+ })}
+ /** Called only for the original POST's observed HTTP409/429, after authority. */
+ refuseRerun(claim,previousRunId,key,status){return this.#tx(()=>{
+  this.check(claim);const customer=claim.mapping.customerId,intent=this.rerunIntent(customer,previousRunId);
+  if(!intent||intent.key!==key||intent.runId||intent.receiptHash||![409,429].includes(status))fail('rerun_not_refused');
+  this.#db.prepare('UPDATE lcr_rerun_intents SET refusal_status=?,refusal_mapping_revision=? WHERE customer_id=? AND previous_run_id=? AND request_key=?').run(status,claim.mapping.revision,customer,previousRunId,key);
+ })}
+ /** Explicit recovery proved this refused key absent and freshly read its agent. */
+ retireRerun(claim,previousRunId,key,agent){return this.#tx(()=>{
+  this.check(claim);const customer=claim.mapping.customerId,active=this.rerunIntent(customer,previousRunId),intent=active??this.retiredRerun(customer,previousRunId);
+  if(!intent||intent.key!==key||intent.runId||intent.receiptHash||![409,429].includes(intent.refusalStatus)||intent.refusalMappingRevision!==claim.mapping.revision)fail('rerun_not_refused');
+  if(intent.agentId!==this.mapping(customer).agentId||agent.id!==intent.agentId||!this.#sameBrief(customer,agent))fail('rerun_scope_mismatch');
+  if(active){
+   this.#db.prepare('INSERT INTO lcr_rerun_refusals VALUES(?,?,?,?,?,?,?)').run(customer,previousRunId,key,intent.agentId,intent.expectedRevision,intent.refusalStatus,intent.refusalMappingRevision);
+   this.#db.prepare('DELETE FROM lcr_rerun_intents WHERE customer_id=? AND previous_run_id=? AND request_key=?').run(customer,previousRunId,key);
+  }
+  return {refused:true,previousRunId};
+ })}
+ #put(customer,agentId,run){
+  if(run.agent_id!==agentId||!id(run.id))fail('run_scope_mismatch');
+  const body=encoded(run),bytes=Buffer.byteLength(body);if(bytes>131072)fail('run_too_large');
+  const old=this.#db.prepare('SELECT * FROM lcr_runs WHERE customer_id=? AND run_id=?').get(customer,run.id);
+  if(old&&old.agent_id!==agentId)fail('run_scope_mismatch');
+  // Admission pages can repeat a stale pending snapshot after an exact read.
+  if(old&&!old.pending){if(pending(run))return;if(!same(JSON.parse(old.record),run))fail('terminal_run_changed');return}
+  const usage=this.#db.prepare('SELECT COUNT(*) n,COALESCE(SUM(bytes),0) bytes FROM lcr_runs').get();
+  if(!old&&usage.n>=this.#maxRuns||usage.bytes-(old?.bytes??0)+bytes>this.#maxBytes)fail('capacity');
+  this.#db.prepare(`INSERT INTO lcr_runs VALUES(?,?,?,?,?,?) ON CONFLICT(customer_id,run_id) DO UPDATE SET record=excluded.record,bytes=excluded.bytes,pending=excluded.pending`).run(customer,run.id,agentId,body,bytes,Number(pending(run)));
+ }
+ saveRun(claim,run){return this.#tx(()=>{this.check(claim);const agentId=this.mapping(claim.mapping.customerId).agentId;if(!agentId)fail('missing_agent');this.#put(claim.mapping.customerId,agentId,run)})}
+ commitPage(claim,page){return this.#tx(()=>{
+  this.check(claim);const customer=claim.mapping.customerId,agentId=this.mapping(customer).agentId;
+  if(!agentId)fail('missing_agent');
+  for(const run of page.items)this.#put(customer,agentId,run);
+  this.#db.prepare('INSERT INTO lcr_cursors VALUES(?,?) ON CONFLICT(customer_id) DO UPDATE SET cursor=excluded.cursor').run(customer,page.next_cursor);
+ })}
+ cursor(customerId){return this.#db.prepare('SELECT cursor FROM lcr_cursors WHERE customer_id=?').get(customerId)?.cursor}
+ pendingCount(customerId){return this.#db.prepare('SELECT COUNT(*) n FROM lcr_runs WHERE customer_id=? AND pending=1').get(customerId).n}
+ pending(customerId){return this.#db.prepare('SELECT run_id FROM lcr_runs WHERE customer_id=? AND pending=1 ORDER BY rowid LIMIT 25').all(customerId).map(r=>r.run_id)}
+ knowsRun(customerId,runId){return !!this.#db.prepare('SELECT 1 FROM lcr_runs WHERE customer_id=? AND run_id=?').get(customerId,runId)}
+ /** Trusted local metadata enumeration after host authorization. No source
+  * text is returned; use the recipe's fresh exact read for display. This local
+  * offset is not an OpenCrawl admission cursor or completion-delivery promise.
+  */
+ storedRuns(customerId,{offset=0,limit=25}={}){
+  if(!Number.isSafeInteger(offset)||offset<0||offset>10000||!positive(limit,25))fail('invalid_page');
+  const rows=this.#db.prepare('SELECT run_id,record FROM lcr_runs WHERE customer_id=? ORDER BY rowid LIMIT ? OFFSET ?').all(customerId,limit+1,offset);
+  return {items:rows.slice(0,limit).map(row=>({runId:row.run_id,status:JSON.parse(row.record).status})),hasMore:rows.length>limit};
+ }
+ /** Metadata only. Use recipe.read() for an authorized remote result; local
+  * persisted evidence is never an automatic fallback on remote denial.
+  */
+ snapshot(customerId){const mapping=this.mapping(customerId),intent=this.intent(customerId);return {mapping,intent:intent?{key:intent.key,accepted:!!intent.receipt,agentId:intent.receipt?.agent.id??null,runId:intent.receipt?.run.id??null}:null,cursor:this.cursor(customerId)??null,pendingIds:this.pending(customerId),pendingCount:this.pendingCount(customerId),savedRuns:this.#db.prepare('SELECT COUNT(*) n FROM lcr_runs WHERE customer_id=?').get(customerId).n}}
+}

package/examples/letter-customer-research.d.mts

@@ -0,0 +1,39 @@
+import type {Fetch,ResearchAgentInput,ResearchAgentRun,ResearchAgentSourceReceipt,ResearchAgentSchedule} from '@getopencrawl/sdk';
+import type {ResearchAgentFeedbackInput,ResearchAgentFeedbackReceipt} from '@getopencrawl/sdk';
+import type {LetterCustomerResearchStore} from './letter-customer-research-store.mjs';
+import {CustomerResearchError} from './letter-customer-research-store.mjs';
+export type CustomerResearchRemoteCode='request_rejected'|'authentication_required'|'access_denied'|'source_not_retained'|'not_found'|'conflict'|'rate_limited';
+/** Finite known HTTP refusal. No response body or cause. It never permits
+ * replay of a saved admission intent or an uncertain mutation. */
+export class CustomerResearchRemoteError extends CustomerResearchError {
+ constructor(code:CustomerResearchRemoteCode,status:number);
+ readonly status:number;
+}
+export type CustomerResearchOptions={signal?:AbortSignal;timeoutMs?:number};
+export type LetterCustomerResearch<Context>={
+ start(context:Context,customerId:string,input:ResearchAgentInput,options?:CustomerResearchOptions):Promise<{agentId:string;runId:string}>;
+ recover(context:Context,customerId:string,options?:CustomerResearchOptions):Promise<{agentId:string;runId:string}>;
+ /** Deliberately repeat the same brief after this known latest terminal run. */
+ rerun(context:Context,customerId:string,previousRunId:string,options?:CustomerResearchOptions):Promise<{agentId:string;runId:string}>;
+ /** GET-only recovery. A confirmed refusal can be retired explicitly; a new
+  * deliberate rerun is a separate action, never performed by this method. */
+ recoverRerun(context:Context,customerId:string,previousRunId:string,options?:CustomerResearchOptions):Promise<{agentId:string;runId:string}|{refused:true;previousRunId:string}>;
+ read(context:Context,customerId:string,runId:string,options?:CustomerResearchOptions):Promise<ResearchAgentRun>;
+ source(context:Context,customerId:string,runId:string,sourceId:string,options?:CustomerResearchOptions):Promise<ResearchAgentSourceReceipt>;
+ schedule(context:Context,customerId:string,options?:CustomerResearchOptions):Promise<ResearchAgentSchedule>;
+ setSchedule(context:Context,customerId:string,input:{expected_revision:number;enabled:boolean},options?:CustomerResearchOptions):Promise<ResearchAgentSchedule>;
+ feedback(context:Context,customerId:string,runId:string,findingId:string,options?:CustomerResearchOptions):Promise<ResearchAgentFeedbackReceipt>;
+ setFeedback(context:Context,customerId:string,runId:string,findingId:string,input:ResearchAgentFeedbackInput,options?:CustomerResearchOptions):Promise<ResearchAgentFeedbackReceipt>;
+ deleteFeedback(context:Context,customerId:string,runId:string,findingId:string,expectedRevision:number,options?:CustomerResearchOptions):Promise<ResearchAgentFeedbackReceipt>;
+ poll(context:Context,customerId:string,options?:CustomerResearchOptions):Promise<{received:number;checkedPending:number;hasMoreAdmissions:boolean;pending:number;observedRunIds:string[]}>;
+};
+/** Server-only, Node24. The host must authorize each customer using trusted
+ * request/session context and resolve secret references to encrypted storage.
+ * No automatic tenant provisioning, create replay, daily runs or timers.
+ */
+export function createLetterCustomerResearch<Context>(options:{
+ store:LetterCustomerResearchStore;baseUrl:string;
+ authorize:(context:Context,customerId:string)=>Promise<boolean>;
+ secrets:{get:(secretRef:string)=>Promise<string|null|undefined>};
+ fetch?:Fetch;
+}):LetterCustomerResearch<Context>;