@sodax/types 2.0.0-rc.2 → 2.0.0-rc.21

package/dist/shared/analytics.d.ts

@@ -0,0 +1,119 @@
+import type { SodaxFeature } from './features.js';
+/**
+ * Analytics for the SDK — structured, opt-in tracking of user-action flows.
+ *
+ * This is deliberately separate from {@link SodaxLogger}. The logger is a developer-facing
+ * diagnostics sink that is **on by default** (`console`) and takes free-form messages. Analytics
+ * is a product-facing event stream that is **off by default**: the SDK emits nothing — and never
+ * even builds an event payload — unless a consumer explicitly enables it via
+ * `new Sodax({ analytics })`. This keeps feature code paths free of analytics overhead when it is
+ * not in use.
+ *
+ * Enable and shape it through {@link AnalyticsOption} on the `Sodax` constructor:
+ * - omitted / `false` — disabled (default).
+ * - an {@link AnalyticsConfig} — forward events to your own product-analytics backend, optionally
+ *   scoped by feature and detail level.
+ */
+/**
+ * Lifecycle phase of a tracked feature action flow. Every event marks where in a feature's action
+ * flow it was emitted, so a sink can pair a `start` with its terminal `success` / `failure`
+ * (e.g. to measure duration or drop-off).
+ */
+export type AnalyticsEventPhase = 'start' | 'success' | 'failure';
+/**
+ * Detail level an event belongs to. Consumers choose how much the SDK tracks:
+ * - `basic` — coarse action flow (feature, action, phase) only.
+ * - `detailed` — adds richer `data` payloads (amounts, tokens, chain keys, …).
+ *
+ * The SDK only builds and emits a `detailed` event when the configured level is `detailed`, so
+ * heavier payloads are never constructed when a consumer stays on `basic`.
+ */
+export type AnalyticsDetailLevel = 'basic' | 'detailed';
+/**
+ * A single user-action analytics event emitted by the SDK at a feature action-flow boundary.
+ *
+ * `feature` + `action` + `phase` form the stable identity of an event — the same `(feature,
+ * action)` tagging the error layer already standardizes — so events line up with errors in a
+ * downstream sink. `data` is an optional structured payload whose richness depends on the
+ * configured {@link AnalyticsDetailLevel}.
+ */
+export interface AnalyticsEvent {
+    /** The high-level feature the action belongs to. */
+    feature: SodaxFeature;
+    /** The feature-level operation in flight, e.g. `'supply'`, `'createIntent'`, `'stake'`. */
+    action: string;
+    /** Where in the action flow this event was emitted. */
+    phase: AnalyticsEventPhase;
+    /** The detail level this event belongs to; gated against the configured level. */
+    level: AnalyticsDetailLevel;
+    /** Optional structured payload. Present mainly on `detailed` events. */
+    data?: Record<string, unknown>;
+}
+/**
+ * Consumer-supplied tracker: the SDK calls it once per emitted event, and the consumer forwards the
+ * event to their product-analytics backend (Segment, Amplitude, PostHog, a custom collector, …),
+ * e.g. `tracker: (event) => amplitude.track(event.action, event.data)`.
+ *
+ * It must be cheap and non-throwing — the SDK treats it as fire-and-forget, does not await it, and
+ * swallows any error it throws so analytics can never break a feature flow.
+ */
+export type AnalyticsTracker = (event: AnalyticsEvent) => void;
+/**
+ * How much of one feature to track, in the {@link AnalyticsConfig.features} allowlist:
+ * - `true` — every action of the feature.
+ * - `{ actions }` — only the named actions (e.g. `{ actions: ['supply', 'borrow'] }`).
+ */
+export type AnalyticsFeatureScope = true | {
+    actions: readonly string[];
+};
+/**
+ * The set of features (and actions) to track — an **allowlist**. Two equivalent forms:
+ * - Object: per-feature {@link AnalyticsFeatureScope}. A feature **omitted from the object is OFF**.
+ *   `{ swap: true, moneyMarket: { actions: ['supply'] } }`.
+ * - Array shorthand: a list of features, each fully tracked. `['swap', 'moneyMarket']`.
+ *
+ * Omitting {@link AnalyticsConfig.features} entirely tracks **everything** (all features, all
+ * actions) — scoping is opt-in.
+ */
+export type AnalyticsFeatures = Partial<Record<SodaxFeature, AnalyticsFeatureScope>> | readonly SodaxFeature[];
+/**
+ * Analytics configuration passed to `new Sodax({ analytics })`.
+ *
+ * Providing this object is what turns analytics on; the {@link AnalyticsTracker} `tracker` is the
+ * only required field. `level` and `features` narrow what gets emitted so consumers track only what
+ * they care about — by detail level and by feature/action.
+ *
+ * @example
+ * new Sodax({
+ *   analytics: {
+ *     tracker: (event) => amplitude.track(event.action, event.data),
+ *     features: {
+ *       swap: true,                              // all swap actions
+ *       moneyMarket: { actions: ['supply', 'borrow'] }, // only these
+ *       // staking omitted → OFF
+ *     }, // or simple form: features: ['swap', 'moneyMarket']
+ *   },
+ * });
+ */
+export interface AnalyticsConfig {
+    /** Where events are delivered. Required — enabling analytics means supplying a tracker. */
+    tracker: AnalyticsTracker;
+    /**
+     * Highest detail level to emit. Defaults to `'basic'`. Events tagged `'detailed'` are only built
+     * and delivered when this is `'detailed'`.
+     */
+    level?: AnalyticsDetailLevel;
+    /**
+     * Allowlist of features/actions to track. Omit to track everything; otherwise only the listed
+     * features (and, with `{ actions }`, only the listed actions) emit. See {@link AnalyticsFeatures}.
+     */
+    features?: AnalyticsFeatures;
+}
+/**
+ * The `analytics` option accepted by `new Sodax(...)`. Either a full {@link AnalyticsConfig} or
+ * `false` (the default — analytics disabled).
+ *
+ * Like `logger`, this is a client-side runtime option resolved once by the SDK; it is never
+ * fetched from or overwritten by the backend config.
+ */
+export type AnalyticsOption = AnalyticsConfig | false;

