@rubicon-caliga/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rubicon
+
+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/dist/contract.d.ts

@@ -0,0 +1,133 @@
+import type { AtomicAmount } from "./money.js";
+/**
+ * Shared API contract between Rubicon (this gateway) and the rubicon-marketing
+ * Next.js application. Both repositories agree on these shapes, the article
+ * states, pricing units (atomic USDC, 1 USDC = 1_000_000), word-counting rules,
+ * wallet format, creator ownership, and seller-agent configuration.
+ *
+ * These types describe the shared persistent data model. The marketing app owns
+ * creator authentication and creator-facing CRUD; Rubicon reads published data
+ * and writes runtime read/earnings activity.
+ */
+/**
+ * Lifecycle of an article. Only `live` articles are consumable by buyer agents
+ * or visible in the public repository.
+ */
+export type ArticleState = "draft" | "live" | "paused" | "archived" | "deleted";
+export declare const PUBLIC_ARTICLE_STATE: ArticleState;
+export type WalletNetwork = string;
+export interface Creator {
+    id: string;
+    username: string;
+    displayName: string;
+    createdAt: string;
+}
+export interface CreatorProfile {
+    creatorId: string;
+    bio?: string;
+    avatarUrl?: string;
+}
+export interface CreatorWallet {
+    creatorId: string;
+    /** Verified receiving wallet. Settlement always pays this address. */
+    address: `0x${string}`;
+    network: WalletNetwork;
+    verified: boolean;
+}
+export interface ArticleSection {
+    id: string;
+    articleId: string;
+    /** Stable slug used by buyer agents for navigation. */
+    sectionId: string;
+    heading: string;
+    level: number;
+    /** Zero-based word index where this section's body begins. */
+    wordStart: number;
+    wordCount: number;
+    ordinal: number;
+}
+/**
+ * Optional per-article seller-agent configuration. Agreed between Rubicon and
+ * rubicon-marketing; absent values fall back to gateway defaults.
+ */
+export interface SellerAgentConfig {
+    persona?: string;
+    /** Identifier of a configured model/provider, e.g. "anthropic:claude-opus-4-8". */
+    model?: string;
+    /** Extra navigation guidance the creator wants the seller agent to follow. */
+    guidance?: string;
+}
+export interface Article {
+    id: string;
+    creatorId: string;
+    title: string;
+    author: string;
+    state: ArticleState;
+    pricePerWordAtomic: AtomicAmount;
+    /** Optional creator-set cap on the total price of the article. */
+    maxArticlePriceAtomic?: AtomicAmount;
+    totalWords: number;
+    revision: number;
+    sellerAgentConfig?: SellerAgentConfig;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface EarningsSummary {
+    creatorId: string;
+    articleId?: string;
+    wordsDelivered: number;
+    creatorAmountAtomic: AtomicAmount;
+    rubiconFeeAtomic: AtomicAmount;
+}
+export interface PaymentActivity {
+    paymentId: string;
+    sessionId: string;
+    articleId: string;
+    sequence: number;
+    amountAtomic: AtomicAmount;
+    creatorAmountAtomic: AtomicAmount;
+    rubiconFeeAtomic: AtomicAmount;
+    network?: string;
+    payTo?: `0x${string}`;
+    transactionHash?: string;
+    transactionHashes?: string[];
+    transferId?: string;
+    createdAt: string;
+}
+export interface SellerAgentMessageRecord {
+    id: string;
+    conversationId: string;
+    sessionId?: string;
+    articleId: string;
+    role: "buyer" | "seller";
+    content: string;
+    createdAt: string;
+}
+export interface StreamSessionRecord {
+    id: string;
+    articleId: string;
+    creatorId: string;
+    conversationId?: string;
+    state: string;
+    wordsPaid: number;
+    wordsDelivered: number;
+    paidAtomic: AtomicAmount;
+    budgetAtomic: AtomicAmount;
+    createdAt: string;
+    expiresAt: string;
+}
+export interface WordDeliveryRecord {
+    sessionId: string;
+    articleId: string;
+    sequence: number;
+    word: string;
+    priceAtomic: AtomicAmount;
+    paymentId: string;
+    createdAt: string;
+}
+export interface ApiError {
+    error: string;
+    message?: string;
+    details?: Record<string, unknown>;
+}
+//# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

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

package/dist/contract.js

@@ -0,0 +1,2 @@
+export const PUBLIC_ARTICLE_STATE = "live";
+//# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAmBA,MAAM,CAAC,MAAM,oBAAoB,GAAiB,MAAM,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./money.js";
+export * from "./contract.js";
+export * from "./pricing.js";
+export * from "./protocol.js";
+export * from "./session.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export * from "./money.js";
+export * from "./contract.js";
+export * from "./pricing.js";
+export * from "./protocol.js";
+export * from "./session.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC"}

package/dist/money.d.ts

@@ -0,0 +1,6 @@
+export declare const USDC_ATOMIC_UNITS = 1000000n;
+export type AtomicAmount = `${bigint}`;
+export declare function parseUsdcToAtomic(value: string): bigint;
+export declare function formatAtomicUsdc(amount: bigint): string;
+export declare function addBasisPoints(amount: bigint, basisPoints: number): bigint;
+//# sourceMappingURL=money.d.ts.map

package/dist/money.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"money.d.ts","sourceRoot":"","sources":["../src/money.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,iBAAiB,WAAa,CAAC;AAE5C,MAAM,MAAM,YAAY,GAAG,GAAG,MAAM,EAAE,CAAC;AAEvC,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIvD;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAIvD;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAE1E"}

package/dist/money.js

