@cesto/sdk 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,573 @@
+/**
+ * Error hierarchy thrown by the SDK.
+ *
+ * Everything extends {@link CestoError}. Server (non-2xx) responses become an
+ * {@link APIError} subclass built from the API's `{ code, message, details,
+ * requestId }` envelope; transport problems become {@link APIConnectionError}
+ * (or its timeout subclass); caller cancellation becomes {@link APIUserAbortError}.
+ */
+/** Base class for every error the SDK throws. */
+declare class CestoError extends Error {
+    constructor(message: string);
+}
+/** Parsed `{ code, message, details, requestId }` envelope from the API. */
+interface APIErrorEnvelope {
+    code?: string;
+    message?: string;
+    details?: unknown;
+    requestId?: string;
+}
+/** A non-2xx HTTP response. */
+declare class APIError extends CestoError {
+    /** HTTP status code. */
+    readonly status: number;
+    /** Machine-readable error code from the API envelope (e.g. `RESOURCE_NOT_FOUND`). */
+    readonly code?: string;
+    /** Correlation id from the API envelope, useful when reporting issues. */
+    readonly requestId?: string;
+    /** Structured error details from the API envelope. */
+    readonly details?: unknown;
+    /** Response headers. */
+    readonly headers?: Headers;
+    constructor(status: number, message: string, opts?: {
+        code?: string;
+        requestId?: string;
+        details?: unknown;
+        headers?: Headers;
+    });
+}
+declare class BadRequestError extends APIError {
+}
+declare class AuthenticationError extends APIError {
+}
+declare class PermissionDeniedError extends APIError {
+}
+declare class NotFoundError extends APIError {
+}
+declare class ConflictError extends APIError {
+}
+declare class UnprocessableEntityError extends APIError {
+}
+/** HTTP 429. Carries `retryAfter` (ms) when the server sent a `Retry-After` header. */
+declare class RateLimitError extends APIError {
+    /** Milliseconds to wait before retrying, derived from `Retry-After`. */
+    readonly retryAfter?: number;
+    constructor(status: number, message: string, opts?: {
+        code?: string;
+        requestId?: string;
+        details?: unknown;
+        headers?: Headers;
+        retryAfter?: number;
+    });
+}
+declare class InternalServerError extends APIError {
+}
+/** A network-level failure (DNS, connection reset, fetch threw). */
+declare class APIConnectionError extends CestoError {
+    readonly cause?: unknown;
+    constructor(message?: string, opts?: {
+        cause?: unknown;
+    });
+}
+/** The request exceeded the configured timeout. */
+declare class APIConnectionTimeoutError extends APIConnectionError {
+    constructor(message?: string);
+}
+/** The caller's `AbortSignal` fired. */
+declare class APIUserAbortError extends CestoError {
+    constructor(message?: string);
+}
+
+/** Which deployed Cesto backend to target. */
+type CestoEnvironment = 'PRODUCTION' | 'BETA';
+/** Options for constructing a {@link Cesto} client. */
+interface ClientOptions {
+    /**
+     * Secret API key (`cesto_sk_…`). Required — the constructor throws if omitted.
+     * Read it from your environment yourself, e.g. `apiKey: process.env.CESTO_API_KEY`.
+     */
+    apiKey?: string;
+    /**
+     * Which backend to target in a deployed build (`NODE_ENV=production`):
+     * `PRODUCTION` → backend.cesto.co, `BETA` → dev.backend.cesto.co. Default `PRODUCTION`.
+     */
+    environment?: CestoEnvironment;
+    /** Per-request timeout in milliseconds. Default `60000`. */
+    timeout?: number;
+    /** Max automatic retries on transient failures. Default `2`. */
+    maxRetries?: number;
+    /** Custom fetch implementation (e.g. undici, a test mock). Default `globalThis.fetch`. */
+    fetch?: typeof fetch;
+}
+/** Per-request overrides accepted by every resource method. */
+interface RequestOptions {
+    /** Override the client timeout (ms) for this request. */
+    timeout?: number;
+    /** Override the client retry count for this request (e.g. `0` to disable). */
+    maxRetries?: number;
+    /** Caller cancellation; composed with the internal timeout signal. */
+    signal?: AbortSignal;
+}
+/** Fully-resolved, validated client configuration. */
+interface ResolvedOptions {
+    apiKey: string;
+    /** Normalized base URL, no trailing slash. */
+    baseURL: string;
+    timeout: number;
+    maxRetries: number;
+    fetch: typeof fetch;
+}
+
+/** Backtest chart window. Only `1y` carries full portfolio metrics. */
+type ChartTimeRange = '7d' | '1m' | '3m' | '6m' | '1y' | 'all';
+type PredictionProtocol = 'kalshi' | 'polymarket';
+type PredictionSide = 'YES' | 'NO';
+type MarketStatus = 'initialized' | 'active' | 'inactive' | 'closed' | 'determined' | 'finalized';
+/** Whether the requester's region may view / invest in a product. */
+interface GeoStatus {
+    canView: boolean;
+    canInvest: boolean;
+}
+/** One incentive campaign overlaid on a product. */
+interface IncentiveOverlayCampaign {
+    campaignId: string;
+    slug: string;
+    partnerName: string;
+    rewardTokenSymbol: string;
+    rewardTokenMint: string;
+    /** Campaign APY in percent, or null when TVL is 0 / not yet computed. */
+    apy: number | null;
+    /** ISO timestamp. */
+    endsAt: string;
+    tvlUsd: string;
+    pointsMultiplier: string | null;
+}
+/** Prediction-market performance (present only for prediction-market products). */
+interface PredictionPerformance {
+    roi: number;
+    impliedProbability: number;
+    daysToExpiration: number;
+    /** ISO timestamp. */
+    expirationDate: string;
+}
+/** Backtested token/basket performance over a window. */
+interface TokenPerformance {
+    avgPercentChange?: number;
+    daysAvailable?: number;
+    startDate?: string;
+    endDate?: string;
+    annualizedReturn?: number;
+    return?: number;
+    netPnL?: number | null;
+    pricePnL?: number | null;
+    netAPY?: number | null;
+    priceAPY?: number | null;
+    yieldBreakdown?: {
+        pricePnL: number;
+        yieldPnL: number;
+        netPnL: number;
+        priceAPY: number;
+        netAPY: number;
+        annualizedReturn: number;
+    } | null;
+    predictionPerformance?: PredictionPerformance | null;
+    /** Incentive overlay (added per window when campaigns apply). */
+    incentiveAPY?: number;
+    totalAPY?: number;
+}
+/** Live state of a prediction market attached to a product. */
+interface PredictionMarketState {
+    marketTicker: string;
+    protocol: PredictionProtocol;
+    side: PredictionSide;
+    title?: string;
+    /** Unix seconds. */
+    closeTime: number;
+    status: MarketStatus;
+    result?: 'yes' | 'no';
+}
+
+/** Product summary attached to a position. */
+interface PositionProduct {
+    id: string;
+    name: string;
+    slug: string;
+    category: string | null;
+    logoUrl: string | null;
+    isActive: boolean;
+}
+/** The product version a position currently tracks. */
+interface PositionVersion {
+    id: string;
+    version: number;
+    isDeprecated: boolean;
+}
+/** One underlying investment row within a position (transparency view). */
+interface PositionInvestment {
+    id: string;
+    /** Invested amount in token base units. */
+    totalInvested: string;
+    totalInvestedUsd: string;
+    tokenMint: string;
+    tokenDecimals: number;
+    /** ISO timestamp. */
+    openedAt: string;
+    closedAt: string | null;
+    closedReason: string | null;
+    creationType: string | null;
+    executionStatus: string | null;
+    /** UI-facing status, e.g. `Active`, `Closing`, `Scheduled`. */
+    displayStatus: string;
+    partialReason: string | null;
+    openingExecutionId: string | null;
+    scheduledToOpenAt: string | null;
+    closingExecutionId: string | null;
+    closeExecutionStatus: string | null;
+    scheduledToCloseAt: string | null;
+}
+/**
+ * Aggregated valuation for a position (live + partial buckets).
+ *
+ * The bucket internals mirror the API's portfolio aggregation and are treated as
+ * loosely-typed until the `/v1` route formalizes them; `totalCurrentValueUsd` is
+ * the field most consumers read.
+ */
+interface PositionValuation {
+    live?: Record<string, unknown>;
+    partial?: Record<string, unknown>;
+    calculatedAt?: string;
+}
+/** A live position — one entry per (user, product). */
+interface Position {
+    productId: string;
+    product: PositionProduct;
+    currentVersion: PositionVersion | null;
+    aggregatedData: PositionValuation | null;
+    investments: PositionInvestment[];
+    incentives: {
+        campaigns: IncentiveOverlayCampaign[];
+    };
+    cacheMetadata: {
+        calculatedAt: string;
+        expiresAt: string;
+    } | null;
+}
+/** Result of `positions.list({ wallet })`. */
+interface PositionsResult {
+    positions: Position[];
+    pendingClosePositions: Position[];
+}
+
+/** Query parameters; `undefined`/`null` values are skipped. */
+type QueryParams = Record<string, string | number | boolean | undefined | null>;
+interface GetOptions extends RequestOptions {
+    query?: QueryParams;
+}
+/** Internal transport: builds requests, applies auth, retries, and parses JSON. */
+declare class APIClientCore {
+    private readonly opts;
+    constructor(opts: ResolvedOptions);
+    get<T>(path: string, options?: GetOptions): Promise<T>;
+    private request;
+    private buildURL;
+}
+
+/** Base class for resource groups; holds a reference to the transport. */
+declare abstract class APIResource {
+    protected readonly client: APIClientCore;
+    constructor(client: APIClientCore);
+}
+
+interface PositionsListParams {
+    /** External Solana wallet address (Phantom/Solflare). Required. */
+    wallet: string;
+}
+declare class Positions extends APIResource {
+    /**
+     * List a user's open/closing positions, resolved from their external Solana
+     * wallet. A wallet with no Cesto account returns an empty result (not an error).
+     */
+    list(params: PositionsListParams, options?: RequestOptions): Promise<PositionsResult>;
+}
+
+/** An item in `products.list()` — `GET /products`. */
+interface ProductListItem {
+    id: string;
+    slug: string;
+    name: string;
+    description: string | null;
+    logoUrl: string | null;
+    category: string | null;
+    tags: string[];
+    isActive: boolean;
+    isPublished: boolean;
+    pointMultiplier: number;
+    metadata: Record<string, unknown> | null;
+    geoStatus: GeoStatus;
+    /** Active incentive campaigns; `[]` when none. */
+    incentives: IncentiveOverlayCampaign[];
+}
+/** Backtested performance for a product — `GET /products/analytics` (per product). */
+interface ProductBacktest {
+    protocolsInvolved: string[];
+    tokensInvolved: string[];
+    tokenPerformance: TokenPerformance | null;
+    tokenPerformance7d: TokenPerformance | null;
+    tokenPerformance30d: TokenPerformance | null;
+    priceChange24h: number | null;
+    tokenPriceChanges: Record<string, {
+        priceChange24h: number | null;
+        priceChange24hPercent: number | null;
+    }>;
+}
+/** `products.list({ includeBacktest: true })` — list item with backtest merged in. */
+type ProductWithBacktest = ProductListItem & {
+    backtest: ProductBacktest | null;
+};
+interface ProductCreator {
+    id: string;
+    username: string | null;
+    email: string | null;
+    solanaWalletAddress: string | null;
+    embeddedWalletAddress: string | null;
+}
+interface OndoTradingStatus {
+    allTradable: boolean;
+    currentSession: string;
+    hasOndoTokens: boolean;
+    tokens: unknown[];
+    untradableTokens: unknown[];
+    nextFullyTradableAt: string | null;
+    nextFullyTradableSession: string | null;
+}
+/** Full product detail — `GET /products/:slug`. */
+interface ProductVersionResponse {
+    id: string;
+    versionId: string;
+    version: number;
+    changelog: string | null;
+    minimumInvestment: string;
+    inputTokenMint: string;
+    inputTokenDecimals: number;
+    about: string | null;
+    riskNotes: string | null;
+    resources: string | null;
+    name: string;
+    slug: string;
+    description: string | null;
+    logoUrl: string | null;
+    category: string | null;
+    tags: string[];
+    isActive: boolean;
+    isPublished: boolean;
+    metadata: Record<string, unknown> | null;
+    pointMultiplier: number;
+    createdBy: string;
+    creator: ProductCreator | null;
+    tokensInvolved: string[];
+    protocolsInvolved: string[];
+    tokenPerformance: TokenPerformance | null;
+    tokenPerformance7d: TokenPerformance | null;
+    tokenPerformance30d: TokenPerformance | null;
+    predictionMarkets?: PredictionMarketState[];
+    canInvest: boolean;
+    /** Raw workflow definition. */
+    definition: unknown;
+    geoStatus: GeoStatus;
+    ondoTradingStatus: OndoTradingStatus;
+    incentives?: IncentiveOverlayCampaign[];
+}
+interface BacktestChartTimeSeriesPoint {
+    timestamp: string;
+    portfolioValue: number;
+    sp500Value?: number;
+    mag7Value?: number;
+    btcValue?: number;
+    solValue?: number;
+    usdcValue?: number;
+    isLiquidated?: boolean;
+    liquidationThreshold?: number;
+}
+interface BacktestChartMetrics {
+    totalReturn: number;
+    cagr: number;
+    volatility: number;
+    maxDrawdown: number;
+    sharpe: number;
+}
+interface PredictionMarketEvent {
+    ticker: string;
+    marketTicker: string;
+    seriesTicker: string;
+    title: string;
+    closeTime: number;
+    currentProbability?: number;
+    currentPrice: number;
+    daysToClose: number;
+    timeSeries: Array<{
+        market_ticker: string;
+        event_ticker: string;
+        raw_numerical_forecast: number;
+        numerical_forecast: number;
+        formatted_forecast: string;
+        end_period_ts: number;
+        period_interval: number;
+    }>;
+}
+/** Token-portfolio backtest chart — `GET /products/:id/graph` (non-prediction). */
+interface BacktestChart {
+    workflowId: string;
+    name: string;
+    timeRange?: ChartTimeRange;
+    timeSeries: BacktestChartTimeSeriesPoint[];
+    /** Computed only when `timeRange === '1y'`; null otherwise. */
+    metrics: BacktestChartMetrics | null;
+    assetPerformance: Array<{
+        token: string;
+        mint: string;
+        returnPct: number;
+    }>;
+    contributions: Array<{
+        token: string;
+        mint: string;
+        contribution: number;
+    }>;
+    assetSparklines: Array<{
+        token: string;
+        mint: string;
+        points: Array<{
+            timestamp: string;
+            value: number;
+            price: number;
+        }>;
+    }>;
+    checkpoints?: Array<{
+        timestamp: string;
+        version: number;
+        fromVersion: number | null;
+        changelog: string | null;
+        added: Array<{
+            token: string;
+            mint: string;
+            allocation: number;
+        }>;
+        removed: Array<{
+            token: string;
+            mint: string;
+            allocation: number;
+        }>;
+        reweighted: Array<{
+            token: string;
+            mint: string;
+            fromPct: number;
+            toPct: number;
+        }>;
+    }>;
+    liquidationInfo?: {
+        hasLiquidations: boolean;
+        liquidationEvents: Array<{
+            timestamp: string;
+            asset: string;
+            liquidationPrice: number;
+            actualPrice: number;
+        }>;
+        liquidationThresholds: Array<{
+            asset: string;
+            mint: string;
+            liquidationPrice: number;
+            entryPrice: number;
+            leverage: number;
+            direction: 'LONG' | 'SHORT';
+        }>;
+    };
+    hasPredictionMarkets?: boolean;
+    predictionMarketEvents?: PredictionMarketEvent[];
+    incentives?: IncentiveOverlayCampaign[];
+}
+/** Prediction-market backtest chart — `GET /products/:id/graph` (prediction). */
+interface PredictionMarketChart {
+    workflowId: string;
+    name: string;
+    predictionMarket: boolean;
+    markets: PredictionMarketEvent[];
+    incentives?: IncentiveOverlayCampaign[];
+}
+/** Union returned by the graph endpoint. Discriminate with {@link isPredictionMarketChart}. */
+type ProductBacktestChart = BacktestChart | PredictionMarketChart;
+/** `products.get(slug, { includeBacktestChart: true })` — detail with chart merged in. */
+type ProductWithBacktestChart = ProductVersionResponse & {
+    backtestChart: ProductBacktestChart | null;
+};
+/** Type guard: is this chart the prediction-market variant? */
+declare function isPredictionMarketChart(chart: ProductBacktestChart): chart is PredictionMarketChart;
+
+interface ProductListParams {
+    /** Filter by category. */
+    category?: string;
+    /**
+     * Also fetch backtested performance (`GET /products/analytics`) and merge it
+     * onto each product as `backtest`. Fails gracefully → `backtest: null`.
+     */
+    includeBacktest?: boolean;
+}
+interface ProductGetParams {
+    /**
+     * Also fetch the product's backtested value chart and attach it as `backtestChart`.
+     * Fails gracefully → `backtestChart: null`.
+     */
+    includeBacktestChart?: boolean;
+    /** Chart window when `includeBacktestChart` is true. Default `'1y'`. */
+    chartTimeRange?: ChartTimeRange;
+}
+declare class Products extends APIResource {
+    /** List products. */
+    list(): Promise<ProductListItem[]>;
+    list(params: ProductListParams & {
+        includeBacktest?: false;
+    }, options?: RequestOptions): Promise<ProductListItem[]>;
+    list(params: ProductListParams & {
+        includeBacktest: true;
+    }, options?: RequestOptions): Promise<ProductWithBacktest[]>;
+    /** Get a product by slug. */
+    get(slug: string): Promise<ProductVersionResponse>;
+    get(slug: string, params: ProductGetParams & {
+        includeBacktestChart?: false;
+    }, options?: RequestOptions): Promise<ProductVersionResponse>;
+    get(slug: string, params: ProductGetParams & {
+        includeBacktestChart: true;
+    }, options?: RequestOptions): Promise<ProductWithBacktestChart>;
+}
+
+/**
+ * The Cesto SDK client.
+ *
+ * @example
+ * ```ts
+ * const cesto = new Cesto({ apiKey: process.env.CESTO_API_KEY! });
+ * const products = await cesto.products.list({ includeBacktest: true });
+ * ```
+ */
+declare class Cesto {
+    readonly products: Products;
+    readonly positions: Positions;
+    private readonly core;
+    constructor(options?: ClientOptions);
+    static readonly CestoError: typeof CestoError;
+    static readonly APIError: typeof APIError;
+    static readonly BadRequestError: typeof BadRequestError;
+    static readonly AuthenticationError: typeof AuthenticationError;
+    static readonly PermissionDeniedError: typeof PermissionDeniedError;
+    static readonly NotFoundError: typeof NotFoundError;
+    static readonly ConflictError: typeof ConflictError;
+    static readonly UnprocessableEntityError: typeof UnprocessableEntityError;
+    static readonly RateLimitError: typeof RateLimitError;
+    static readonly InternalServerError: typeof InternalServerError;
+    static readonly APIConnectionError: typeof APIConnectionError;
+    static readonly APIConnectionTimeoutError: typeof APIConnectionTimeoutError;
+    static readonly APIUserAbortError: typeof APIUserAbortError;
+}
+
+/** SDK version. Keep in sync with package.json `version`. */
+declare const VERSION = "0.0.1";
+
+export { APIConnectionError, APIConnectionTimeoutError, APIError, type APIErrorEnvelope, APIUserAbortError, AuthenticationError, type BacktestChart, type BacktestChartMetrics, type BacktestChartTimeSeriesPoint, BadRequestError, Cesto, type CestoEnvironment, CestoError, type ChartTimeRange, type ClientOptions, ConflictError, type GeoStatus, type IncentiveOverlayCampaign, InternalServerError, type MarketStatus, NotFoundError, type OndoTradingStatus, PermissionDeniedError, type Position, type PositionInvestment, type PositionProduct, type PositionValuation, type PositionVersion, type PositionsListParams, type PositionsResult, type PredictionMarketChart, type PredictionMarketEvent, type PredictionMarketState, type PredictionPerformance, type PredictionProtocol, type PredictionSide, type ProductBacktest, type ProductBacktestChart, type ProductCreator, type ProductGetParams, type ProductListItem, type ProductListParams, type ProductVersionResponse, type ProductWithBacktest, type ProductWithBacktestChart, RateLimitError, type RequestOptions, type TokenPerformance, UnprocessableEntityError, VERSION, isPredictionMarketChart };