@traffical/svelte 0.1.0

package/src/index.ts

@@ -0,0 +1,144 @@
+/**
+ * @traffical/svelte
+ *
+ * Traffical SDK for Svelte 5 applications.
+ * Provides Provider component and hooks for parameter resolution and decision tracking.
+ *
+ * Features:
+ * - Full SSR/hydration support for SvelteKit
+ * - Svelte 5 runes for reactive, fine-grained updates
+ * - Browser-optimized with sendBeacon, localStorage persistence
+ * - Automatic stable ID for anonymous users
+ * - Plugin system support (DecisionTrackingPlugin enabled by default)
+ * - Decision and exposure deduplication
+ *
+ * @example
+ * ```svelte
+ * <!-- +layout.svelte -->
+ * <script>
+ *   import { TrafficalProvider } from '@traffical/svelte';
+ *
+ *   let { data, children } = $props();
+ * </script>
+ *
+ * <TrafficalProvider
+ *   config={{
+ *     orgId: 'org_123',
+ *     projectId: 'proj_456',
+ *     env: 'production',
+ *     apiKey: 'pk_...',
+ *     initialBundle: data.traffical?.bundle,
+ *   }}
+ * >
+ *   {@render children()}
+ * </TrafficalProvider>
+ * ```
+ *
+ * @example
+ * ```svelte
+ * <!-- MyComponent.svelte -->
+ * <script>
+ *   import { useTraffical } from '@traffical/svelte';
+ *
+ *   const { params, ready } = useTraffical({
+ *     defaults: { 'ui.hero.title': 'Welcome' },
+ *   });
+ * </script>
+ *
+ * {#if ready}
+ *   <h1>{params['ui.hero.title']}</h1>
+ * {:else}
+ *   <h1>Loading...</h1>
+ * {/if}
+ * ```
+ */
+
+// =============================================================================
+// Re-export from @traffical/core
+// =============================================================================
+
+export {
+  // Resolution functions
+  resolveParameters,
+  decide,
+  evaluateCondition,
+  evaluateConditions,
+  // Hashing utilities
+  fnv1a,
+  computeBucket,
+  isInBucketRange,
+  // ID generation
+  generateEventId,
+  generateDecisionId,
+  generateExposureId,
+  generateRewardId,
+} from "@traffical/core";
+
+// =============================================================================
+// Re-export from @traffical/js-client
+// =============================================================================
+
+export {
+  // Client
+  TrafficalClient,
+  createTrafficalClient,
+  createTrafficalClientSync,
+  // Storage providers
+  LocalStorageProvider,
+  MemoryStorageProvider,
+  createStorageProvider,
+  // Plugins
+  createDOMBindingPlugin,
+} from "@traffical/js-client";
+
+// =============================================================================
+// Svelte-specific exports
+// =============================================================================
+
+// Context
+export {
+  initTraffical,
+  getTrafficalContext,
+  hasTrafficalContext,
+} from "./context.svelte.js";
+
+// Hooks
+export {
+  useTraffical,
+  useTrafficalTrack,
+  useTrafficalReward,
+  useTrafficalClient,
+  useTrafficalPlugin,
+} from "./hooks.svelte.js";
+
+// Provider component
+export { default as TrafficalProvider } from "./TrafficalProvider.svelte";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export type {
+  // Provider config
+  TrafficalProviderConfig,
+  TrafficalContextValue,
+  // Hook types
+  UseTrafficalOptions,
+  UseTrafficalResult,
+  BoundTrackOptions,
+  TrackEventOptions,
+  // Deprecated types (kept for backward compatibility)
+  BoundTrackRewardOptions,
+  TrackRewardOptions,
+  // SvelteKit types
+  LoadTrafficalBundleOptions,
+  LoadTrafficalBundleResult,
+  // Re-exported types
+  ConfigBundle,
+  Context,
+  DecisionResult,
+  ParameterValue,
+  TrafficalClient as TrafficalClientType,
+  TrafficalPlugin,
+} from "./types.js";
+

package/src/sveltekit.test.ts

