@reclaimprotocol/client 0.1.0-dev.1

package/lib/types/openapi.gen.js

@@ -0,0 +1,5 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+export {};

package/lib/types/openapi.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,56 @@
+{
+	"name": "@reclaimprotocol/client",
+	"title": "Reclaim Client",
+	"version": "0.1.0-dev.1",
+	"description": "Typed SDK client for @reclaimprotocol/app. Used by @reclaimprotocol/agent and any other consumer that needs programmatic API access without the full agent.",
+	"type": "module",
+	"main": "./lib/index.js",
+	"types": "./lib/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./lib/index.d.ts",
+			"import": "./lib/index.js"
+		}
+	},
+	"files": [
+		"lib",
+		"src",
+		"README.md",
+		"LICENSE"
+	],
+	"engines": {
+		"node": ">=20"
+	},
+	"repository": {
+		"url": "https://github.com/reclaimprotocol/builder",
+		"type": "git"
+	},
+	"websiteUrl": "https://docs.reclaimprotocol.org",
+	"scripts": {
+		"build": "tsc",
+		"openapi:typegen": "openapi-typescript ../app/openapi.yaml --output ./src/types/openapi.gen.ts && node ../app/scripts/mcp-tools-gen.ts",
+		"prepublishOnly": "npm run build",
+		"dev": "tsc --watch",
+		"test": "node --test tests/*.test.ts"
+	},
+	"keywords": [
+		"sdk",
+		"reclaimprotocol",
+		"verification",
+		"http-client"
+	],
+	"author": {
+		"name": "Reclaim Protocol",
+		"email": "support@reclaimprotocol.org"
+	},
+	"license": "MIT",
+	"dependencies": {
+		"@hapi/boom": "^9.1.4"
+	},
+	"devDependencies": {
+		"@types/node": "^24.0.0",
+		"openapi-typescript": "^7.13.0",
+		"typescript": "^5.9.0",
+		"yaml": "^2.6.0"
+	}
+}

package/src/client.ts

