@cesto/sdk 0.0.1

package/LICENSE

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

package/README.md

@@ -0,0 +1,184 @@
+# @cesto/sdk
+
+Typed, server-side TypeScript client for the Cesto read-only API.
+
+> **Server-side only.** Authentication uses a **secret** API key (`cesto_sk_…`).
+> Never use it in a browser — the client throws if it detects one.
+
+## Install
+
+```bash
+npm i @cesto/sdk
+```
+
+Requires Node 18+ (uses the global `fetch`).
+
+## Quick start
+
+```ts
+import { Cesto } from '@cesto/sdk';
+
+const cesto = new Cesto({ apiKey: process.env.CESTO_API_KEY! });
+```
+
+Pass your secret key as `apiKey` (read it from your environment, e.g. `process.env.CESTO_API_KEY`).
+The constructor throws if it's missing.
+
+### Products
+
+```ts
+// List products
+const products = await cesto.products.list();
+const defi = await cesto.products.list({ category: 'defi' });
+
+// List + backtested performance (one extra request, merged per product)
+const withPerf = await cesto.products.list({ includeBacktest: true });
+withPerf[0].backtest; // ProductBacktest | null
+
+// Get one product by slug
+const product = await cesto.products.get('my-basket-slug');
+
+// Get + backtested value chart (default 1y window)
+const detailed = await cesto.products.get('my-basket-slug', {
+  includeBacktestChart: true,
+  chartTimeRange: '1y',
+});
+detailed.backtestChart; // BacktestChart | PredictionMarketChart | null
+```
+
+The chart is a union — discriminate it with the shipped guard:
+
+```ts
+import { isPredictionMarketChart } from '@cesto/sdk';
+
+if (detailed.backtestChart && isPredictionMarketChart(detailed.backtestChart)) {
+  detailed.backtestChart.markets; // PredictionMarketEvent[]
+}
+```
+
+> `includeBacktest` / `includeBacktestChart` make a second request. If it fails, the
+> folded-in field is `null` — your primary data is never lost to a flaky secondary call.
+
+### Positions (by external Solana wallet)
+
+```ts
+const { positions, pendingClosePositions } = await cesto.positions.list({
+  wallet: 'EXTERNAL_SOLANA_ADDRESS',
+});
+```
+
+A wallet with no Cesto account returns an empty result (not an error).
+
+## Full example
+
+```ts
+import { Cesto, isPredictionMarketChart } from '@cesto/sdk';
+
+async function main() {
+  // Read the key from your environment — never hard-code a secret key.
+  const cesto = new Cesto({
+    apiKey: process.env.CESTO_API_KEY!,
+    environment: 'PRODUCTION', // 'PRODUCTION' | 'BETA'
+    timeout: 30_000,
+    maxRetries: 2,
+  });
+
+  // List products + backtested performance (one extra request, merged per product).
+  // A failed analytics call degrades gracefully → backtest: null.
+  const products = await cesto.products.list({ includeBacktest: true });
+  console.log(`${products.length} products`);
+
+  // Get one product by slug, with its backtested value chart.
+  const slug = products[0]?.slug;
+  if (slug) {
+    const detail = await cesto.products.get(slug, {
+      includeBacktestChart: true,
+      chartTimeRange: '1y',
+    });
+
+    // The chart is a union — discriminate with the shipped type guard.
+    const chart = detail.backtestChart;
+    if (chart && !isPredictionMarketChart(chart)) {
+      console.log(`${detail.name}: ${chart.timeSeries.length} chart points`);
+    }
+  }
+
+  // Positions by external Solana wallet. An unknown wallet returns empty.
+  const { positions } = await cesto.positions.list({
+    wallet: 'EXTERNAL_SOLANA_ADDRESS',
+  });
+  for (const pos of positions) {
+    console.log(`• ${pos.product.name} — ${pos.investments.length} investment(s)`);
+  }
+}
+
+main().catch((err) => {
+  // Typed error handling — narrow with the classes hung off `Cesto`.
+  if (err instanceof Cesto.AuthenticationError) {
+    console.error('Auth failed — check your CESTO_API_KEY.');
+  } else if (err instanceof Cesto.RateLimitError) {
+    console.error(`Rate limited. Retry after ~${err.retryAfter ?? '?'}ms.`);
+  } else if (err instanceof Cesto.APIError) {
+    console.error(`API error ${err.status}: ${err.message} [${err.code ?? 'no-code'}]`);
+  } else {
+    console.error('Unexpected error:', err);
+  }
+  process.exitCode = 1;
+});
+```
+
+## Configuration
+
+```ts
+new Cesto({
+  apiKey: 'cesto_sk_…',       // required
+  environment: 'PRODUCTION',  // 'PRODUCTION' | 'BETA', default 'PRODUCTION'
+  timeout: 60_000,            // ms, default 60s
+  maxRetries: 2,              // default 2
+  fetch: customFetch,         // optional fetch override
+});
+```
+
+The backend URL is **not a free-form option**. `NODE_ENV` decides local-vs-deployed,
+and `environment` selects which deployed backend:
+
+| NODE_ENV | environment | URL |
+|---|---|---|
+| `production` | `PRODUCTION` (default) | `https://backend.cesto.co` |
+| `production` | `BETA` | `https://dev.backend.cesto.co` |
+
+Keys are environment-specific (each backend has its own) — use the `PRODUCTION` key with
+`PRODUCTION`, the `BETA` key with `BETA`.
+
+Per-request overrides (second/third argument on every method):
+
+```ts
+await cesto.products.list({ category: 'defi' }, { timeout: 5_000, maxRetries: 0, signal });
+```
+
+## Errors
+
+All errors extend `CestoError`. Server responses become typed `APIError` subclasses;
+transport problems become `APIConnectionError` / `APIConnectionTimeoutError`; caller
+cancellation becomes `APIUserAbortError`.
+
+```ts
+import { Cesto } from '@cesto/sdk';
+
+try {
+  await cesto.products.get('missing');
+} catch (err) {
+  if (err instanceof Cesto.NotFoundError) {
+    // 404 — err.code, err.requestId, err.details available
+  } else if (err instanceof Cesto.RateLimitError) {
+    // 429 — err.retryAfter (ms)
+  } else if (err instanceof Cesto.APIConnectionError) {
+    // network / timeout
+  } else {
+    throw err;
+  }
+}
+```
+
+Transient failures (429, 5xx, network, timeouts) are retried automatically with
+exponential backoff + jitter, honoring `Retry-After`.

