@traffical/svelte 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,206 @@
+/**
+ * @traffical/svelte - Type Definitions
+ *
+ * TypeScript types for the Svelte 5 SDK.
+ */
+import type { TrafficalClient, TrafficalPlugin } from "@traffical/js-client";
+import type { ConfigBundle, Context, DecisionResult, ParameterValue } from "@traffical/core";
+/**
+ * Configuration for the TrafficalProvider component.
+ */
+export interface TrafficalProviderConfig {
+    /** Organization ID */
+    orgId: string;
+    /** Project ID */
+    projectId: string;
+    /** Environment (e.g., "production", "staging") */
+    env: string;
+    /** API key for authentication */
+    apiKey: string;
+    /** Base URL for the SDK API (edge worker) */
+    baseUrl?: string;
+    /** Local config bundle for offline fallback */
+    localConfig?: ConfigBundle;
+    /** Refresh interval in milliseconds (default: 60000) */
+    refreshIntervalMs?: number;
+    /**
+     * Function to get the unit key value.
+     * If not provided, the SDK will use automatic stable ID generation.
+     */
+    unitKeyFn?: () => string;
+    /** Function to get additional context (optional) */
+    contextFn?: () => Context;
+    /**
+     * Whether to automatically track decision events (default: true).
+     * When enabled, every call to decide() automatically sends a DecisionEvent
+     * to the control plane, enabling intent-to-treat analysis.
+     */
+    trackDecisions?: boolean;
+    /**
+     * Decision deduplication TTL in milliseconds (default: 1 hour).
+     * Same user+assignment combination won't be tracked again within this window.
+     */
+    decisionDeduplicationTtlMs?: number;
+    /**
+     * Exposure deduplication session TTL in milliseconds (default: 30 minutes).
+     * Same user seeing same variant won't trigger multiple exposure events.
+     */
+    exposureSessionTtlMs?: number;
+    /**
+     * Plugins to register with the client.
+     * The DecisionTrackingPlugin is included by default unless trackDecisions is false.
+     */
+    plugins?: TrafficalPlugin[];
+    /** Max events before auto-flush (default: 10) */
+    eventBatchSize?: number;
+    /** Auto-flush interval in ms (default: 30000) */
+    eventFlushIntervalMs?: number;
+    /**
+     * Pre-fetched config bundle from server-side load function.
+     * When provided, the SDK is immediately ready without fetching.
+     */
+    initialBundle?: ConfigBundle | null;
+    /**
+     * Pre-resolved params from SSR for immediate hydration.
+     * Used to prevent FOOC (Flash of Original Content).
+     */
+    initialParams?: Record<string, unknown>;
+}
+/**
+ * Internal context value shared via Svelte's setContext/getContext.
+ */
+export interface TrafficalContextValue {
+    /** The Traffical client instance (null during SSR) */
+    readonly client: TrafficalClient | null;
+    /** Whether the client is ready (config loaded) */
+    readonly ready: boolean;
+    /** Any initialization error */
+    readonly error: Error | null;
+    /** The current config bundle */
+    readonly bundle: ConfigBundle | null;
+    /** Function to get the unit key */
+    getUnitKey: () => string;
+    /** Function to get the full context */
+    getContext: () => Context;
+    /** Initial params from SSR for hydration */
+    initialParams?: Record<string, unknown>;
+}
+/**
+ * Options for the useTraffical hook.
+ */
+export interface UseTrafficalOptions<T extends Record<string, ParameterValue> = Record<string, ParameterValue>> {
+    /** Default parameter values (required for type inference) */
+    defaults: T;
+    /** Additional context to merge (optional) */
+    context?: Context;
+    /**
+     * Tracking mode (default: "full")
+     * - "full": Track decision + exposure (default, recommended for UI)
+     * - "decision": Track decision only, manual exposure control
+     * - "none": No tracking (SSR, internal logic, tests)
+     */
+    tracking?: "full" | "decision" | "none";
+}
+/**
+ * Options for the bound track function returned by useTraffical.
+ */
+export interface BoundTrackOptions {
+    /** Additional event properties */
+    properties?: Record<string, unknown>;
+}
+/**
+ * @deprecated Use BoundTrackOptions instead.
+ * Options for the bound trackReward function returned by useTraffical.
+ */
+export interface BoundTrackRewardOptions {
+    /** The reward value (e.g., revenue amount, conversion count) */
+    reward: number;
+    /** Type of reward (e.g., "revenue", "conversion", "engagement") */
+    rewardType?: string;
+    /** Multiple reward values keyed by type */
+    rewards?: Record<string, number>;
+}
+/**
+ * Return value from the useTraffical hook.
+ * All properties are reactive via Svelte 5 runes.
+ */
+export interface UseTrafficalResult<T extends Record<string, ParameterValue> = Record<string, ParameterValue>> {
+    /** Resolved parameter values (reactive) */
+    readonly params: T;
+    /** The full decision result (null when tracking="none") */
+    readonly decision: DecisionResult | null;
+    /** Whether the client is ready (config loaded) */
+    readonly ready: boolean;
+    /** Any error that occurred */
+    readonly error: Error | null;
+    /** Function to manually track exposure (no-op when tracking="none") */
+    trackExposure: () => void;
+    /**
+     * Track a user event. The decisionId is automatically bound.
+     * No-op if tracking="none" or no decision is available.
+     *
+     * @example
+     * track('purchase', { value: 99.99, orderId: 'ord_123' });
+     * track('add_to_cart', { itemId: 'sku_456' });
+     */
+    track: (event: string, properties?: Record<string, unknown>) => void;
+    /**
+     * @deprecated Use track() instead.
+     * Track a reward for this decision. The decisionId is automatically bound.
+     * No-op if tracking="none" or no decision is available.
+     */
+    trackReward: (options: BoundTrackRewardOptions) => void;
+}
+/**
+ * Options for tracking an event with the standalone hook.
+ */
+export interface TrackEventOptions {
+    /** Event name (e.g., 'purchase', 'add_to_cart') */
+    event: string;
+    /** Additional event properties */
+    properties?: Record<string, unknown>;
+    /** Reference to the decision (optional, for attribution) */
+    decisionId?: string;
+}
+/**
+ * @deprecated Use TrackEventOptions instead.
+ * Options for tracking a reward.
+ */
+export interface TrackRewardOptions {
+    /** Reference to the decision (optional, will use last decision if not provided) */
+    decisionId?: string;
+    /** The reward value (e.g., revenue amount, conversion count) */
+    reward: number;
+    /** Type of reward (e.g., "revenue", "conversion", "engagement") */
+    rewardType?: string;
+    /** Multiple reward values keyed by type */
+    rewards?: Record<string, number>;
+}
+/**
+ * Options for loading the Traffical config bundle in a SvelteKit load function.
+ */
+export interface LoadTrafficalBundleOptions {
+    /** Organization ID */
+    orgId: string;
+    /** Project ID */
+    projectId: string;
+    /** Environment (e.g., "production", "staging") */
+    env: string;
+    /** API key for authentication */
+    apiKey: string;
+    /** SvelteKit's fetch function (from load context) */
+    fetch: typeof globalThis.fetch;
+    /** Base URL for the SDK API (optional, defaults to https://sdk.traffical.io) */
+    baseUrl?: string;
+}
+/**
+ * Result from loading the Traffical config bundle.
+ */
+export interface LoadTrafficalBundleResult {
+    /** The fetched config bundle, or null if fetch failed */
+    bundle: ConfigBundle | null;
+    /** Error message if fetch failed */
+    error?: string;
+}
+export type { ConfigBundle, Context, DecisionResult, ParameterValue, TrafficalClient, TrafficalPlugin, };
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,6 @@
+/**
+ * @traffical/svelte - Type Definitions
+ *
+ * TypeScript types for the Svelte 5 SDK.
+ */
+export {};

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@traffical/svelte",
+  "version": "0.1.0",
+  "description": "Traffical SDK for Svelte 5 - Provider and hooks for parameter resolution with SSR support",
+  "type": "module",
+  "svelte": "./src/index.ts",
+  "main": "./src/index.ts",
+  "module": "./src/index.ts",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "svelte": "./src/index.ts",
+      "bun": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./sveltekit": {
+      "types": "./dist/sveltekit.d.ts",
+      "bun": "./src/sveltekit.ts",
+      "import": "./src/sveltekit.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "svelte-package --input src",
+    "dev": "svelte-package --input src --watch",
+    "test": "bun test",
+    "typecheck": "svelte-check --tsconfig ./tsconfig.json"
+  },
+  "dependencies": {
+    "@traffical/core": "workspace:^",
+    "@traffical/js-client": "workspace:^"
+  },
+  "devDependencies": {
+    "@sveltejs/package": "^2.3.0",
+    "@types/bun": "latest",
+    "svelte": "^5.46.4",
+    "svelte-check": "^4.0.0",
+    "typescript": "^5.3.0"
+  },
+  "peerDependencies": {
+    "svelte": "^5.0.0"
+  },
+  "keywords": [
+    "traffical",
+    "feature-flags",
+    "experimentation",
+    "a/b-testing",
+    "svelte",
+    "svelte5",
+    "sveltekit",
+    "runes",
+    "ssr"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/traffical/js-sdk"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}
+

package/src/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/src/context.svelte.ts

@@ -0,0 +1,232 @@
+/**
+ * @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";
+import type { Context as TrafficalContext } from "@traffical/core";
+import type {
+  TrafficalProviderConfig,
+  TrafficalContextValue,
+} from "./types.js";
+
+// =============================================================================
+// 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(): boolean {
+  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: TrafficalProviderConfig
+): TrafficalContextValue {
+  // Reactive state using Svelte 5 runes
+  let client = $state<TrafficalClient | null>(null);
+  let ready = $state(!!config.initialBundle); // Ready immediately if we have initial bundle
+  let error = $state<Error | null>(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(): string {
+    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(): TrafficalContext {
+    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: TrafficalProviderConfig
+): TrafficalContextValue {
+  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(): TrafficalContextValue {
+  const context = getContext<TrafficalContextValue | undefined>(
+    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(): boolean {
+  try {
+    const context = getContext<TrafficalContextValue | undefined>(
+      TRAFFICAL_CONTEXT_KEY
+    );
+    return context !== undefined;
+  } catch {
+    return false;
+  }
+}
+