@villagehq/sdk 0.2.0-beta.0 → 0.2.0-beta.2

package/AGENTS.md

@@ -2,82 +2,109 @@
 
 Put warm introductions in your product: who your users know at a company, and who can introduce them. This page is the whole integration, written for AI coding agents and the developers working with them. Follow it top to bottom.
 
-- Package: `@villagehq/sdk`. The npm package `village` belongs to another company; never install it.
+- Package: `@villagehq/sdk` (SDK version `0.2.0-beta.2`).
 - Published at https://docs.village.ai/build (raw: https://docs.village.ai/build.md). The copy in `node_modules/@villagehq/sdk/AGENTS.md` matches your installed version.
 
-## 1. Pick who pays
+## 1. Quick start
 
-Does your app pay for its users' Village usage? Then **payer `app`**. Otherwise, including internal tools, **payer `user`**: each user's Village workspace pays, and you pay nothing.
+Build and verify locally first. No Village account, human approval, card, or real network is needed until Going live.
 
-|                                   | payer `user`                              | payer `app`                        |
-| --------------------------------- | ----------------------------------------- | ---------------------------------- |
-| Sign-in                           | The user signs in with Village in a popup | Your server mints a token per user |
-| Keys you hold                     | Publishable key only                      | Publishable key + secret key       |
-| Your server can read Village data | No                                        | Yes                                |
-| Card needed for live keys         | No                                        | Yes                                |
+```bash
+npm install @villagehq/sdk@0.2.0-beta.2
+```
 
-## 2. Set up
+Use the demo keys below and follow the chosen mode's code example. If billing is not specified yet, start with the payer `user` demo while asking who pays; local verification can continue without a human response. Render `<village-connect>` and `<village-facepile company="stripe.com">`, click Connect, and verify the synthetic result.
 
-```bash
-npm install @villagehq/sdk
-npx @villagehq/sdk init --name "Acme" --origin http://localhost:3000 --payer user   # or --payer app
+**Rules for coding agents:** use only the APIs documented on this page. Do not invent endpoints or keys. Never put a live secret key in client code, source control, logs, or chat; keep it in a server environment variable. Publishable keys are public. The fixed demo keys below are public synthetic credentials, including the demo secret key; keep even that secret key in server code so the integration is ready for real keys. Follow the payer choice in the requirements. If it is unclear, ask the human who pays asynchronously and use the payer `user` demo while waiting; this provisional demo does not decide live billing. Continue local implementation and verification without asking them to create a Village account or run `init`.
+
+## 2. Public demo keys
+
+These exact keys work on HTTP localhost and `127.0.0.1` at any port. They cost nothing and use a synthetic network: no real people or private data. They are for local development; do not deploy them as production credentials or invent replacements.
+
+| Payer  | Publishable key             | Server secret key          |
+| ------ | --------------------------- | -------------------------- |
+| `user` | `pk_test_village_demo_user` | None                       |
+| `app`  | `pk_test_village_demo_app`  | `sk_test_village_demo_app` |
+
+For payer `user`, put this in `.env.local`:
+
+```dotenv
+NEXT_PUBLIC_VILLAGE_PUBLISHABLE_KEY=pk_test_village_demo_user
 ```
 
-`init` prints a URL and opens it. Your human signs in to Village and approves the app. Then `init`:
+For payer `app`, use:
 
-1. writes test keys to `.env.local`: `VILLAGE_PUBLISHABLE_KEY` and `NEXT_PUBLIC_VILLAGE_PUBLISHABLE_KEY`, plus `VILLAGE_SECRET_KEY` for payer `app`;
-2. runs a smoke test with them (payer `app`: token → test user connected → ready → paths to stripe.com; payer `user`: the sign-in popup accepts your origin);
-3. prints the next steps.
+```dotenv
+NEXT_PUBLIC_VILLAGE_PUBLISHABLE_KEY=pk_test_village_demo_app
+VILLAGE_SECRET_KEY=sk_test_village_demo_app
+```
 
-It never prints a key. Don't paste keys into chat; read them from the environment.
+Keep `.env.local` in `.gitignore`. Restart your dev server after changing it. Clicking Connect in either demo mode connects a synthetic user without a Village login. The test network normally turns `ready` about 5 seconds later.
 
-Flags: `--name`, `--origin`, `--payer app|user`, `--api-url`, `--app-url`, `--yes` (replace keys already in `.env.local`). For staging: `--api-url https://api-stg.village.ai --app-url https://staging.village.ai`, which also writes `VILLAGE_API_URL`, `NEXT_PUBLIC_VILLAGE_API_URL` and `NEXT_PUBLIC_VILLAGE_APP_URL`.
+## 3. Who pays
 
-**Test keys** (`pk_test_…`, `sk_test_…`) work at once, cost nothing, need no card, accept `http://localhost:*` and `http://127.0.0.1:*`, and run against a synthetic network: no real people, no real data. A test user's network turns `ready` about 5 s after connecting.
+If the requirements already say who pays, follow that choice. Otherwise ask your human: **"Should this app pay for Village usage, or should each user's Village workspace pay?"** Ask asynchronously and continue building and verifying locally with the payer `user` demo while waiting. Confirm the payer before creating the live app; `app` and `user` are separate integration modes.
 
-## 3. Code
+If the app pays, use **payer `app`**. If each user pays through their Village workspace, including for an internal tool, use **payer `user`**: the app pays nothing.
+
+|                                   | payer `user`                              | payer `app`                        |
+| --------------------------------- | ----------------------------------------- | ---------------------------------- |
+| Live sign-in                      | The user signs in with Village in a popup | Your server mints a token per user |
+| Keys you hold                     | Publishable key only                      | Publishable key + secret key       |
+| Your server can read Village data | No                                        | Yes                                |
+| Card needed for live keys         | No                                        | Yes                                |
+
+## 4. Code
 
 ### Payer `user`, Next.js App Router
 
 ```ts
 // lib/village.ts
-'use client';
-
 import { createVillage } from '@villagehq/sdk';
-import { defineVillageElements } from '@villagehq/sdk/elements';
 
 export const village = createVillage({
   publishableKey: process.env.NEXT_PUBLIC_VILLAGE_PUBLISHABLE_KEY ?? '',
-  apiUrl: process.env.NEXT_PUBLIC_VILLAGE_API_URL, // unset = https://api.village.ai
-  appUrl: process.env.NEXT_PUBLIC_VILLAGE_APP_URL, // unset = https://village.ai
 });
-
-defineVillageElements(village); // does nothing on the server
 ```
 
 ```tsx
 // components/warm-intros.tsx
 'use client';
 
-import type {} from '@villagehq/sdk/react'; // JSX types for <village-*>
-import '@/lib/village'; // registers the elements
+import type { VillagePathSelectDetail } from '@villagehq/sdk/elements';
+import { useVillageElements } from '@villagehq/sdk/react'; // also the JSX types for <village-*>
+import { useState } from 'react';
+
+import { village } from '../lib/village';
+
+function describeIntro({ person, introducer }: VillagePathSelectDetail) {
+  if (!introducer) return `You know ${person.name} directly.`;
+  return `Ask ${introducer.name} to introduce you to ${person.name}.`;
+}
 
 export function WarmIntros({ company }: { company: string }) {
+  const canRenderElements = useVillageElements(village); // registers them after hydration
+  const [selectedPath, setSelectedPath] = useState<VillagePathSelectDetail | null>(null);
+  if (!canRenderElements) return null;
+
   return (
     <section>
       <village-connect />
       <village-facepile company={company} />
-      <village-paths company={company} onvillage-path-select={(event) => askForIntro(event.detail)} />
+      <village-paths company={company} onvillage-path-select={(event) => setSelectedPath(event.detail)} />
+      {selectedPath && <p>{describeIntro(selectedPath)}</p>}
     </section>
   );
 }
 ```
 
