@savvagent/solid 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Savvagent, LLC
+
+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,82 @@
+# @savvagent/solid
+
+SolidJS SDK for Savvagent with reactive primitives (signals and resources).
+
+## Installation
+
+```bash
+npm install @savvagent/solid
+```
+
+## Quick Start
+
+```tsx
+import { SavvagentProvider, createFlag } from '@savvagent/solid';
+import { Show } from 'solid-js';
+
+function App() {
+  return (
+    <SavvagentProvider config={{ apiKey: 'sdk_...' }}>
+      <MyFeature />
+    </SavvagentProvider>
+  );
+}
+
+function MyFeature() {
+  const flag = createFlag('new-feature');
+
+  return (
+    <Show when={!flag.loading()} fallback={<div>Loading...</div>}>
+      <Show when={flag.value()} fallback={<OldFeature />}>
+        <NewFeature />
+      </Show>
+    </Show>
+  );
+}
+```
+
+## API Reference
+
+### `createFlag(flagKey, options)`
+
+Create a reactive flag with full state.
+
+```tsx
+const flag = createFlag('new-feature', {
+  context: { user_id: userId() },
+  defaultValue: false,
+  realtime: true,
+});
+
+// Access values
+flag.value();   // boolean
+flag.loading(); // boolean
+flag.error();   // Error | null
+flag.refetch(); // force re-evaluation
+```
+
+### `createFlagValue(flagKey, options)`
+
+Simple accessor for flag value only.
+
+```tsx
+const isEnabled = createFlagValue('new-feature');
+
+return <Show when={isEnabled()}><NewFeature /></Show>;
+```
+
+### `createUserSignals()`
+
+Manage user identification.
+
+```tsx
+const [userId, setUserId] = createUserSignals();
+
+createEffect(() => {
+  setUserId(currentUser()?.id || null);
+});
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,173 @@
+import * as solid_js from 'solid-js';
+import { ParentProps, Accessor } from 'solid-js';
+import { FlagClientConfig, FlagClient, FlagContext, FlagEvaluationResult } from '@savvagent/sdk';
+export { ApiTypes, ErrorEvent, EvaluationEvent, FlagClient, FlagClientConfig, FlagContext, FlagEvaluationResult, FlagUpdateEvent, components } from '@savvagent/sdk';
+
+interface SavvagentProviderProps extends ParentProps {
+    config: FlagClientConfig;
+}
+/**
+ * Provider component that initializes and provides the Savvagent client.
+ *
+ * @example
+ * ```tsx
+ * import { SavvagentProvider } from '@savvagent/solid';
+ *
+ * function App() {
+ *   return (
+ *     <SavvagentProvider config={{ apiKey: 'sdk_...' }}>
+ *       <MyApp />
+ *     </SavvagentProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function SavvagentProvider(props: SavvagentProviderProps): solid_js.JSX.Element;
+/**
+ * Get the Savvagent client instance.
+ * Must be used within a SavvagentProvider.
+ *
+ * @returns The FlagClient instance
+ * @throws Error if used outside of SavvagentProvider
+ *
+ * @example
+ * ```tsx
+ * import { useSavvagent } from '@savvagent/solid';
+ *
+ * function MyComponent() {
+ *   const client = useSavvagent();
+ *   const enabled = await client.isEnabled('my-feature');
+ *   return <div>Enabled: {enabled}</div>;
+ * }
+ * ```
+ */
+declare function useSavvagent(): FlagClient;
+interface CreateFlagOptions {
+    /** Context for flag evaluation */
+    context?: FlagContext;
+    /** Default value while loading or on error */
+    defaultValue?: boolean;
+    /** Enable real-time updates */
+    realtime?: boolean;
+    /** Custom error handler */
+    onError?: (error: Error) => void;
+}
+interface CreateFlagReturn {
+    /** Current flag value */
+    value: Accessor<boolean>;
+    /** Whether the flag is loading */
+    loading: Accessor<boolean>;
+    /** Error if evaluation failed */
+    error: Accessor<Error | null>;
+    /** Detailed evaluation result */
+    result: Accessor<FlagEvaluationResult | null>;
+    /** Force re-evaluation */
+    refetch: () => void;
+}
+/**
+ * Create a reactive flag with automatic updates.
+ *
+ * @param flagKey - The feature flag key
+ * @param options - Configuration options
+ * @returns Reactive flag state
+ *
+ * @example
+ * ```tsx
+ * import { createFlag } from '@savvagent/solid';
+ * import { Show } from 'solid-js';
+ *
+ * function MyComponent() {
+ *   const flag = createFlag('new-feature', {
+ *     context: { user_id: userId() },
+ *     defaultValue: false,
+ *     realtime: true,
+ *   });
+ *
+ *   return (
+ *     <Show when={!flag.loading()} fallback={<div>Loading...</div>}>
+ *       <Show when={flag.value()} fallback={<OldFeature />}>
+ *         <NewFeature />
+ *       </Show>
+ *     </Show>
+ *   );
+ * }
+ * ```
+ */
+declare function createFlag(flagKey: string, options?: CreateFlagOptions): CreateFlagReturn;
+/**
+ * Create a simple reactive flag that returns only the boolean value.
+ *
+ * @param flagKey - The feature flag key
+ * @param options - Configuration options
+ * @returns Accessor for flag value
+ *
+ * @example
+ * ```tsx
+ * import { createFlagValue } from '@savvagent/solid';
+ * import { Show } from 'solid-js';
+ *
+ * function MyComponent() {
+ *   const isEnabled = createFlagValue('new-feature');
+ *
+ *   return (
+ *     <Show when={isEnabled()}>
+ *       <NewFeature />
+ *     </Show>
+ *   );
+ * }
+ * ```
+ */
+declare function createFlagValue(flagKey: string, options?: CreateFlagOptions): Accessor<boolean>;
+/**
+ * Create signals for user identification.
+ *
+ * @returns User ID management functions
+ *
+ * @example
+ * ```tsx
+ * import { createUserSignals } from '@savvagent/solid';
+ * import { createEffect } from 'solid-js';
+ *
+ * function AuthHandler() {
+ *   const [userId, setUserId] = createUserSignals();
+ *
+ *   createEffect(() => {
+ *     if (currentUser()) {
+ *       setUserId(currentUser().id);
+ *     } else {
+ *       setUserId(null);
+ *     }
+ *   });
+ *
+ *   return null;
+ * }
+ * ```
+ */
+declare function createUserSignals(): readonly [Accessor<string | null>, (id: string | null) => void];
+/**
+ * Track an error with flag context.
+ *
+ * @param flagKey - The flag key associated with the error
+ * @param error - The error that occurred
+ * @param context - Optional context
+ *
+ * @example
+ * ```tsx
+ * import { trackError } from '@savvagent/solid';
+ *
+ * function MyComponent() {
+ *   const handleAction = async () => {
+ *     try {
+ *       await doSomething();
+ *     } catch (error) {
+ *       trackError('new-feature', error as Error);
+ *     }
+ *   };
+ *
+ *   return <button onClick={handleAction}>Try Feature</button>;
+ * }
+ * ```
+ */
+declare function trackError(flagKey: string, error: Error, context?: FlagContext): void;
+
+export { type CreateFlagOptions, type CreateFlagReturn, SavvagentProvider, type SavvagentProviderProps, createFlag, createFlagValue, createUserSignals, trackError, useSavvagent };

package/dist/index.d.ts

@@ -0,0 +1,173 @@
+import * as solid_js from 'solid-js';
+import { ParentProps, Accessor } from 'solid-js';
+import { FlagClientConfig, FlagClient, FlagContext, FlagEvaluationResult } from '@savvagent/sdk';
+export { ApiTypes, ErrorEvent, EvaluationEvent, FlagClient, FlagClientConfig, FlagContext, FlagEvaluationResult, FlagUpdateEvent, components } from '@savvagent/sdk';
+
+interface SavvagentProviderProps extends ParentProps {
+    config: FlagClientConfig;
+}
+/**
+ * Provider component that initializes and provides the Savvagent client.
+ *
+ * @example
+ * ```tsx
+ * import { SavvagentProvider } from '@savvagent/solid';
+ *
+ * function App() {
+ *   return (
+ *     <SavvagentProvider config={{ apiKey: 'sdk_...' }}>
+ *       <MyApp />
+ *     </SavvagentProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function SavvagentProvider(props: SavvagentProviderProps): solid_js.JSX.Element;
+/**
+ * Get the Savvagent client instance.
+ * Must be used within a SavvagentProvider.
+ *
+ * @returns The FlagClient instance
+ * @throws Error if used outside of SavvagentProvider
+ *
+ * @example
+ * ```tsx
+ * import { useSavvagent } from '@savvagent/solid';
+ *
+ * function MyComponent() {
+ *   const client = useSavvagent();
+ *   const enabled = await client.isEnabled('my-feature');
+ *   return <div>Enabled: {enabled}</div>;
+ * }
+ * ```
+ */
+declare function useSavvagent(): FlagClient;
+interface CreateFlagOptions {
+    /** Context for flag evaluation */
+    context?: FlagContext;
+    /** Default value while loading or on error */
+    defaultValue?: boolean;
+    /** Enable real-time updates */
+    realtime?: boolean;
+    /** Custom error handler */
+    onError?: (error: Error) => void;
+}
+interface CreateFlagReturn {
+    /** Current flag value */
+    value: Accessor<boolean>;
+    /** Whether the flag is loading */
+    loading: Accessor<boolean>;
+    /** Error if evaluation failed */
+    error: Accessor<Error | null>;
+    /** Detailed evaluation result */
+    result: Accessor<FlagEvaluationResult | null>;
+    /** Force re-evaluation */
+    refetch: () => void;
+}
+/**
+ * Create a reactive flag with automatic updates.
+ *
+ * @param flagKey - The feature flag key
+ * @param options - Configuration options
+ * @returns Reactive flag state
+ *
+ * @example
+ * ```tsx
+ * import { createFlag } from '@savvagent/solid';
+ * import { Show } from 'solid-js';
+ *
+ * function MyComponent() {
+ *   const flag = createFlag('new-feature', {
+ *     context: { user_id: userId() },
+ *     defaultValue: false,
+ *     realtime: true,
+ *   });
+ *
+ *   return (
+ *     <Show when={!flag.loading()} fallback={<div>Loading...</div>}>
+ *       <Show when={flag.value()} fallback={<OldFeature />}>
+ *         <NewFeature />
+ *       </Show>
+ *     </Show>
+ *   );
+ * }
+ * ```
+ */
+declare function createFlag(flagKey: string, options?: CreateFlagOptions): CreateFlagReturn;
+/**
+ * Create a simple reactive flag that returns only the boolean value.
+ *
+ * @param flagKey - The feature flag key
+ * @param options - Configuration options
+ * @returns Accessor for flag value
+ *
+ * @example
+ * ```tsx
+ * import { createFlagValue } from '@savvagent/solid';
+ * import { Show } from 'solid-js';
+ *
+ * function MyComponent() {
+ *   const isEnabled = createFlagValue('new-feature');
+ *
+ *   return (
+ *     <Show when={isEnabled()}>
+ *       <NewFeature />
+ *     </Show>
+ *   );
+ * }
+ * ```
+ */
+declare function createFlagValue(flagKey: string, options?: CreateFlagOptions): Accessor<boolean>;
+/**
+ * Create signals for user identification.
+ *
+ * @returns User ID management functions
+ *
+ * @example
+ * ```tsx
+ * import { createUserSignals } from '@savvagent/solid';
+ * import { createEffect } from 'solid-js';
+ *
+ * function AuthHandler() {
+ *   const [userId, setUserId] = createUserSignals();
+ *
+ *   createEffect(() => {
+ *     if (currentUser()) {
+ *       setUserId(currentUser().id);
+ *     } else {
+ *       setUserId(null);
+ *     }
+ *   });
+ *
+ *   return null;
+ * }
+ * ```
+ */
+declare function createUserSignals(): readonly [Accessor<string | null>, (id: string | null) => void];
+/**
+ * Track an error with flag context.
+ *
+ * @param flagKey - The flag key associated with the error
+ * @param error - The error that occurred
+ * @param context - Optional context
+ *
+ * @example
+ * ```tsx
+ * import { trackError } from '@savvagent/solid';
+ *
+ * function MyComponent() {
+ *   const handleAction = async () => {
+ *     try {
+ *       await doSomething();
+ *     } catch (error) {
+ *       trackError('new-feature', error as Error);
+ *     }
+ *   };
+ *
+ *   return <button onClick={handleAction}>Try Feature</button>;
+ * }
+ * ```
+ */
+declare function trackError(flagKey: string, error: Error, context?: FlagContext): void;
+
+export { type CreateFlagOptions, type CreateFlagReturn, SavvagentProvider, type SavvagentProviderProps, createFlag, createFlagValue, createUserSignals, trackError, useSavvagent };

package/dist/index.js

@@ -0,0 +1,117 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.tsx
+var index_exports = {};
+__export(index_exports, {
+  FlagClient: () => import_sdk2.FlagClient,
+  SavvagentProvider: () => SavvagentProvider,
+  createFlag: () => createFlag,
+  createFlagValue: () => createFlagValue,
+  createUserSignals: () => createUserSignals,
+  trackError: () => trackError,
+  useSavvagent: () => useSavvagent
+});
+module.exports = __toCommonJS(index_exports);
+var import_solid_js = require("solid-js");
+var import_sdk = require("@savvagent/sdk");
+var import_sdk2 = require("@savvagent/sdk");
+var SavvagentContext = (0, import_solid_js.createContext)();
+function SavvagentProvider(props) {
+  const client = new import_sdk.FlagClient(props.config);
+  (0, import_solid_js.onCleanup)(() => {
+    client.close();
+  });
+  return /* @__PURE__ */ React.createElement(SavvagentContext.Provider, { value: client }, props.children);
+}
+function useSavvagent() {
+  const client = (0, import_solid_js.useContext)(SavvagentContext);
+  if (!client) {
+    throw new Error("useSavvagent must be used within a SavvagentProvider");
+  }
+  return client;
+}
+function createFlag(flagKey, options = {}) {
+  const client = useSavvagent();
+  const {
+    context,
+    defaultValue = false,
+    realtime = true,
+    onError
+  } = options;
+  const [trigger, setTrigger] = (0, import_solid_js.createSignal)(0);
+  const [result] = (0, import_solid_js.createResource)(
+    trigger,
+    async () => {
+      try {
+        return await client.evaluate(flagKey, context);
+      } catch (err) {
+        const error2 = err;
+        onError?.(error2);
+        throw error2;
+      }
+    }
+  );
+  const value = () => result()?.value ?? defaultValue;
+  const loading = () => result.loading;
+  const error = () => result.error ?? null;
+  (0, import_solid_js.createEffect)(() => {
+    if (!realtime) return;
+    const unsubscribe = client.subscribe(flagKey, () => {
+      setTrigger((t) => t + 1);
+    });
+    (0, import_solid_js.onCleanup)(() => {
+      unsubscribe();
+    });
+  });
+  return {
+    value,
+    loading,
+    error,
+    result: () => result() ?? null,
+    refetch: () => setTrigger((t) => t + 1)
+  };
+}
+function createFlagValue(flagKey, options = {}) {
+  const flag = createFlag(flagKey, options);
+  return flag.value;
+}
+function createUserSignals() {
+  const client = useSavvagent();
+  const [userId, setUserIdSignal] = (0, import_solid_js.createSignal)(client.getUserId());
+  const setUserId = (id) => {
+    client.setUserId(id);
+    setUserIdSignal(id);
+  };
+  return [userId, setUserId];
+}
+function trackError(flagKey, error, context) {
+  const client = useSavvagent();
+  client.trackError(flagKey, error, context);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FlagClient,
+  SavvagentProvider,
+  createFlag,
+  createFlagValue,
+  createUserSignals,
+  trackError,
+  useSavvagent
+});

package/dist/index.mjs

@@ -0,0 +1,93 @@
+// src/index.tsx
+import {
+  createContext,
+  useContext,
+  createSignal,
+  createResource,
+  createEffect,
+  onCleanup
+} from "solid-js";
+import { FlagClient } from "@savvagent/sdk";
+import { FlagClient as FlagClient2 } from "@savvagent/sdk";
+var SavvagentContext = createContext();
+function SavvagentProvider(props) {
+  const client = new FlagClient(props.config);
+  onCleanup(() => {
+    client.close();
+  });
+  return /* @__PURE__ */ React.createElement(SavvagentContext.Provider, { value: client }, props.children);
+}
+function useSavvagent() {
+  const client = useContext(SavvagentContext);
+  if (!client) {
+    throw new Error("useSavvagent must be used within a SavvagentProvider");
+  }
+  return client;
+}
+function createFlag(flagKey, options = {}) {
+  const client = useSavvagent();
+  const {
+    context,
+    defaultValue = false,
+    realtime = true,
+    onError
+  } = options;
+  const [trigger, setTrigger] = createSignal(0);
+  const [result] = createResource(
+    trigger,
+    async () => {
+      try {
+        return await client.evaluate(flagKey, context);
+      } catch (err) {
+        const error2 = err;
+        onError?.(error2);
+        throw error2;
+      }
+    }
+  );
+  const value = () => result()?.value ?? defaultValue;
+  const loading = () => result.loading;
+  const error = () => result.error ?? null;
+  createEffect(() => {
+    if (!realtime) return;
+    const unsubscribe = client.subscribe(flagKey, () => {
+      setTrigger((t) => t + 1);
+    });
+    onCleanup(() => {
+      unsubscribe();
+    });
+  });
+  return {
+    value,
+    loading,
+    error,
+    result: () => result() ?? null,
+    refetch: () => setTrigger((t) => t + 1)
+  };
+}
+function createFlagValue(flagKey, options = {}) {
+  const flag = createFlag(flagKey, options);
+  return flag.value;
+}
+function createUserSignals() {
+  const client = useSavvagent();
+  const [userId, setUserIdSignal] = createSignal(client.getUserId());
+  const setUserId = (id) => {
+    client.setUserId(id);
+    setUserIdSignal(id);
+  };
+  return [userId, setUserId];
+}
+function trackError(flagKey, error, context) {
+  const client = useSavvagent();
+  client.trackError(flagKey, error, context);
+}
+export {
+  FlagClient2 as FlagClient,
+  SavvagentProvider,
+  createFlag,
+  createFlagValue,
+  createUserSignals,
+  trackError,
+  useSavvagent
+};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@savvagent/solid",
+  "version": "1.0.0",
+  "description": "SolidJS SDK for Savvagent feature flags with reactive primitives",
+  "author": "Savvagent",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "solid-js": ">=1.0.0"
+  },
+  "dependencies": {
+    "@savvagent/sdk": "1.0.0"
+  },
+  "devDependencies": {
+    "solid-js": "^1.8.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  },
+  "keywords": [
+    "savvagent",
+    "feature-flags",
+    "solidjs",
+    "solid",
+    "reactive",
+    "signals",
+    "feature-toggles"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/savvagent/savvagent-sdks",
+    "directory": "packages/solid"
+  },
+  "bugs": {
+    "url": "https://github.com/savvagent/savvagent-sdks/issues"
+  },
+  "homepage": "https://github.com/savvagent/savvagent-sdks/tree/main/packages/solid#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.tsx --format cjs,esm --dts --external solid-js",
+    "dev": "tsup src/index.tsx --format cjs,esm --dts --external solid-js --watch",
+    "test": "vitest",
+    "lint": "eslint src --ext .ts,.tsx",
+    "format": "prettier --write \"src/**/*.{ts,tsx}\""
+  }
+}