package/dist/shared/analytics.js

@@ -0,0 +1 @@
+export {};

package/dist/shared/features.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The set of high-level SODAX SDK features.
+ *
+ * Used as a first-class tag across cross-cutting concerns — error reporting
+ * (`SodaxError.feature` in `@sodax/sdk`) and analytics ({@link AnalyticsEvent.feature} and
+ * per-feature analytics toggles). It lives in `@sodax/types`, the lowest layer, so every package
+ * shares one source of truth instead of redefining the list; `@sodax/sdk` re-exports it.
+ */
+export type SodaxFeature = 'swap' | 'moneyMarket' | 'bridge' | 'staking' | 'migration' | 'dex' | 'partner' | 'recovery' | 'backend' | 'leverageYield';

package/dist/shared/features.js

@@ -0,0 +1 @@
+export {};

package/dist/shared/index.d.ts

@@ -1,2 +1,4 @@
 export * from './shared.js';
-//# sourceMappingURL=index.d.ts.map
+export * from './logger.js';
+export * from './features.js';
+export * from './analytics.js';

package/dist/shared/index.js

@@ -1,2 +1,4 @@
 export * from './shared.js';
-//# sourceMappingURL=index.js.map
+export * from './logger.js';
+export * from './features.js';
+export * from './analytics.js';

package/dist/shared/logger.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Unified logging interface for the SDK.
+ *
+ * The SDK routes all of its internal diagnostics through a `SodaxLogger` instead of
+ * calling `console.*` directly, so consumers can redirect or silence SDK output and
+ * forward it to a structured sink (Sentry, Pino, Datadog, etc.).
+ *
+ * Pass one to `new Sodax({ logger })` via {@link SodaxLoggerOption}:
+ * - `'console'` — default; mirrors the SDK's historical `console.*` behavior.
+ * - `'silent'`  — drop all SDK logs.
+ * - a custom `SodaxLogger` — forward to your own sink.
+ *
+ * `error()` receives the thrown value separately from structured `data` so adapters
+ * can attach it as the exception (e.g. `Sentry.captureException(error, { extra: data })`).
+ * SDK errors are `SodaxError` instances whose `toJSON()` is the canonical serialization surface.
+ */
+export interface SodaxLogger {
+    debug(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, error?: unknown, data?: Record<string, unknown>): void;
+}
+/**
+ * Logger configuration accepted by `new Sodax(...)`. Either a built-in preset name or a
+ * custom {@link SodaxLogger} implementation. Resolved to a concrete `SodaxLogger` by the SDK.
+ */
+export type SodaxLoggerOption = SodaxLogger | 'console' | 'silent';

package/dist/shared/logger.js

@@ -0,0 +1 @@
+export {};

package/dist/shared/shared.d.ts

@@ -14,4 +14,24 @@ export type TxPollingConfig = {
     pollingIntervalMs: number;
     maxTimeoutMs: number;
 };
-//# sourceMappingURL=shared.d.ts.map
+/**
+ * Tuning for the viem `fallback()` transport used when more than one RPC endpoint is configured.
+ * Plain serializable mirror of viem's fallback options so this type stays dependency-free.
+ */
+export type RpcFallbackOptions = {
+    /** Re-rank endpoints by latency instead of strict listed order (viem default: off; ignored unless more than one endpoint is configured). */
+    rank?: boolean;
+    /** Retries of the overall failover request before the error surfaces (viem default: 3); each attempt tries the endpoints in listed order. */
+    retryCount?: number;
+    /** Delay in ms between retries. */
+    retryDelay?: number;
+};
+/**
+ * Optional multi-endpoint RPC failover, mixed into EVM chain configs that support it.
+ * When `rpcUrls` is present and non-empty it supersedes the single `rpcUrl` (first entry is primary);
+ * an absent or empty `rpcUrls` preserves single-endpoint behavior.
+ */
+export type RpcFailoverConfig = {
+    rpcUrls?: readonly string[];
+    rpcOptions?: RpcFallbackOptions;
+};

package/dist/shared/shared.js

@@ -3,4 +3,3 @@
  * Forbidden to import types from other packages in this file!
  */
 export {};
-//# sourceMappingURL=shared.js.map

package/dist/sodax-config/index.d.ts

@@ -1,2 +1 @@
 export * from './sodax-config.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/sodax-config/index.js

@@ -1,2 +1 @@
 export * from './sodax-config.js';
-//# sourceMappingURL=index.js.map