@@ -0,0 +1,146 @@
+import { notFound } from '@hapi/boom'
+import assert from 'node:assert'
+import type {
+	IOperationArgs,
+	IOperationId,
+	IOperationResponse,
+} from './types/openapi.ts'
+import { DEFAULT_BASE_URL, USER_AGENT } from './consts.ts'
+import { throwProblemError } from './errors.ts'
+// `ROUTES` is generated from `packages/app/openapi.yaml` and is the
+// single source of method/path mapping for every operation. New
+// endpoints added to the spec are picked up by re-running
+// `npm run openapi:typegen --workspace=packages/client`.
+import { ROUTES } from './routes.gen.ts'
+
+export type ReclaimClientOptions = {
+	/** Backend base URL. Defaults to {@link DEFAULT_BASE_URL}. */
+	baseUrl?: string
+	/** Bearer token for authenticated operations. */
+	token?: string
+	/** Custom fetch implementation. Defaults to global `fetch`. */
+	fetch?: typeof fetch
+	/** Extra headers merged into every request. */
+	headers?: Record<string, string>
+}
+
+/**
+ * Core HTTP client. Shared by the SDK entrypoint, MCP server, and CLI —
+ * extend behaviour here rather than duplicating it across surfaces.
+ *
+ * Per @reclaimprotocol/app conventions, validation lives in the openapi
+ * spec; this client forwards requests and maps RFC 9457 problem responses
+ * to {@link ProblemError}.
+ */
+export class ReclaimClient {
+	readonly baseUrl: string
+	#token: string | undefined
+	#fetch: typeof fetch
+	#headers: Record<string, string>
+
+	constructor(opts: ReclaimClientOptions = {}) {
+		this.baseUrl = (opts.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, '')
+		this.#token = opts.token
+		this.#fetch = opts.fetch || fetch
+		this.#headers = {
+			'User-Agent': USER_AGENT,
+			Accept: 'application/json',
+			...opts.headers,
+		}
+	}
+
+	setToken(token: string | undefined) {
+		this.#token = token
+	}
+
+	getToken() {
+		return this.#token
+	}
+
+	async call<T extends IOperationId>(
+		operationId: T,
+		...argsRest: {} extends IOperationArgs<T>
+			? [args?: IOperationArgs<T>]
+			: [args: IOperationArgs<T>]
+	): Promise<{ data: IOperationResponse<T>, response: Response }> {
+		const args = argsRest[0] ?? {} as IOperationArgs<T>
+		const op = ROUTES[operationId] as
+			| { method: string, path: string }
+			| undefined
+		assert(op, notFound(`Unknown operation: ${String(operationId)}`))
+
+		let url = `${this.baseUrl}${op.path}`
+		if(args.params) {
+			for(const [key, value] of Object.entries(args.params)) {
+				url = url.replace(`{${key}}`, String(value))
+			}
+		}
+
+		if(args.query && Object.keys(args.query).length > 0) {
+			const search = new URLSearchParams()
+			for(const [key, value] of Object.entries(args.query)) {
+				if(value === undefined || value === null) {
+					continue
+				}
+
+				if(Array.isArray(value)) {
+					for(const v of value) {
+						search.append(key, String(v))
+					}
+				} else {
+					search.append(key, String(value))
+				}
+			}
+
+			url += `?${search.toString()}`
+		}
+
+		const headers: Record<string, string> = {
+			...this.#headers,
+			Accept: 'application/json',
+		}
+		if(this.#token) {
+			headers['Authorization'] = `Bearer ${this.#token}`
+		}
+
+		// Per-request header parameters (e.g. `If-Match` for optimistic
+		// concurrency). Applied last so spec-declared headers win over the
+		// client-wide defaults, but never override Authorization.
+		if(args.headers) {
+			for(const [key, value] of Object.entries(args.headers)) {
+				if(value === undefined || value === null) {
+					continue
+				}
+
+				headers[key] = String(value)
+			}
+		}
+
+		const init: RequestInit = {
+			method: op.method.toUpperCase(),
+			headers,
+		}
+		// Write methods always carry a JSON body (defaulting to `{}`) plus a
+		// Content-Type. Some endpoints — e.g. the auth-only attach session —
+		// take an empty body, and omitting Content-Type makes the server
+		// reject the request with `415 unsupported media type`.
+		const method = op.method.toLowerCase()
+		if(method !== 'get' && method !== 'head') {
+			init.body = JSON.stringify(args.body ?? {})
+			headers['Content-Type'] = 'application/json'
+		}
+
+		const res = await this.#fetch(url, init)
+
+		if(!res.ok) {
+			await throwProblemError(res)
+		}
+
+		if(res.status === 204 || res.headers.get('content-length') === '0') {
+			return { data: undefined as IOperationResponse<T>, response: res }
+		}
+
+		const data = await res.json() as IOperationResponse<T>
+		return { data, response: res }
+	}
+}

package/src/consts.ts

@@ -0,0 +1,6 @@
+// TODO: Update to production url
+export const DEFAULT_BASE_URL = 'http://localhost:4001'
+
+export const USER_AGENT = '@reclaimprotocol/client'
+
+export const PROBLEM_CONTENT_TYPE = 'application/problem+json'

package/src/errors.ts

