@replanejs/sdk 0.5.12 → 0.6.2

package/dist/index.d.ts

@@ -1,6 +1,84 @@
-//#region src/index.d.ts
+//#region src/client-types.d.ts
+/**
+ * Base type for config objects
+ */
 type Configs = object;
-type ReplaneContext = Record<string, unknown>;
+/**
+ * Context object for override evaluation.
+ * Keys are property names, values can be strings, numbers, booleans, null, or undefined.
+ */
+type ReplaneContext = Record<string, string | number | boolean | null | undefined>;
+/**
+ * Logger interface for SDK logging
+ */
+interface ReplaneLogger {
+  debug(...args: unknown[]): void;
+  info(...args: unknown[]): void;
+  warn(...args: unknown[]): void;
+  error(...args: unknown[]): void;
+}
+/**
+ * Options for getting a config value
+ */
+interface GetConfigOptions {
+  /**
+   * Context for override evaluation (merged with client-level context).
+   */
+  context?: ReplaneContext;
+}
+/**
+ * Helper type for mapping configs to their names and values
+ */
+type MapConfig<T extends Configs> = { [K in keyof T]: {
+  name: K;
+  value: T[K];
+} }[keyof T];
+/**
+ * Serializable snapshot of the client state.
+ * Can be used to restore a client on the client-side from server-fetched configs.
+ */
+interface ReplaneSnapshot<_T extends Configs = Configs> {
+  /** Serialized config data */
+  configs: Array<{
+    name: string;
+    value: unknown;
+    overrides: Array<{
+      name: string;
+      conditions: unknown[];
+      value: unknown;
+    }>;
+  }>;
+  /** Default context used for override evaluation */
+  context?: ReplaneContext;
+}
+/**
+ * The Replane client interface
+ */
+interface ReplaneClient<T extends Configs> {
+  /** Get a config by its name. */
+  get<K extends keyof T>(configName: K, options?: GetConfigOptions): T[K];
+  /** Subscribe to config changes.
+   *  @param callback - A function to call when an config is changed. The callback will be called with the new config value.
+   *  @returns A function to unsubscribe from the config changes.
+   */
+  subscribe(callback: (config: MapConfig<T>) => void): () => void;
+  /** Subscribe to a specific config change.
+   *  @param configName - The name of the config to subscribe to.
+   *  @param callback - A function to call when the config is changed. The callback will be called with the new config value.
+   *  @returns A function to unsubscribe from the config changes.
+   */
+  subscribe<K extends keyof T>(configName: K, callback: (config: MapConfig<Pick<T, K>>) => void): () => void;
+  /**
+   * Get a serializable snapshot of the current client state.
+   * Useful for SSR/hydration scenarios where you want to pass configs from server to client.
+   */
+  getSnapshot(): ReplaneSnapshot<T>;
+  /** Close the client and clean up resources. */
+  close(): void;
+}
+/**
+ * Options for creating a Replane client
+ */
 interface ReplaneClientOptions<T extends Configs> {
   /**
    * Base URL of the Replane instance (no trailing slash).
@@ -39,7 +117,7 @@ interface ReplaneClientOptions<T extends Configs> {
   /**
    * Timeout in ms for SSE connection inactivity.
    * If no events (including pings) are received within this time, the connection will be re-established.
-   * @default 60000
+   * @default 30000
    */
   inactivityTimeoutMs?: number;
   /**
@@ -82,60 +160,137 @@ interface ReplaneClientOptions<T extends Configs> {
    */
   fallbacks?: { [K in keyof T]: T[K] };
 }
-interface ReplaneLogger {
-  debug(...args: unknown[]): void;
-  info(...args: unknown[]): void;
-  warn(...args: unknown[]): void;
-  error(...args: unknown[]): void;
-}
-interface GetConfigOptions {
+/**
+ * Options for restoring a Replane client from a snapshot
+ */
+interface RestoreReplaneClientOptions<T extends Configs> {
   /**
-   * Context for override evaluation (merged with client-level context).
+   * Snapshot from a server-side client's getSnapshot() call.
    */
-  context?: ReplaneContext;
-}
-type MapConfig<T extends Configs> = { [K in keyof T]: {
-  name: K;
-  value: T[K];
-} }[keyof T];
-interface ReplaneClient<T extends Configs> {
-  /** Get a config by its name. */
-  get<K extends keyof T>(configName: K, options?: GetConfigOptions): T[K];
-  /** Subscribe to config changes.
-   *  @param callback - A function to call when an config is changed. The callback will be called with the new config value.
-   *  @returns A function to unsubscribe from the config changes.
+  snapshot: ReplaneSnapshot<T>;
+  /**
+   * Optional connection options for live updates.
+   * If provided, the client will connect to the Replane server for real-time config updates.
+   * If not provided, the client will only use the snapshot data (no live updates).
    */
-  subscribe(callback: (config: MapConfig<T>) => void): () => void;
-  /** Subscribe to a specific config change.
-   *  @param configName - The name of the config to subscribe to.
-   *  @param callback - A function to call when the config is changed. The callback will be called with the new config value.
-   *  @returns A function to unsubscribe from the config changes.
+  connection?: {
+    /**
+     * Base URL of the Replane instance (no trailing slash).
+     */
+    baseUrl: string;
+    /**
+     * Project SDK key for authorization.
+     */
+    sdkKey: string;
+    /**
+     * Custom fetch implementation (useful for tests / polyfills).
+     */
+    fetchFn?: typeof fetch;
+    /**
+     * Optional timeout in ms for the request.
+     * @default 2000
+     */
+    requestTimeoutMs?: number;
+    /**
+     * Delay between retries in ms.
+     * @default 200
+     */
+    retryDelayMs?: number;
+    /**
+     * Timeout in ms for SSE connection inactivity.
+     * @default 30000
+     */
+    inactivityTimeoutMs?: number;
+    /**
+     * Optional logger (defaults to console).
+     */
+    logger?: ReplaneLogger;
+  };
+  /**
+   * Override the context from the snapshot.
    */
-  subscribe<K extends keyof T>(configName: K, callback: (config: MapConfig<Pick<T, K>>) => void): () => void;
-  /** Close the client and clean up resources. */
-  close(): void;
-}
-declare class ReplaneError extends Error {
-  code: string;
-  constructor(params: {
-    message: string;
-    code: string;
-    cause?: unknown;
-  });
+  context?: ReplaneContext;
 }