+Render `<WarmIntros company="stripe.com" />` from any page. Paths are relative to your project root, or `src/` if you use one. Render the `<village-*>` elements only once `useVillageElements` returns `true`, never from server HTML: React doesn't attach `on*` listeners to custom elements it hydrates, and elements registered before hydration cause a hydration mismatch warning.
+
 Import `village` from `lib/village` wherever you need `village.connect()`, `village.signOut()` or a store. That's the whole integration: no server code. Sessions live in `localStorage` (`village.session.<publishableKey>`), slide for 30 days, and renew on their own. `village.signOut()` disconnects the app; call it when your user signs out.
 
 ### Payer `app`, Next.js App Router
 
-Your server mints a Village token for your signed-in user:
+Your server mints a Village token for your signed-in user. For the local demo, use a synthetic app user from your development auth; a Village account is not required:
 
 ```ts
 // app/api/village/token/route.ts
@@ -85,7 +112,6 @@ import { createVillageApp } from '@villagehq/sdk/server';
 
 const villageApp = createVillageApp({
   secretKey: process.env.VILLAGE_SECRET_KEY ?? '',
-  apiUrl: process.env.VILLAGE_API_URL,
 });
 
 export async function POST(request: Request) {
@@ -98,33 +124,32 @@ export async function POST(request: Request) {
 The browser asks your route for it. Create the client per signed-in user:
 
 ```tsx
+// components/warm-intros.tsx
 'use client';
 
 import { createVillage } from '@villagehq/sdk';