@@ -0,0 +1,15 @@
+export const USDC_ATOMIC_UNITS = 1000000n;
+export function parseUsdcToAtomic(value) {
+    const [whole = "0", fraction = ""] = value.split(".");
+    const paddedFraction = `${fraction}000000`.slice(0, 6);
+    return BigInt(whole) * USDC_ATOMIC_UNITS + BigInt(paddedFraction);
+}
+export function formatAtomicUsdc(amount) {
+    const whole = amount / USDC_ATOMIC_UNITS;
+    const fraction = `${amount % USDC_ATOMIC_UNITS}`.padStart(6, "0").replace(/0+$/, "");
+    return fraction.length > 0 ? `${whole}.${fraction}` : `${whole}`;
+}
+export function addBasisPoints(amount, basisPoints) {
+    return amount + (amount * BigInt(basisPoints)) / 10000n;
+}
+//# sourceMappingURL=money.js.map

package/dist/money.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"money.js","sourceRoot":"","sources":["../src/money.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,iBAAiB,GAAG,QAAU,CAAC;AAI5C,MAAM,UAAU,iBAAiB,CAAC,KAAa;IAC7C,MAAM,CAAC,KAAK,GAAG,GAAG,EAAE,QAAQ,GAAG,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACtD,MAAM,cAAc,GAAG,GAAG,QAAQ,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACvD,OAAO,MAAM,CAAC,KAAK,CAAC,GAAG,iBAAiB,GAAG,MAAM,CAAC,cAAc,CAAC,CAAC;AACpE,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,MAAc;IAC7C,MAAM,KAAK,GAAG,MAAM,GAAG,iBAAiB,CAAC;IACzC,MAAM,QAAQ,GAAG,GAAG,MAAM,GAAG,iBAAiB,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACrF,OAAO,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,IAAI,QAAQ,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,EAAE,CAAC;AACnE,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,MAAc,EAAE,WAAmB;IAChE,OAAO,MAAM,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC,GAAG,MAAO,CAAC;AAC3D,CAAC"}

package/dist/pricing.d.ts

@@ -0,0 +1,40 @@
+export type MeteringUnit = "word";
+/**
+ * The atomic content unit in Rubicon is exactly one word. A quote describes the
+ * price the creator earns for a single word and the amount the buyer must pay to
+ * release one additional word.
+ *
+ * Rubicon never bills in chunks. Circle/x402 may batch settlement internally,
+ * but the application-level accounting is always one word = one paid unit.
+ */
+export interface WordPriceQuote {
+    currency: "USDC";
+    meteringUnit: MeteringUnit;
+    /** Price the creator earns for one delivered word. */
+    pricePerWordAtomic: `${bigint}`;
+    /** Rubicon gateway fee in basis points. Defaults to 0. */
+    gatewayFeeBps: number;
+    /** Exact amount the buyer authorizes/sends to release one additional word. */
+    wordPaymentAtomic: `${bigint}`;
+}
+export interface WordUsageReport {
+    unit: MeteringUnit;
+    /** Number of individually delivered, individually paid words. */
+    wordsDelivered: number;
+    /** Full word price accruing to the creator (no Rubicon fee deducted). */
+    creatorAmountAtomic: `${bigint}`;
+    /** Rubicon fee. Zero by default — creators keep the full word price. */
+    rubiconFeeAtomic: `${bigint}`;
+    /** Total atomic USDC the buyer paid for these words. */
+    totalPaidAtomic: `${bigint}`;
+}
+export declare function quotePerWord(input: {
+    pricePerWordAtomic: bigint;
+    gatewayFeeBps?: number;
+}): WordPriceQuote;
+export declare function usageForWords(input: {
+    wordsDelivered: number;
+    pricePerWordAtomic: bigint;
+    gatewayFeeBps?: number;
+}): WordUsageReport;
+//# sourceMappingURL=pricing.d.ts.map

package/dist/pricing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pricing.d.ts","sourceRoot":"","sources":["../src/pricing.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAElC;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,YAAY,CAAC;IAC3B,sDAAsD;IACtD,kBAAkB,EAAE,GAAG,MAAM,EAAE,CAAC;IAChC,0DAA0D;IAC1D,aAAa,EAAE,MAAM,CAAC;IACtB,8EAA8E;IAC9E,iBAAiB,EAAE,GAAG,MAAM,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,YAAY,CAAC;IACnB,iEAAiE;IACjE,cAAc,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,mBAAmB,EAAE,GAAG,MAAM,EAAE,CAAC;IACjC,wEAAwE;IACxE,gBAAgB,EAAE,GAAG,MAAM,EAAE,CAAC;IAC9B,wDAAwD;IACxD,eAAe,EAAE,GAAG,MAAM,EAAE,CAAC;CAC9B;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE;IAClC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,GAAG,cAAc,CAUjB;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE;IACnC,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,GAAG,eAAe,CAWlB"}

package/dist/pricing.js

@@ -0,0 +1,25 @@
+import { addBasisPoints } from "./money.js";
+export function quotePerWord(input) {
+    const gatewayFeeBps = input.gatewayFeeBps ?? 0;
+    const wordPayment = addBasisPoints(input.pricePerWordAtomic, gatewayFeeBps);
+    return {
+        currency: "USDC",
+        meteringUnit: "word",
+        pricePerWordAtomic: `${input.pricePerWordAtomic}`,
+        gatewayFeeBps,
+        wordPaymentAtomic: `${wordPayment}`,
+    };
+}
+export function usageForWords(input) {
+    const gatewayFeeBps = input.gatewayFeeBps ?? 0;
+    const creatorAmount = input.pricePerWordAtomic * BigInt(input.wordsDelivered);
+    const total = addBasisPoints(creatorAmount, gatewayFeeBps);
+    return {
+        unit: "word",
+        wordsDelivered: input.wordsDelivered,
+        creatorAmountAtomic: `${creatorAmount}`,
+        rubiconFeeAtomic: `${total - creatorAmount}`,
+        totalPaidAtomic: `${total}`,
+    };
+}
+//# sourceMappingURL=pricing.js.map