+/**
+ * Internal options after processing user options
+ */
+//#endregion
+//#region src/client.d.ts
 /**
  * Create a Replane client bound to an SDK key.
- * Usage:
- *   const client = await createReplaneClient({ sdkKey: 'your-sdk-key', baseUrl: 'https://app.replane.dev' })
- *   const value = client.getConfig('my-config')
+ *
+ * @example
+ * ```typescript
+ * const client = await createReplaneClient({
+ *   sdkKey: 'your-sdk-key',
+ *   baseUrl: 'https://app.replane.dev'
+ * });
+ * const value = client.get('my-config');
+ * ```
  */
 declare function createReplaneClient<T extends Configs = Record<string, unknown>>(sdkOptions: ReplaneClientOptions<T>): Promise<ReplaneClient<T>>;
 /**
  * Create a Replane client that uses in-memory storage.
- * Usage:
- *   const client = createInMemoryReplaneClient({ 'my-config': 123 })
- *   const value = client.getConfig('my-config') // 123
+ * Useful for testing or when you have static config values.
+ *
+ * @example
+ * ```typescript
+ * const client = createInMemoryReplaneClient({ 'my-config': 123 });
+ * const value = client.get('my-config'); // 123
+ * ```
  */
 declare function createInMemoryReplaneClient<T extends Configs = Record<string, unknown>>(initialData: T): ReplaneClient<T>;
+/**
+ * Restore a Replane client from a snapshot.
+ * This is useful for SSR/hydration scenarios where the server has already fetched configs.
+ *
+ * @example
+ * ```typescript
+ * // On the server:
+ * const serverClient = await createReplaneClient({ ... });
+ * const snapshot = serverClient.getSnapshot();
+ * // Pass snapshot to client via props/serialization
+ *
+ * // On the client:
+ * const client = restoreReplaneClient({
+ *   snapshot,
+ *   connection: { sdkKey, baseUrl }
+ * });
+ * const value = client.get('my-config');
+ * ```
+ */
+declare function restoreReplaneClient<T extends Configs = Record<string, unknown>>(options: RestoreReplaneClientOptions<T>): ReplaneClient<T>;
+//# sourceMappingURL=client.d.ts.map
+//#endregion
+//#region src/error.d.ts
+/**
+ * Error codes for ReplaneError
+ */
+declare enum ReplaneErrorCode {
+  NotFound = "not_found",
+  Timeout = "timeout",
+  NetworkError = "network_error",
+  AuthError = "auth_error",
+  Forbidden = "forbidden",
+  ServerError = "server_error",
+  ClientError = "client_error",
+  Closed = "closed",
+  NotInitialized = "not_initialized",
+  Unknown = "unknown",
+}
+/**
+ * Custom error class for Replane SDK errors
+ */
+declare class ReplaneError extends Error {
+  code: string;
+  constructor(params: {
+    message: string;
+    code: string;
+    cause?: unknown;
+  });
+}
+//# sourceMappingURL=error.d.ts.map
+
 //#endregion
-export { GetConfigOptions, ReplaneClient, ReplaneClientOptions, ReplaneContext, ReplaneError, ReplaneLogger, createInMemoryReplaneClient, createReplaneClient };
+export { type GetConfigOptions, type ReplaneClient, type ReplaneClientOptions, type ReplaneContext, ReplaneError, ReplaneErrorCode, type ReplaneLogger, type ReplaneSnapshot, type RestoreReplaneClientOptions, createInMemoryReplaneClient, createReplaneClient, restoreReplaneClient };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/client-types.ts","../src/client.ts","../src/error.ts"],"sourcesContent":[],"mappings":"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"}