@@ -0,0 +1,30 @@
+import { Boom } from '@hapi/boom'
+import type { ProblemDetails } from './types/openapi.ts'
+import { PROBLEM_CONTENT_TYPE } from './consts.ts'
+export type { ProblemDetails } from './types/openapi.ts'
+
+export type ProblemError = Boom<ProblemDetails>
+
+// Reads an `application/problem+json` response and throws a Boom-style
+// error. Falls back to status-only mapping when the body isn't a problem doc.
+export async function throwProblemError(res: Response): Promise<void> {
+	const contentType = res.headers.get('Content-Type') || ''
+	let problem: ProblemDetails
+	if(contentType.includes(PROBLEM_CONTENT_TYPE)) {
+		problem = (await res.json()) as ProblemDetails
+	} else {
+		problem = {
+			type: 'about:blank',
+			status: res.status,
+			title: res.statusText,
+		}
+	}
+
+	throw new Boom<ProblemDetails>(
+		problem.title,
+		{
+			statusCode: res.status,
+			data: problem,
+		},
+	)
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export * from './client.ts'
+export type * from './client.ts'
+export { ProblemError, type ProblemDetails } from './errors.ts'
+export { DEFAULT_BASE_URL, PROBLEM_CONTENT_TYPE, USER_AGENT } from './consts.ts'
+export {
+	deriveFromPrivateKey,
+	type EthKeypair,
+	generateKeypair,
+} from './keypair.ts'
+export * from './types/index.ts'

package/src/keypair.ts

@@ -0,0 +1,63 @@
+import { keccak_256 } from '@noble/hashes/sha3.js'
+import * as secp from '@noble/secp256k1'
+
+export type EthKeypair = {
+	address: string
+	privateKey: string
+}
+
+/**
+ * Generate a fresh secp256k1 key-pair and derive its lowercase
+ * Ethereum address (keccak-256 of the uncompressed pubkey minus the
+ * `0x04` prefix, last 20 bytes).
+ *
+ * Lives in the client SDK so every consumer — the MCP `issue_credentials`
+ * tool, scripts, future SDK callers — mints credentials the same way.
+ * The private key is returned to the caller and MUST stay local; only
+ * the derived address is ever sent to the server. The public key is an
+ * intermediate value used to compute the address and is not retained.
+ */
+export function generateKeypair(): EthKeypair {
+	const priv = secp.utils.randomSecretKey()
+	const pub = secp.getPublicKey(priv, false)
+	return {
+		address: '0x' + bytesToHex(keccak_256(pub.slice(1))).slice(-40),
+		privateKey: '0x' + bytesToHex(priv),
+	}
+}
+
+/**
+ * Recover the address from a hex-encoded private key. Used when
+ * importing a key the user already holds.
+ */
+export function deriveFromPrivateKey(privateKey: string): EthKeypair {
+	const hex = privateKey.replace(/^0x/, '')
+	const priv = hexToBytes(hex)
+	const pub = secp.getPublicKey(priv, false)
+	return {
+		address: '0x' + bytesToHex(keccak_256(pub.slice(1))).slice(-40),
+		privateKey: '0x' + hex,
+	}
+}
+
+function bytesToHex(bytes: Uint8Array): string {
+	let out = ''
+	for(const b of bytes) {
+		out += b.toString(16).padStart(2, '0')
+	}
+
+	return out
+}
+
+function hexToBytes(hex: string): Uint8Array {
+	if(hex.length % 2 !== 0) {
+		throw new Error('private key hex must have even length')
+	}
+
+	const out = new Uint8Array(hex.length / 2)
+	for(let i = 0; i < out.length; i++) {
+		out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16)
+	}
+
+	return out
+}

package/src/routes.gen.ts

