@nanorail/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NanoRail
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# @nanorail/sdk
+
+The MPP-native metering SDK for priced digital units. Mark content with
+`data-nanorail-*` attributes and NanoRail generates the agent-readable manifest, a
+discovery API, policy-bounded unlocks, receipts, and Tempo settlement — for humans
+and autonomous agents alike.
+
+## Install
+
+```bash
+npm i @nanorail/sdk
+```
+
+## Use
+
+```ts
+import { initNanoRail } from '@nanorail/sdk';
+
+const nr = initNanoRail({
+  gatewayUrl: 'https://gateway.yoursite.com',
+  articleId: 'your-article-id',
+  autoUnlockOnScroll: true, // humans: meter eligible chunks open as they read
+});
+```
+
+Mark any element:
+
+```html
+<p
+  data-nanorail-chunk="para-3"
+  data-nanorail-price="0.005"
+  data-nanorail-type="text"
+  data-nanorail-title="The micropayment thesis"
+  data-nanorail-teaser="Why metering beats blocking for machine readers."
+  data-nanorail-tags="MPP, micropayments, metering"
+>
+  Premium content…
+</p>
+```
+
+### Script tag (no bundler)
+
+```html
+<script>
+  window.NANORAIL_CONFIG = { gatewayUrl: 'http://localhost:4020', articleId: 'your-article-id' };
+</script>
+<script src="https://cdn.yoursite.com/nanorail.js"></script>
+```
+
+## API
+
+`initNanoRail(config)` returns an instance:
+
+- `client` — `NanoRailClient`: sessions, policy, unlocks, receipts
+- `manifest` — the auto-generated `ArticleManifest`
+- `rescan()` — re-scan + lock any newly added chunks
+- `runAgent(opts)` — discovery → plan → buy → summarize
+- `unlockTempoSnippet()` — the real Tempo MPP settlement path
+
+Policy is enforced both client-side (before signing) and server-side (independently).
+Chunks that are over budget or of a blocked type stay gated. Unlocks emit lifecycle
+events and receipts.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,488 @@
+// Generated by dts-bundle-generator v9.5.1
+
+export type ContentType = "text" | "chart" | "citation_pack" | "video";
+export type Currency = "USD";
+/** The visible MPP lifecycle labels. These exact strings are shown in the dashboard. */
+export type LifecycleLabel = "discovery query" | "discovery match" | "session opened" | "chunk challenge issued" | "voucher signed" | "receipt returned" | "policy blocked" | "batch settled" | "Real Tempo MPP unlock";
+/** Actor that drove a unlock/block — used for human-vs-agent breakdowns. */
+export type Actor = "human" | "agent";
+/** Agent-readable manifest entry for a single purchasable chunk. */
+export interface ManifestChunk {
+	chunkId: string;
+	type: ContentType;
+	title: string;
+	price: string;
+	currency: Currency;
+	recipient: string;
+	/** Public teaser/preview shown before purchase (no gated content). */
+	teaser: string;
+	/** Topical tags the discovery layer searches over. */
+	tags: string[];
+	/** Concrete endpoints (paths) an agent calls to buy this exact chunk. */
+	endpoints: {
+		challenge: string;
+		unlock: string;
+	};
+}
+export interface ArticleManifest {
+	articleId: string;
+	publisherId: string;
+	title: string;
+	currency: Currency;
+	/** How this manifest was produced. */
+	source: "sdk-scan" | "gateway-default";
+	/** Epoch ms the manifest was generated (set by the SDK scan). */
+	generatedAt?: number;
+	/** Endpoint templates an agent can follow. */
+	endpoints: {
+		challenge: string;
+		unlock: string;
+	};
+	chunks: ManifestChunk[];
+}
+/** Client + server policy. Decimal-string money fields are the human-facing form. */
+export interface Policy {
+	autoPayEnabled: boolean;
+	/** Max total spend per article (decimal string USD). */
+	maxSpendPerArticle: string;
+	/** Max spend on a single chunk (decimal string USD). */
+	maxSpendPerChunk: string;
+	allowedPublishers: string[];
+	allowedContentTypes: ContentType[];
+	blockedContentTypes: ContentType[];
+	/** Any chunk above this amount needs manual approval (decimal string USD). */
+	requireManualApprovalAbove: string;
+	/** Total budget for the whole session (decimal string USD). */
+	sessionBudget: string;
+	sessionExpiryMinutes: number;
+}
+/** A funded mock MPP session. */
+export interface Session {
+	sessionId: string;
+	/** Hex Ed25519 public key of the session payer. */
+	payerPublicKey: string;
+	policy: Policy;
+	/** Funded budget in micro-USD. */
+	budgetMicros: number;
+	/** Amount already spent in micro-USD. */
+	spentMicros: number;
+	createdAt: number;
+	expiresAt: number;
+}
+export interface Receipt {
+	receiptId: string;
+	voucherId: string;
+	sessionId: string;
+	articleId: string;
+	publisherId: string;
+	chunkId: string;
+	chunkType: ContentType;
+	/** Decimal string USD. */
+	amount: string;
+	currency: Currency;
+	recipient: string;
+	createdAt: number;
+}
+/** Result of a policy evaluation. */
+export interface PolicyDecision {
+	allowed: boolean;
+	/** Set when allowed but the amount exceeds requireManualApprovalAbove. */
+	requiresManualApproval: boolean;
+	/** Human-readable reason, present when blocked. */
+	reason?: string;
+}
+/**
+ * A discovery result. Carries only publicly-safe metadata + a relevance score —
+ * never the gated content. The Discovery Agent is a recommendation layer, not a
+ * source of truth (see README "Trust model").
+ */
+export interface DiscoveryMatch {
+	chunkId: string;
+	title: string;
+	teaser: string;
+	tags: string[];
+	type: ContentType;
+	price: string;
+	currency: Currency;
+	/** Relevance score in [0, 1]. */
+	confidence: number;
+	/** Human-readable explanation of why it matched. */
+	reason: string;
+}
+export interface NanoRailEventDetail {
+	label: LifecycleLabel;
+	chunkId?: string;
+	chunkType?: ContentType;
+	amount?: string;
+	reason?: string;
+	detail?: string;
+	actor?: Actor;
+	receiptId?: string;
+	batchId?: string;
+	at: number;
+}
+/** Slugged event name for a lifecycle label, e.g. "voucher signed" -> "nanorail:voucher-signed". */
+export declare function eventName(label: LifecycleLabel): string;
+/**
+ * Tiny event bus. Dispatches two events per lifecycle step: a generic
+ * `nanorail:lifecycle` and a typed `nanorail:<slug>`. Both carry the exact
+ * lifecycle label string in their detail.
+ */
+export declare class NanoRailEvents {
+	private target;
+	constructor(target: EventTarget);
+	emit(detail: Omit<NanoRailEventDetail, "at">): void;
+	on(label: LifecycleLabel | "lifecycle", handler: (e: NanoRailEventDetail) => void): () => void;
+}
+export interface ChunkDescriptor {
+	chunkId: string;
+	type: ContentType;
+	price: string;
+	publisherId: string;
+	articleId: string;
+	recipient: string;
+	title: string;
+	teaser?: string;
+	tags?: string[];
+}
+export interface NanoRailConfig {
+	gatewayUrl?: string;
+	policy?: Policy;
+	/** Default actor for unlocks driven by this client ('human' for the page). */
+	actor?: Actor;
+	/** Injectable for tests; defaults to globalThis.fetch. */
+	fetchImpl?: typeof fetch;
+	/** Event target; defaults to document, falling back to a fresh EventTarget. */
+	eventTarget?: EventTarget;
+}
+export interface UnlockOutcome {
+	ok: boolean;
+	content?: string;
+	title?: string;
+	receipt?: Receipt;
+	/** True when the purchase was blocked by policy (no voucher signed). */
+	blocked?: boolean;
+	/** True when allowed but manual approval is required and was not granted. */
+	needsApproval?: boolean;
+	reason?: string;
+}
+/** Outcome of the real Tempo MPP snippet unlock (separate from the mock flow). */
+export interface TempoUnlockOutcome {
+	ok: boolean;
+	snippet?: string;
+	receipt?: Receipt;
+	/** On-chain (real) or simulated (offline) settlement reference. */
+	settlementRef?: string;
+	mode?: "real-network" | "offline-fallback";
+	/** Present when a real-network attempt failed and fell back to offline. */
+	error?: string;
+	/** Recipient address/handle the payment settled to. */
+	recipient?: string;
+	/** Tempo testnet explorer URL (recipient address page); real-network only. */
+	explorerUrl?: string;
+	reason?: string;
+}
+/**
+ * Framework-free NanoRail client. Owns the mock session keypair, opens/reuses a
+ * funded session, evaluates client-side policy before signing, signs vouchers,
+ * unlocks chunks, and emits the six lifecycle events. No DOM dependency, so it
+ * is unit-testable with an injected fetch.
+ */
+export declare class NanoRailClient {
+	readonly events: NanoRailEvents;
+	private readonly gatewayUrl;
+	private readonly fetchImpl;
+	private readonly policy;
+	private readonly defaultActor;
+	private privateKeyHex?;
+	publicKeyHex?: string;
+	session?: Session;
+	spentMicros: number;
+	receipts: Receipt[];
+	blocked: Array<{
+		chunkId: string;
+		reason: string;
+		at: number;
+	}>;
+	/** Chunk ids the user has manually approved (for amounts above the threshold). */
+	approvals: Set<string>;
+	private sessionPromise?;
+	private settlementWatch?;
+	private lastBatchCount;
+	constructor(config?: NanoRailConfig);
+	getPolicy(): Policy;
+	/** Fetch the agent-readable manifest for an article. */
+	getManifest(articleId: string): Promise<ArticleManifest>;
+	/**
+	 * Ask the publisher's discovery endpoint "what paid content is about X?".
+	 * Returns ranked, publicly-safe matches (no gated content). This is a
+	 * recommendation layer — the publisher is as trustworthy as the matches.
+	 */
+	discover(articleId: string, query: string, actor?: Actor): Promise<DiscoveryMatch[]>;
+	/** Register an SDK-generated manifest so agents can discover this article. */
+	registerManifest(manifest: ArticleManifest): Promise<{
+		ok: boolean;
+		chunks?: number;
+	}>;
+	/** Open a funded session once; concurrent callers share the same promise. */
+	ensureSession(): Promise<Session>;
+	private openSession;
+	/** Pure client-side policy check using locally-tracked spend. */
+	evaluate(chunk: ChunkDescriptor): PolicyDecision;
+	/**
+	 * Full unlock flow for one chunk:
+	 *  1. evaluate client policy — if blocked, record + emit `policy blocked`, never sign.
+	 *  2. if manual approval needed and not granted, return needsApproval.
+	 *  3. request challenge, sign voucher, POST unlock.
+	 *  4. on success record receipt + reveal content.
+	 */
+	unlock(chunk: ChunkDescriptor, opts?: {
+		actor?: Actor;
+		approved?: boolean;
+		viaDiscovery?: boolean;
+	}): Promise<UnlockOutcome>;
+	private requestChallenge;
+	/** Record a client-side policy block (no voucher signed) and emit the event. */
+	recordClientBlock(chunk: ChunkDescriptor, reason: string, actor?: Actor): Promise<void>;
+	/** Trigger the server-side forced-rejection demo path for a chunk. */
+	forceServerRejection(chunk: ChunkDescriptor, actor?: Actor): Promise<{
+		rejected: boolean;
+		reason?: string;
+	}>;
+	/**
+	 * Unlock the premium snippet via the REAL Tempo MPP path (HTTP 402 → payment →
+	 * receipt). This is settled by the gateway's PaymentProvider (real Tempo testnet
+	 * when configured, offline fallback otherwise) and is intentionally separate from
+	 * the mock Ed25519 voucher flow. Emits a `Real Tempo MPP unlock` event on success.
+	 */
+	unlockTempoSnippet(): Promise<TempoUnlockOutcome>;
+	/** Poll settlements so the widget timeline shows `batch settled` events. */
+	startSettlementWatch(intervalMs?: number): void;
+	stopSettlementWatch(): void;
+	/** Snapshot of state for the widget. */
+	snapshot(): {
+		sessionId: string | undefined;
+		publicKey: string | undefined;
+		policy: Policy;
+		budget: string;
+		spent: number;
+		receipts: Receipt[];
+		blocked: {
+			chunkId: string;
+			reason: string;
+			at: number;
+		}[];
+		approvalsPending: string;
+	};
+}
+/** Read a chunk descriptor from a `[data-nanorail-price]` element. */
+export declare function readChunk(el: HTMLElement): ChunkDescriptor;
+/**
+ * Pure gate for scroll auto-unlock: a chunk unlocks itself as the reader reaches
+ * it only when policy ALLOWS it AND it does not require manual approval. Pricier
+ * / approval-gated / blocked chunks always keep their explicit button — so the
+ * policy is proven live, not hidden. Unit-tested directly (no DOM/observer).
+ */
+export declare function shouldAutoUnlock(decision: PolicyDecision): boolean;
+export interface ScanOptions {
+	/** Auto-unlock policy-eligible chunks as they scroll into view. Default false. */
+	autoUnlock?: boolean;
+}
+/**
+ * Find every `[data-nanorail-price]` element, lock it, and render an unlock
+ * control. Returns the list of locked elements (useful for tests). With
+ * `{ autoUnlock: true }`, policy-eligible chunks unlock themselves on scroll.
+ */
+export declare function scanAndLock(client: NanoRailClient, root?: ParentNode, opts?: ScanOptions): HTMLElement[];
+export interface GenerateManifestOptions {
+	/** DOM subtree to scan; defaults to the whole document. */
+	root?: ParentNode;
+	/** Override the article id (else derived from the chunks' attributes). */
+	articleId?: string;
+	/** Override the publisher id (else derived from the chunks' attributes). */
+	publisherId?: string;
+	/** Override the article title (else taken from <h1> or document.title). */
+	title?: string;
+}
+/**
+ * Build a machine-readable manifest purely from the publisher's
+ * `data-nanorail-*` attributes — no separately-maintained manifest file. The
+ * publisher marks content; this derives article metadata, chunk ids/types/prices,
+ * teasers, and per-chunk unlock endpoints automatically.
+ */
+export declare function generateManifest(opts?: GenerateManifestOptions): ArticleManifest;
+/**
+ * The NanoRail **Agent Wallet** — the user-facing control layer for what an agent
+ * is allowed to spend money on. Budget, permissions, and purchase rules are the
+ * primary UI; the raw MPP protocol lifecycle is tucked into a collapsed
+ * "Technical details" section for judges who want to see the wire-level flow.
+ */
+export declare class NanoRailWidget {
+	private client;
+	private root;
+	/** Human-readable recent purchases / blocks. */
+	private activity;
+	/** Raw protocol events for the Technical details drawer. */
+	private tech;
+	private collapsed;
+	private showTech;
+	constructor(client: NanoRailClient);
+	toggle(): void;
+	render(): void;
+}
+export interface AgentStep {
+	chunkId: string;
+	type: string;
+	decision: "bought" | "skipped" | "blocked";
+	reason?: string;
+	receiptId?: string;
+	/** The unlocked content, when bought. */
+	content?: string;
+}
+/** The agent's up-front decision for one manifest chunk, shown before execution. */
+export interface AgentPlanItem {
+	chunkId: string;
+	type: ContentType;
+	title: string;
+	price: string;
+	action: "buy" | "skip" | "block";
+	reason: string;
+	/** Discovery confidence that informed the decision, when available. */
+	confidence?: number;
+}
+/** One purchased source in the final answer (title + price + receipt). */
+export interface AgentPurchase {
+	chunkId: string;
+	title: string;
+	type: ContentType;
+	price: string;
+	receiptId: string;
+}
+export interface AgentResult {
+	task: string;
+	query: string;
+	matches: DiscoveryMatch[];
+	plan: AgentPlanItem[];
+	steps: AgentStep[];
+	receiptIds: string[];
+	/** Sources the agent actually bought (for the final answer). */
+	purchased: AgentPurchase[];
+	/** Total spent across all purchases, decimal USD string. */
+	totalCost: string;
+	summary: string;
+}
+/** Staged progress emitted while the agent works, so a UI can render it live. */
+export type AgentProgress = {
+	phase: "task";
+	task: string;
+	query: string;
+} | {
+	phase: "discovery";
+	query: string;
+	matches: DiscoveryMatch[];
+} | {
+	phase: "plan";
+	plan: AgentPlanItem[];
+} | {
+	phase: "chunk-start";
+	item: AgentPlanItem;
+} | {
+	phase: "bought";
+	chunkId: string;
+	receiptId: string;
+	content?: string;
+} | {
+	phase: "blocked";
+	chunkId: string;
+	reason: string;
+} | {
+	phase: "skipped";
+	chunkId: string;
+	reason: string;
+} | {
+	phase: "done";
+	result: AgentResult;
+};
+export interface AgentOptions {
+	/** Task description shown to the user (default: an MPP summary task). */
+	task?: string;
+	/** Discovery query sent to the publisher (default: derived from the task). */
+	query?: string;
+	/** Called at each stage so the demo can render the flow step by step. */
+	onProgress?: (p: AgentProgress) => void;
+	/** Pause between steps (ms) so judges can watch the lifecycle stream. */
+	stepDelayMs?: number;
+}
+/**
+ * Simulates an autonomous agent that **discovers before it buys** — so it never
+ * pays blindly:
+ *
+ *   1. POST /discover                          → ranked, publicly-safe matches
+ *   2. build a plan from the matches + policy  → buy what discovery surfaced and
+ *                                                policy allows; skip the rest;
+ *                                                block disallowed types (video)
+ *   3. per bought chunk: challenge → voucher → unlock   (same MPP flow a human uses)
+ *   4. emit a summary with receipt IDs
+ *
+ * Discovery results are treated as a recommendation, not as truth — the agent
+ * still applies its own policy before signing any voucher.
+ */
+export declare function runAgentSummary(client: NanoRailClient, articleId?: string, opts?: AgentOptions): Promise<AgentResult>;
+/** Example tasks shown in the console; each maps to a discovery query. */
+export interface AgentTask {
+	label: string;
+	query: string;
+}
+export declare const DEFAULT_AGENT_TASKS: AgentTask[];
+export interface AgentConsoleOptions {
+	tasks?: AgentTask[];
+	/** Pause between agent steps (ms) so the economic decisions are watchable. */
+	stepDelayMs?: number;
+}
+/**
+ * Mount the Agent Console: injects a launcher button + a modal. Returns an object
+ * with `open()`/`close()`. Safe to call once per page.
+ */
+export declare function mountAgentConsole(instance: NanoRailInstance, opts?: AgentConsoleOptions): {
+	open: () => void;
+	close: () => void;
+};
+export interface InitNanoRailConfig {
+	gatewayUrl?: string;
+	articleId?: string;
+	/** Scan + lock [data-nanorail-price] chunks on init (default true). */
+	autoScan?: boolean;
+	/** Mount the floating widget (default true). */
+	mountWidget?: boolean;
+	/**
+	 * Auto-unlock policy-eligible chunks as the reader scrolls to them (default
+	 * false). Approval-gated and blocked chunks always keep their button.
+	 */
+	autoUnlockOnScroll?: boolean;
+	/** Mount the first-class Agent Mode console (launcher + modal). Default false. */
+	agentConsole?: boolean;
+	/** Override the example tasks shown in the Agent Console. */
+	agentTasks?: AgentTask[];
+	actor?: Actor;
+}
+export interface NanoRailInstance {
+	client: NanoRailClient;
+	widget?: NanoRailWidget;
+	manifest: ArticleManifest;
+	rescan: () => void;
+	regenerateManifest: () => Promise<ArticleManifest>;
+	runAgent: (opts?: AgentOptions) => Promise<AgentResult>;
+	forceVideoRejection: () => Promise<{
+		rejected: boolean;
+		reason?: string;
+	}>;
+	unlockTempoSnippet: () => Promise<TempoUnlockOutcome>;
+	/** Open the Agent Mode console (present when `agentConsole` is enabled). */
+	openAgentConsole?: () => void;
+}
+/** Create and mount a NanoRail instance on the current page. */
+export declare function initNanoRail(config?: InitNanoRailConfig): NanoRailInstance;
+/** Turn a chunk content string into HTML for insertion into the page. */
+export declare function renderContent(content: string): string;
+
+export {};