@traffical/svelte 0.1.0

package/README.md

@@ -0,0 +1,365 @@
+# @traffical/svelte
+
+Traffical SDK for Svelte 5 applications. Provides reactive hooks and components for parameter resolution, A/B testing, and feature flags with full SSR/hydration support.
+
+## Features
+
+- **Svelte 5 Runes** - Uses `$state`, `$derived`, and `$effect` for reactive, fine-grained updates
+- **Full SSR Support** - Pre-fetch config bundles in SvelteKit load functions
+- **Hydration-Safe** - No FOOC (Flash of Original Content) with proper initialization
+- **Feature Parity** - Same capabilities as the React SDK
+- **Type-Safe** - Full TypeScript support with generic parameter types
+
+## Installation
+
+```bash
+bun add @traffical/svelte
+# or
+npm install @traffical/svelte
+# or
+pnpm add @traffical/svelte
+```
+
+## Quick Start
+
+### 1. Set up the Provider
+
+In your root layout, initialize Traffical:
+
+```svelte
+<!-- src/routes/+layout.svelte -->
+<script lang="ts">
+  import { TrafficalProvider } from '@traffical/svelte';
+  import { PUBLIC_TRAFFICAL_API_KEY } from '$env/static/public';
+
+  let { data, children } = $props();
+</script>
+
+<TrafficalProvider
+  config={{
+    orgId: 'org_123',
+    projectId: 'proj_456',
+    env: 'production',
+    apiKey: PUBLIC_TRAFFICAL_API_KEY,
+    initialBundle: data.traffical?.bundle,
+  }}
+>
+  {@render children()}
+</TrafficalProvider>
+```
+
+### 2. Use Parameters in Components
+
+```svelte
+<!-- src/routes/checkout/+page.svelte -->
+<script lang="ts">
+  import { useTraffical } from '@traffical/svelte';
+
+  const { params, ready, track } = useTraffical({
+    defaults: {
+      'checkout.ctaText': 'Buy Now',
+      'checkout.ctaColor': '#000000',
+    },
+  });
+
+  function handlePurchase(amount: number) {
+    // track has the decisionId already bound!
+    track('purchase', { value: amount, orderId: 'ord_123' });
+  }
+</script>
+
+{#if ready}
+  <button
+    style="background: {params['checkout.ctaColor']}"
+    onclick={() => handlePurchase(99.99)}
+  >
+    {params['checkout.ctaText']}
+  </button>
+{:else}
+  <button disabled>Loading...</button>
+{/if}
+```
+
+## SSR with SvelteKit
+
+For optimal performance and to prevent content flashing, fetch the config bundle on the server:
+
+### Server Load Function
+
+```typescript
+// src/routes/+layout.server.ts
+import { loadTrafficalBundle } from '@traffical/svelte/sveltekit';
+import { TRAFFICAL_API_KEY } from '$env/static/private';
+
+export async function load({ fetch }) {
+  const { bundle, error } = await loadTrafficalBundle({
+    orgId: 'org_123',
+    projectId: 'proj_456',
+    env: 'production',
+    apiKey: TRAFFICAL_API_KEY,
+    fetch,
+  });
+
+  if (error) {
+    console.warn('[Traffical] Failed to load config:', error);
+  }
+
+  return {
+    traffical: { bundle },
+  };
+}
+```
+
+### Pre-resolve Parameters (Optional)
+
+For pages where you need resolved values during SSR:
+
+```typescript
+// src/routes/checkout/+page.server.ts
+import { loadTrafficalBundle, resolveParamsSSR } from '@traffical/svelte/sveltekit';
+import { TRAFFICAL_API_KEY } from '$env/static/private';
+
+export async function load({ fetch, cookies }) {
+  const { bundle } = await loadTrafficalBundle({
+    orgId: 'org_123',
+    projectId: 'proj_456',
+    env: 'production',
+    apiKey: TRAFFICAL_API_KEY,
+    fetch,
+  });
+
+  // Get user context from cookies/session
+  const userId = cookies.get('userId') || 'anonymous';
+
+  // Pre-resolve params for this page
+  const checkoutParams = resolveParamsSSR(
+    bundle,
+    { userId },
+    {
+      'checkout.ctaText': 'Buy Now',
+      'checkout.ctaColor': '#000000',
+    }
+  );
+
+  return {
+    traffical: { bundle },
+    checkoutParams,
+  };
+}
+```
+
+## API Reference
+
+### Provider
+
+#### `<TrafficalProvider>`
+
+Wrapper component that initializes Traffical context.
+
+```svelte
+<TrafficalProvider config={...}>
+  <slot />
+</TrafficalProvider>
+```
+
+#### `initTraffical(config)`
+
+Function-based alternative to the Provider component.
+
+```svelte
+<script>
+  import { initTraffical } from '@traffical/svelte';
+
+  initTraffical({
+    orgId: 'org_123',
+    projectId: 'proj_456',
+    env: 'production',
+    apiKey: 'pk_...',
+  });
+</script>
+```
+
+### Hooks
+
+#### `useTraffical(options)`
+
+Primary hook for parameter resolution and decision tracking.
+
+```typescript
+const { params, ready, decision, error, trackExposure, track } = useTraffical({
+  defaults: { 'feature.name': 'default-value' },
+  context: { customField: 'value' }, // Optional
+  tracking: 'full', // 'full' | 'decision' | 'none'
+});
+```
+
+**Tracking Modes:**
+- `'full'` (default) - Track decision + automatic exposure
+- `'decision'` - Track decision only, manual exposure control
+- `'none'` - No tracking (for SSR, tests, or internal logic)
+
+**Return Value:**
+- `params` - Resolved parameter values (reactive)
+- `decision` - Decision metadata (null when `tracking="none"`)
+- `ready` - Whether the client is ready
+- `error` - Any initialization error
+- `trackExposure` - Manually track exposure (no-op when `tracking="none"`)
+- `track` - Track event with bound decisionId (no-op when `tracking="none"`)
+
+#### `useTrafficalTrack()`
+
+Returns a function to track user events.
+
+> **Tip:** For most use cases, use the bound `track` from `useTraffical()` instead. It automatically includes the `decisionId`. Use this standalone hook for advanced scenarios like cross-component event tracking.
+
+```typescript
+// Recommended: use bound track from useTraffical
+const { params, track } = useTraffical({
+  defaults: { 'checkout.ctaText': 'Buy Now' },
+});
+track('purchase', { value: 99.99, orderId: 'ord_123' });
+
+// Advanced: standalone hook when you need to attribute to a specific decision
+const standaloneTrack = useTrafficalTrack();
+standaloneTrack({
+  event: 'purchase',
+  properties: { value: 99.99 },
+  decisionId: someOtherDecision.decisionId,
+});
+```
+
+#### `useTrafficalReward()` (deprecated)
+
+> **Deprecated:** Use `useTrafficalTrack()` instead.
+
+#### `useTrafficalClient()`
+
+Access the underlying Traffical client directly.
+
+```typescript
+const { client, ready, error } = useTrafficalClient();
+
+if (client) {
+  const version = client.getConfigVersion();
+  const stableId = client.getStableId();
+}
+```
+
+#### `useTrafficalPlugin(name)`
+
+Access a registered plugin by name.
+
+```typescript
+import type { DOMBindingPlugin } from '@traffical/js-client';
+
+const domPlugin = useTrafficalPlugin<DOMBindingPlugin>('dom-binding');
+domPlugin?.applyBindings();
+```
+
+### SvelteKit Helpers
+
+#### `loadTrafficalBundle(options)`
+
+Fetch the config bundle in a SvelteKit load function.
+
+```typescript
+import { loadTrafficalBundle } from '@traffical/svelte/sveltekit';
+
+const { bundle, error } = await loadTrafficalBundle({
+  orgId: 'org_123',
+  projectId: 'proj_456',
+  env: 'production',
+  apiKey: 'pk_...',
+  fetch, // SvelteKit's fetch
+});
+```
+
+#### `resolveParamsSSR(bundle, context, defaults)`
+
+Resolve parameters on the server for SSR.
+
+```typescript
+import { resolveParamsSSR } from '@traffical/svelte/sveltekit';
+
+const params = resolveParamsSSR(bundle, { userId: 'user_123' }, {
+  'feature.name': 'default',
+});
+```
+
+## Configuration Options
+
+```typescript
+interface TrafficalProviderConfig {
+  // Required
+  orgId: string;
+  projectId: string;
+  env: string;
+  apiKey: string;
+
+  // Optional - Connection
+  baseUrl?: string;
+  localConfig?: ConfigBundle;
+  refreshIntervalMs?: number; // Default: 60000
+
+  // Optional - Identity
+  unitKeyFn?: () => string;
+  contextFn?: () => Context;
+
+  // Optional - Tracking
+  trackDecisions?: boolean; // Default: true
+  decisionDeduplicationTtlMs?: number; // Default: 1 hour
+  exposureSessionTtlMs?: number; // Default: 30 minutes
+
+  // Optional - Plugins
+  plugins?: TrafficalPlugin[];
+
+  // Optional - Event Batching
+  eventBatchSize?: number; // Default: 10
+  eventFlushIntervalMs?: number; // Default: 30000
+
+  // Optional - SSR
+  initialBundle?: ConfigBundle | null;
+  initialParams?: Record<string, unknown>;
+}
+```
+
+## TypeScript
+
+The SDK is fully typed. Use generics for type-safe parameter access:
+
+```typescript
+interface CheckoutParams {
+  'checkout.ctaText': string;
+  'checkout.ctaColor': string;
+  'checkout.showDiscount': boolean;
+}
+
+const { params } = useTraffical<CheckoutParams>({
+  defaults: {
+    'checkout.ctaText': 'Buy Now',
+    'checkout.ctaColor': '#000000',
+    'checkout.showDiscount': false,
+  },
+});
+
+// params['checkout.ctaText'] is typed as string
+// params['checkout.showDiscount'] is typed as boolean
+```
+
+## Comparison with React SDK
+
+| Feature | React | Svelte |
+|---------|-------|--------|
+| Provider | `<TrafficalProvider>` | `<TrafficalProvider>` |
+| Main hook | `useTraffical()` | `useTraffical()` |
+| Bound event tracking | `track` from `useTraffical()` | `track` from `useTraffical()` |
+| Standalone track hook | `useTrafficalTrack()` | `useTrafficalTrack()` |
+| Client access | `useTrafficalClient()` | `useTrafficalClient()` |
+| Plugin access | `useTrafficalPlugin()` | `useTrafficalPlugin()` |
+| Reactivity | `useState`/`useEffect` | `$state`/`$derived` |
+| SSR | `initialParams` prop | `loadTrafficalBundle()` helper |
+
+## License
+
+MIT
+

