agentex-creator-sdk 1.0.0

package/dist/packages/sdk/src/buyer.d.ts

@@ -0,0 +1,534 @@
+import { z } from 'zod';
+import { type BuyerProfile, type PaymentAsset } from './rails.js';
+import { type ResearchReport } from './report.js';
+export { AgentexApiError, isAgentexApiError, type BuyerErrorKind } from './errors.js';
+export * from './rails.js';
+export * from './report.js';
+/**
+ * Typed buyer SDK for the AGENTEX buyer API (https://agentex.sh). It sends only `Authorization: Bearer <key>`, never cookies, never follows
+ * redirects and never includes the API key in an error. Plain HTTP is allowed only to loopback origins. Payment rails are chosen by asset id
+ * (SOL first; USDC on Solana; ETH on Robinhood Chain), and an API key is bound to one of them.
+ */
+export declare const BUYER_SDK_VERSION = "1.0.0";
+/** The production API origin. The buyer API is served from the site's own origin. */
+export declare const DEFAULT_API_ORIGIN = "https://agentex.sh";
+export declare const API_KEY_PATTERN: RegExp;
+export declare const IdempotencyKeySchema: z.ZodString;
+/** The public catalog's offer filter: SOL or USDC on the Solana rail, ETH custody, or SIM on local rehearsal servers. */
+export type CatalogProfile = BuyerProfile;
+/** Chains an agent can analyse. The payment rail is independent of the analysed chain. */
+export type ChainKey = 'ethereum' | 'base' | 'robinhood' | 'solana';
+/** Marketplace topics (the catalog's controlled vocabulary; `topic` filter). */
+export declare const CATALOG_TOPICS: readonly ["token-intelligence", "contract-forensics", "wallet-intelligence", "transaction-safety", "monitoring", "defi", "liquidity", "lending-yield", "staking", "stablecoins", "governance", "treasuries", "rwa", "bridges", "chain-activity", "launches", "nfts", "security"];
+export type CatalogTopic = typeof CATALOG_TOPICS[number];
+export type AgentCategory = 'token_research' | 'transaction_inspection' | 'monitoring' | 'custom_workflow' | 'deployer_investigation' | 'wallet_analysis';
+/** Research workflows (most catalog agents) take named values. Read `getAgent(id).inputFields` for the names, types and options. */
+export interface WorkflowQuoteInput {
+    workflow: 'agentex.workflow.v1';
+    chain: ChainKey;
+    values: Record<string, string | number | boolean>;
+}
+/**
+ * Run input. Research workflows: `workflowInput(chain, values)`. Token Researcher and the other EVM kinds: `{ chain, address }` (or their named
+ * fields such as `contract` or `wallet`). The Solana Transaction Inspector: `{ analysisChain: 'solana', ... }`.
+ */
+export type QuoteInput = WorkflowQuoteInput | {
+    chain: string;
+    [field: string]: unknown;
+} | {
+    analysisChain: 'solana';
+    [field: string]: unknown;
+};
+/** Builds a research-workflow input: `workflowInput('solana', { mint })`. */
+export declare function workflowInput(chain: ChainKey, values: Record<string, string | number | boolean>): WorkflowQuoteInput;
+export type BuyerScope = 'catalog:read' | 'quotes:write' | 'runs:read' | 'runs:cancel' | 'billing:read' | 'monitors:read' | 'monitors:write';
+export interface BuyerKey {
+    id: string;
+    name: string;
+    prefix: string;
+    last4: string;
+    scopes: BuyerScope[];
+    profile: BuyerProfile;
+    assetId: string;
+    listingIds: string[] | null;
+    spendLimitAtomic: string;
+    spendUsedAtomic: string;
+    remainingSpendAtomic: string;
+    rateLimitPerMinute: number;
+    requestsLast24h: number;
+    createdAt: string;
+    expiresAt: string;
+    lastUsedAt: string | null;
+    revokedAt: string | null;
+    status: 'active' | 'expired' | 'revoked';
+}
+export interface OfferPricing {
+    /** The per-run price cap: the most one run can reserve, in the offer's asset. */
+    maximumBuyerDebitAtomic: string;
+    grossCreatorFeeAtomic: string;
+    maxExecutionChargeAtomic: string;
+    platformFeeAtomic: string;
+    creatorCreditAtomic: string;
+    assetId: string;
+    currencyLabel?: string;
+    revision?: number;
+    [key: string]: unknown;
+}
+/** One payment rail a listing accepts. A listing can accept SOL, USDC and ETH at once. */
+export interface AgentOffer {
+    profile: BuyerProfile;
+    label: string;
+    currencyLabel: string;
+    enabled: boolean;
+    purchasePath: string;
+    pricing: OfferPricing;
+}
+export interface AgentSummary {
+    listingId: string;
+    name: string;
+    description: string;
+    /** Chains this server covers for the agent (declared chains it cannot run are in `availability.unavailableChains`). */
+    chains: string[];
+    ownership: 'first-party' | 'independent';
+    creatorLabel: string;
+    creator?: {
+        profileId: string;
+        displayName: string;
+        [key: string]: unknown;
+    };
+    category?: {
+        id: AgentCategory;
+        label: string;
+    };
+    priceStructure?: {
+        id: 'per_run' | 'per_monitoring_window';
+        label: string;
+    };
+    permissionLevel?: {
+        id: 'read_only' | 'proposes_transactions' | 'sends_notifications';
+        label: string;
+    };
+    topics?: {
+        id: string;
+        label: string;
+    }[];
+    topicsDeclared?: boolean;
+    /** Set for listings bought as something other than a run (a Watchtower monitor, created on the website). */
+    action?: {
+        kind: 'monitor';
+        label: string;
+        href: string;
+    };
+    review: {
+        status: string;
+        label: string;
+        scope: string;
+        [key: string]: unknown;
+    };
+    offers: AgentOffer[];
+    availability: {
+        available: boolean;
+        reasons: string[];
+        unavailableChains?: {
+            chain: string;
+            label: string;
+            reason: string;
+        }[];
+    };
+    versionNumber: number;
+    createdAt: string;
+    ratings?: Record<string, unknown>;
+}
+export interface AgentInputField {
+    name: string;
+    type: string;
+    description: string;
+    required: boolean;
+    options: (string | number | boolean)[] | null;
+}
+export interface AgentDetail extends AgentSummary {
+    task: {
+        description: string;
+        scope: string;
+        output: string;
+    };
+    permissions: {
+        id: string;
+        label: string;
+        detail: string;
+    }[];
+    limits: {
+        maximumRpcCalls: number;
+        maximumDurationMs: number;
+        maximumOutputBytes: number;
+    };
+    inputFields: AgentInputField[];
+    resultPolicies: {
+        policy: string;
+        id: string;
+        description: string;
+        default: boolean;
+    }[];
+    refundPolicy: string[];
+    limitations: string[];
+    [key: string]: unknown;
+}
+export interface AgentPage {
+    agents: AgentSummary[];
+    nextCursor: string | null;
+    /** Listings matching the query across every page. */ total?: number;
+    /** True when the query reached the server's scan bound (newest 1,000 public listings). */ truncated?: boolean;
+    sort?: 'newest' | 'name' | 'price';
+    environment?: {
+        kind: string;
+        notice: string;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+export interface AgentQuery {
+    /** Searches names and descriptions; a topic name also matches by topic. */ q?: string;
+    chain?: ChainKey | (string & {});
+    ownership?: 'first-party' | 'independent';
+    review?: 'reviewed' | 'any';
+    /** Only listings that offer this payment profile. */ profile?: CatalogProfile;
+    /** Only listings that accept this asset (sets `profile`). */ assetId?: string;
+    available?: 'true' | 'false' | boolean;
+    category?: AgentCategory | (string & {});
+    priceStructure?: 'per_run' | 'per_monitoring_window';
+    permission?: 'read_only' | 'proposes_transactions' | 'sends_notifications';
+    topic?: CatalogTopic | (string & {});
+    /** Server-side order over every matching listing. */ sort?: 'newest' | 'name' | 'price';
+    /** 1 to 50 (default 20). */ limit?: number;
+    cursor?: string;
+}
+export interface Quote {
+    id: string;
+    contractHash: string;
+    /** The most this run can reserve, in atomic units of `asset`. */ maximumBuyerDebitAtomic: string;
+    expiresAt: string;
+    /** The ledger asset the quote is priced in; `assetIdOf(quote.asset)` gives its asset id. */ asset?: Record<string, unknown>;
+    currencyLabel?: string;
+    grossCreatorFeeAtomic?: string;
+    platformFeeAtomic?: string;
+    creatorCreditAtomic?: string;
+    maxExecutionChargeAtomic?: string;
+    feeBps?: number;
+    resultPolicy?: string;
+    resultContract?: {
+        id: string;
+        description: string;
+        [key: string]: unknown;
+    };
+    input?: unknown;
+    notice?: string;
+    agentKind?: string;
+    [key: string]: unknown;
+}
+export type RunStatus = 'queued' | 'running' | 'succeeded' | 'partial' | 'failed' | 'cancelled';
+export interface Run {
+    id: string;
+    versionId: string;
+    status: RunStatus;
+    input: unknown;
+    output: Record<string, unknown> | null;
+    error: unknown;
+    mode: string;
+    rpcUsed: number;
+    createdAt: string;
+    updatedAt: string;
+    [key: string]: unknown;
+}
+export interface RunEvent {
+    id: string;
+    step: string;
+    message: string;
+    createdAt: string;
+}
+export interface RunState {
+    run: Run;
+    events: RunEvent[];
+}
+export interface Acceptance {
+    run: Run;
+    reservation: {
+        id: string;
+        maximumAtomic: string;
+        [key: string]: unknown;
+    };
+    notice: string;
+    idempotencyKey: string;
+}
+export interface Settlement {
+    reservationId: string;
+    outcome: 'succeeded' | 'partial' | 'failed' | 'cancelled' | 'expired';
+    chargedAtomic: string;
+    creatorFeeAtomic: string;
+    platformFeeAtomic: string;
+    executionChargeAtomic: string;
+    [key: string]: unknown;
+}
+export interface Billing {
+    runId: string;
+    reservationId: string;
+    quoteId: string;
+    status: 'reserved' | 'pending' | 'settled';
+    settlement: Settlement | null;
+    pendingReason: string | null;
+    modelCost?: Record<string, unknown> | null;
+    authorizedRpcCalls?: number;
+    reconciledRpcCalls?: number;
+    unresolvedRpcCalls?: number;
+    notice?: string;
+    [key: string]: unknown;
+}
+export interface RunResult {
+    artifactId: string | null;
+    run: Run;
+    version: Record<string, unknown>;
+    events: RunEvent[];
+}
+/** A buyer-side receipt: the run's billing with its payment asset. Amounts are exact atomic strings plus a formatted `charged`. */
+export interface BuyerReceipt {
+    runId: string;
+    quoteId: string;
+    reservationId: string;
+    status: Billing['status'];
+    outcome: Settlement['outcome'] | null;
+    payment: PaymentAsset;
+    /** The quote's maximum, when the quote was passed in. */ maximumDebitAtomic: string | null;
+    chargedAtomic: string | null; /** For example "0.0022 SOL", once settled. */
+    charged: string | null;
+    fees: {
+        creatorFeeAtomic: string;
+        platformFeeAtomic: string;
+        executionChargeAtomic: string;
+    } | null;
+    pendingReason: string | null;
+    billing: Billing;
+}
+export interface Monitor {
+    id: string;
+    name: string;
+    versionId: string;
+    chain: string;
+    status: 'active' | 'paused' | 'stopped' | 'expired' | 'exhausted';
+    statusReason: string | null;
+    webhook: {
+        url: string;
+        signature: string;
+    } | null;
+    [key: string]: unknown;
+}
+export interface MonitorDetail {
+    monitor: Monitor;
+    windows: Record<string, unknown>[];
+    missedWindows: Record<string, unknown>[];
+    events: Record<string, unknown>[];
+    retractedEvents: Record<string, unknown>[];
+    deliveries: Record<string, unknown>[];
+}
+export interface Notification {
+    id: string;
+    monitorId: string;
+    kind: string;
+    title: string;
+    body: string;
+    event: Record<string, unknown>;
+    createdAt: string;
+    acknowledgedAt: string | null;
+}
+export interface MonitorRequest {
+    versionId: string;
+    name: string;
+    chain: string;
+    rules: Record<string, unknown>[];
+    windowBlocks?: number;
+    maximumLogs?: number;
+    durationSeconds: number;
+    tickBudget: number;
+    rpcBudget: number;
+    startBlock?: string;
+    webhookUrl?: string;
+    idempotencyKey?: string;
+}
+/** Polling for `waitForRun` and settled receipts: exponential backoff from `intervalMs` to `maxIntervalMs`, bounded by `timeoutMs`. */
+export interface WaitOptions {
+    /** First poll interval (default 1,000 ms). */ intervalMs?: number;
+    /** Longest poll interval (default 10,000 ms). */ maxIntervalMs?: number;
+    /** Interval multiplier per poll (default 1.5; 1 polls at a fixed interval). */ backoff?: number;
+    /** Give up after this long (default 300,000 ms) with a retryable `timeout` error. */ timeoutMs?: number;
+    signal?: AbortSignal;
+    /** Called with every run state read while waiting. */ onStatus?: (state: RunState) => void;
+}
+export interface CallOptions {
+    signal?: AbortSignal;
+}
+export interface ResearchRequest {
+    listingId: string;
+    input: QuoteInput;
+    /** Payment asset (an asset id or `sol`, `usdc`, `eth`). Defaults to the client's `assetId`, else the API key's own asset. */ assetId?: string;
+    resultPolicy?: 'complete_only' | 'canonical_metadata';
+    /** Consent bound: refuse (without accepting) a quote that could reserve more than this, in the asset's atomic units. */ maxDebitAtomic?: string;
+    /** Consent callback: return true to accept this exact quote. Runs after the `maxDebitAtomic` check. */ approve?: (quote: Quote) => boolean | Promise<boolean>;
+    /** Reuse the same key to retry an uncertain acceptance without reserving twice. Generated when omitted. */ idempotencyKey?: string;
+    wait?: WaitOptions;
+    signal?: AbortSignal;
+}
+export interface ResearchOutcome {
+    quote: Quote;
+    acceptance: Acceptance;
+    idempotencyKey: string;
+    run: Run;
+    events: RunEvent[];
+    /** Typed findings, evidence and sources of the finished run (empty when the run produced no report). */ report: ResearchReport;
+    /** The asset the run was paid in, when known. */ payment: PaymentAsset | null;
+}
+/** An exact origin. HTTPS anywhere; plain HTTP only on loopback, so a bearer key never crosses a network in clear text. */
+export declare function buyerApiOrigin(raw: string): string;
+/** The offer a listing makes in one asset (an asset id or `sol`, `usdc`, `eth`), or undefined when it does not accept that asset. */
+export declare function offerFor(agent: Pick<AgentSummary, 'offers'>, assetId: string): AgentOffer | undefined;
+export interface BuyerClientOptions {
+    /** A buyer API key from https://agentex.sh/developers (`agx_live_...`). It is sent only as a bearer header and never printed. */
+    apiKey: string;
+    /** API origin. Default `https://agentex.sh`. HTTPS, or HTTP on loopback only. */
+    origin?: string;
+    /** Payment profile. Omit it (recommended) to use the key's own profile, read once from `GET /v1/buyer/key`. */
+    profile?: BuyerProfile;
+    /** Default payment asset for quotes and billing (an asset id or `sol`, `usdc`, `eth`). It implies the profile. */
+    assetId?: string;
+    /** A fetch implementation (default: the global fetch). */
+    fetch?: typeof fetch;
+    /** Per-request timeout (default 15,000 ms). */ timeoutMs?: number;
+    /** Retries for idempotent calls (default 2, at most 5). Quote creation is never retried. */ maxRetries?: number;
+    /** First retry delay (default 250 ms), doubling per attempt up to 8 s; a server `Retry-After` up to 30 s is honoured. */ retryDelayMs?: number;
+}
+export declare function createBuyerClient(options: BuyerClientOptions): {
+    origin: string;
+    /** The explicit or derived payment profile; undefined until the key's own profile has been read. */
+    readonly profile: BuyerProfile | undefined;
+    /** The profile this client quotes and pays with: the explicit one, the asset's, or the key's own (one `GET /v1/buyer/key`). */
+    resolveProfile: () => Promise<BuyerProfile>;
+    /** The asset this client pays in: the client's `assetId`, else the key's own asset. */
+    paymentAsset(): Promise<PaymentAsset>;
+    /** The key's own scopes, asset, expiry and `remainingSpendAtomic`. Any valid key may read it. */
+    key(call?: CallOptions): Promise<BuyerKey>;
+    /** One page of public agents. Pass `nextCursor` back as `cursor`; `null` means the last page. Needs `catalog:read`. */
+    listAgents(input?: AgentQuery, call?: CallOptions): Promise<AgentPage>;
+    /** Iterates pages until `nextCursor` is null, bounded by `maxPages` (default 20). */
+    agents(input?: Omit<AgentQuery, "cursor">, maxPages?: number): AsyncGenerator<AgentSummary>;
+    /** Permissions, limits, input fields, offers (one per payment rail) and limitations of one listing. */
+    getAgent(listingId: string, call?: CallOptions): Promise<AgentDetail>;
+    /** The listings this key can buy with its rail (full manifests and tariffs), with the rail's pricing policy. */
+    listings(input?: {
+        assetId?: string;
+    } & CallOptions): Promise<{
+        listings: Record<string, unknown>[];
+        pricingPolicy: unknown;
+    }>;
+    /**
+     * Creates a server-priced quote on the rail of `assetId` (or the client's default, or the key's own asset). It reserves nothing and expires
+     * after 240 seconds. Never retried. When an asset was named, a quote priced in any other asset is refused with `asset_mismatch`.
+     */
+    createQuote(input: {
+        listingId: string;
+        input: QuoteInput;
+        resultPolicy?: "complete_only" | "canonical_metadata";
+        assetId?: string;
+    } & CallOptions): Promise<Quote>;
+    /**
+     * Consents to one exact quote. The contract hash must be the one returned by createQuote. One idempotency key is used for all retries
+     * of this call (generated if omitted and returned), so a lost response never reserves twice. Pass the quote's `assetId` when the client
+     * has no default asset and the key's rail is not the quote's.
+     */
+    acceptQuote(input: {
+        quoteId: string;
+        contractHash: string;
+        idempotencyKey?: string;
+        assetId?: string;
+    } & CallOptions): Promise<Acceptance>;
+    /** Run status and its latest events (at most 250). */
+    getRun(runId: string, call?: CallOptions): Promise<RunState>;
+    /**
+     * Polls until the run leaves queued/running, with backoff (1 s growing to 10 s by default). Transient failures keep polling; a timeout
+     * throws a retryable `timeout` error (`wait_timeout`) and an aborted signal throws `aborted`. The run itself is never affected.
+     */
+    waitForRun(runId: string, wait?: WaitOptions): Promise<RunState>;
+    /** Typed findings, evidence and sources of a finished run. A run without a report yet is a `conflict` (`report_unavailable`). */
+    getReport(runId: string, call?: CallOptions): Promise<ResearchReport>;
+    /** The canonical stored export (run, immutable version, events). A run without a report yet is a 409 `conflict`. */
+    getResult(runId: string, call?: CallOptions): Promise<RunResult>;
+    /** Cancels a run; repeating it returns the current state. Cancellation charges only execution already incurred. */
+    cancelRun(runId: string, call?: CallOptions): Promise<Run>;
+    /** Reservation and settlement of a run on its rail (the client's default asset or the key's own). */
+    getBilling(runId: string, input?: {
+        assetId?: string;
+    } & CallOptions): Promise<Billing>;
+    /**
+     * The run's billing with its payment asset and a formatted charge. The asset comes from `quote` when given, else `assetId`, else the key's
+     * own asset (a key only sees runs paid in its asset). `waitForSettlement` polls until the reservation settles.
+     */
+    getReceipt(runId: string, input?: {
+        quote?: Pick<Quote, "asset" | "maximumBuyerDebitAtomic">;
+        assetId?: string;
+        waitForSettlement?: boolean | Omit<WaitOptions, "onStatus">;
+    } & CallOptions): Promise<BuyerReceipt>;
+    /**
+     * Quote, consent check, accept and wait in one call. It needs a consent bound (`maxDebitAtomic`, `approve`, or both) and refuses, without
+     * accepting, a quote above it. A wait failure after acceptance carries `runId` so you can resume with `waitForRun`.
+     */
+    research(input: ResearchRequest): Promise<ResearchOutcome>;
+    /** Creates a monitor on your own Watchtower version. The webhook secret is returned only on first creation (null on replay). */
+    createMonitor(input: MonitorRequest, call?: CallOptions): Promise<{
+        idempotencyKey: string;
+        monitor: Monitor;
+        webhookSecret: string | null;
+        replayed: boolean;
+    }>;
+    listMonitors(call?: CallOptions): Promise<Monitor[]>;
+    getMonitor(monitorId: string, call?: CallOptions): Promise<MonitorDetail>;
+    stopMonitor(monitorId: string, call?: CallOptions): Promise<Monitor>;
+    listNotifications(call?: CallOptions): Promise<Notification[]>;
+    acknowledgeNotification(notificationId: string, call?: CallOptions): Promise<Notification>;
+};
+export type BuyerClient = ReturnType<typeof createBuyerClient>;
+/** Records delivery IDs already processed. `claim` must be atomic: true only for the first caller of an ID. */
+export interface WebhookReplayStore {
+    claim(deliveryId: string, expiresAt: Date): boolean | Promise<boolean>;
+}
+export declare function createMemoryReplayStore(maximumEntries?: number): WebhookReplayStore;
+export declare const WebhookPayloadSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        "monitor.event": "monitor.event";
+        "monitor.event.retracted": "monitor.event.retracted";
+    }>;
+    eventId: z.ZodUUID;
+    monitorId: z.ZodUUID;
+    chain: z.ZodString;
+    status: z.ZodEnum<{
+        active: "active";
+        retracted: "retracted";
+    }>;
+}, z.core.$loose>;
+export type WebhookPayload = z.infer<typeof WebhookPayloadSchema>;
+export type WebhookVerification = {
+    ok: true;
+    deliveryId: string;
+    payload: WebhookPayload;
+} | {
+    ok: false;
+    reason: 'invalid_signature' | 'duplicate' | 'invalid_payload';
+};
+/**
+ * Verifies a monitor webhook with the monitoring package's HMAC check (signature, event ID and a 5-minute timestamp window), then
+ * claims the delivery ID in `replay` so a duplicate callback is rejected. Pass the raw request body exactly as received.
+ * Signature failure is checked first, so a forged request can never consume a genuine delivery ID.
+ */
+export declare function verifyWebhook(input: {
+    secret: string;
+    headers: Record<string, string | string[] | undefined>;
+    body: string;
+    replay: WebhookReplayStore;
+    now?: Date;
+    toleranceSeconds?: number;
+}): Promise<WebhookVerification>;