package/dist/pricing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pricing.js","sourceRoot":"","sources":["../src/pricing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAmC5C,MAAM,UAAU,YAAY,CAAC,KAG5B;IACC,MAAM,aAAa,GAAG,KAAK,CAAC,aAAa,IAAI,CAAC,CAAC;IAC/C,MAAM,WAAW,GAAG,cAAc,CAAC,KAAK,CAAC,kBAAkB,EAAE,aAAa,CAAC,CAAC;IAC5E,OAAO;QACL,QAAQ,EAAE,MAAM;QAChB,YAAY,EAAE,MAAM;QACpB,kBAAkB,EAAE,GAAG,KAAK,CAAC,kBAAkB,EAAE;QACjD,aAAa;QACb,iBAAiB,EAAE,GAAG,WAAW,EAAE;KACpC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAI7B;IACC,MAAM,aAAa,GAAG,KAAK,CAAC,aAAa,IAAI,CAAC,CAAC;IAC/C,MAAM,aAAa,GAAG,KAAK,CAAC,kBAAkB,GAAG,MAAM,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;IAC9E,MAAM,KAAK,GAAG,cAAc,CAAC,aAAa,EAAE,aAAa,CAAC,CAAC;IAC3D,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,cAAc,EAAE,KAAK,CAAC,cAAc;QACpC,mBAAmB,EAAE,GAAG,aAAa,EAAE;QACvC,gBAAgB,EAAE,GAAG,KAAK,GAAG,aAAa,EAAE;QAC5C,eAAe,EAAE,GAAG,KAAK,EAAE;KAC5B,CAAC;AACJ,CAAC"}

package/dist/protocol.d.ts

@@ -0,0 +1,218 @@
+import type { AtomicAmount } from "./money.js";
+import type { ArticleState } from "./contract.js";
+import type { WordUsageReport } from "./pricing.js";
+import type { SessionState } from "./session.js";
+export interface Budget {
+    currency: "USDC";
+    maxAmountAtomic: AtomicAmount;
+}
+/** Safe public article metadata. Never includes unpaid body text. */
+export interface ArticleSummary {
+    articleId: string;
+    creatorId: string;
+    creatorUsername: string;
+    title: string;
+    author: string;
+    state: ArticleState;
+    totalWords: number;
+    pricePerWordAtomic: AtomicAmount;
+    /** Maximum possible total price to read the whole article. */
+    maxArticlePriceAtomic: AtomicAmount;
+    sections: ArticleSectionSummary[];
+}
+/** Safe per-section navigation metadata. Headings only, no body content. */
+export interface ArticleSectionSummary {
+    sectionId: string;
+    heading: string;
+    level: number;
+    wordStart: number;
+    wordCount: number;
+}
+export interface ArticleNavigation {
+    articleId: string;
+    sections: ArticleSectionSummary[];
+    /** Free, safe routing produced by the seller agent (no unpaid body text). */
+    sellerAgent: SellerNavigationSummary;
+    stopConditions: StreamStopCondition[];
+}
+export interface SellerNavigationSummary {
+    recommendedSectionId: string;
+    alternativeSectionIds: string[];
+    rationale: string;
+    safeHints: string[];
+    withheld: string[];
+}
+export interface StreamStopCondition {
+    kind: "max_words" | "max_payments" | "max_spend_atomic" | "sufficient_information" | "article_completed" | "payment_rejected";
+    description: string;
+    value?: string | number;
+}
+export interface StartConversationRequest {
+    articleId: string;
+    goal?: string;
+    message?: string;
+}
+export interface StartConversationResponse {
+    conversationId: string;
+    articleId: string;
+    article: ArticleSummary;
+    navigation: ArticleNavigation;
+    messages: ConversationMessage[];
+}
+export interface SendConversationMessageRequest {
+    message: string;
+}
+export interface SendConversationMessageResponse {
+    conversationId: string;
+    messages: ConversationMessage[];
+    recommendedSectionId?: string;
+}
+export interface ConversationMessage {
+    id: string;
+    role: "buyer" | "seller";
+    content: string;
+    recommendedSectionId?: string;
+    createdAt: string;
+}
+export interface StartSessionRequest {
+    articleId: string;
+    goal?: string;
+    conversationId?: string;
+    sectionId?: string;
+    budget: Budget;
+    metadata?: Record<string, unknown>;
+}
+export interface StartSessionResponse {
+    sessionId: string;
+    state: SessionState;
+    article: ArticleSummary;
+    navigation: ArticleNavigation;
+    /** Price the creator earns for one word. */
+    pricePerWordAtomic: AtomicAmount;
+    /** Maximum possible total price for the whole article. */
+    maxArticlePriceAtomic: AtomicAmount;
+    conversationId: string;
+    /** Exact amount the buyer pays to release one additional word. */
+    wordPaymentAtomic: AtomicAmount;
+    gatewayFeeBps: number;
+    /** x402 payment requirement for one word (when Circle/x402 is enabled). */
+    paymentRequired?: unknown;
+    expiresAt: string;
+    wordsPaid: number;
+    wordsDelivered: number;
+    paidAtomic: AtomicAmount;
+}
+/**
+ * One word-level payment. `idempotencyKey` ties a payment to a specific next
+ * word sequence so retries never release or charge for a word twice.
+ */
+export interface StreamPaymentRequest {
+    paymentPayload: unknown;
+    idempotencyKey?: string;
+}
+export interface StreamPaymentResponse {
+    accepted: boolean;
+    sequence: number;
+    word: string;
+    priceAtomic: AtomicAmount;
+    wordsPaid: number;
+    wordsDelivered: number;
+    paidAtomic: AtomicAmount;
+    completed: boolean;
+    /** Canonical, per-word settlement receipt. Present whenever a word is released. */
+    payment?: WordPaymentReceipt;
+    /** On-chain settlement transaction hash returned by the payment facilitator. */
+    transactionHash?: string;
+    /** All on-chain settlement transaction hashes for this payment, when available. */
+    transactionHashes?: string[];
+    /** Backwards-compatible alias for transactionHash. */
+    transferId?: string;
+}
+export interface WordPaymentReceipt {
+    paymentId: string;
+    sessionId: string;
+    articleId: string;
+    sequence: number;
+    meteringUnit: "word";
+    amountAtomic: AtomicAmount;
+    currency: "USDC";
+    network?: string;
+    payTo?: `0x${string}`;
+    transactionHash?: string;
+    transactionHashes?: string[];
+    /** Backwards-compatible alias for transactionHash. */
+    transferId?: string;
+    settledAt: string;
+}
+export interface PaymentVerification {
+    accepted: boolean;
+    transactionHash?: string;
+    transactionHashes?: string[];
+    transferId?: string;
+    network?: string;
+    payTo?: `0x${string}`;
+    amountAtomic?: AtomicAmount;
+    reason?: string;
+}
+export type GatewayEvent = {
+    type: "session.started";
+    sessionId: string;
+    articleId: string;
+    state: SessionState;
+    article: ArticleSummary;
+    pricePerWordAtomic: AtomicAmount;
+    wordPaymentAtomic: AtomicAmount;
+} | {
+    type: "seller.message";
+    sessionId: string;
+    conversationId: string;
+    role: "seller";
+    message: string;
+    recommendedSectionId?: string;
+} | {
+    type: "word.payment_accepted";
+    sessionId: string;
+    sequence: number;
+    paymentId: string;
+    amountAtomic: AtomicAmount;
+    network?: string;
+    payTo?: `0x${string}`;
+    transactionHash?: string;
+    transactionHashes?: string[];
+    transferId?: string;
+} | {
+    type: "article.word";
+    sessionId: string;
+    articleId: string;
+    sequence: number;
+    word: string;
+    priceAtomic: AtomicAmount;
+    totalWordsStreamed: number;
+    totalPaidAtomic: AtomicAmount;
+} | {
+    type: "article.usage";
+    sessionId: string;
+    usage: WordUsageReport;
+    wordsPaid: number;
+    wordsDelivered: number;
+    paidAtomic: AtomicAmount;
+} | {
+    type: "article.completed";
+    sessionId: string;
+    articleId: string;
+    totalWordsStreamed: number;
+    totalPaidAtomic: AtomicAmount;
+} | {
+    type: "article.error";
+    sessionId: string;
+    message: string;
+} | {
+    type: "session.aborted";
+    sessionId: string;
+    reason: string;
+} | {
+    type: "session.closed";
+    sessionId: string;
+    reason: string;
+};
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

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