package/dist/TrafficalProvider.svelte

@@ -0,0 +1,34 @@
+<!--
+  @traffical/svelte - TrafficalProvider Component
+
+  Wrapper component that initializes the Traffical context.
+  Alternative to calling initTraffical() directly in your layout.
+-->
+<script lang="ts">
+  import type { Snippet } from "svelte";
+  import { initTraffical } from "./context.svelte.js";
+  import type { TrafficalProviderConfig } from "./types.js";
+
+  interface Props {
+    /** Configuration for the Traffical client */
+    config: TrafficalProviderConfig;
+    /** Child content */
+    children: Snippet;
+  }
+
+  let { config, children }: Props = $props();
+
+  // Initialize context - this sets up the client and makes it available to children
+  const context = initTraffical(config);
+
+  // Cleanup on component destroy
+  $effect(() => {
+    return () => {
+      // Destroy client when provider unmounts
+      context.client?.destroy();
+    };
+  });
+</script>
+
+{@render children()}
+

package/dist/TrafficalProvider.svelte.d.ts

@@ -0,0 +1,12 @@
+import type { Snippet } from "svelte";
+import type { TrafficalProviderConfig } from "./types.js";
+interface Props {
+    /** Configuration for the Traffical client */
+    config: TrafficalProviderConfig;
+    /** Child content */
+    children: Snippet;
+}
+declare const TrafficalProvider: import("svelte").Component<Props, {}, "">;
+type TrafficalProvider = ReturnType<typeof TrafficalProvider>;
+export default TrafficalProvider;
+//# sourceMappingURL=TrafficalProvider.svelte.d.ts.map