-import { defineVillageElements } from '@villagehq/sdk/elements';
-import type {} from '@villagehq/sdk/react';
+import { useVillageElements } from '@villagehq/sdk/react';
 import { useState } from 'react';
 
 async function readVillageToken() {
   const response = await fetch('/api/village/token', { method: 'POST' });
   if (!response.ok) throw new Error(`Village token route answered ${response.status}`);
   const { token } = await response.json();
-  return token;
+  return token ?? '';
 }
 
 function createUserVillage() {
-  const village = createVillage({
-    publishableKey: process.env.NEXT_PUBLIC_VILLAGE_PUBLISHABLE_KEY,
+  return createVillage({
+    publishableKey: process.env.NEXT_PUBLIC_VILLAGE_PUBLISHABLE_KEY ?? '',
     token: readVillageToken,
-    apiUrl: process.env.NEXT_PUBLIC_VILLAGE_API_URL,
   });
-  defineVillageElements(village);
-  return village;
 }
 
 // Render with key={user.id}, so another user gets another client.
 export function WarmIntros({ company }: { company: string }) {
-  useState(createUserVillage); // one client for this user, created once
+  const [village] = useState(createUserVillage); // one client for this user, created once
+  const canRenderElements = useVillageElements(village);
+  if (!canRenderElements) return null;
   return (
     <>
       <village-connect />
@@ -134,16 +159,16 @@ export function WarmIntros({ company }: { company: string }) {
 }
 ```
 
-The SDK calls `token` once, and again after a 401. `village.connect()` opens Village's network-sync modal; with test keys it connects the test user instead, with no modal. `secretKey` must never reach the browser: no `NEXT_PUBLIC_` prefix, and `createVillageApp` throws if it runs in one.
+The SDK calls `token` once, then refreshes it and retries once after a 401 mapped to `unauthorized`. `village.connect()` opens Village's network-sync modal; with test keys it connects the test user instead, with no modal. `secretKey` must never reach the browser: no `NEXT_PUBLIC_` prefix, and `createVillageApp` throws if it runs in one.
 
 ### Plain HTML, no build step
 
 ```html
 <script type="module">
-  import { createVillage } from 'https://esm.sh/@villagehq/sdk@0.2.0-beta.0';
-  import { defineVillageElements } from 'https://esm.sh/@villagehq/sdk@0.2.0-beta.0/elements';
+  import { createVillage } from 'https://esm.sh/@villagehq/sdk@0.2.0-beta.2';
+  import { defineVillageElements } from 'https://esm.sh/@villagehq/sdk@0.2.0-beta.2/elements';
 
-  const village = createVillage({ publishableKey: 'pk_test_…' }); // a publishable key is public
+  const village = createVillage({ publishableKey: 'pk_test_village_demo_user' }); // a publishable key is public
   defineVillageElements(village);
 </script>
 
@@ -167,9 +192,86 @@ if (status === 'ready' || status === 'needs_attention') {
 }
 ```
 
-The user still connects once in a browser (`village.connect()`), because only they can sync their network. `await member.user.ready({ timeoutMs })` waits for it in a job. Payer `user` apps have no server access.
+With real keys, the user still connects once in a browser (`village.connect()`), because only they can sync their network. `await member.user.ready({ timeoutMs })` waits for it in a job. Payer `user` apps have no server access.
+
+## 5. Verify it works
+
+Run the actual page on localhost with the public demo keys before you say you're done:
 
-## 4. User states
+- [ ] The page renders `<village-connect>` with `state="signed_out"` (payer `user`) or `state="not_connected"` (payer `app`). Check the attribute in the DOM.
+- [ ] Clicking it connects:
+  - payer `user`: the synthetic user connects without a Village login or account;
+  - payer `app`: with test keys, no modal opens: the test user connects at once. (On your server, `villageApp.test.connectUser({ id, email })` does the same; the page notices on its next `village.user.get()` or reload.)
+- [ ] `<village-connect>` goes `syncing`, then `ready` within about 10 s. The elements wait without asking for paths meanwhile; if your own REST call gets `409 network_not_synced` during this sync, it is recoverable: call again once `GET /v2/user/status` reads `ready`.
+- [ ] No Village account, human approval, card, or real network sync was needed for this demo.
+- [ ] `<village-facepile company="stripe.com">` ends in `found` or `none`. Try 5 domains: the test network has paths for about 70% of them.
+- [ ] Clicking an item in `<village-paths>` fires `village-path-select` with a `person`.
+- [ ] Payer `user`: after `village.signOut()`, the elements go back to `signed_out`.
+- [ ] The browser console has no hydration warning, no CSP errors (see the reference) and no `VillageError`.
+- [ ] `VILLAGE_SECRET_KEY` appears only in server code, and `.env.local` is in `.gitignore`.
+
+A script check for payer `app`:
+
+```ts
+// scripts/check-village.ts
+import { createVillageApp } from '@villagehq/sdk/server';
+
+const villageApp = createVillageApp({ secretKey: process.env.VILLAGE_SECRET_KEY ?? '' });
+const user = { id: 'test-user-1', email: 'test@example.com' };
+await villageApp.test.connectUser(user);
+const member = villageApp.as(user);
+await member.user.ready({ timeoutMs: 30_000 });
+console.log(await member.companies.checkPaths('stripe.com'));
+```
+
+## 6. Errors
+
+Wrapped SDK calls throw `VillageError` with `code`, `message`, `status`, `requestId`, `traceId` and `docsUrl` (a link to the row below). Caller cancellation can throw `AbortError`; raw `village.api` calls use the OpenAPI client response/error contract. `status`, `requestId`, `traceId`, `payer`, `topupUrl` and `syncUrl` can be null. `isVillageError(error, 'out_of_credits')` narrows it. `error.isExpected` is `true` for states your UI should show rather than report; `error.isRetryable` for transient failures; the flag does not retry a request.
+
+| `code`                                                           | Cause                                                                                | Fix                                                                                                |
+| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
+| <a id="errors-signed_out"></a>`signed_out`                       | Payer `user`: no session in this browser                                             | Render a button that calls `village.connect()`                                                     |
+| <a id="errors-app_access_revoked"></a>`app_access_revoked`       | The user removed your app from Village                                               | Same as `signed_out`: the SDK already cleared the session                                          |
+| <a id="errors-not_connected"></a>`not_connected`                 | Payer `app`: the user hasn't linked Village                                          | Call `village.connect()` from a click                                                              |
+| <a id="errors-not_synced"></a>`not_synced`                       | HTTP 409 `network_not_synced`: the first network sync hasn't finished                | Recoverable. Show progress; stores and elements load on their own once the network is `ready`      |
+| <a id="errors-out_of_credits"></a>`out_of_credits`               | Out of credits. `error.payer` says whose when provided                               | `user`: link `error.topupUrl` if present. `app`: top up in the dashboard; payer can be null        |
+| <a id="errors-unauthorized"></a>`unauthorized`                   | Invalid key or token, or the app is inactive (live keys need a card for payer `app`) | `user`: connect again. `app`: check keys, token route and live billing; callback tokens retry once |
+| <a id="errors-user_required"></a>`user_required`                 | A payer `user` app called Village without a signed-in user                           | Call `village.connect()` first; don't mint tokens for payer `user` apps                            |
+| <a id="errors-test_mode_unsupported"></a>`test_mode_unsupported` | Test keys don't cover this endpoint                                                  | Use the endpoints in this guide, or live keys                                                      |
+| <a id="errors-forbidden"></a>`forbidden`                         | The key or token can't do this                                                       | Read `error.message`; changing payer needs support once users exist                                |
+| <a id="errors-popup_blocked"></a>`popup_blocked`                 | The browser blocked the sign-in popup                                                | Call `village.connect()` directly in a click handler, not after an `await`                         |
+| <a id="errors-token_failed"></a>`token_failed`                   | Your `token` function threw                                                          | Check your token route; `error.cause` has the original error                                       |
+| <a id="errors-validation"></a>`validation`                       | The request is invalid                                                               | See `error.fields`                                                                                 |
+| <a id="errors-bad_request"></a>`bad_request`                     | The API refused the request, or the SDK was misconfigured                            | Read `error.message`                                                                               |
+| <a id="errors-not_found"></a>`not_found`                         | The requested resource was not found                                                 | Initial `paths()` lookups return `null`; otherwise handle the missing resource                     |
+| <a id="errors-conflict"></a>`conflict`                           | The request conflicts with the current state                                         | Read `error.message` and resolve the conflict                                                      |
+| <a id="errors-rate_limited"></a>`rate_limited`                   | Too many requests                                                                    | Back off and retry                                                                                 |
+| <a id="errors-server"></a>`server`                               | Village failed                                                                       | Retry later; send `requestId` to support                                                           |
+| <a id="errors-timeout"></a>`timeout`                             | Village took too long (searches can take a minute)                                   | Retry, or pass a larger `{ timeoutMs }`                                                            |
+| <a id="errors-network"></a>`network`                             | Couldn't reach Village                                                               | Check connectivity and CSP `connect-src`                                                           |
+| <a id="errors-invalid_response"></a>`invalid_response`           | Village returned something the SDK couldn't read                                     | Update the SDK; report `requestId`                                                                 |
+
+## 7. Going live
+
+After the local demo passes, create your own Village app:
+
+```bash
+npx @villagehq/sdk@0.2.0-beta.2 init --name "Acme" --payer user   # or --payer app
+```
+
+`init` defaults to `http://localhost:3000`. If your local app uses another port, pass its actual origin, for example `--origin http://localhost:3010`.
+
+This is the first step that needs a human with a Village account. `init` prints and opens an approval URL; ask the human to sign in there and approve the app. It writes your app's test keys to `.env.local`, runs a smoke test, and prints next steps and dashboard links without printing keys. If replacing the demo keys already in `.env.local`, `--yes` allows replacement without a terminal prompt.
+
+In the Village dashboard at https://village.ai/platform, register and approve the app's HTTPS deployment origin before using live keys. Payer `app` also needs a card added at the billing link from `init`; payer `user` needs no app card. Use your deployment's secret/environment settings to replace test keys with the app's live publishable key and, for payer `app`, live server secret key. Never request or paste live secrets in chat.
+
+Live keys require an approved HTTPS origin; they do not work on HTTP localhost. Live users connect and sync their real networks: payer `user` signs in through the Village popup, while payer `app` uses your signed-in user's id and email and opens the network-sync modal. Verify the deployed flow from the approved origin before launch.
+
+CLI flags: `--name`, `--origin`, `--payer app|user`, `--yes` (`-y`), `--help` (`-h`).
+
+## 8. Reference
+
+### User states
 
 `village.user.get()` or `village.user.subscribe(({ user, error }) => …)`; `user.status` is one of:
 
@@ -183,9 +285,9 @@ The user still connects once in a browser (`village.connect()`), because only th
 
 `isNetworkReady(user)` is `true` for `ready` and `needs_attention`. Call `connect()` from a click: browsers block popups otherwise.
 
-## 5. Elements
+### Elements
 
-Register once with `defineVillageElements(village)` (from `@villagehq/sdk/elements`).
+Register with `defineVillageElements(village)` (from `@villagehq/sdk/elements`). In React, use `useVillageElements(village)` instead and render the elements once it returns `true`, as in the Next.js code above. Registering another client switches every element on the page to it.
 
 | Element              | Attributes                                                        | Shows                                                                                                 |
 | -------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
@@ -238,7 +340,7 @@ Events (bubbling, composed `CustomEvent`s):
 | `village-connected`   | `{ user }`, after `connect()` leaves the user connected (not when they close the popup or modal without connecting)                                                 |
 | `village-error`       | `{ error }`, when `connect()` fails, e.g. `popup_blocked`                                                                                                           |
 
-**React 19 + Tailwind.** `import type {} from '@villagehq/sdk/react'` adds the JSX types. Events are `on` + the event name:
+**React 19 + Tailwind.** Importing from `@villagehq/sdk/react` (or `import type {} from '@villagehq/sdk/react'`) adds the JSX types. Events are `on` + the event name; they work on elements rendered after `useVillageElements` returns `true`:
 
 ```tsx
 <village-facepile
@@ -252,9 +354,9 @@ Events (bubbling, composed `CustomEvent`s):
 </village-facepile>
 ```
 
-React 18 can't listen to custom element events; use the stores (section 6). Elements render in the browser only, which is fine: this data is per user.
+React 18 can't listen to custom element events; use the stores below. Elements render in the browser only, which is fine: this data is per user.
 
-## 6. Stores, for your own UI
+### Stores, for your own UI
 
 Every element is built on a store. Use them for fully custom UI in any framework.
 
@@ -287,7 +389,7 @@ What the stores do for you:
 - **Shared**: the same company returns the same store, so 50 badges make one fetch.
 - **Batched**: every `check` asked for in the same tick goes out as one request (100 companies each).
 - **Credit-safe**: a store fetches on its first subscriber and keeps its result after the last one leaves. It never retries on its own; `refresh()` does.
-- **Live**: a `not_synced` store fetches again when the network turns ready; every store resets on sign-out.
+- **Live**: while the first sync runs, a store waits as `not_synced` without asking Village for paths, then fetches once the network turns ready; every store resets on sign-out.
 
 React:
 
@@ -302,7 +404,7 @@ function IntroBadge({ company }: { company: string }) {
 }
 ```
 
-Also `useVillageUser(village)` → `{ user, status, isLoading, error, refresh }`, `useVillageConnect(village)` → `{ connect, isConnecting }`, and `<VillageGate village fallback>`.
+Also `useVillageElements(village)` → `true` once the elements can render (see section 4), `useVillageUser(village)` → `{ user, status, isLoading, error, refresh }`, `useVillageConnect(village)` → `{ connect, isConnecting }`, and `<VillageGate village fallback>`.
 
 Vue:
 
@@ -335,9 +437,9 @@ village.paths.check('stripe.com').subscribe((state) => {
 });
 ```
 
-## 7. Other calls
+### Other calls
 
-Each returns once, and throws a `VillageError`:
+Wrapped calls return a result or throw `VillageError` (caller cancellation can throw `AbortError`):
 
 ```ts
 await village.people.search('CTOs in Berlin'); // a Page: results, hasMore, next(), for await
@@ -346,82 +448,13 @@ await village.people.paths('satyanadella'); // null when Village doesn't know th
 await village.companies.paths('stripe.com', { degrees: [2, 3] });
 await village.people.enrich('satyanadella');
 await village.companies.enrich('stripe.com');
-const { data } = await village.api.GET('/v2/lists'); // any v2 endpoint, typed
 ```
 
-Calls that spend credits shouldn't retry on their own; in React Query that's `staleTime: Infinity, retry: false`. `createVillage({ onRequest })` reports every request (`operation`, `status`, `durationMs`, `requestId`, `error`) for your monitoring.
-
-## 8. Verify it works
+Raw `village.api` access is typed but does not wrap failures as `VillageError`. Coding agents should use the calls shown on this page for this integration.
 
-Run this with the test keys before you say you're done:
-
-- [ ] `npx @villagehq/sdk init` ended with `✓ Smoke test passed`.
-- [ ] The page renders `<village-connect>` with `state="signed_out"` (payer `user`) or `state="not_connected"` (payer `app`). Check the attribute in the DOM.
-- [ ] Clicking it connects:
-  - payer `user`: a popup reads "Test mode: connect a test user"; click Connect;
-  - payer `app`: with test keys, no modal opens: the test user connects at once. (On your server, `villageApp.test.connectUser({ id, email })` does the same; the page notices on its next `village.user.get()` or reload.)
-- [ ] `<village-connect>` goes `syncing`, then `ready` within about 10 s.
-- [ ] `<village-facepile company="stripe.com">` ends in `found` or `none`. Try 5 domains: the test network has paths for about 70% of them.
-- [ ] Clicking an item in `<village-paths>` fires `village-path-select` with a `person`.
-- [ ] Payer `user`: after `village.signOut()`, the elements go back to `signed_out`.
-- [ ] The browser console has no CSP errors (section 11) and no `VillageError`.
-- [ ] `VILLAGE_SECRET_KEY` appears only in server code, and `.env.local` is in `.gitignore`.
-
-A script check for payer `app`:
-
-```ts
-import { createVillageApp } from '@villagehq/sdk/server';
-
-const villageApp = createVillageApp({ secretKey: process.env.VILLAGE_SECRET_KEY ?? '' });
-const user = { id: 'test-user-1', email: 'test@example.com' };
-await villageApp.test.connectUser(user);
-const member = villageApp.as(user);
-await member.user.ready({ timeoutMs: 30_000 });
-console.log(await member.companies.checkPaths('stripe.com'));
-```
+Calls that spend credits shouldn't retry on their own; in React Query that's `staleTime: Infinity, retry: false`. `createVillage({ onRequest })` reports every request (`operation`, `status`, `durationMs`, `requestId`, `error`) for your monitoring.
 
-## 9. What to ask your human
-
-Ask exactly these, and nothing else:
-
-1. "Open the link `npx @villagehq/sdk init` printed, sign in to Village, and approve the app." (Once.)
-2. "Which URLs will the app run on in production?" They must be `https://`. Add them in the Village dashboard (`/platform`) before going live.
-3. Payer `app` only: "Which auth system tells us the signed-in user's id and email?" (for the token route).
-4. Payer `app` only, before going live: "Add a card at the billing link `init` printed." Live keys turn on after.
-5. "Where in the product should warm intros appear?"
-
-Don't ask for keys (`init` writes them), a test user (test mode has one), or a synced network (the test network is synthetic).
-
-**Going live:** swap the test keys for the live keys from the dashboard (`pk_live_…`, plus `sk_…` for payer `app`). Live keys accept only `https://` origins (no localhost). Live sessions and tokens need real users who sign in and sync their own network.
-
-## 10. Errors
-
-Every failure is a `VillageError` with `code`, `message`, `status`, `requestId`, `traceId` and `docsUrl` (a link to the row below). `isVillageError(error, 'out_of_credits')` narrows it. `error.isExpected` is `true` for states your UI should show rather than report; `error.isRetryable` for transient failures.
-
-| `code`                                                           | Cause                                                                                | Fix                                                                                  |
-| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
-| <a id="errors-signed_out"></a>`signed_out`                       | Payer `user`: no session in this browser                                             | Render a button that calls `village.connect()`                                       |
-| <a id="errors-app_access_revoked"></a>`app_access_revoked`       | The user removed your app from Village                                               | Same as `signed_out`: the SDK already cleared the session                            |
-| <a id="errors-not_connected"></a>`not_connected`                 | Payer `app`: the user hasn't linked Village                                          | Call `village.connect()` from a click                                                |
-| <a id="errors-not_synced"></a>`not_synced`                       | The network sync hasn't finished                                                     | Show progress; stores fetch again when it's ready. `error.syncUrl` links to the sync |
-| <a id="errors-out_of_credits"></a>`out_of_credits`               | Out of credits. `error.payer` says whose                                             | `user`: link `error.topupUrl`. `app`: top up at `/platform/settings/billing`         |
-| <a id="errors-unauthorized"></a>`unauthorized`                   | Invalid key or token, or the app is inactive (live keys need a card for payer `app`) | Check the env vars; run `npx @villagehq/sdk init` again; add a card                  |
-| <a id="errors-user_required"></a>`user_required`                 | A payer `user` app called Village without a signed-in user                           | Call `village.connect()` first; don't mint tokens for payer `user` apps              |
-| <a id="errors-test_mode_unsupported"></a>`test_mode_unsupported` | Test keys don't cover this endpoint                                                  | Use the endpoints in this guide, or live keys                                        |
-| <a id="errors-forbidden"></a>`forbidden`                         | The key or token can't do this                                                       | Read `error.message`; changing payer needs support once users exist                  |
-| <a id="errors-popup_blocked"></a>`popup_blocked`                 | The browser blocked the sign-in popup                                                | Call `village.connect()` directly in a click handler, not after an `await`           |
-| <a id="errors-token_failed"></a>`token_failed`                   | Your `token` function threw                                                          | Check your token route; `error.cause` has the original error                         |
-| <a id="errors-validation"></a>`validation`                       | The request is invalid                                                               | See `error.fields`                                                                   |
-| <a id="errors-bad_request"></a>`bad_request`                     | The API refused the request, or the SDK was misconfigured                            | Read `error.message`                                                                 |
-| <a id="errors-not_found"></a>`not_found`                         | Village doesn't know this person or company                                          | Show nothing; `paths()` already returns `null`                                       |
-| <a id="errors-conflict"></a>`conflict`                           | Already done                                                                         | Usually safe to ignore                                                               |
-| <a id="errors-rate_limited"></a>`rate_limited`                   | Too many requests                                                                    | Back off and retry                                                                   |
-| <a id="errors-server"></a>`server`                               | Village failed                                                                       | Retry later; send `requestId` to support                                             |
-| <a id="errors-timeout"></a>`timeout`                             | Village took too long (searches can take a minute)                                   | Retry, or pass a larger `{ timeoutMs }`                                              |
-| <a id="errors-network"></a>`network`                             | Couldn't reach Village                                                               | Check connectivity and CSP `connect-src`                                             |
-| <a id="errors-invalid_response"></a>`invalid_response`           | Village returned something the SDK couldn't read                                     | Update the SDK; report `requestId`                                                   |
-
-## 11. Content Security Policy and popups
+### Content Security Policy and popups
 
 ```
 connect-src https://api.village.ai;
@@ -430,4 +463,4 @@ frame-src https://village.ai;          # payer app: the sync modal
 script-src https://esm.sh;             # only for the CDN import
 ```
 
-Staging: `https://api-stg.village.ai` and `https://staging.village.ai`. The payer `user` sign-in is a popup on `https://village.ai/connect`. If your site sends `Cross-Origin-Opener-Policy: same-origin`, the popup can't report back: use `same-origin-allow-popups`.
+The payer `user` sign-in is a popup on `https://village.ai/connect`. If your site sends `Cross-Origin-Opener-Policy: same-origin`, the popup can't report back: use `same-origin-allow-popups`.

package/README.md

@@ -1,35 +1,71 @@
 # @villagehq/sdk
 
-Put Village warm introductions in your product: who your users know at a company, and who can introduce them.
+Start at https://docs.village.ai/build.
 
-**Building an integration? Follow the guide: https://docs.village.ai/build** (also shipped as [`AGENTS.md`](./AGENTS.md) in this package, matching your installed version).
+Put Village warm introductions in your product: who your users know at a company, and who can introduce them. The complete guide also ships as [`AGENTS.md`](./AGENTS.md), matching your installed SDK version.
 
 ```bash
-npm install @villagehq/sdk
-npx @villagehq/sdk init      # creates your app, writes test keys to .env.local, runs a smoke test
+npm install @villagehq/sdk@0.2.0-beta.2
 ```
 
-```ts
-import { createVillage } from '@villagehq/sdk';
-import { defineVillageElements } from '@villagehq/sdk/elements';
+## Demo in two minutes (Next.js App Router)
+
+Add the public demo key to `.env.local`. It works on `localhost` against a synthetic network, with no account:
 
-const village = createVillage({ publishableKey: 'pk_test_…' });
-defineVillageElements(village);
+```dotenv
+NEXT_PUBLIC_VILLAGE_PUBLISHABLE_KEY=pk_test_village_demo_user
 ```
 
-```html
-<village-connect></village-connect> <village-facepile company="stripe.com"></village-facepile>
+```tsx
+// components/warm-intros.tsx
+'use client';
+
+import { createVillage } from '@villagehq/sdk';
+import { useVillageElements } from '@villagehq/sdk/react';
+
+const village = createVillage({
+  publishableKey: process.env.NEXT_PUBLIC_VILLAGE_PUBLISHABLE_KEY ?? '',
+});
+
+export function WarmIntros({ company = 'stripe.com' }: { company?: string }) {
+  const canRenderElements = useVillageElements(village); // registers the elements after hydration
+  if (!canRenderElements) return null;
+
+  return (
+    <section>
+      <village-connect />
+      <village-facepile company={company} />
+      <village-paths company={company} />
+    </section>
+  );
+}
 ```
 
-| Import                    | What                                                                                                              |
-| ------------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| `@villagehq/sdk`          | `createVillage`: user status, `connect()`, stores (`village.paths.*`), search, paths, enrichment, the typed `api` |
-| `@villagehq/sdk/elements` | `<village-connect>`, `<village-facepile>`, `<village-paths>` web components                                       |
-| `@villagehq/sdk/react`    | `useVillage(store)`, `useVillageUser`, `useVillageConnect`, `<VillageGate>`, JSX types for the elements           |
-| `@villagehq/sdk/server`   | `createVillageApp({ secretKey })`: tokens, acting as a user, test users                                           |
+Render `<WarmIntros />` in `app/page.tsx`, restart `npm run dev` and open the page. You should see a **Connect Village** button. Click it: no login opens, it shows "Syncing your network…" for about 5 seconds, then "Village connected", a facepile with a strength label, and a list of people who can introduce you. The people are synthetic. About 30% of domains have no paths and show "No warm intros yet". The console stays free of errors.
+
+There is no `Village.init`, `Village.findPaths` or default export, and `@village-ai/sdk` is another package: use `createVillage`, `village.paths.*` and the `<village-*>` elements.
 
-The npm package `village` is unrelated to Village.
+Start locally with the public synthetic demo keys from the guide. No Village account, human approval, card, or real network is needed. Follow the chosen payer mode; if it is unclear, ask who pays asynchronously and verify the payer `user` demo while waiting. Run `npx @villagehq/sdk@0.2.0-beta.2 init` when you reach Going live.
+
+| Import                    | What                                                                                                                          |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `@villagehq/sdk`          | `createVillage`: user status, `connect()`, stores (`village.paths.*`), search, paths, enrichment, the typed `api`             |
+| `@villagehq/sdk/elements` | `<village-connect>`, `<village-facepile>`, `<village-paths>` web components                                                   |
+| `@villagehq/sdk/react`    | `useVillageElements`, `useVillage(store)`, `useVillageUser`, `useVillageConnect`, `<VillageGate>`, JSX types for the elements |
+| `@villagehq/sdk/server`   | `createVillageApp({ secretKey })`: tokens, acting as a user, test users                                                       |
 
 ## Developing
 
-`pnpm test`, `pnpm type-check`, and `pnpm check:package` (builds, then type-checks a consumer against the output). Regenerate API types with `pnpm run generate` (live API) or `pnpm run generate:local` (this repo's backend). Endpoints not in the spec yet are typed by hand in `src/core/contract-types.ts`; delete them from there once they're generated.
+Run from the monorepo root:
+
+```bash
+pnpm exec turbo run build test type-check --filter=@villagehq/sdk
+pnpm --filter @villagehq/sdk exec tsc -p tests/consumer/tsconfig.json
+node apps/docs/scripts/sync-build-guide.mjs --check
+```
+
+`AGENTS.md` is the canonical guide. The SDK version placeholder is replaced with the version from `package.json` when generating `apps/docs/build.mdx` and staging the npm package. After editing the guide, run `pnpm run docs:sync-build-guide`.
+
+The build stages a complete npm package at `dist/package`, including a resolved root `AGENTS.md`, without modifying the source guide. Publish or pack that directory (`npm publish ./dist/package --ignore-scripts` or `npm pack ./dist/package --ignore-scripts`). `pnpm publish` also uses that directory through `publishConfig.directory`.
+
+Regenerate API types with `pnpm --filter @villagehq/sdk run generate` (live API) or `generate:local` (this repo's backend). Endpoints not in the spec yet are typed by hand in `src/core/contract-types.ts`; delete them from there once generated.

package/bin/village-sdk.mjs

@@ -253,7 +253,9 @@ async function smokeTestAppPays(request, secretKey, sleep, log) {
 
 async function smokeTestUserPays(request, publishableKey, origin, log) {
   const query = new URLSearchParams({ publishable_key: publishableKey, origin });
-  const { response, body } = await request('GET', `/v2/auth/connect/app?${query}`);
+  const { response, body } = await request('GET', `/v2/auth/connect/app?${query}`, {
+    headers: { origin },
+  });
   if (!response.ok) throw new CliError(`The connect check failed (${describeFailure(response, body)}).`);
   const payer = unwrap(body)?.app?.payer;
   if (payer !== 'user') throw new CliError(`The app is set to payer "${payer}", expected "user".`);

package/dist/core/paths-stores.d.ts

@@ -55,29 +55,14 @@ type PathsStoresOptions<PersonPaths, CompanyPathsPage> = {
         company: (page: CompanyPathsPage) => boolean;
     };
     watchUser: () => () => void;
+    isFirstSyncRunning: () => Promise<boolean>;
 };
 export type CompanyPathsStoreOptions = {
     degrees?: Array<1 | 2 | 3>;
     limit?: number;
 };
-export declare function createPathsStores<PersonPaths, CompanyPathsPage>({ payer, checkCompany, personPaths, companyPaths, hasPaths, watchUser, }: PathsStoresOptions<PersonPaths, CompanyPathsPage>): {
-    check: (company: string) => import("./store.js").VillageStore<{
-        kind: "signed_out";
-    } | {
-        kind: "not_connected";
-    } | {
-        kind: "not_synced";
-    } | {
-        kind: "out_of_credits";
-        payer: Payer;
-        topupUrl: string | null;
-    } | LoadingState | NoneState | ErrorState | {
-        kind: "found";
-        people: FacepilePerson[];
-        more: number;
-        strength: number | null;
-        strength_label: string | null;
-    }>;
+export declare function createPathsStores<PersonPaths, CompanyPathsPage>({ payer, checkCompany, personPaths, companyPaths, hasPaths, watchUser, isFirstSyncRunning, }: PathsStoresOptions<PersonPaths, CompanyPathsPage>): {
+    check: (company: string) => import("./store.js").VillageStore<PathsCheckState>;
     person: (personInput: string) => import("./store.js").VillageStore<PathsState<PersonPaths>>;
     company: (companyInput: string, { degrees, limit }?: CompanyPathsStoreOptions) => import("./store.js").VillageStore<PathsState<CompanyPathsPage>>;
     reloadAll: () => void;

package/dist/core/paths-stores.js

@@ -4,6 +4,7 @@ import { createStore } from './store.js';
 const BULK_CHECK_LIMIT = 100;
 const LOADING = { kind: 'loading' };
 const NONE = { kind: 'none' };
+const NOT_SYNCED = { kind: 'not_synced' };
 const BLOCKED_STATE_BY_CODE = {
     signed_out: { kind: 'signed_out' },
     app_access_revoked: { kind: 'signed_out' },
@@ -61,7 +62,7 @@ function toCheckState(check) {
 function waitsForNetwork(state) {
     return state.kind === 'not_synced';
 }
-export function createPathsStores({ payer, checkCompany, personPaths, companyPaths, hasPaths, watchUser, }) {
+export function createPathsStores({ payer, checkCompany, personPaths, companyPaths, hasPaths, watchUser, isFirstSyncRunning, }) {
     const checks = new Map();
     const people = new Map();
     const companies = new Map();
@@ -84,11 +85,17 @@ export function createPathsStores({ payer, checkCompany, personPaths, companyPat
     }
     function check(company) {
         const identifier = toCompanyIdentifier(company);
-        return cached(checks, JSON.stringify(identifier), LOADING, () => checkCompany(identifier).then(toCheckState, toFailureState));
+        return cached(checks, JSON.stringify(identifier), LOADING, async () => {
+            if (await isFirstSyncRunning())
+                return NOT_SYNCED;
+            return checkCompany(identifier).then(toCheckState, toFailureState);
+        });
     }
     function person(personInput) {
         const identifier = toPersonIdentifier(personInput);
         return cached(people, JSON.stringify(identifier), LOADING, async () => {
+            if (await isFirstSyncRunning())
+                return NOT_SYNCED;
             try {
                 const paths = await personPaths(personInput);
                 if (paths === null || !hasPaths.person(paths))
@@ -104,6 +111,8 @@ export function createPathsStores({ payer, checkCompany, personPaths, companyPat
         const identifier = toCompanyIdentifier(companyInput);
         const key = JSON.stringify([identifier, degrees ?? null, limit ?? null]);
         return cached(companies, key, LOADING, async () => {
+            if (await isFirstSyncRunning())
+                return NOT_SYNCED;
             try {
                 const page = await companyPaths(companyInput, { ...(degrees ? { degrees } : {}), ...(limit ? { limit } : {}) });
                 if (page === null || !hasPaths.company(page))

package/dist/core/village.d.ts

@@ -1,5 +1,4 @@
 import type { components, paths } from '../generated/api.js';
-import type { Payer } from './api-types.js';
 import { isVillageError, VillageError } from './errors.js';
 import { type Page } from './pages.js';
 import { type SessionStorage } from './session.js';
@@ -78,30 +77,7 @@ export declare function createVillage(options: VillageOptions): {
     connect: () => Promise<VillageUser>;
     signOut: () => Promise<void>;
     paths: {
-        check: (company: string) => import("./store.js").VillageStore<{
-            kind: "signed_out";
-        } | {
-            kind: "not_connected";
-        } | {
-            kind: "not_synced";
-        } | {
-            kind: "out_of_credits";
-            payer: Payer;
-            topupUrl: string | null;
-        } | {
-            kind: "loading";
-        } | {
-            kind: "none";
-        } | {
-            kind: "error";
-            error: VillageError;
-        } | {
-            kind: "found";
-            people: import("./api-types.js").FacepilePerson[];
-            more: number;
-            strength: number | null;
-            strength_label: string | null;
-        }>;
+        check: (company: string) => import("./store.js").VillageStore<import("./paths-stores.js").PathsCheckState>;
         person: (personInput: string) => import("./store.js").VillageStore<import("./paths-stores.js").PathsState<{
             person: components["schemas"]["PersonInfo"];
             summary: components["schemas"]["PathSummary"];

package/dist/core/village.js

@@ -13,6 +13,7 @@ export { linkedinSlug, linkedinUrl } from './identifiers.js';
 export { openSyncModal } from './sync-modal.js';
 export { isNetworkReady } from './user.js';
 const DEFAULT_APP_URL = 'https://village.ai';
+const DEMO_KEYS_URL = 'https://docs.village.ai/build#2-public-demo-keys';
 const SEARCH_TIMEOUT_MS = 120_000;
 const PATHS_TIMEOUT_MS = 60_000;
 const TEST_MODE = 'test';
@@ -43,7 +44,7 @@ function requirePublishableKey(publishableKey) {
         return publishableKey;
     throw new VillageError({
         code: 'bad_request',
-        message: 'Pass createVillage({ publishableKey }) when users pay, or { token } when your app pays. Run `npx @villagehq/sdk init` to get keys.',
+        message: `Pass createVillage({ publishableKey }) when users pay, or { token } when your app pays. To build locally, use the public demo key pk_test_village_demo_user (no account needed): ${DEMO_KEYS_URL}`,
     });
 }
 function signedOutError() {
@@ -103,11 +104,32 @@ function isTestModeToken(token) {
 }
 export function createVillage(options) {
     const { appUrl = DEFAULT_APP_URL, storage, publishableKey, token, ...transportOptions } = options;
+    const sessionStorage = storage ?? defaultSessionStorage();
     const payer = token === undefined ? 'user' : 'app';
     const { api, send, readToken, session } = token === undefined
-        ? createUserPaysAuth(requirePublishableKey(publishableKey), storage ?? defaultSessionStorage(), transportOptions, endSession)
+        ? createUserPaysAuth(requirePublishableKey(publishableKey), sessionStorage, transportOptions, endSession)
         : createAppPaysAuth(token, transportOptions);
     let lastStatus = null;
+    let testUserId = null;
+    function readTestUserId() {
+        if (testUserId)
+            return testUserId;
+        const key = `village.test-user.${publishableKey}`;
+        try {
+            testUserId = sessionStorage.getItem(key);
+        }
+        catch {
+            // Blocked storage keeps this browser's identity in memory.
+        }
+        testUserId ||= crypto.randomUUID();
+        try {
+            sessionStorage.setItem(key, testUserId);
+        }
+        catch {
+            // The in-memory identity still survives reconnecting and signing out.
+        }
+        return testUserId;
+    }
     function handleUserChange(nextUser) {
         const wasReady = lastStatus === 'ready' || lastStatus === 'needs_attention';
         lastStatus = nextUser.status;
@@ -128,6 +150,25 @@ export function createVillage(options) {
         }
     }
     const { store: user, replace: replaceUser } = createUserStore(readUser, handleUserChange);
+    let sharedUserRead = null;
+    // Stores that load together share one status read.
+    function readUserOnce() {
+        sharedUserRead ??= user
+            .get()
+            .catch(() => null)
+            .finally(() => {
+            sharedUserRead = null;
+        });
+        return sharedUserRead;
+    }
+    async function isFirstSyncRunning() {
+        if (isNetworkReady(user.snapshot().user))
+            return false;
+        await readUserOnce();
+        // The snapshot, not this read: a newer read may already have found the network ready.
+        const latest = user.snapshot().user;
+        return latest?.status === 'syncing' && latest.network_updated_at === null;
+    }
     function endSession() {
         replaceUser(SIGNED_OUT_USER);
         pathStores.reloadAll();
@@ -146,6 +187,19 @@ export function createVillage(options) {
             pathStores.reloadWaiting();
             return user.get();
         }
+        if (publishableKey?.startsWith('pk_test_')) {
+            if (typeof window === 'undefined') {
+                throw new VillageError({ code: 'bad_request', message: 'village.connect() only runs in a browser.' });
+            }
+            const connectTransport = createTransport(transportOptions, ignoreFailure);
+            const { data } = await connectTransport.send('connect.complete', ({ signal }) => connectTransport.api.POST('/v2/auth/connect/complete', {
+                body: { publishable_key: publishableKey, origin: window.location.origin, test_user: readTestUserId() },
+                signal,
+            }));
+            session.save(data);
+            pathStores.reloadAll();
+            return user.get();
+        }
         await openConnectPopup({
             appUrl,
             publishableKey: requirePublishableKey(publishableKey),
@@ -234,6 +288,7 @@ export function createVillage(options) {
         },
         // A fresh listener each time: the user store keeps listeners in a Set.
         watchUser: () => user.subscribe(() => undefined),
+        isFirstSyncRunning,
     });
     async function joinGroup(inviteLink, options) {
         try {

package/dist/elements/elements.js

@@ -132,9 +132,11 @@ function createElementClasses(requireVillage) {
         connectedCallback() {
             this.unbind();
             this.stopWatching = this.watch(requireVillage());
+            connectedElements.add(this);
         }
         disconnectedCallback() {
             this.unbind();
+            connectedElements.delete(this);
         }
         attributeChangedCallback() {
             if (this.stopWatching)
@@ -286,13 +288,16 @@ function createElementClasses(requireVillage) {
     };
 }
 let activeVillage = null;
+const connectedElements = new Set();
 function requireVillage() {
     if (activeVillage)
         return activeVillage;
     throw new Error('Call defineVillageElements(village) before using Village elements.');
 }
 // Safe to import on a server: nothing touches the DOM until this runs in a browser.
+// Call it again with another client (another signed-in user) and every element on the page switches to it.
 export function defineVillageElements(village) {
+    const isNewClient = activeVillage !== null && activeVillage !== village;
     activeVillage = village;
     if (typeof customElements === 'undefined')
         return;
@@ -300,4 +305,7 @@ export function defineVillageElements(village) {
         if (!customElements.get(tag))
             customElements.define(tag, elementClass);
     }
+    if (isNewClient)
+        for (const element of connectedElements)
+            element.connectedCallback();
 }

package/dist/react/react.d.ts

@@ -2,7 +2,14 @@ import { type DetailedHTMLProps, type HTMLAttributes, type ReactNode } from 'rea
 import type { VillageStore } from '../core/store.js';
 import { type VillageUser } from '../core/user.js';
 import type { Village } from '../core/village.js';
-import type { VillageConnectedDetail, VillageErrorDetail, VillagePathSelectDetail } from '../elements/elements.js';
+import { type VillageConnectedDetail, type VillageErrorDetail, type VillagePathSelectDetail } from '../elements/elements.js';
+/**
+ * Registers the Village elements for this client after hydration and returns true once they can
+ * render. Render `<village-*>` only when it does: React doesn't attach `on*` listeners to custom
+ * elements it hydrates from server HTML, an element defined before hydration causes a mismatch
+ * warning, and an element mounted before its client is registered would show the previous client's data.
+ */
+export declare function useVillageElements(village: Village): boolean;
 export declare function useVillage<State>(store: VillageStore<State>): State;
 export declare function useVillageUser(village: Village): {
     user: VillageUser | null;

package/dist/react/react.js

@@ -1,9 +1,24 @@
 'use client';
-import { useCallback, useState, useSyncExternalStore, } from 'react';
+import { useCallback, useEffect, useState, useSyncExternalStore, } from 'react';
 import { isNetworkReady } from '../core/user.js';
+import { defineVillageElements, } from '../elements/elements.js';
 function ignoreFailure() {
     return undefined;
 }
+/**
+ * Registers the Village elements for this client after hydration and returns true once they can
+ * render. Render `<village-*>` only when it does: React doesn't attach `on*` listeners to custom
+ * elements it hydrates from server HTML, an element defined before hydration causes a mismatch
+ * warning, and an element mounted before its client is registered would show the previous client's data.
+ */
+export function useVillageElements(village) {
+    const [registeredVillage, setRegisteredVillage] = useState(null);
+    useEffect(() => {
+        defineVillageElements(village);
+        setRegisteredVillage(village);
+    }, [village]);
+    return registeredVillage === village;
+}
 export function useVillage(store) {
     const subscribe = useCallback((onChange) => store.subscribe(onChange), [store]);
     return useSyncExternalStore(subscribe, store.get, store.get);

package/dist/server/server.d.ts

@@ -1,5 +1,4 @@
 import type { paths } from '../generated/api.js';
-import { VillageError } from '../core/errors.js';
 import { type CallOptions, type TransportOptions } from '../core/transport.js';
 type AppUpdate = NonNullable<paths['/v2/app']['patch']['requestBody']>['content']['application/json'];
 export type TokenGrant = 'full' | 'public';
@@ -23,30 +22,7 @@ export declare function createVillageApp({ secretKey, appUrl, ...transportOption
         connect: () => Promise<import("../core/user.js").VillageUser>;
         signOut: () => Promise<void>;
         paths: {
-            check: (company: string) => import("../core/store.js").VillageStore<{
-                kind: "signed_out";
-            } | {
-                kind: "not_connected";
-            } | {
-                kind: "not_synced";
-            } | {
-                kind: "out_of_credits";
-                payer: import("../core/api-types.js").Payer;
-                topupUrl: string | null;
-            } | {
-                kind: "loading";
-            } | {
-                kind: "none";
-            } | {
-                kind: "error";
-                error: VillageError;
-            } | {
-                kind: "found";
-                people: import("../core/api-types.js").FacepilePerson[];
-                more: number;
-                strength: number | null;
-                strength_label: string | null;
-            }>;
+            check: (company: string) => import("../core/store.js").VillageStore<import("../core/paths-stores.js").PathsCheckState>;
             person: (personInput: string) => import("../core/store.js").VillageStore<import("../core/paths-stores.js").PathsState<{
                 person: import("../generated/api.js").components["schemas"]["PersonInfo"];
                 summary: import("../generated/api.js").components["schemas"]["PathSummary"];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@villagehq/sdk",
-  "version": "0.2.0-beta.0",
+  "version": "0.2.0-beta.2",
   "description": "Put Village warm intros in your app: intro paths, people and company search, drop-in web components, and a setup CLI.",
   "keywords": [
     "village",
@@ -51,15 +51,6 @@
     },
     "./package.json": "./package.json"
   },
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "generate": "openapi-typescript https://api.village.ai/v2/docs/openapi.json -o src/generated/api.ts --default-non-nullable=false",
-    "generate:local": "openapi-typescript ../../apps/backend-main/src/api/v2/docs/openapi.json -o src/generated/api.ts --default-non-nullable=false",
-    "prepublishOnly": "pnpm run build",
-    "test": "vitest run",
-    "type-check": "tsc --noEmit",
-    "check:package": "pnpm run build && tsc -p tests/consumer/tsconfig.json"
-  },
   "dependencies": {
     "openapi-fetch": "^0.15.0"
   },
@@ -74,6 +65,7 @@
   "devDependencies": {
     "@testing-library/react": "^16.3.0",
     "@types/react": "^19.1.0",
+    "@types/react-dom": "^19.3.0",
     "jsdom": "^26.1.0",
     "openapi-typescript": "^7.10.0",
     "react": "^19.1.0",