@coframe/sdk 1.1.0 → 1.1.1

package/README.md

@@ -0,0 +1,218 @@
+# @coframe/sdk
+
+Bring your UX to life with AI-powered optimization and personalization.
+
+[![npm](https://img.shields.io/npm/v/@coframe/sdk.svg)](https://www.npmjs.com/package/@coframe/sdk)
+
+Coframe helps you personalize and optimize your site with experiments, targeting, anti-flicker rendering, analytics callbacks, and conversion tracking.
+
+This package exposes three entry points:
+
+- `@coframe/sdk` for the browser runtime
+- `@coframe/sdk/server` for SSR and edge prefetching
+- `@coframe/sdk/react` for React apps
+
+## Install
+
+```sh
+npm install @coframe/sdk
+```
+
+If you use the React entry point, install React as well:
+
+```sh
+npm install react@">=17"
+```
+
+## Quick start
+
+### Browser
+
+```ts
+import { init } from '@coframe/sdk'
+
+await init({
+  config: {
+    projectId: 'your-project-id',
+  },
+})
+```
+
+`init()` accepts `config` and optional `projectData`, so npm consumers do not need to manually populate `window.CFQ` first.
+
+### React
+
+```tsx
+import { CoframeProvider } from '@coframe/sdk/react'
+import type { CoframeConfig } from '@coframe/sdk'
+
+const projectConfig: CoframeConfig = {
+  projectId: 'your-project-id',
+}
+
+export default function App({ children }) {
+  return (
+    <CoframeProvider projectConfig={projectConfig}>
+      {children}
+    </CoframeProvider>
+  )
+}
+```
+
+Mount the provider once at the root of your app. It initializes the SDK on mount and keeps treatment state available to child components.
+
+### Server prefetch
+
+```ts
+import { getProjectData } from '@coframe/sdk/server'
+
+const serverData = await getProjectData({
+  projectId: 'your-project-id',
+  currentUrl: request.url,
+  headers: request.headers,
+})
+
+const projectData = serverData?.project
+  ? {
+      project: serverData.project,
+      personalizationHeaders: serverData.personalizationHeaders,
+    }
+  : undefined
+```
+
+Pass `projectData` into `<CoframeProvider>` to avoid the extra client-side project fetch and personalize on first paint.
+
+## Common React usage
+
+### Read variants in components
+
+```tsx
+'use client'
+
+import { useCoframeVariant } from '@coframe/sdk/react'
+
+export function CheckoutPage() {
+  const variant = useCoframeVariant('checkout_flow_v2')
+
+  if (variant === undefined) return <CheckoutSkeleton />
+  if (variant === 'treatment') return <NewCheckout />
+  return <OldCheckout />
+}
+```
+
+Other hooks:
+
+- `useCoframeTreatments()` returns all treatments or `null` while init is in flight
+- `useCoframeTreatment(experimentId)` returns one treatment payload
+
+### Track conversions
+
+```tsx
+'use client'
+
+import { trackConversion } from '@coframe/sdk'
+
+export function CheckoutButton() {
+  return (
+    <button
+      onClick={() =>
+        trackConversion({
+          metricName: 'checkout_complete',
+          value: 99.95,
+        })
+      }
+    >
+      Complete checkout
+    </button>
+  )
+}
+```
+
+### Analytics and log callbacks
+
+```tsx
+import { CoframeProvider } from '@coframe/sdk/react'
+
+<CoframeProvider
+  projectConfig={projectConfig}
+  onTreatmentAppliedBulkV2={(data) => {
+    for (const treatment of data) {
+      analytics.track('Experiment Viewed', treatment)
+    }
+  }}
+  onLog={(payload) => {
+    console.error('[coframe]', payload.monitoring_type, payload)
+  }}
+>
+  {children}
+</CoframeProvider>
+```
+
+Outside React, you can also register callbacks from the main entry:
+
+```ts
+import { onLog, onTreatmentApplied } from '@coframe/sdk'
+```
+
+## Next.js / Remix / SSR notes
+
+- `getProjectData()` is intended for SSR and edge runtimes that can provide a full request URL and request headers.
+- In Pages Router or Remix, per-request server loaders are the most straightforward place to call it.
+- In App Router, keep the provider mounted in a persistent shell, but be careful about request URL handling in `layout.tsx` if you need query-sensitive SSR targeting.
+
+## Package layout
+
+The published tarball contains only `dist/pkg/`:
+
+```text
+dist/pkg/
+├── cf.esm.mjs        cf.cjs.js        types/index.d.ts    ← @coframe/sdk
+├── server.esm.mjs    server.cjs.js    types/server.d.ts   ← @coframe/sdk/server
+└── react.esm.mjs     react.cjs.js     types/react.d.ts    ← @coframe/sdk/react
+```
+
+## TypeScript compatibility
+
+The package publishes typed subpath exports for:
+
+- `@coframe/sdk`
+- `@coframe/sdk/server`
+- `@coframe/sdk/react`
+
+If your app uses an older TypeScript module resolution mode, prefer moving to one of:
+
+- `moduleResolution: "bundler"`
+- `moduleResolution: "node16"`
+- `moduleResolution: "nodenext"`
+
+Modern resolution modes handle package subpath exports more reliably.
+
+## API overview
+
+### `@coframe/sdk`
+
+- `init(options)`
+- `trackConversion(payload)`
+- `setConsent(enabled)`
+- `setUserToken(token)`
+- `setFeatureFlag(enabled)`
+- `setPageHydrated()`
+- `onTreatmentApplied(...)`
+- `onLog(...)`
+
+### `@coframe/sdk/server`
+
+- `getProjectData(options)`
+
+Returns a payload that may include:
+
+- `project`
+- `personalizationHeaders`
+- `antiflickerCSS`
+
+### `@coframe/sdk/react`
+
+- `CoframeProvider`
+- `useCoframeTreatments()`
+- `useCoframeTreatment(experimentId)`
+- `useCoframeVariant(experimentId)`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coframe/sdk",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Coframe optimizes your website using generative AI to deliver maximum impact to your audience and allow your site to improve itself as you sleep. Learn more at coframe.com.",
   "main": "dist/pkg/cf.cjs.js",
   "module": "dist/pkg/cf.esm.mjs",