@@ -0,0 +1,218 @@
+/**
+ * @traffical/svelte - SvelteKit Helpers Tests
+ */
+
+import { describe, test, expect, mock } from "bun:test";
+import { loadTrafficalBundle, resolveParamsSSR } from "./sveltekit.js";
+import type { ConfigBundle } from "@traffical/core";
+
+// =============================================================================
+// Test Fixtures
+// =============================================================================
+
+const mockBundle: ConfigBundle = {
+  version: new Date().toISOString(),
+  orgId: "org_test",
+  projectId: "proj_test",
+  env: "test",
+  hashing: {
+    unitKey: "userId",
+    bucketCount: 10000,
+  },
+  parameters: [
+    {
+      key: "checkout.ctaText",
+      type: "string",
+      default: "Buy Now",
+      layerId: "layer_1",
+      namespace: "checkout",
+    },
+  ],
+  layers: [
+    {
+      id: "layer_1",
+      policies: [],
+    },
+  ],
+  domBindings: [],
+};
+
+// =============================================================================
+// loadTrafficalBundle Tests
+// =============================================================================
+
+describe("loadTrafficalBundle", () => {
+  test("returns bundle on successful fetch", async () => {
+    const mockFetch = mock(() =>
+      Promise.resolve({
+        ok: true,
+        json: () => Promise.resolve(mockBundle),
+      } as Response)
+    ) as unknown as typeof fetch;
+
+    const result = await loadTrafficalBundle({
+      orgId: "org_123",
+      projectId: "proj_456",
+      env: "production",
+      apiKey: "pk_test",
+      fetch: mockFetch,
+    });
+
+    expect(result.bundle).toEqual(mockBundle);
+    expect(result.error).toBeUndefined();
+  });
+
+  test("returns null bundle on HTTP error", async () => {
+    const mockFetch = mock(() =>
+      Promise.resolve({
+        ok: false,
+        status: 404,
+        statusText: "Not Found",
+      } as Response)
+    ) as unknown as typeof fetch;
+
+    const result = await loadTrafficalBundle({
+      orgId: "org_123",
+      projectId: "proj_456",
+      env: "production",
+      apiKey: "pk_test",
+      fetch: mockFetch,
+    });
+
+    expect(result.bundle).toBeNull();
+    expect(result.error).toBe("HTTP 404: Not Found");
+  });
+
+  test("returns null bundle on network error", async () => {
+    const mockFetch = mock(() =>
+      Promise.reject(new Error("Network error"))
+    ) as unknown as typeof fetch;
+
+    const result = await loadTrafficalBundle({
+      orgId: "org_123",
+      projectId: "proj_456",
+      env: "production",
+      apiKey: "pk_test",
+      fetch: mockFetch,
+    });
+
+    expect(result.bundle).toBeNull();
+    expect(result.error).toBe("Network error");
+  });
+
+  test("uses correct URL format", async () => {
+    let capturedUrl = "";
+    const mockFetch = mock((url: string) => {
+      capturedUrl = url;
+      return Promise.resolve({
+        ok: true,
+        json: () => Promise.resolve(mockBundle),
+      } as Response);
+    }) as unknown as typeof fetch;
+
+    await loadTrafficalBundle({
+      orgId: "org_123",
+      projectId: "proj_456",
+      env: "staging",
+      apiKey: "pk_test",
+      fetch: mockFetch,
+    });
+
+    expect(capturedUrl).toBe(
+      "https://sdk.traffical.io/v1/config/proj_456?env=staging"
+    );
+  });
+
+  test("uses custom baseUrl when provided", async () => {
+    let capturedUrl = "";
+    const mockFetch = mock((url: string) => {
+      capturedUrl = url;
+      return Promise.resolve({
+        ok: true,
+        json: () => Promise.resolve(mockBundle),
+      } as Response);
+    }) as unknown as typeof fetch;
+
+    await loadTrafficalBundle({
+      orgId: "org_123",
+      projectId: "proj_456",
+      env: "production",
+      apiKey: "pk_test",
+      fetch: mockFetch,
+      baseUrl: "https://custom.api.com",
+    });
+
+    expect(capturedUrl).toBe(
+      "https://custom.api.com/v1/config/proj_456?env=production"
+    );
+  });
+
+  test("includes authorization header", async () => {
+    let capturedOptions: RequestInit | undefined;
+    const mockFetch = mock((_url: string, options?: RequestInit) => {
+      capturedOptions = options;
+      return Promise.resolve({
+        ok: true,
+        json: () => Promise.resolve(mockBundle),
+      } as Response);
+    }) as unknown as typeof fetch;
+
+    await loadTrafficalBundle({
+      orgId: "org_123",
+      projectId: "proj_456",
+      env: "production",
+      apiKey: "pk_secret_key",
+      fetch: mockFetch,
+    });
+
+    expect(capturedOptions?.headers).toEqual({
+      "Content-Type": "application/json",
+      Authorization: "Bearer pk_secret_key",
+    });
+  });
+});
+
+// =============================================================================
+// resolveParamsSSR Tests
+// =============================================================================
+
+describe("resolveParamsSSR", () => {
+  test("returns defaults when bundle is null", () => {
+    const defaults = {
+      "checkout.ctaText": "Default",
+    };
+
+    const result = resolveParamsSSR(null, { userId: "user_123" }, defaults);
+
+    expect(result).toEqual(defaults);
+  });
+
+  test("resolves parameters from bundle", () => {
+    const defaults = {
+      "checkout.ctaText": "Fallback",
+    };
+
+    const result = resolveParamsSSR(
+      mockBundle,
+      { userId: "user_123" },
+      defaults
+    );
+
+    expect(result["checkout.ctaText"]).toBe("Buy Now");
+  });
+
+  test("uses context for resolution", () => {
+    const defaults = {
+      "checkout.ctaText": "Fallback",
+    };
+
+    // Both should resolve to the same value since we're using defaults
+    const result1 = resolveParamsSSR(mockBundle, { userId: "user_1" }, defaults);
+    const result2 = resolveParamsSSR(mockBundle, { userId: "user_2" }, defaults);
+
+    // Without active policies, results should be the same (bundle defaults)
+    expect(result1["checkout.ctaText"]).toBe("Buy Now");
+    expect(result2["checkout.ctaText"]).toBe("Buy Now");
+  });
+});
+

