@reclaimprotocol/agent 0.1.1 → 0.1.3

package/src/provider/to-version.ts

@@ -3,7 +3,51 @@ import type {
 	CreateProviderVersionRequest,
 	ProviderVersionRef,
 } from '@reclaimprotocol/client/openapi'
-import type { ReclaimProvider } from './schema.ts'
+import type {
+	HttpMethod,
+	ReclaimProvider,
+	ResponseMatch,
+	ResponseRedaction,
+} from './schema.ts'
+import { DYNAMIC_GEO, normalizeGeoLocation } from './schema.ts'
+
+/** One entry of the version's `requests[]` (a `RequestSelection`), derived
+ *  from the openapi type so it can't drift from what the server accepts. */
+type RequestSelection = CreateProviderVersionRequest['requests'][number]
+
+/** The subset of a draft a request selection is built from — the only fields
+ *  `providerToRequestSelection` reads. A full `ReclaimProvider` satisfies it,
+ *  as does a lighter injected-request draft (no `name`/`paramValues`). */
+export interface DraftRequest {
+	url: string
+	method: HttpMethod
+	body?: string
+	writeRedactionMode?: ReclaimProvider['writeRedactionMode']
+	additionalClientOptions?: ReclaimProvider['additionalClientOptions']
+	responseMatches?: ResponseMatch[]
+	responseRedactions?: ResponseRedaction[]
+}
+
+/** A request the page's injection script is allowed to fire, plus the
+ *  pagination/optionality flags of `RequestSelectionTemplate`. Reuses the
+ *  shared `DraftRequest` shape — no provider `name`/`paramValues` required. */
+export interface AllowedJsRequest extends DraftRequest {
+	/** Allow the template to match many requests (e.g. pagination). Default
+	 *  true. */
+	multiple?: boolean
+	/** Fail validation if no request matches this template. Default true. */
+	required?: boolean
+}
+
+/** Optional extras for a create-version body beyond the request list. */
+export interface CreateVersionOptions {
+	notes?: string
+	version?: ProviderVersionRef
+	/** JS injected before every page load (`webSettings.jsUserScripts`). */
+	jsUserScripts?: string
+	/** Requests the injection script may fire, as `RequestSelectionTemplate`s. */
+	allowedJsRequests?: AllowedJsRequest[]
+}
 
 /**
  * Translate a drafted ReclaimProvider into the body for
@@ -24,15 +68,29 @@ const CONTEXT_PARAM_RE = /\{\{context\.([A-Za-z_][A-Za-z0-9_]*)\}\}/g
 
 /**
  * Derive the version's `requiredContext` JSON Schema from the
- * `{{context.<name>}}` placeholders in the provider's url/body — mechanical,
- * so a published recipe can never reference a context value the Builder
- * doesn't require. Returns undefined when the recipe has none (the field is
- * optional). Authors can refine types/descriptions in the version editor.
+ * `{{context.<name>}}` placeholders across EVERY request's url/body (plus any
+ * injected requests and the injection script) — mechanical, so a published
+ * recipe can never reference a context value the Builder doesn't require.
+ * Returns undefined when nothing references context (the field is optional).
+ * Authors can refine types/descriptions in the version editor.
  */
 export function deriveRequiredContext(
-	provider: ReclaimProvider,
+	providers: ReclaimProvider[],
+	injection: {
+		allowedJsRequests?: AllowedJsRequest[]
+		jsUserScripts?: string
+	} = {},
 ): CreateProviderVersionRequest['requiredContext'] {
-	const haystack = `${provider.url}\n${provider.body ?? ''}`
+	const parts: string[] = []
+	for(const p of [...providers, ...(injection.allowedJsRequests ?? [])]) {
+		parts.push(p.url, p.body ?? '')
+	}
+
+	if(injection.jsUserScripts) {
+		parts.push(injection.jsUserScripts)
+	}
+
+	const haystack = parts.join('\n')
 	const names = new Set<string>()
 	for(const m of haystack.matchAll(CONTEXT_PARAM_RE)) {
 		names.add(m[1])
@@ -50,42 +108,90 @@ export function deriveRequiredContext(
 	return { type: 'object', required: [...names], properties }
 }
 
+/**
+ * Translate one drafted request into a `RequestSelection`. Shared by the
+ * top-level `requests` and by `allowedJsRequests`.
+ *
+ * `responseMatches`/`responseRedactions` are INDEPENDENT parallel arrays,
+ * isomorphic to the attestor's `ProviderParams<'http'>` (no nested fold).
+ * `responseRedactions` decide which portions of the response are revealed;
+ * `responseMatches` then run against the union of the revealed content. Neither
+ * depends on the other's length or order, so both pass through untouched.
+ * (The old-devtools translator has its own opt-in index-pairing concern; the
+ * builder deliberately does not.)
+ */
+export function providerToRequestSelection(
+	provider: DraftRequest,
+): RequestSelection {
+	const responseMatches = (provider.responseMatches ?? []).map((match) => ({
+		type: match.type,
+		value: match.value,
+		isOptional: false,
+	}))
+	const responseRedactions = provider.responseRedactions ?? []
+
+	return {
+		url: provider.url,
+		method: provider.method,
+		credentials: 'include',
+		...(provider.body ? { requestBodyTemplate: provider.body } : {}),
+		...(provider.writeRedactionMode
+			? { writeRedactionMode: provider.writeRedactionMode }
+			: {}),
+		...(provider.additionalClientOptions
+			? { additionalClientOptions: provider.additionalClientOptions }
+			: {}),
+		...(responseMatches.length > 0 ? { responseMatches } : {}),
+		...(responseRedactions.length > 0 ? { responseRedactions } : {}),
+	}
+}
+
+/** First provider that declares an explicit (non-default) egress wins; if none
+ *  do, fall back to DYNAMIC_GEO (resolved to the verifying user's country). */
+function pickGeoLocation(providers: ReclaimProvider[]): string {
+	for(const provider of providers) {
+		const geo = normalizeGeoLocation(provider.geoLocation)
+		if(geo) {
+			return geo
+		}
+	}
+
+	return DYNAMIC_GEO
+}
+
 export function providerToCreateVersionRequest(
-	provider: ReclaimProvider,
+	providers: ReclaimProvider[],
 	initialUrl: string,
-	notes?: string,
-	version?: ProviderVersionRef,
+	opts: CreateVersionOptions = {},
 ): CreateProviderVersionRequest {
-	const requiredContext = deriveRequiredContext(provider)
-	// Inline responseRedactions into matches[*].extract (1-to-1 by index).
-	const matches = (provider.responseMatches ?? []).map((match, i) => {
-		const redaction = provider.responseRedactions?.[i]
-		return {
-			type: match.type,
-			value: match.value,
-			isOptional: false,
-			...(redaction ? { extract: redaction } : {}),
-		}
+	const { notes, version, jsUserScripts, allowedJsRequests } = opts
+	const requiredContext = deriveRequiredContext(providers, {
+		allowedJsRequests,
+		jsUserScripts,
 	})
 
+	// Each injected request carries its template flags (default true/true per
+	// RequestSelectionTemplate) on top of the shared request shape.
+	const allowedJs = (allowedJsRequests ?? []).map((req) => ({
+		...providerToRequestSelection(req),
+		multiple: req.multiple ?? true,
+		required: req.required ?? true,
+	}))
+	const script = jsUserScripts?.trim()
+
 	return {
 		version: version ?? { major: 1, minor: 0, patch: 0 },
 		initialUrl,
-		requests: [
-			{
-				url: provider.url,
-				method: provider.method,
-				credentials: 'include',
-				...(provider.body ? { requestBodyTemplate: provider.body } : {}),
-				...(matches.length > 0 ? { matches } : {}),
-			},
-		],
-		allowedJsRequests: [],
+		// Every drafted provider becomes one request — the recipe runs them all.
+		requests: providers.map(providerToRequestSelection),
+		allowedJsRequests: allowedJs,
 		// Mirror the builder openapi defaults explicitly — the server does not
 		// apply schema defaults to request bodies.
 		webSettings: {
-			geoLocation: '{{DYNAMIC_GEO}}',
+			geoLocation: pickGeoLocation(providers),
 			clientOptions: { portal: { useProxy: true } },
+			// Only set when non-empty; an empty string would store a no-op script.
+			...(script ? { jsUserScripts: script } : {}),
 		},
 		// Derived from `{{context.<name>}}` placeholders only — a captured
 		// provider's `paramValues` are extracted response parameters, not