{"_id":"@afzal-plenteous/homebase-sdk","_rev":"5-82d62333229e1869b95d92d3489fdeb8","name":"@afzal-plenteous/homebase-sdk","dist-tags":{"latest":"4.2.1"},"versions":{"2.0.0":{"name":"@afzal-plenteous/homebase-sdk","version":"2.0.0","keywords":["homebase","plenteous","authentication","supabase","react","sso"],"license":"MIT","_id":"@afzal-plenteous/homebase-sdk@2.0.0","maintainers":[{"name":"afzal-plenteous","email":"afzal@plenteous.com"}],"homepage":"https://github.com/plenteous/homebase-sdk#readme","bugs":{"url":"https://github.com/plenteous/homebase-sdk/issues"},"dist":{"shasum":"19f85eb187515fdb736a11fe91251a9b08d27393","tarball":"https://registry.npmjs.org/@afzal-plenteous/homebase-sdk/-/homebase-sdk-2.0.0.tgz","fileCount":10,"integrity":"sha512-SMymmtmZaS7vkd8UjWOkvO2Mat9r4cEB4kDHh61ZNrf/QjB2EGOU/HkosE80c2WjH5iqSWTNwug6fkLWKWvavQ==","signatures":[{"sig":"MEUCIFV5fRcWHnsKwPT4149px/iMVBaBHEBm/Ea2J91piX3nAiEA3puGLcymffpfBqnHEU/zDg9rERJ3ApXctA3e/g++3c0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":151161},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","browser":"./dist/index.js","default":"./dist/index.js"},"./server":{"types":"./dist/server.d.ts","import":"./dist/server.js","browser":null,"default":"./dist/server.js"},"./package.json":"./package.json"},"scripts":{"dev":"tsup --watch","lint":"eslint \"src/**/*.{ts,tsx}\" \"tests/**/*.{ts,tsx}\"","test":"vitest run","build":"tsup","format":"prettier --write .","lint:fix":"eslint \"src/**/*.{ts,tsx}\" \"tests/**/*.{ts,tsx}\" --fix","typecheck":"tsc --noEmit","test:watch":"vitest","format:check":"prettier --check .","prepublishOnly":"npm run typecheck && npm run lint && npm run test && npm run build"},"_npmUser":{"name":"afzal-plenteous","email":"afzal@plenteous.com"},"repository":{"url":"git+https://github.com/plenteous/homebase-sdk.git","type":"git"},"_npmVersion":"10.9.3","description":"Homebase authentication SDK for Plenteous applications","directories":{},"sideEffects":false,"_nodeVersion":"22.19.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.4.0","jsdom":"^26.0.0","react":"^19.0.0","eslint":"^8.57.1","vitest":"^3.0.8","prettier":"^3.5.3","react-dom":"^19.0.0","typescript":"^5.8.2","@types/node":"^22.13.10","@types/react":"^19.0.10","@types/react-dom":"^19.0.4","eslint-plugin-react":"^7.37.4","@vitejs/plugin-react":"^4.3.4","@supabase/supabase-js":"^2.49.1","@testing-library/react":"^16.2.0","eslint-config-prettier":"^10.1.1","@testing-library/jest-dom":"^6.6.3","@typescript-eslint/parser":"^8.26.1","eslint-plugin-react-hooks":"^5.2.0","@typescript-eslint/eslint-plugin":"^8.26.1"},"peerDependencies":{"react":">=18 <20","react-dom":">=18 <20","@supabase/supabase-js":">=2.45 <3"},"_npmOperationalInternal":{"tmp":"tmp/homebase-sdk_2.0.0_1783593316175_0.7662287296569055","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"4.0.0":{"name":"@afzal-plenteous/homebase-sdk","version":"4.0.0","keywords":["homebase","plenteous","authorization","sso","react"],"license":"MIT","_id":"@afzal-plenteous/homebase-sdk@4.0.0","maintainers":[{"name":"afzal-plenteous","email":"afzal@plenteous.com"}],"homepage":"https://github.com/plenteous/homebase-sdk#readme","bugs":{"url":"https://github.com/plenteous/homebase-sdk/issues"},"dist":{"shasum":"16f859a30fedf0e7fcbd048a89915da7487f8c5e","tarball":"https://registry.npmjs.org/@afzal-plenteous/homebase-sdk/-/homebase-sdk-4.0.0.tgz","fileCount":14,"integrity":"sha512-N8cm+ulRp3ZgVwOvnSLD/rPzh3iMwvonmHeYD3RRL68gcXcNWy9gIavZrzcy0duL+9/tei/urW+bZ6a7WMrBqg==","signatures":[{"sig":"MEQCIG0yJUa5zzmKvw2OYtu6xw4PHgRxiF1SWRC30AILt8f6AiA/5ugH3FfeSDZ9xOlgjVTMOvoaX4BcrQhMfDCJnmOVgg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":164355},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","browser":"./dist/index.js","default":"./dist/index.js"},"./server":{"types":"./dist/server.d.ts","import":"./dist/server.js","browser":null,"default":"./dist/server.js"},"./package.json":"./package.json"},"scripts":{"dev":"tsup --watch","lint":"eslint \"src/**/*.{ts,tsx}\" \"tests/**/*.{ts,tsx}\"","test":"vitest run","build":"tsup","format":"prettier --write .","lint:fix":"eslint \"src/**/*.{ts,tsx}\" \"tests/**/*.{ts,tsx}\" --fix","typecheck":"tsc --noEmit","test:watch":"vitest","format:check":"prettier --check .","prepublishOnly":"npm run typecheck && npm run lint && npm run test && npm run build"},"_npmUser":{"name":"afzal-plenteous","email":"afzal@plenteous.com"},"repository":{"url":"git+https://github.com/plenteous/homebase-sdk.git","type":"git"},"_npmVersion":"10.9.3","description":"Homebase identity and authorization SDK for Plenteous applications (host-auth architecture)","directories":{},"sideEffects":false,"_nodeVersion":"22.19.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.4.0","jsdom":"^26.0.0","react":"^19.0.0","eslint":"^8.57.1","vitest":"^3.0.8","prettier":"^3.5.3","react-dom":"^19.0.0","typescript":"^5.8.2","@types/node":"^22.13.10","@types/react":"^19.0.10","@types/react-dom":"^19.0.4","eslint-plugin-react":"^7.37.4","@vitejs/plugin-react":"^4.3.4","@supabase/supabase-js":"^2.49.1","@testing-library/react":"^16.2.0","eslint-config-prettier":"^10.1.1","@testing-library/jest-dom":"^6.6.3","@typescript-eslint/parser":"^8.26.1","eslint-plugin-react-hooks":"^5.2.0","@typescript-eslint/eslint-plugin":"^8.26.1"},"peerDependencies":{"react":">=18 <20","react-dom":">=18 <20"},"peerDependenciesMeta":{"@supabase/supabase-js":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/homebase-sdk_4.0.0_1783600650261_0.5552499516297182","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"4.1.1":{"name":"@afzal-plenteous/homebase-sdk","version":"4.1.1","keywords":["homebase","plenteous","authorization","sso","feedback","react"],"license":"MIT","_id":"@afzal-plenteous/homebase-sdk@4.1.1","maintainers":[{"name":"afzal-plenteous","email":"afzal@plenteous.com"}],"homepage":"https://github.com/plenteous/homebase-sdk#readme","bugs":{"url":"https://github.com/plenteous/homebase-sdk/issues"},"dist":{"shasum":"4e9a3726b34df3a64aecaac763762f394bc4d0fc","tarball":"https://registry.npmjs.org/@afzal-plenteous/homebase-sdk/-/homebase-sdk-4.1.1.tgz","fileCount":14,"integrity":"sha512-UhQyCojGkBP45LHEV8+tqy7aobH825maEbptqbEyQwMYQOEKkAUHqyOVQudkZ6UviKjTRlHFihLP1O94sbIvGg==","signatures":[{"sig":"MEUCIQCKAGLvz+sPXd36vP1vvGNDjcI23uqNdVT+T0VpTum8agIgQWpL73s4PFm3Cg5+bELcZMjR7t0eK+E01y2K+aupY/I=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":308837},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","browser":"./dist/index.js","default":"./dist/index.js"},"./server":{"types":"./dist/server.d.ts","import":"./dist/server.js","browser":null,"default":"./dist/server.js"},"./package.json":"./package.json"},"scripts":{"dev":"tsup --watch","lint":"eslint \"src/**/*.{ts,tsx}\" \"tests/**/*.{ts,tsx}\"","test":"vitest run","build":"tsup","format":"prettier --write .","lint:fix":"eslint \"src/**/*.{ts,tsx}\" \"tests/**/*.{ts,tsx}\" --fix","typecheck":"tsc --noEmit","test:watch":"vitest","format:check":"prettier --check .","prepublishOnly":"npm run typecheck && npm run lint && npm run test && npm run build"},"_npmUser":{"name":"afzal-plenteous","email":"afzal@plenteous.com"},"repository":{"url":"git+https://github.com/plenteous/homebase-sdk.git","type":"git"},"_npmVersion":"10.9.3","description":"Homebase identity, authorization, and feedback SDK for Plenteous applications (host-auth architecture)","directories":{},"sideEffects":false,"_nodeVersion":"22.19.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.4.0","jsdom":"^26.0.0","react":"^19.0.0","eslint":"^8.57.1","vitest":"^3.0.8","prettier":"^3.5.3","react-dom":"^19.0.0","typescript":"^5.8.2","@types/node":"^22.13.10","@types/react":"^19.0.10","html-to-image":"^1.11.13","@types/react-dom":"^19.0.4","eslint-plugin-react":"^7.37.4","@vitejs/plugin-react":"^4.3.4","@supabase/supabase-js":"^2.49.1","@testing-library/react":"^16.2.0","eslint-config-prettier":"^10.1.1","@testing-library/jest-dom":"^6.6.3","@typescript-eslint/parser":"^8.26.1","eslint-plugin-react-hooks":"^5.2.0","@testing-library/user-event":"^14.6.1","@typescript-eslint/eslint-plugin":"^8.26.1"},"peerDependencies":{"react":">=18 <20","react-dom":">=18 <20","html-to-image":">=1.11.0"},"peerDependenciesMeta":{"html-to-image":{"optional":true},"@supabase/supabase-js":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/homebase-sdk_4.1.1_1783605331800_0.16558832117737987","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"4.2.1":{"name":"@afzal-plenteous/homebase-sdk","version":"4.2.1","keywords":["homebase","plenteous","authorization","sso","feedback","react"],"license":"MIT","_id":"@afzal-plenteous/homebase-sdk@4.2.1","maintainers":[{"name":"afzal-plenteous","email":"afzal@plenteous.com"}],"homepage":"https://github.com/plenteous/homebase-sdk#readme","bugs":{"url":"https://github.com/plenteous/homebase-sdk/issues"},"dist":{"shasum":"d229f88f8dceaac1239cb6aa0965b29dbe82edee","tarball":"https://registry.npmjs.org/@afzal-plenteous/homebase-sdk/-/homebase-sdk-4.2.1.tgz","fileCount":14,"integrity":"sha512-HWJ7tgjehctTpphaEfoMmjd4wQoPAXmMYw3syS3JAItFNEwHc47e6jBkyPa99bzJDFe/f1NCHDujs97Zr03fVw==","signatures":[{"sig":"MEYCIQD8YIuG1iW2JOkM17PFU3acIUVN+Vz3WOJ6KeBTwDFfvwIhAJSY4rUOTQA1C/IvP8ImuDaJ5SCbqlZG9J8d7pr2AOBp","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":337922},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","browser":"./dist/index.js","default":"./dist/index.js"},"./server":{"types":"./dist/server.d.ts","import":"./dist/server.js","browser":null,"default":"./dist/server.js"},"./package.json":"./package.json"},"scripts":{"dev":"tsup --watch","lint":"eslint \"src/**/*.{ts,tsx}\" \"tests/**/*.{ts,tsx}\"","test":"vitest run","build":"tsup","format":"prettier --write .","lint:fix":"eslint \"src/**/*.{ts,tsx}\" \"tests/**/*.{ts,tsx}\" --fix","typecheck":"tsc --noEmit","test:watch":"vitest","format:check":"prettier --check .","prepublishOnly":"npm run typecheck && npm run lint && npm run test && npm run build"},"_npmUser":{"name":"afzal-plenteous","email":"afzal@plenteous.com"},"repository":{"url":"git+https://github.com/plenteous/homebase-sdk.git","type":"git"},"_npmVersion":"10.9.3","description":"Homebase identity, authorization, and feedback SDK for Plenteous applications (host-auth architecture)","directories":{},"sideEffects":false,"_nodeVersion":"22.19.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.4.0","jsdom":"^26.0.0","react":"^19.0.0","eslint":"^8.57.1","vitest":"^3.0.8","prettier":"^3.5.3","react-dom":"^19.0.0","typescript":"^5.8.2","@types/node":"^22.13.10","@types/react":"^19.0.10","html-to-image":"^1.11.13","@types/react-dom":"^19.0.4","eslint-plugin-react":"^7.37.4","@vitejs/plugin-react":"^4.3.4","@supabase/supabase-js":"^2.49.1","@testing-library/react":"^16.2.0","eslint-config-prettier":"^10.1.1","@testing-library/jest-dom":"^6.6.3","@typescript-eslint/parser":"^8.26.1","eslint-plugin-react-hooks":"^5.2.0","@testing-library/user-event":"^14.6.1","@typescript-eslint/eslint-plugin":"^8.26.1"},"peerDependencies":{"react":">=18 <20","react-dom":">=18 <20","html-to-image":">=1.11.0"},"peerDependenciesMeta":{"html-to-image":{"optional":true},"@supabase/supabase-js":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/homebase-sdk_4.2.1_1783610239937_0.4043496834460585","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."}},"time":{"created":"2026-07-09T10:35:15.985Z","modified":"2026-07-14T10:59:34.272Z","2.0.0":"2026-07-09T10:35:16.328Z","4.0.0":"2026-07-09T12:37:30.396Z","4.1.1":"2026-07-09T13:55:31.943Z","4.2.1":"2026-07-09T15:17:20.076Z"},"bugs":{"url":"https://github.com/plenteous/homebase-sdk/issues"},"license":"MIT","homepage":"https://github.com/plenteous/homebase-sdk#readme","keywords":["homebase","plenteous","authorization","sso","feedback","react"],"repository":{"url":"git+https://github.com/plenteous/homebase-sdk.git","type":"git"},"description":"Homebase identity, authorization, and feedback SDK for Plenteous applications (host-auth architecture)","maintainers":[{"name":"afzal-plenteous","email":"afzal@plenteous.com"}],"readme":"# @afzal-plenteous/homebase-sdk\n\nHomebase identity, authorization, and feedback SDK for Plenteous applications (**v4.2 — host-auth + Feedback + auto SDK registration**).\n\nThe host application owns Google OAuth / sessions (Supabase, Lovable, or any IdP).  \nThe SDK begins **after** the host has an authenticated user: validate against Homebase, build context, gate UI, and optionally collect product feedback.\n\n```\nHost App → Google OAuth → Authenticated User → HomebaseProvider → validate-email → useHomebase()\n                                         ├→ (automatic) sdk/register → Launchpad version status\n                                         └→ FeedbackProvider → host /api/feedback/submit → Homebase\n```\n\n## Installation\n\n```bash\nnpm install @afzal-plenteous/homebase-sdk\n# or\nbun add @afzal-plenteous/homebase-sdk\n```\n\n**Peer dependencies:** `react` and `react-dom` (`>=18 <20`).  \nOptional: `html-to-image` (screenshots), `@supabase/supabase-js` (host OAuth only).\n\n## Quick start — Auth\n\n### 1. Server adapter (server-only)\n\n```ts\nimport {\n  createHomebaseServerClient,\n  readHomebaseEnv,\n  validateHomebaseUser,\n} from '@afzal-plenteous/homebase-sdk/server';\n\n// Inside a TanStack / Next / Lovable server handler:\n// Forward the full input so automatic SDK registration can run.\nexport async function validateEmail(input: {\n  email: string;\n  registerSdk?: boolean;\n}) {\n  const env = readHomebaseEnv();\n  return validateHomebaseUser({\n    appSlug: env.appSlug,\n    launchSecret: env.launchSecret,\n    homebaseUrl: env.homebaseUrl,\n    email: input.email,\n    registerSdk: input.registerSdk,\n  });\n}\n```\n\n### 2. Host auth + provider\n\n```tsx\nimport {\n  HomebaseProvider,\n  AuthGuard,\n  AccessDenied,\n  useHomebase,\n} from '@afzal-plenteous/homebase-sdk';\n\n// Host owns OAuth — example with Supabase:\nconst { data: { session } } = await supabase.auth.getSession();\nconst hostUser = session?.user\n  ? {\n      id: session.user.id,\n      email: session.user.email!,\n      full_name: session.user.user_metadata?.full_name ?? null,\n    }\n  : null;\n\nfunction App() {\n  return (\n    <HomebaseProvider\n      user={hostUser}\n      config={{\n        appSlug: 'employee-tasks-demo',\n        validate: (input) => validateEmail(input),\n        onSignOut: () => supabase.auth.signOut({ scope: 'global' }),\n      }}\n    >\n      <AuthGuard\n        denied={(reason) => <AccessDenied reason={reason} />}\n        unauthenticated={() => <LoginPage />}\n      >\n        <Dashboard />\n      </AuthGuard>\n    </HomebaseProvider>\n  );\n}\n\nfunction Dashboard() {\n  const { user, workspaceRole, isAllowed, refresh } = useHomebase();\n  return (\n    <div>\n      <p>{user?.email} ({workspaceRole})</p>\n      <button type=\"button\" onClick={() => void refresh()}>Refresh access</button>\n    </div>\n  );\n}\n```\n\n## Quick start — Feedback\n\nThe SDK owns the floating button, modal, context collection, and screenshot capture.  \n**Homebase** owns storage, admin dashboard, and workflows.  \nThe browser **never** receives `APP_LAUNCH_SECRET`.\n\n### 1. Host proxy route (server-only)\n\n```ts\nimport {\n  createFeedbackServerClient,\n  readHomebaseEnv,\n} from '@afzal-plenteous/homebase-sdk/server';\n\n// POST /api/feedback/submit  (TanStack / Next / Remix — same shape)\nexport async function POST(request: Request) {\n  const env = readHomebaseEnv();\n  const payload = await request.json();\n  const client = createFeedbackServerClient({\n    appSlug: env.appSlug,\n    launchSecret: env.launchSecret,\n    homebaseUrl: env.homebaseUrl,\n  });\n  const result = await client.submit(payload);\n  return Response.json(result, { status: result.ok ? 200 : result.status ?? 400 });\n}\n```\n\n### 2. Provider + button\n\n```tsx\nimport {\n  FeedbackProvider,\n  FeedbackButton,\n  useFeedback,\n} from '@afzal-plenteous/homebase-sdk';\n\nfunction App() {\n  return (\n    <FeedbackProvider\n      config={{\n        appSlug: 'employee-tasks-demo',\n        // Optional: pass a server fn instead of posting to /api/feedback/submit\n        // submit: hostSubmitFeedback,\n        actor: () => ({ email: currentUser?.email, name: currentUser?.name }),\n      }}\n    >\n      <YourApp />\n      {/* FeedbackButton auto-mounts; omit autoMountButton={false} to place it yourself */}\n    </FeedbackProvider>\n  );\n}\n\nfunction Toolbar() {\n  const { open } = useFeedback();\n  return (\n    <button type=\"button\" onClick={() => open()}>\n      Report a problem\n    </button>\n  );\n}\n```\n\nEnable the **Feedback** service for the app in Homebase Launchpad before testing.\n\n## Public API\n\n### Browser — `@afzal-plenteous/homebase-sdk`\n\n| Export | Description |\n|---|---|\n| `HomebaseProvider` | Accepts host `user` + `config`; validates with Homebase |\n| `useHomebase()` | `{ user, workspace, app, workspaceRole, isLoading, isAuthenticated, isAllowed, accessDeniedReason, refresh, validate }` |\n| `AuthGuard` | Requires host user **and** Homebase allow |\n| `AccessDenied` | Denial UI (host-owned sign-out via `onSignOut`) |\n| `getHomebaseSnapshot()` | Sync read for loaders |\n| `FeedbackProvider` | Feedback config + modal state |\n| `FeedbackButton` | Floating trigger (position + brand color) |\n| `FeedbackModal` | Form modal (type, title, priority, screenshot) |\n| `useFeedback()` | `{ open, close, isOpen, submit, submitting, lastResult, config }` |\n| `submitFeedback()` | POST to host proxy (no secrets) |\n| `captureScreenshot()` | Best-effort `html-to-image` capture |\n| `FeedbackContext` | React context (prefer `useFeedback`) |\n| Types | `HostUser`, `HomebaseUser`, `FeedbackType`, `SubmitFeedbackInput`, … |\n\n### Server — `@afzal-plenteous/homebase-sdk/server`\n\n| Export | Description |\n|---|---|\n| `createHomebaseServerClient` | Low-level `validateEmail` / `validateHomebaseUser` / `verifyLaunchToken` |\n| `validateHomebaseUser` | One-shot validate helper |\n| `createFeedbackServerClient` | Injects `app` + `launch_secret` → Homebase feedback ingest |\n| `submitFeedbackToHomebase` | One-shot feedback submit helper |\n| `feedbackSubmitUrl` | Absolute Homebase feedback ingest URL |\n| `readHomebaseEnv` | Reads `APP_LAUNCH_SECRET`, `HOMEBASE_APP_SLUG`, … |\n\n### Deprecated (compat only)\n\n| Export | Behavior |\n|---|---|\n| `useAuth()` | Maps to `useHomebase()`; `login()` throws; `logout()` → `onSignOut` |\n| `login()` | Always throws |\n| `logout()` | Calls `config.onSignOut` or throws |\n\nSee [MIGRATION.md](./MIGRATION.md).\n\n## Configuration\n\n### Server env\n\n| Name | Required | Purpose |\n|---|---|---|\n| `APP_LAUNCH_SECRET` | yes | App identity secret (server-only) |\n| `HOMEBASE_APP_SLUG` | yes | Registered app slug |\n| `HOMEBASE_URL` | no | Default `https://plenteous.app` |\n\nNever put `APP_LAUNCH_SECRET` in `VITE_*` / `NEXT_PUBLIC_*`.\n\n### Auth provider config\n\n```ts\nconfig={{\n  appSlug: 'my-app',\n  validate: serverValidateFn,       // required\n  verifyLaunchToken?: serverVerify, // optional ?lt= bridge\n  onEvent?: (evt) => void,\n  onSignOut?: () => void,           // for AccessDenied button\n  supportEmail?: 'support@…',\n  loginPath?: '/auth',             // hint for host redirects\n}}\n```\n\n### Feedback provider config\n\n```ts\nconfig={{\n  appSlug: 'my-app',\n  submit?: hostSubmitFn,              // preferred server adapter\n  submitEndpoint?: '/api/feedback/submit', // default host proxy\n  enabled?: true,\n  position?: 'bottom-right',\n  brandColor?: '#ec4899',\n  defaultPriority?: 'medium',\n  defaultType?: 'general',\n  includeScreenshotByDefault?: true,\n  actor?: () => ({ email, name }),\n  onSubmitted?: (id) => void,\n  onEvent?: (evt) => void,\n}}\n```\n\n### Automatic SDK registration (v4.2+)\n\nBeginning with **v4.2**, `HomebaseProvider` automatically registers the installed SDK package and version with Homebase after a successful initialization path. **No application registration code is required.**\n\n| Behavior | Detail |\n|---|---|\n| When | Once per browser session, on the first validate call after the host user is present |\n| How | Provider sets `registerSdk: true` on the host `validate` adapter; the server client POSTs to `/api/public/sdk/register` with `app`, `launch_secret`, `sdk_package`, `sdk_version` |\n| Identity | `sdk_package` / `sdk_version` are read from this package’s `package.json` at build time (never hardcoded in app code) |\n| Failures | Ignored silently (dev warning only); retry on the next browser session |\n| Launchpad | Shows Installed SDK Version, Last Checked, Installed Date, and Up-to-date / Update Available |\n\nForward `registerSdk` from your host validate adapter (see Quick start). Omitting it still registers on every server validate call that uses `createHomebaseServerClient` / `validateHomebaseUser` (process-deduped).\n\n### Events\n\n| Event | When |\n|---|---|\n| `homebase.validation.started` | Validation begins |\n| `homebase.validation.success` | Homebase allowed |\n| `homebase.validation.failed` | Denied or network/config error |\n| `homebase.context.loaded` | Context ready after allow |\n| `homebase.context.cleared` | Host user became `null` |\n| `homebase.sdk.register.scheduled` | Once-per-session SDK registration requested |\n| `homebase.feedback.open` | Feedback modal opened |\n| `homebase.feedback.close` | Feedback modal closed |\n| `homebase.feedback.submit.started` | Submit began |\n| `homebase.feedback.submitted` | Submit succeeded |\n| `homebase.feedback.submit.failed` | Submit failed |\n| `homebase.feedback.screenshot.captured` | Screenshot captured |\n| `homebase.feedback.screenshot.failed` | Screenshot failed (submit continues) |\n\n## Docs\n\n| Doc | Audience |\n|---|---|\n| [MIGRATION.md](./MIGRATION.md) | Upgrading from v1/v2 → v3/v4 |\n| [LOVABLE.md](./LOVABLE.md) | Lovable / Vite apps |\n| [CURSOR.md](./CURSOR.md) | Cursor agent integration notes |\n| [DEPLOYMENT.md](./DEPLOYMENT.md) | npm publish |\n| [examples/](./examples/) | Framework sketches |\n\n## License\n\nMIT\n","readmeFilename":"README.md"}