package/dist/TrafficalProvider.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TrafficalProvider.svelte.d.ts","sourceRoot":"","sources":["../src/TrafficalProvider.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAEtC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAGxD,UAAU,KAAK;IACb,6CAA6C;IAC7C,MAAM,EAAE,uBAAuB,CAAC;IAChC,oBAAoB;IACpB,QAAQ,EAAE,OAAO,CAAC;CACnB;AA2BH,QAAA,MAAM,iBAAiB,2CAAwC,CAAC;AAChE,KAAK,iBAAiB,GAAG,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAC9D,eAAe,iBAAiB,CAAC"}

package/dist/context.svelte.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @traffical/svelte - Context Layer
+ *
+ * SSR-safe context management using Svelte 5 runes and Svelte's context API.
+ * Initializes the TrafficalClient with environment-appropriate providers.
+ */
+import type { TrafficalProviderConfig, TrafficalContextValue } from "./types.js";
+/**
+ * Initializes the Traffical context.
+ * Must be called at the root of your application (e.g., in +layout.svelte).
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { initTraffical } from '@traffical/svelte';
+ *
+ *   let { data, children } = $props();
+ *
+ *   initTraffical({
+ *     orgId: 'org_123',
+ *     projectId: 'proj_456',
+ *     env: 'production',
+ *     apiKey: 'pk_...',
+ *     initialBundle: data.traffical?.bundle,
+ *   });
+ * </script>
+ *
+ * {@render children()}
+ * ```
+ */
+export declare function initTraffical(config: TrafficalProviderConfig): TrafficalContextValue;
+/**
+ * Gets the Traffical context value.
+ * Must be called within a component tree where initTraffical() has been called.
+ *
+ * @throws Error if called outside of Traffical context
+ */
+export declare function getTrafficalContext(): TrafficalContextValue;
+/**
+ * Checks if Traffical context is available.
+ * Useful for conditional rendering or optional Traffical integration.
+ */
+export declare function hasTrafficalContext(): boolean;
+//# sourceMappingURL=context.svelte.d.ts.map