package/dist/protocol.js

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

package/dist/protocol.js.map

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

package/dist/session.d.ts

@@ -0,0 +1,55 @@
+import type { AtomicAmount } from "./money.js";
+import type { Budget } from "./protocol.js";
+export type SessionState = "open" | "active" | "completed" | "aborted" | "expired";
+/**
+ * Runtime state for one budgeted reading session. All trusted values
+ * (pricePerWordAtomic, gatewayFeeBps, sellerWallet, creatorId) are loaded from
+ * persistent storage when the session is created — never from buyer input.
+ */
+export interface SessionRecord {
+    id: string;
+    articleId: string;
+    creatorId: string;
+    conversationId?: string;
+    goal?: string;
+    sectionId?: string;
+    budget: Budget;
+    /** Trusted price snapshot, copied from the stored article at session start. */
+    pricePerWordAtomic: bigint;
+    gatewayFeeBps: number;
+    /** Trusted settlement recipient, copied from the verified creator wallet. */
+    sellerWallet: `0x${string}`;
+    metadata: Record<string, unknown>;
+    state: SessionState;
+    /** Words the buyer has paid for (one payment === one word). */
+    wordsPaid: number;
+    /** Words actually delivered to the buyer. */
+    wordsDelivered: number;
+    /** Total atomic USDC the buyer has paid in this session. */
+    paidAtomic: bigint;
+    createdAt: Date;
+    updatedAt: Date;
+    expiresAt: Date;
+}
+export declare function createSession(input: {
+    id?: string;
+    articleId: string;
+    creatorId: string;
+    conversationId?: string;
+    goal?: string;
+    sectionId?: string;
+    budget: Budget;
+    pricePerWordAtomic: bigint;
+    gatewayFeeBps: number;
+    sellerWallet: `0x${string}`;
+    metadata?: Record<string, unknown>;
+    ttlMs: number;
+}): SessionRecord;
+/** Whether one more word payment fits inside the session budget. */
+export declare function canAffordNextWord(session: SessionRecord, wordPaymentAtomic: bigint): boolean;
+/** Record that one word's payment has been accepted. */
+export declare function recordWordPayment(session: SessionRecord, amountAtomic: AtomicAmount): SessionRecord;
+/** Record that one paid word has been delivered. */
+export declare function recordWordDelivery(session: SessionRecord): SessionRecord;
+export declare function isSessionExpired(session: SessionRecord, now?: Date): boolean;
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAE5C,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,QAAQ,GAAG,WAAW,GAAG,SAAS,GAAG,SAAS,CAAC;AAEnF;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,kBAAkB,EAAE,MAAM,CAAC;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,YAAY,EAAE,KAAK,MAAM,EAAE,CAAC;IAC5B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,KAAK,EAAE,YAAY,CAAC;IACpB,+DAA+D;IAC/D,SAAS,EAAE,MAAM,CAAC;IAClB,6CAA6C;IAC7C,cAAc,EAAE,MAAM,CAAC;IACvB,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;CACjB;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE;IACnC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB,EAAE,MAAM,CAAC;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,KAAK,MAAM,EAAE,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,KAAK,EAAE,MAAM,CAAC;CACf,GAAG,aAAa,CAsBhB;AAED,oEAAoE;AACpE,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,GAAG,OAAO,CAE5F;AAED,wDAAwD;AACxD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,GAAG,aAAa,CAQnG;AAED,oDAAoD;AACpD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,aAAa,GAAG,aAAa,CAIxE;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,OAAa,GAAG,OAAO,CAElF"}