package/dist/index.cjs

@@ -0,0 +1,394 @@
+'use strict';
+
+// src/core/errors.ts
+var CestoError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = new.target.name;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var APIError = class extends CestoError {
+  /** HTTP status code. */
+  status;
+  /** Machine-readable error code from the API envelope (e.g. `RESOURCE_NOT_FOUND`). */
+  code;
+  /** Correlation id from the API envelope, useful when reporting issues. */
+  requestId;
+  /** Structured error details from the API envelope. */
+  details;
+  /** Response headers. */
+  headers;
+  constructor(status, message, opts = {}) {
+    super(message);
+    this.status = status;
+    this.code = opts.code;
+    this.requestId = opts.requestId;
+    this.details = opts.details;
+    this.headers = opts.headers;
+  }
+};
+var BadRequestError = class extends APIError {
+};
+var AuthenticationError = class extends APIError {
+};
+var PermissionDeniedError = class extends APIError {
+};
+var NotFoundError = class extends APIError {
+};
+var ConflictError = class extends APIError {
+};
+var UnprocessableEntityError = class extends APIError {
+};
+var RateLimitError = class extends APIError {
+  /** Milliseconds to wait before retrying, derived from `Retry-After`. */
+  retryAfter;
+  constructor(status, message, opts = {}) {
+    super(status, message, opts);
+    this.retryAfter = opts.retryAfter;
+  }
+};
+var InternalServerError = class extends APIError {
+};
+var APIConnectionError = class extends CestoError {
+  cause;
+  constructor(message = "Connection error", opts = {}) {
+    super(message);
+    this.cause = opts.cause;
+  }
+};
+var APIConnectionTimeoutError = class extends APIConnectionError {
+  constructor(message = "Request timed out") {
+    super(message);
+  }
+};
+var APIUserAbortError = class extends CestoError {
+  constructor(message = "Request was aborted") {
+    super(message);
+  }
+};
+function makeAPIError(status, envelope, headers, retryAfter) {
+  const message = envelope.message || `HTTP ${status}`;
+  const opts = {
+    code: envelope.code,
+    requestId: envelope.requestId,
+    details: envelope.details,
+    headers
+  };
+  switch (status) {
+    case 400:
+      return new BadRequestError(status, message, opts);
+    case 401:
+      return new AuthenticationError(status, message, opts);
+    case 403:
+      return new PermissionDeniedError(status, message, opts);
+    case 404:
+      return new NotFoundError(status, message, opts);
+    case 409:
+      return new ConflictError(status, message, opts);
+    case 422:
+      return new UnprocessableEntityError(status, message, opts);
+    case 429:
+      return new RateLimitError(status, message, { ...opts, retryAfter });
+    default:
+      if (status >= 500) return new InternalServerError(status, message, opts);
+      return new APIError(status, message, opts);
+  }
+}
+
+// src/core/options.ts
+var PROD_BASE_URL = "https://backend.cesto.co";
+var BETA_BASE_URL = "https://dev.backend.cesto.co";
+var DEFAULT_TIMEOUT_MS = 6e4;
+var DEFAULT_MAX_RETRIES = 2;
+function isBrowser() {
+  return typeof window !== "undefined" && typeof window.document !== "undefined";
+}
+function resolveBaseURL(environment) {
+  return environment === "BETA" ? BETA_BASE_URL : PROD_BASE_URL;
+}
+function resolveOptions(options) {
+  if (isBrowser()) {
+    throw new CestoError(
+      "The Cesto SDK is server-side only. It must not run in a browser \u2014 a secret key (cesto_sk_\u2026) would be exposed to end users."
+    );
+  }
+  const apiKey = options.apiKey;
+  if (!apiKey) {
+    throw new CestoError("Missing API key. Pass { apiKey } when constructing the client.");
+  }
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  if (typeof fetchImpl !== "function") {
+    throw new CestoError(
+      "No fetch implementation found. Use Node 18+ or pass a custom { fetch } in ClientOptions."
+    );
+  }
+  const timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+  if (!Number.isFinite(timeout) || timeout < 0) {
+    throw new CestoError("`timeout` must be a finite number >= 0.");
+  }
+  const maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+  if (!Number.isInteger(maxRetries) || maxRetries < 0) {
+    throw new CestoError("`maxRetries` must be an integer >= 0.");
+  }
+  const environment = options.environment ?? "PRODUCTION";
+  if (environment !== "PRODUCTION" && environment !== "BETA") {
+    throw new CestoError(`Invalid environment: ${environment}. Use 'PRODUCTION' or 'BETA'.`);
+  }
+  return {
+    apiKey,
+    baseURL: resolveBaseURL(environment),
+    timeout,
+    maxRetries,
+    fetch: options.fetch ?? fetchImpl.bind(globalThis)
+  };
+}
+
+// src/core/version.ts
+var VERSION = "0.0.1";
+
+// src/core/request.ts
+var RETRY_BASE_MS = 500;
+var RETRY_CAP_MS = 8e3;
+var APIClientCore = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  get(path, options = {}) {
+    return this.request("GET", path, options);
+  }
+  async request(method, path, options) {
+    const url = this.buildURL(path, options.query);
+    const timeout = options.timeout ?? this.opts.timeout;
+    const maxRetries = options.maxRetries ?? this.opts.maxRetries;
+    let attempt = 0;
+    for (; ; ) {
+      const timer = withTimeout(options.signal, timeout);
+      let response;
+      try {
+        response = await this.opts.fetch(url, {
+          method,
+          headers: buildHeaders(this.opts.apiKey, attempt),
+          signal: timer.signal
+        });
+      } catch (err) {
+        timer.cleanup();
+        const mapped = mapFetchError(err, timer, options.signal);
+        if (mapped instanceof APIUserAbortError) throw mapped;
+        if (attempt < maxRetries) {
+          attempt += 1;
+          await sleep(backoff(attempt));
+          continue;
+        }
+        throw mapped;
+      }
+      timer.cleanup();
+      if (response.ok) {
+        return parseJSON(response);
+      }
+      if (shouldRetryStatus(response.status) && attempt < maxRetries) {
+        attempt += 1;
+        await sleep(parseRetryAfter(response.headers) ?? backoff(attempt));
+        continue;
+      }
+      throw await errorFromResponse(response);
+    }
+  }
+  buildURL(path, query) {
+    const url = new URL(`${this.opts.baseURL}${path}`);
+    if (query) {
+      for (const [key, value] of Object.entries(query)) {
+        if (value !== void 0 && value !== null) url.searchParams.set(key, String(value));
+      }
+    }
+    return url.toString();
+  }
+};
+function buildHeaders(apiKey, attempt) {
+  const headers = {
+    "X-API-Key": apiKey,
+    Accept: "application/json"
+  };
+  const ua = userAgent();
+  if (ua) headers["User-Agent"] = ua;
+  if (attempt > 0) headers["x-cesto-retry-count"] = String(attempt);
+  return headers;
+}
+function userAgent() {
+  if (typeof process !== "undefined" && process.versions?.node) {
+    return `cesto-sdk/${VERSION} (node/${process.versions.node})`;
+  }
+  return `cesto-sdk/${VERSION}`;
+}
+function withTimeout(userSignal, timeoutMs) {
+  const controller = new AbortController();
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    controller.abort(new Error("timeout"));
+  }, timeoutMs);
+  const onUserAbort = () => controller.abort(userSignal?.reason);
+  if (userSignal) {
+    if (userSignal.aborted) controller.abort(userSignal.reason);
+    else userSignal.addEventListener("abort", onUserAbort, { once: true });
+  }
+  return {
+    signal: controller.signal,
+    didTimeout: () => timedOut,
+    cleanup: () => {
+      clearTimeout(timer);
+      userSignal?.removeEventListener("abort", onUserAbort);
+    }
+  };
+}
+function mapFetchError(err, timer, userSignal) {
+  if (userSignal?.aborted) return new APIUserAbortError();
+  if (timer.didTimeout()) return new APIConnectionTimeoutError();
+  return new APIConnectionError("Connection error", { cause: err });
+}
+function shouldRetryStatus(status) {
+  return status === 408 || status === 409 || status === 429 || status >= 500;
+}
+async function parseJSON(response) {
+  const text = await response.text();
+  if (!text) return void 0;
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new CestoError("Failed to parse response body as JSON.");
+  }
+}
+async function errorFromResponse(response) {
+  let envelope = {};
+  try {
+    const text = await response.text();
+    if (text) {
+      const parsed = JSON.parse(text);
+      if (parsed && typeof parsed === "object") envelope = parsed;
+    }
+  } catch {
+  }
+  return makeAPIError(
+    response.status,
+    envelope,
+    response.headers,
+    parseRetryAfter(response.headers)
+  );
+}
+function parseRetryAfter(headers) {
+  const value = headers.get("retry-after");
+  if (!value) return void 0;
+  const seconds = Number(value);
+  if (!Number.isNaN(seconds)) return Math.max(0, seconds * 1e3);
+  const dateMs = Date.parse(value);
+  if (!Number.isNaN(dateMs)) return Math.max(0, dateMs - Date.now());
+  return void 0;
+}
+function backoff(attempt) {
+  const ceiling = Math.min(RETRY_CAP_MS, RETRY_BASE_MS * 2 ** (attempt - 1));
+  return Math.random() * ceiling;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/resources/resource.ts
+var APIResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+};
+
+// src/resources/positions.ts
+var Positions = class 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, options) {
+    if (!params?.wallet) throw new CestoError("wallet is required");
+    return this.client.get("/positions/by-wallet", {
+      query: { wallet: params.wallet },
+      ...options
+    });
+  }
+};
+
+// src/resources/products.ts
+var DEFAULT_CHART_TIME_RANGE = "1y";
+var Products = class extends APIResource {
+  async list(params = {}, options) {
+    const query = params.category ? { category: params.category } : void 0;
+    if (!params.includeBacktest) {
+      return this.client.get("/products", { query, ...options });
+    }
+    const [items, backtests] = await Promise.all([
+      this.client.get("/products", { query, ...options }),
+      this.client.get("/products/analytics", { query, ...options }).catch(() => ({}))
+    ]);
+    return items.map((item) => ({ ...item, backtest: backtests[item.id] ?? null }));
+  }
+  async get(slug, params = {}, options) {
+    const product = await this.client.get(
+      `/products/${encodeURIComponent(slug)}`,
+      options
+    );
+    if (!params.includeBacktestChart) return product;
+    const backtestChart = await this.client.get(`/products/${encodeURIComponent(product.id)}/graph`, {
+      query: { timeRange: params.chartTimeRange ?? DEFAULT_CHART_TIME_RANGE },
+      ...options
+    }).catch(() => null);
+    return { ...product, backtestChart };
+  }
+};
+
+// src/client.ts
+var Cesto = class {
+  products;
+  positions;
+  core;
+  constructor(options = {}) {
+    this.core = new APIClientCore(resolveOptions(options));
+    this.products = new Products(this.core);
+    this.positions = new Positions(this.core);
+  }
+  // Error classes re-exposed for ergonomic `instanceof` checks:
+  //   catch (e) { if (e instanceof Cesto.NotFoundError) … }
+  static CestoError = CestoError;
+  static APIError = APIError;
+  static BadRequestError = BadRequestError;
+  static AuthenticationError = AuthenticationError;
+  static PermissionDeniedError = PermissionDeniedError;
+  static NotFoundError = NotFoundError;
+  static ConflictError = ConflictError;
+  static UnprocessableEntityError = UnprocessableEntityError;
+  static RateLimitError = RateLimitError;
+  static InternalServerError = InternalServerError;
+  static APIConnectionError = APIConnectionError;
+  static APIConnectionTimeoutError = APIConnectionTimeoutError;
+  static APIUserAbortError = APIUserAbortError;
+};
+
+// src/types/products.ts
+function isPredictionMarketChart(chart) {
+  return chart.predictionMarket === true;
+}
+
+exports.APIConnectionError = APIConnectionError;
+exports.APIConnectionTimeoutError = APIConnectionTimeoutError;
+exports.APIError = APIError;
+exports.APIUserAbortError = APIUserAbortError;
+exports.AuthenticationError = AuthenticationError;
+exports.BadRequestError = BadRequestError;
+exports.Cesto = Cesto;
+exports.CestoError = CestoError;
+exports.ConflictError = ConflictError;
+exports.InternalServerError = InternalServerError;
+exports.NotFoundError = NotFoundError;
+exports.PermissionDeniedError = PermissionDeniedError;
+exports.RateLimitError = RateLimitError;
+exports.UnprocessableEntityError = UnprocessableEntityError;
+exports.VERSION = VERSION;
+exports.isPredictionMarketChart = isPredictionMarketChart;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map