@@ -0,0 +1,78 @@
+// AUTO-GENERATED by packages/app/scripts/mcp-tools-gen.ts
+// from packages/app/openapi.yaml.
+// Run `npm run openapi:typegen --workspace=packages/client`
+// to regenerate. Do not edit by hand.
+
+export const ROUTES = {
+	"AddOrgMember": {"method":"post","path":"/orgs/{orgId}/members"},
+	"AdminHome": {"method":"get","path":"/admin"},
+	"AdminOrgs": {"method":"get","path":"/admin/orgs"},
+	"AdminProviders": {"method":"get","path":"/admin/providers"},
+	"AdminReviews": {"method":"get","path":"/admin/reviews"},
+	"AdminThemes": {"method":"get","path":"/admin/themes"},
+	"AdminUsers": {"method":"get","path":"/admin/users"},
+	"AttachPage": {"method":"get","path":"/attach/{code}"},
+	"CancelPublicListingRequest": {"method":"post","path":"/providers/{providerId}/versions/{version}/cancel-review"},
+	"ComponentsDemo": {"method":"get","path":"/components_demo"},
+	"ConfirmAttachSession": {"method":"post","path":"/credentials/attach/sessions/{code}/confirm"},
+	"CreateAttachSession": {"method":"post","path":"/credentials/attach/sessions"},
+	"CreateOrg": {"method":"post","path":"/orgs"},
+	"CreateProvider": {"method":"post","path":"/providers"},
+	"CreateProviderVersion": {"method":"post","path":"/providers/{providerId}/versions"},
+	"CreateTheme": {"method":"post","path":"/orgs/{orgId}/themes"},
+	"CredentialAuthChallenge": {"method":"post","path":"/credentials/auth/challenge"},
+	"CredentialAuthVerify": {"method":"post","path":"/credentials/auth/verify"},
+	"DecideProviderVersionReview": {"method":"post","path":"/providers/{providerId}/versions/{version}/review-decision"},
+	"DeleteOrg": {"method":"delete","path":"/orgs/{orgId}"},
+	"DeleteOrgBilling": {"method":"delete","path":"/orgs/{orgId}/billing"},
+	"DeleteOrgIcon": {"method":"delete","path":"/orgs/{orgId}/icon"},
+	"DeleteProvider": {"method":"delete","path":"/providers/{providerId}"},
+	"DeleteProviderVersion": {"method":"delete","path":"/providers/{providerId}/versions/{version}"},
+	"DeleteTheme": {"method":"delete","path":"/orgs/{orgId}/themes/{themeId}"},
+	"Docs": {"method":"get","path":"/docs"},
+	"ExplorePreviewImage": {"method":"get","path":"/og/explore.png"},
+	"GetAttachSession": {"method":"get","path":"/credentials/attach/sessions/{code}"},
+	"GetCredential": {"method":"get","path":"/credentials/{credentialId}"},
+	"GetCredentialByAddress": {"method":"get","path":"/credentials/by-address/{address}"},
+	"GetImage": {"method":"get","path":"/images/{imageId}"},
+	"GetMe": {"method":"get","path":"/me"},
+	"GetOrg": {"method":"get","path":"/orgs/{orgId}"},
+	"GetOrgBilling": {"method":"get","path":"/orgs/{orgId}/billing"},
+	"GetProvider": {"method":"get","path":"/providers/{providerId}"},
+	"GetProviderBySlug": {"method":"get","path":"/providers/{providerId}/{slug}"},
+	"GetProviderVersion": {"method":"get","path":"/providers/{providerId}/versions/{version}"},
+	"GetTheme": {"method":"get","path":"/orgs/{orgId}/themes/{themeId}"},
+	"GetUser": {"method":"get","path":"/users/{userId}"},
+	"Index": {"method":"get","path":"/"},
+	"LinkCredential": {"method":"post","path":"/credentials"},
+	"ListOrgCredentials": {"method":"get","path":"/orgs/{orgId}/credentials"},
+	"ListOrgs": {"method":"get","path":"/orgs"},
+	"ListProviderVersions": {"method":"get","path":"/providers/{providerId}/versions"},
+	"ListThemes": {"method":"get","path":"/orgs/{orgId}/themes"},
+	"Login": {"method":"post","path":"/auth/login"},
+	"LoginPage": {"method":"get","path":"/login"},
+	"Logout": {"method":"post","path":"/logout"},
+	"MakePrivate": {"method":"post","path":"/providers/{providerId}/make-private"},
+	"OpenApiSpec": {"method":"get","path":"/openapi.yaml"},
+	"ProviderPreviewImage": {"method":"get","path":"/providers/{providerId}/preview.png"},
+	"Providers": {"method":"get","path":"/providers"},
+	"PublishProviderVersion": {"method":"post","path":"/providers/{providerId}/versions/{version}/publish"},
+	"RemoveOrgMember": {"method":"delete","path":"/orgs/{orgId}/members/{memberId}"},
+	"RequestPublicListing": {"method":"post","path":"/providers/{providerId}/request-public"},
+	"RevokeCredential": {"method":"delete","path":"/credentials/{credentialId}"},
+	"Robots": {"method":"get","path":"/robots.txt"},
+	"SetupProviderCreate": {"method":"post","path":"/providers/setup"},
+	"Sitemap": {"method":"get","path":"/sitemap.xml"},
+	"SubmitProviderVersionForReview": {"method":"post","path":"/providers/{providerId}/versions/{version}/review"},
+	"TransferProvider": {"method":"post","path":"/providers/{providerId}/transfer"},
+	"UpdateMe": {"method":"patch","path":"/me"},
+	"UpdateOrg": {"method":"patch","path":"/orgs/{orgId}"},
+	"UpdateOrgBilling": {"method":"put","path":"/orgs/{orgId}/billing"},
+	"UpdateOrgIcon": {"method":"put","path":"/orgs/{orgId}/icon"},
+	"UpdateOrgMember": {"method":"patch","path":"/orgs/{orgId}/members/{memberId}"},
+	"UpdateProvider": {"method":"patch","path":"/providers/{providerId}"},
+	"UpdateProviderVersion": {"method":"patch","path":"/providers/{providerId}/versions/{version}"},
+	"UpdateTheme": {"method":"patch","path":"/orgs/{orgId}/themes/{themeId}"},
+} as const
+
+export type RouteId = keyof typeof ROUTES

package/src/types/index.ts

@@ -0,0 +1,2 @@
+export * from './openapi.ts'
+export type { components, operations, paths } from './openapi.gen.ts'