package/dist/session.js

@@ -0,0 +1,48 @@
+import { randomUUID } from "node:crypto";
+export function createSession(input) {
+    const now = new Date();
+    return {
+        id: input.id ?? randomUUID(),
+        articleId: input.articleId,
+        creatorId: input.creatorId,
+        conversationId: input.conversationId,
+        goal: input.goal,
+        sectionId: input.sectionId,
+        budget: input.budget,
+        pricePerWordAtomic: input.pricePerWordAtomic,
+        gatewayFeeBps: input.gatewayFeeBps,
+        sellerWallet: input.sellerWallet,
+        metadata: input.metadata ?? {},
+        state: "open",
+        wordsPaid: 0,
+        wordsDelivered: 0,
+        paidAtomic: 0n,
+        createdAt: now,
+        updatedAt: now,
+        expiresAt: new Date(now.getTime() + input.ttlMs),
+    };
+}
+/** Whether one more word payment fits inside the session budget. */
+export function canAffordNextWord(session, wordPaymentAtomic) {
+    return session.paidAtomic + wordPaymentAtomic <= BigInt(session.budget.maxAmountAtomic);
+}
+/** Record that one word's payment has been accepted. */
+export function recordWordPayment(session, amountAtomic) {
+    session.paidAtomic += BigInt(amountAtomic);
+    session.wordsPaid += 1;
+    session.updatedAt = new Date();
+    if (session.state === "open") {
+        session.state = "active";
+    }
+    return session;
+}
+/** Record that one paid word has been delivered. */
+export function recordWordDelivery(session) {
+    session.wordsDelivered += 1;
+    session.updatedAt = new Date();
+    return session;
+}
+export function isSessionExpired(session, now = new Date()) {
+    return session.expiresAt.getTime() <= now.getTime();
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAsCzC,MAAM,UAAU,aAAa,CAAC,KAa7B;IACC,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;IACvB,OAAO;QACL,EAAE,EAAE,KAAK,CAAC,EAAE,IAAI,UAAU,EAAE;QAC5B,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,cAAc,EAAE,KAAK,CAAC,cAAc;QACpC,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,kBAAkB,EAAE,KAAK,CAAC,kBAAkB;QAC5C,aAAa,EAAE,KAAK,CAAC,aAAa;QAClC,YAAY,EAAE,KAAK,CAAC,YAAY;QAChC,QAAQ,EAAE,KAAK,CAAC,QAAQ,IAAI,EAAE;QAC9B,KAAK,EAAE,MAAM;QACb,SAAS,EAAE,CAAC;QACZ,cAAc,EAAE,CAAC;QACjB,UAAU,EAAE,EAAE;QACd,SAAS,EAAE,GAAG;QACd,SAAS,EAAE,GAAG;QACd,SAAS,EAAE,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC;KACjD,CAAC;AACJ,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,iBAAiB,CAAC,OAAsB,EAAE,iBAAyB;IACjF,OAAO,OAAO,CAAC,UAAU,GAAG,iBAAiB,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;AAC1F,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,iBAAiB,CAAC,OAAsB,EAAE,YAA0B;IAClF,OAAO,CAAC,UAAU,IAAI,MAAM,CAAC,YAAY,CAAC,CAAC;IAC3C,OAAO,CAAC,SAAS,IAAI,CAAC,CAAC;IACvB,OAAO,CAAC,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC;IAC/B,IAAI,OAAO,CAAC,KAAK,KAAK,MAAM,EAAE,CAAC;QAC7B,OAAO,CAAC,KAAK,GAAG,QAAQ,CAAC;IAC3B,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,oDAAoD;AACpD,MAAM,UAAU,kBAAkB,CAAC,OAAsB;IACvD,OAAO,CAAC,cAAc,IAAI,CAAC,CAAC;IAC5B,OAAO,CAAC,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC;IAC/B,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,OAAsB,EAAE,GAAG,GAAG,IAAI,IAAI,EAAE;IACvE,OAAO,OAAO,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;AACtD,CAAC"}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@rubicon-caliga/core",
+  "version": "0.1.0",
+  "description": "Shared protocol types, pricing math, and session primitives for the Rubicon x402 streaming gateway.",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/michaelzoub/rubicon.git",
+    "directory": "packages/core"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/index.ts",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test dist/**/*.test.js",
+    "prepublishOnly": "pnpm run build"
+  }
+}

package/src/contract.ts

