@ergoblockchain/sage-widget 0.1.0 → 0.2.0

package/dist/types-yv1THHVz.d.ts

@@ -0,0 +1,229 @@
+/**
+ * Public types for the Sage activity feed and paid chat flow.
+ *
+ * The source of truth is the API at https://www.ergoblockchain.org/api/sage/activity;
+ * this file re-states the schema so consumers don't have to depend on the
+ * server-side fetcher.
+ */
+type SageActivityType = "settlement" | "issuance" | "transfer";
+interface SageActivityEvent {
+    /** 64-char hex transaction id. */
+    txId: string;
+    /** Block height at inclusion. */
+    blockHeight: number;
+    /** Block timestamp (ms epoch). */
+    timestamp: number;
+    /** Heuristic classification of the tx. */
+    type: SageActivityType;
+    /** nanoERG flowing into the seller wallet from this tx (sum of outputs). */
+    inflowNanoErg: number;
+    /**
+     * For settlements: value of the redeemed Note (= what the buyer paid).
+     * For other event types: undefined.
+     *
+     * Use this — not `inflowNanoErg` — when displaying "amount paid for a
+     * settled query". `inflowNanoErg` includes change boxes in test setups
+     * where the buyer and seller share an address.
+     */
+    paymentNanoErg?: number;
+    /** First input box that carries Note-shape registers, if any. */
+    noteBoxId?: string;
+}
+interface SageActivityResponse {
+    ok: boolean;
+    network: "testnet" | "mainnet";
+    /** Sage seller wallet address. */
+    receiver: string;
+    /** Total number of txs ever touching the wallet, per the explorer. */
+    total: number;
+    events: SageActivityEvent[];
+    error?: string;
+}
+/**
+ * Configuration accepted by every entry point (React component +
+ * vanilla mount fn). Defaults below are sensible for the canonical
+ * ergoblockchain.org deployment.
+ */
+interface SageWidgetOptions {
+    /**
+     * Base URL of the Sage host. Override if you run your own Sage
+     * deployment behind a custom domain. Default: ergoblockchain.org.
+     */
+    apiBase?: string;
+    /**
+     * Number of events to display (max 25). Default: 5.
+     */
+    limit?: number;
+    /**
+     * Polling interval in ms. Default: 60000 (60s). Set to 0 to disable
+     * polling — the widget will fetch once on mount and never refresh.
+     */
+    refreshMs?: number;
+    /**
+     * Optional callback fired every time a fresh response arrives. Useful
+     * for analytics or for triggering host-side animations on new
+     * settlements.
+     */
+    onUpdate?: (response: SageActivityResponse) => void;
+    /**
+     * Optional callback fired on fetch errors. Default: console.warn.
+     */
+    onError?: (error: unknown) => void;
+}
+type SageChatRole = "user" | "assistant";
+interface SageChatMessage {
+    role: SageChatRole;
+    content: string;
+}
+interface SageTenantConfig {
+    /** Stable tenant id for analytics, logs, or future multi-tenant routing. */
+    id?: string;
+    /** Human-facing label shown in the default widgets. */
+    label?: string;
+    /** Extra headers attached to Sage API requests. */
+    headers?: Record<string, string>;
+}
+interface SageQuote {
+    quoteId: string;
+    taskHash: string;
+    price: string;
+    issuedAt?: string;
+    expiresAt: string;
+    receiverAddress: string;
+    reserveBoxId: string;
+    deadline: `+${number} blocks`;
+}
+type SagePremiumReason = "explicit_command" | "code_request" | "long_answer" | "deep_research" | "multi_turn_followup";
+interface SageQuoteResponse {
+    premium: boolean;
+    reason?: SagePremiumReason;
+    rationale?: string;
+    quote?: SageQuote;
+}
+interface SageVerifyPaymentResponse {
+    ok: true;
+    paymentToken: string;
+    receiptId: string;
+    receiptUrl: string;
+    receiptApiUrl: string;
+    settlementTxId?: string | null;
+    accordSettlementId?: string;
+    receiptStorage?: {
+        ok: boolean;
+        skipped?: boolean;
+        reason?: string;
+        path?: string;
+        aliases?: string[];
+        error?: string;
+    };
+}
+interface SagePremiumPaymentRequired {
+    error: "premium_payment_required";
+    reason?: SagePremiumReason;
+    rationale?: string;
+}
+type SageChatTier = "free" | "premium";
+type SageChatStreamEvent = {
+    type: "tier";
+    tier: SageChatTier;
+    model?: string;
+} | {
+    type: "delta";
+    text: string;
+} | {
+    type: "done";
+    stopReason?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+} | {
+    type: "error";
+    message: string;
+};
+interface SageChatStreamResult {
+    ok: boolean;
+    status: number;
+    text: string;
+    tier?: SageChatTier;
+    paymentRequired?: SagePremiumPaymentRequired;
+    error?: string;
+}
+interface SageReceiptBundle {
+    ok: true;
+    type: "sage.receipt_bundle.v1";
+    version: "v1";
+    id: string;
+    status: "settled_on_chain" | "verified_pending_redemption";
+    completeness: "full_receipt_bundle" | "full" | "chain_proof_only";
+    public_receipt_url: string;
+    api_receipt_url: string;
+    explorer_url: string | null;
+    accord?: {
+        agreement_hash?: string | null;
+        verification_receipt_hash?: string | null;
+        settlement_receipt_hash?: string | null;
+        agreement_json?: unknown;
+        verification_receipt_json?: unknown;
+        settlement_receipt_json?: unknown;
+    };
+}
+interface SagePaymentWidgetOptions {
+    /**
+     * Base URL of the Sage host. Default: ergoblockchain.org.
+     */
+    apiBase?: string;
+    /**
+     * Optional tenant metadata. Current public Sage ignores tenant routing,
+     * but the widget keeps this shape stable for multi-tenant deployments.
+     */
+    tenant?: SageTenantConfig;
+    /** Initial chat messages, useful for preloaded context. */
+    initialMessages?: SageChatMessage[];
+    /** Placeholder text for the default input. */
+    placeholder?: string;
+    /** Widget heading. React also accepts this through component props. */
+    title?: string;
+    /** Optional host-specific payment copy and links. */
+    paymentInstructions?: SagePaymentInstructions;
+    /** Called whenever a message is appended by the widget. */
+    onMessage?: (message: SageChatMessage, messages: SageChatMessage[]) => void;
+    /** Called after Sage returns a premium quote. */
+    onQuote?: (quote: SageQuoteResponse) => void;
+    /** Called after a payment verifies and Sage returns a receipt link. */
+    onReceipt?: (receipt: SageVerifyPaymentResponse) => void;
+    /** Called after the widget fetches the full machine-readable receipt bundle. */
+    onReceiptBundle?: (receipt: SageReceiptBundle) => void;
+    /** Called when the chat stream reports free vs premium tier. */
+    onTier?: (tier: SageChatTier) => void;
+    /** Called when the widget phase changes. */
+    onPhase?: (phase: SagePaymentPhase) => void;
+    /** Called with a compact state snapshot after important widget events. */
+    onStatus?: (status: SagePaymentWidgetStatus) => void;
+    /** Optional callback fired on fetch or stream errors. */
+    onError?: (error: unknown) => void;
+}
+type SagePaymentPhase = "idle" | "quoting" | "payment_required" | "verifying" | "streaming" | "error";
+interface SagePaymentInstructions {
+    /** Short copy displayed above the Note box input. */
+    helperText?: string;
+    /** Optional link to host payment/wallet instructions. */
+    walletUrl?: string;
+    /** Optional custom label for the Note box input. */
+    noteBoxLabel?: string;
+}
+interface SagePaymentWidgetStatus {
+    phase: SagePaymentPhase;
+    tier: SageChatTier | null;
+    quote: SageQuoteResponse["quote"] | null;
+    receipt: SageVerifyPaymentResponse | null;
+    receiptBundle: SageReceiptBundle | null;
+    error: string | null;
+    /** Latest chat transcript known to the widget. */
+    messages: SageChatMessage[];
+    /** Question currently tied to the active quote/payment cycle. */
+    activeQuestion: string | null;
+}
+declare const DEFAULT_API_BASE = "https://www.ergoblockchain.org";
+declare const DEFAULT_LIMIT = 5;
+declare const DEFAULT_REFRESH_MS = 60000;
+
+export { DEFAULT_API_BASE as D, type SageActivityEvent as S, DEFAULT_LIMIT as a, DEFAULT_REFRESH_MS as b, type SageActivityResponse as c, type SageActivityType as d, type SageChatMessage as e, type SageChatRole as f, type SageChatStreamEvent as g, type SageChatStreamResult as h, type SageChatTier as i, type SagePaymentInstructions as j, type SagePaymentPhase as k, type SagePaymentWidgetOptions as l, type SagePaymentWidgetStatus as m, type SagePremiumPaymentRequired as n, type SagePremiumReason as o, type SageQuote as p, type SageQuoteResponse as q, type SageReceiptBundle as r, type SageTenantConfig as s, type SageVerifyPaymentResponse as t, type SageWidgetOptions as u };