package/dist/context.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.svelte.d.ts","sourceRoot":"","sources":["../src/context.svelte.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAUH,OAAO,KAAK,EACV,uBAAuB,EACvB,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAmJpB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,uBAAuB,GAC9B,qBAAqB,CAIvB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,IAAI,qBAAqB,CAa3D;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAS7C"}

package/dist/context.svelte.js

@@ -0,0 +1,192 @@
+/**
+ * @traffical/svelte - Context Layer
+ *
+ * SSR-safe context management using Svelte 5 runes and Svelte's context API.
+ * Initializes the TrafficalClient with environment-appropriate providers.
+ */
+import { getContext, setContext } from "svelte";
+import { TrafficalClient, createTrafficalClientSync, MemoryStorageProvider, LocalStorageProvider, } from "@traffical/js-client";
+// =============================================================================
+// Constants
+// =============================================================================
+const TRAFFICAL_CONTEXT_KEY = Symbol("traffical");
+// =============================================================================
+// Browser Detection
+// =============================================================================
+/**
+ * Check if we're running in a browser environment.
+ * SSR-safe - returns false during server-side rendering.
+ */
+function isBrowser() {
+    return typeof window !== "undefined" && typeof document !== "undefined";
+}
+// =============================================================================
+// Context State Factory
+// =============================================================================
+/**
+ * Creates the reactive Traffical context state.
+ * Uses $state for reactive properties that work with SSR.
+ */
+function createTrafficalContextState(config) {
+    // Reactive state using Svelte 5 runes
+    let client = $state(null);
+    let ready = $state(!!config.initialBundle); // Ready immediately if we have initial bundle
+    let error = $state(null);
+    let bundle = $state(config.initialBundle ?? null);
+    // Initialize client only in browser
+    if (isBrowser()) {
+        // Use localStorage in browser, memory storage would lose data
+        const storage = new LocalStorageProvider();
+        const clientInstance = createTrafficalClientSync({
+            orgId: config.orgId,
+            projectId: config.projectId,
+            env: config.env,
+            apiKey: config.apiKey,
+            baseUrl: config.baseUrl,
+            localConfig: config.initialBundle ?? config.localConfig,
+            refreshIntervalMs: config.refreshIntervalMs,
+            storage,
+            // Decision tracking options
+            trackDecisions: config.trackDecisions,
+            decisionDeduplicationTtlMs: config.decisionDeduplicationTtlMs,
+            // Exposure options
+            exposureSessionTtlMs: config.exposureSessionTtlMs,
+            // Event batching options
+            eventBatchSize: config.eventBatchSize,
+            eventFlushIntervalMs: config.eventFlushIntervalMs,
+            // Plugins
+            plugins: config.plugins,
+        });
+        client = clientInstance;
+        // Initialize asynchronously (fetches fresh config if needed)
+        clientInstance
+            .initialize()
+            .then(() => {
+            ready = true;
+            // Update bundle if client fetched a newer one
+            const configVersion = clientInstance.getConfigVersion();
+            if (configVersion) {
+                // Bundle is internal, but we track ready state
+            }
+        })
+            .catch((err) => {
+            error = err instanceof Error ? err : new Error(String(err));
+            // Still mark as ready - we'll use defaults/initial bundle
+            ready = true;
+        });
+    }
+    else {
+        // On server, use memory storage and mark as ready if we have initial data
+        // The client won't actually be used for tracking on server
+        if (config.initialBundle) {
+            const storage = new MemoryStorageProvider();
+            const clientInstance = createTrafficalClientSync({
+                orgId: config.orgId,
+                projectId: config.projectId,
+                env: config.env,
+                apiKey: config.apiKey,
+                localConfig: config.initialBundle,
+                storage,
+                // Disable background operations on server
+                refreshIntervalMs: 0,
+            });
+            client = clientInstance;
+            ready = true;
+        }
+    }
+    // Unit key getter - uses config function or client's stable ID
+    function getUnitKey() {
+        if (config.unitKeyFn) {
+            return config.unitKeyFn();
+        }
+        // Fall back to client's auto-generated stable ID
+        return client?.getStableId() ?? "";
+    }
+    // Context getter - merges unit key with additional context
+    function getContext() {
+        const unitKey = getUnitKey();
+        const additionalContext = config.contextFn?.() ?? {};
+        return {
+            ...additionalContext,
+            // Include common unit key field names for compatibility
+            userId: unitKey,
+            deviceId: unitKey,
+            anonymousId: unitKey,
+        };
+    }
+    return {
+        get client() {
+            return client;
+        },
+        get ready() {
+            return ready;
+        },
+        get error() {
+            return error;
+        },
+        get bundle() {
+            return bundle;
+        },
+        getUnitKey,
+        getContext,
+        initialParams: config.initialParams,
+    };
+}
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * Initializes the Traffical context.
+ * Must be called at the root of your application (e.g., in +layout.svelte).
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { initTraffical } from '@traffical/svelte';
+ *
+ *   let { data, children } = $props();
+ *
+ *   initTraffical({
+ *     orgId: 'org_123',
+ *     projectId: 'proj_456',
+ *     env: 'production',
+ *     apiKey: 'pk_...',
+ *     initialBundle: data.traffical?.bundle,
+ *   });
+ * </script>
+ *
+ * {@render children()}
+ * ```
+ */
+export function initTraffical(config) {
+    const contextValue = createTrafficalContextState(config);
+    setContext(TRAFFICAL_CONTEXT_KEY, contextValue);
+    return contextValue;
+}
+/**
+ * Gets the Traffical context value.
+ * Must be called within a component tree where initTraffical() has been called.
+ *
+ * @throws Error if called outside of Traffical context
+ */
+export function getTrafficalContext() {
+    const context = getContext(TRAFFICAL_CONTEXT_KEY);
+    if (!context) {
+        throw new Error("getTrafficalContext() must be called within a component tree where initTraffical() has been called. " +
+            "Make sure to call initTraffical() in your root layout or wrap your app with <TrafficalProvider>.");
+    }
+    return context;
+}
+/**
+ * Checks if Traffical context is available.
+ * Useful for conditional rendering or optional Traffical integration.
+ */
+export function hasTrafficalContext() {
+    try {
+        const context = getContext(TRAFFICAL_CONTEXT_KEY);
+        return context !== undefined;
+    }
+    catch {
+        return false;
+    }
+}