@@ -0,0 +1,148 @@
+import type { AtomicAmount } from "./money.js";
+
+/**
+ * Shared API contract between Rubicon (this gateway) and the rubicon-marketing
+ * Next.js application. Both repositories agree on these shapes, the article
+ * states, pricing units (atomic USDC, 1 USDC = 1_000_000), word-counting rules,
+ * wallet format, creator ownership, and seller-agent configuration.
+ *
+ * These types describe the shared persistent data model. The marketing app owns
+ * creator authentication and creator-facing CRUD; Rubicon reads published data
+ * and writes runtime read/earnings activity.
+ */
+
+/**
+ * Lifecycle of an article. Only `live` articles are consumable by buyer agents
+ * or visible in the public repository.
+ */
+export type ArticleState = "draft" | "live" | "paused" | "archived" | "deleted";
+
+export const PUBLIC_ARTICLE_STATE: ArticleState = "live";
+
+export type WalletNetwork = string; // CAIP-2 string, e.g. "eip155:5042002"
+
+export interface Creator {
+  id: string;
+  username: string;
+  displayName: string;
+  createdAt: string;
+}
+
+export interface CreatorProfile {
+  creatorId: string;
+  bio?: string;
+  avatarUrl?: string;
+}
+
+export interface CreatorWallet {
+  creatorId: string;
+  /** Verified receiving wallet. Settlement always pays this address. */
+  address: `0x${string}`;
+  network: WalletNetwork;
+  verified: boolean;
+}
+
+export interface ArticleSection {
+  id: string;
+  articleId: string;
+  /** Stable slug used by buyer agents for navigation. */
+  sectionId: string;
+  heading: string;
+  level: number;
+  /** Zero-based word index where this section's body begins. */
+  wordStart: number;
+  wordCount: number;
+  ordinal: number;
+}
+
+/**
+ * Optional per-article seller-agent configuration. Agreed between Rubicon and
+ * rubicon-marketing; absent values fall back to gateway defaults.
+ */
+export interface SellerAgentConfig {
+  persona?: string;
+  /** Identifier of a configured model/provider, e.g. "anthropic:claude-opus-4-8". */
+  model?: string;
+  /** Extra navigation guidance the creator wants the seller agent to follow. */
+  guidance?: string;
+}
+
+export interface Article {
+  id: string;
+  creatorId: string;
+  title: string;
+  author: string;
+  state: ArticleState;
+  pricePerWordAtomic: AtomicAmount;
+  /** Optional creator-set cap on the total price of the article. */
+  maxArticlePriceAtomic?: AtomicAmount;
+  totalWords: number;
+  revision: number;
+  sellerAgentConfig?: SellerAgentConfig;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface EarningsSummary {
+  creatorId: string;
+  articleId?: string;
+  wordsDelivered: number;
+  creatorAmountAtomic: AtomicAmount;
+  rubiconFeeAtomic: AtomicAmount;
+}
+
+export interface PaymentActivity {
+  paymentId: string;
+  sessionId: string;
+  articleId: string;
+  sequence: number;
+  amountAtomic: AtomicAmount;
+  creatorAmountAtomic: AtomicAmount;
+  rubiconFeeAtomic: AtomicAmount;
+  network?: string;
+  payTo?: `0x${string}`;
+  transactionHash?: string;
+  transactionHashes?: string[];
+  transferId?: string;
+  createdAt: string;
+}
+
+export interface SellerAgentMessageRecord {
+  id: string;
+  conversationId: string;
+  sessionId?: string;
+  articleId: string;
+  role: "buyer" | "seller";
+  content: string;
+  createdAt: string;
+}
+
+export interface StreamSessionRecord {
+  id: string;
+  articleId: string;
+  creatorId: string;
+  conversationId?: string;
+  state: string;
+  wordsPaid: number;
+  wordsDelivered: number;
+  paidAtomic: AtomicAmount;
+  budgetAtomic: AtomicAmount;
+  createdAt: string;
+  expiresAt: string;
+}
+
+export interface WordDeliveryRecord {
+  sessionId: string;
+  articleId: string;
+  sequence: number;
+  word: string;
+  priceAtomic: AtomicAmount;
+  paymentId: string;
+  createdAt: string;
+}
+
+export interface ApiError {
+  error: string;
+  message?: string;
+  details?: Record<string, unknown>;
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from "./money.js";
+export * from "./contract.js";
+export * from "./pricing.js";
+export * from "./protocol.js";
+export * from "./session.js";

package/src/money.ts

@@ -0,0 +1,19 @@
+export const USDC_ATOMIC_UNITS = 1_000_000n;
+
+export type AtomicAmount = `${bigint}`;
+
+export function parseUsdcToAtomic(value: string): bigint {
+  const [whole = "0", fraction = ""] = value.split(".");
+  const paddedFraction = `${fraction}000000`.slice(0, 6);
+  return BigInt(whole) * USDC_ATOMIC_UNITS + BigInt(paddedFraction);
+}
+
+export function formatAtomicUsdc(amount: bigint): string {
+  const whole = amount / USDC_ATOMIC_UNITS;
+  const fraction = `${amount % USDC_ATOMIC_UNITS}`.padStart(6, "0").replace(/0+$/, "");
+  return fraction.length > 0 ? `${whole}.${fraction}` : `${whole}`;
+}
+
+export function addBasisPoints(amount: bigint, basisPoints: number): bigint {
+  return amount + (amount * BigInt(basisPoints)) / 10_000n;
+}

package/src/pricing.ts

@@ -0,0 +1,66 @@
+import { addBasisPoints } from "./money.js";
+
+export type MeteringUnit = "word";
+
+/**
+ * The atomic content unit in Rubicon is exactly one word. A quote describes the
+ * price the creator earns for a single word and the amount the buyer must pay to
+ * release one additional word.
+ *
+ * Rubicon never bills in chunks. Circle/x402 may batch settlement internally,
+ * but the application-level accounting is always one word = one paid unit.
+ */
+export interface WordPriceQuote {
+  currency: "USDC";
+  meteringUnit: MeteringUnit;
+  /** Price the creator earns for one delivered word. */
+  pricePerWordAtomic: `${bigint}`;
+  /** Rubicon gateway fee in basis points. Defaults to 0. */
+  gatewayFeeBps: number;
+  /** Exact amount the buyer authorizes/sends to release one additional word. */
+  wordPaymentAtomic: `${bigint}`;
+}
+
+export interface WordUsageReport {
+  unit: MeteringUnit;
+  /** Number of individually delivered, individually paid words. */
+  wordsDelivered: number;
+  /** Full word price accruing to the creator (no Rubicon fee deducted). */
+  creatorAmountAtomic: `${bigint}`;
+  /** Rubicon fee. Zero by default — creators keep the full word price. */
+  rubiconFeeAtomic: `${bigint}`;
+  /** Total atomic USDC the buyer paid for these words. */
+  totalPaidAtomic: `${bigint}`;
+}
+
+export function quotePerWord(input: {
+  pricePerWordAtomic: bigint;
+  gatewayFeeBps?: number;
+}): WordPriceQuote {
+  const gatewayFeeBps = input.gatewayFeeBps ?? 0;
+  const wordPayment = addBasisPoints(input.pricePerWordAtomic, gatewayFeeBps);
+  return {
+    currency: "USDC",
+    meteringUnit: "word",
+    pricePerWordAtomic: `${input.pricePerWordAtomic}`,
+    gatewayFeeBps,
+    wordPaymentAtomic: `${wordPayment}`,
+  };
+}
+
+export function usageForWords(input: {
+  wordsDelivered: number;
+  pricePerWordAtomic: bigint;
+  gatewayFeeBps?: number;
+}): WordUsageReport {
+  const gatewayFeeBps = input.gatewayFeeBps ?? 0;
+  const creatorAmount = input.pricePerWordAtomic * BigInt(input.wordsDelivered);
+  const total = addBasisPoints(creatorAmount, gatewayFeeBps);
+  return {
+    unit: "word",
+    wordsDelivered: input.wordsDelivered,
+    creatorAmountAtomic: `${creatorAmount}`,
+    rubiconFeeAtomic: `${total - creatorAmount}`,
+    totalPaidAtomic: `${total}`,
+  };
+}

package/src/protocol.ts

@@ -0,0 +1,250 @@
+import type { AtomicAmount } from "./money.js";
+import type { ArticleState } from "./contract.js";
+import type { WordUsageReport } from "./pricing.js";
+import type { SessionState } from "./session.js";
+
+export interface Budget {
+  currency: "USDC";
+  maxAmountAtomic: AtomicAmount;
+}
+
+/** Safe public article metadata. Never includes unpaid body text. */
+export interface ArticleSummary {
+  articleId: string;
+  creatorId: string;
+  creatorUsername: string;
+  title: string;
+  author: string;
+  state: ArticleState;
+  totalWords: number;
+  pricePerWordAtomic: AtomicAmount;
+  /** Maximum possible total price to read the whole article. */
+  maxArticlePriceAtomic: AtomicAmount;
+  sections: ArticleSectionSummary[];
+}
+
+/** Safe per-section navigation metadata. Headings only, no body content. */
+export interface ArticleSectionSummary {
+  sectionId: string;
+  heading: string;
+  level: number;
+  wordStart: number;
+  wordCount: number;
+}
+
+export interface ArticleNavigation {
+  articleId: string;
+  sections: ArticleSectionSummary[];
+  /** Free, safe routing produced by the seller agent (no unpaid body text). */
+  sellerAgent: SellerNavigationSummary;
+  stopConditions: StreamStopCondition[];
+}
+
+export interface SellerNavigationSummary {
+  recommendedSectionId: string;
+  alternativeSectionIds: string[];
+  rationale: string;
+  safeHints: string[];
+  withheld: string[];
+}
+
+export interface StreamStopCondition {
+  kind:
+    | "max_words"
+    | "max_payments"
+    | "max_spend_atomic"
+    | "sufficient_information"
+    | "article_completed"
+    | "payment_rejected";
+  description: string;
+  value?: string | number;
+}
+
+// ---------------------------------------------------------------------------
+// Seller-agent conversations
+// ---------------------------------------------------------------------------
+
+export interface StartConversationRequest {
+  articleId: string;
+  goal?: string;
+  message?: string;
+}
+
+export interface StartConversationResponse {
+  conversationId: string;
+  articleId: string;
+  article: ArticleSummary;
+  navigation: ArticleNavigation;
+  messages: ConversationMessage[];
+}
+
+export interface SendConversationMessageRequest {
+  message: string;
+}
+
+export interface SendConversationMessageResponse {
+  conversationId: string;
+  messages: ConversationMessage[];
+  recommendedSectionId?: string;
+}
+
+export interface ConversationMessage {
+  id: string;
+  role: "buyer" | "seller";
+  content: string;
+  recommendedSectionId?: string;
+  createdAt: string;
+}
+
+// ---------------------------------------------------------------------------
+// Sessions
+// ---------------------------------------------------------------------------
+
+export interface StartSessionRequest {
+  articleId: string;
+  goal?: string;
+  conversationId?: string;
+  sectionId?: string;
+  budget: Budget;
+  metadata?: Record<string, unknown>;
+}
+
+export interface StartSessionResponse {
+  sessionId: string;
+  state: SessionState;
+  article: ArticleSummary;
+  navigation: ArticleNavigation;
+  /** Price the creator earns for one word. */
+  pricePerWordAtomic: AtomicAmount;
+  /** Maximum possible total price for the whole article. */
+  maxArticlePriceAtomic: AtomicAmount;
+  conversationId: string;
+  /** Exact amount the buyer pays to release one additional word. */
+  wordPaymentAtomic: AtomicAmount;
+  gatewayFeeBps: number;
+  /** x402 payment requirement for one word (when Circle/x402 is enabled). */
+  paymentRequired?: unknown;
+  expiresAt: string;
+  wordsPaid: number;
+  wordsDelivered: number;
+  paidAtomic: AtomicAmount;
+}
+
+/**
+ * One word-level payment. `idempotencyKey` ties a payment to a specific next
+ * word sequence so retries never release or charge for a word twice.
+ */
+export interface StreamPaymentRequest {
+  paymentPayload: unknown;
+  idempotencyKey?: string;
+}
+
+export interface StreamPaymentResponse {
+  accepted: boolean;
+  sequence: number;
+  word: string;
+  priceAtomic: AtomicAmount;
+  wordsPaid: number;
+  wordsDelivered: number;
+  paidAtomic: AtomicAmount;
+  completed: boolean;
+  /** Canonical, per-word settlement receipt. Present whenever a word is released. */
+  payment?: WordPaymentReceipt;
+  /** On-chain settlement transaction hash returned by the payment facilitator. */
+  transactionHash?: string;
+  /** All on-chain settlement transaction hashes for this payment, when available. */
+  transactionHashes?: string[];
+  /** Backwards-compatible alias for transactionHash. */
+  transferId?: string;
+}
+
+export interface WordPaymentReceipt {
+  paymentId: string;
+  sessionId: string;
+  articleId: string;
+  sequence: number;
+  meteringUnit: "word";
+  amountAtomic: AtomicAmount;
+  currency: "USDC";
+  network?: string;
+  payTo?: `0x${string}`;
+  transactionHash?: string;
+  transactionHashes?: string[];
+  /** Backwards-compatible alias for transactionHash. */
+  transferId?: string;
+  settledAt: string;
+}
+
+export interface PaymentVerification {
+  accepted: boolean;
+  transactionHash?: string;
+  transactionHashes?: string[];
+  transferId?: string;
+  network?: string;
+  payTo?: `0x${string}`;
+  amountAtomic?: AtomicAmount;
+  reason?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Events
+// ---------------------------------------------------------------------------
+
+export type GatewayEvent =
+  | {
+      type: "session.started";
+      sessionId: string;
+      articleId: string;
+      state: SessionState;
+      article: ArticleSummary;
+      pricePerWordAtomic: AtomicAmount;
+      wordPaymentAtomic: AtomicAmount;
+    }
+  | {
+      type: "seller.message";
+      sessionId: string;
+      conversationId: string;
+      role: "seller";
+      message: string;
+      recommendedSectionId?: string;
+    }
+  | {
+      type: "word.payment_accepted";
+      sessionId: string;
+      sequence: number;
+      paymentId: string;
+      amountAtomic: AtomicAmount;
+      network?: string;
+      payTo?: `0x${string}`;
+      transactionHash?: string;
+      transactionHashes?: string[];
+      transferId?: string;
+    }
+  | {
+      type: "article.word";
+      sessionId: string;
+      articleId: string;
+      sequence: number;
+      word: string;
+      priceAtomic: AtomicAmount;
+      totalWordsStreamed: number;
+      totalPaidAtomic: AtomicAmount;
+    }
+  | {
+      type: "article.usage";
+      sessionId: string;
+      usage: WordUsageReport;
+      wordsPaid: number;
+      wordsDelivered: number;
+      paidAtomic: AtomicAmount;
+    }
+  | {
+      type: "article.completed";
+      sessionId: string;
+      articleId: string;
+      totalWordsStreamed: number;
+      totalPaidAtomic: AtomicAmount;
+    }
+  | { type: "article.error"; sessionId: string; message: string }
+  | { type: "session.aborted"; sessionId: string; reason: string }
+  | { type: "session.closed"; sessionId: string; reason: string };

package/src/session.ts

@@ -0,0 +1,101 @@
+import { randomUUID } from "node:crypto";
+
+import type { AtomicAmount } from "./money.js";
+import type { Budget } from "./protocol.js";
+
+export type SessionState = "open" | "active" | "completed" | "aborted" | "expired";
+
+/**
+ * Runtime state for one budgeted reading session. All trusted values
+ * (pricePerWordAtomic, gatewayFeeBps, sellerWallet, creatorId) are loaded from
+ * persistent storage when the session is created — never from buyer input.
+ */
+export interface SessionRecord {
+  id: string;
+  articleId: string;
+  creatorId: string;
+  conversationId?: string;
+  goal?: string;
+  sectionId?: string;
+  budget: Budget;
+  /** Trusted price snapshot, copied from the stored article at session start. */
+  pricePerWordAtomic: bigint;
+  gatewayFeeBps: number;
+  /** Trusted settlement recipient, copied from the verified creator wallet. */
+  sellerWallet: `0x${string}`;
+  metadata: Record<string, unknown>;
+  state: SessionState;
+  /** Words the buyer has paid for (one payment === one word). */
+  wordsPaid: number;
+  /** Words actually delivered to the buyer. */
+  wordsDelivered: number;
+  /** Total atomic USDC the buyer has paid in this session. */
+  paidAtomic: bigint;
+  createdAt: Date;
+  updatedAt: Date;
+  expiresAt: Date;
+}
+
+export function createSession(input: {
+  id?: string;
+  articleId: string;
+  creatorId: string;
+  conversationId?: string;
+  goal?: string;
+  sectionId?: string;
+  budget: Budget;
+  pricePerWordAtomic: bigint;
+  gatewayFeeBps: number;
+  sellerWallet: `0x${string}`;
+  metadata?: Record<string, unknown>;
+  ttlMs: number;
+}): SessionRecord {
+  const now = new Date();
+  return {
+    id: input.id ?? randomUUID(),
+    articleId: input.articleId,
+    creatorId: input.creatorId,
+    conversationId: input.conversationId,
+    goal: input.goal,
+    sectionId: input.sectionId,
+    budget: input.budget,
+    pricePerWordAtomic: input.pricePerWordAtomic,
+    gatewayFeeBps: input.gatewayFeeBps,
+    sellerWallet: input.sellerWallet,
+    metadata: input.metadata ?? {},
+    state: "open",
+    wordsPaid: 0,
+    wordsDelivered: 0,
+    paidAtomic: 0n,
+    createdAt: now,
+    updatedAt: now,
+    expiresAt: new Date(now.getTime() + input.ttlMs),
+  };
+}
+
+/** Whether one more word payment fits inside the session budget. */
+export function canAffordNextWord(session: SessionRecord, wordPaymentAtomic: bigint): boolean {
+  return session.paidAtomic + wordPaymentAtomic <= BigInt(session.budget.maxAmountAtomic);
+}
+
+/** Record that one word's payment has been accepted. */
+export function recordWordPayment(session: SessionRecord, amountAtomic: AtomicAmount): SessionRecord {
+  session.paidAtomic += BigInt(amountAtomic);
+  session.wordsPaid += 1;
+  session.updatedAt = new Date();
+  if (session.state === "open") {
+    session.state = "active";
+  }
+  return session;
+}
+
+/** Record that one paid word has been delivered. */
+export function recordWordDelivery(session: SessionRecord): SessionRecord {
+  session.wordsDelivered += 1;
+  session.updatedAt = new Date();
+  return session;
+}
+
+export function isSessionExpired(session: SessionRecord, now = new Date()): boolean {
+  return session.expiresAt.getTime() <= now.getTime();
+}