package/src/sveltekit.ts

@@ -0,0 +1,139 @@
+/**
+ * @traffical/svelte - SvelteKit Helpers
+ *
+ * Server-side utilities for SvelteKit load functions.
+ * Enables SSR with pre-fetched config bundles.
+ */
+
+import { resolveParameters } from "@traffical/core";
+import type { ConfigBundle, Context, ParameterValue } from "@traffical/core";
+import type {
+  LoadTrafficalBundleOptions,
+  LoadTrafficalBundleResult,
+} from "./types.js";
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+const DEFAULT_BASE_URL = "https://sdk.traffical.io";
+
+// =============================================================================
+// Load Functions
+// =============================================================================
+
+/**
+ * Loads the Traffical config bundle in a SvelteKit load function.
+ *
+ * Call this in your +layout.server.ts or +page.server.ts to fetch the config
+ * bundle on the server, enabling SSR without FOOC (Flash of Original Content).
+ *
+ * @example
+ * ```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 } = await loadTrafficalBundle({
+ *     orgId: 'org_123',
+ *     projectId: 'proj_456',
+ *     env: 'production',
+ *     apiKey: TRAFFICAL_API_KEY,
+ *     fetch,
+ *   });
+ *
+ *   return {
+ *     traffical: { bundle },
+ *   };
+ * }
+ * ```
+ */
+export async function loadTrafficalBundle(
+  options: LoadTrafficalBundleOptions
+): Promise<LoadTrafficalBundleResult> {
+  const baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+  const url = `${baseUrl}/v1/config/${options.projectId}?env=${options.env}`;
+
+  try {
+    const response = await options.fetch(url, {
+      method: "GET",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${options.apiKey}`,
+      },
+    });
+
+    if (!response.ok) {
+      return {
+        bundle: null,
+        error: `HTTP ${response.status}: ${response.statusText}`,
+      };
+    }
+
+    const bundle = (await response.json()) as ConfigBundle;
+    return { bundle };
+  } catch (err) {
+    return {
+      bundle: null,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+// =============================================================================
+// SSR Resolution
+// =============================================================================
+
+/**
+ * Resolves parameters on the server for SSR.
+ *
+ * Use this to pre-resolve specific parameters in your load function,
+ * enabling server-side rendering with the correct values.
+ *
+ * @example
+ * ```typescript
+ * // src/routes/checkout/+page.server.ts
+ * import { loadTrafficalBundle, resolveParamsSSR } from '@traffical/svelte/sveltekit';
+ *
+ * export async function load({ fetch, cookies }) {
+ *   const { bundle } = await loadTrafficalBundle({ ... });
+ *
+ *   // Get user context from cookies/session
+ *   const userId = cookies.get('userId');
+ *
+ *   // Pre-resolve params for this page
+ *   const checkoutParams = resolveParamsSSR(
+ *     bundle,
+ *     { userId },
+ *     {
+ *       'checkout.ctaText': 'Buy Now',
+ *       'checkout.ctaColor': '#000',
+ *     }
+ *   );
+ *
+ *   return {
+ *     traffical: { bundle },
+ *     checkoutParams,
+ *   };
+ * }
+ * ```
+ */
+export function resolveParamsSSR<T extends Record<string, ParameterValue>>(
+  bundle: ConfigBundle | null,
+  context: Context,
+  defaults: T
+): T {
+  if (!bundle) {
+    return defaults;
+  }
+
+  return resolveParameters(bundle, context, defaults);
+}
+
+// =============================================================================
+// Types Re-export
+// =============================================================================
+
+export type { LoadTrafficalBundleOptions, LoadTrafficalBundleResult };
+