@villagehq/sdk 0.1.0-beta.0 → 0.2.0-beta.1

package/AGENTS.md

@@ -0,0 +1,455 @@
+# Build on Village
+
+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` (SDK version `0.2.0-beta.1`).
+- 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. Quick start
+
+Build and verify locally first. No Village account, human approval, card, or real network is needed until Going live.
+
+```bash
+npm install @villagehq/sdk@0.2.0-beta.1
+```
+
+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.
+
+**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
+```
+
+For payer `app`, use:
+
+```dotenv
+NEXT_PUBLIC_VILLAGE_PUBLISHABLE_KEY=pk_test_village_demo_app
+VILLAGE_SECRET_KEY=sk_test_village_demo_app
+```
+
+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.
+
+## 3. Who pays
+
+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.
+
+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 ?? '',
+});
+
+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
+
+export function WarmIntros({ company }: { company: string }) {
+  return (
+    <section>
+      <village-connect />
+      <village-facepile company={company} />
+      <village-paths company={company} onvillage-path-select={(event) => askForIntro(event.detail)} />
+    </section>
+  );
+}
+```
+
+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. 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
+import { createVillageApp } from '@villagehq/sdk/server';
+
+const villageApp = createVillageApp({
+  secretKey: process.env.VILLAGE_SECRET_KEY ?? '',
+});
+
+export async function POST(request: Request) {
+  const user = await requireSignedInUser(request); // your auth: return 401 when signed out
+  const { token } = await villageApp.tokens.create({ id: user.id, email: user.email });
+  return Response.json({ token });
+}
+```
+
+The browser asks your route for it. Create the client per signed-in user:
+
+```tsx
+'use client';
+
+import { createVillage } from '@villagehq/sdk';
+import { defineVillageElements } from '@villagehq/sdk/elements';
+import type {} 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 ?? '';
+}
+
+function createUserVillage() {
+  const village = createVillage({
+    publishableKey: process.env.NEXT_PUBLIC_VILLAGE_PUBLISHABLE_KEY ?? '',
+    token: readVillageToken,
+  });
+  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
+  return (
+    <>
+      <village-connect />
+      <village-facepile company={company} />
+    </>
+  );
+}
+```
+
+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.1';
+  import { defineVillageElements } from 'https://esm.sh/@villagehq/sdk@0.2.0-beta.1/elements';
+
+  const village = createVillage({ publishableKey: 'pk_test_village_demo_user' }); // a publishable key is public
+  defineVillageElements(village);
+</script>
+
+<village-connect></village-connect>
+<village-facepile company="stripe.com"><span slot="empty">No warm intros yet</span></village-facepile>
+```
+
+Pin the version in the URL.
+
+### Server only (payer `app`)
+
+```ts
+import { createVillageApp } from '@villagehq/sdk/server';
+
+const villageApp = createVillageApp({ secretKey: process.env.VILLAGE_SECRET_KEY ?? '' });
+const member = villageApp.as({ id: user.id, email: user.email });
+
+const { status } = await member.user.get();
+if (status === 'ready' || status === 'needs_attention') {
+  const page = await member.companies.paths('stripe.com', { degrees: [1, 2], limit: 10 });
+}
+```
+
+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:
+
+- [ ] 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.
+- [ ] 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 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
+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`                       | The network has not been synced, or sync is unfinished                               | Connect/sync if needed, then show progress; use `error.syncUrl` when present                       |
+| <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.1 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:
+
+| `status`          | Meaning                                              | Render                                              |
+| ----------------- | ---------------------------------------------------- | --------------------------------------------------- |
+| `signed_out`      | Payer `user`: nobody signed in, or the session ended | A button that calls `village.connect()`             |
+| `not_connected`   | Payer `app`: no Village network linked yet           | A button that calls `village.connect()`             |
+| `syncing`         | Importing the network; paths come soon               | Progress                                            |
+| `ready`           | Everything works                                     | The feature                                         |
+| `needs_attention` | Works on older data; an integration needs re-auth    | The feature, plus "Reconnect" → `village.connect()` |
+
+`isNetworkReady(user)` is `true` for `ready` and `needs_attention`. Call `connect()` from a click: browsers block popups otherwise.
+
+### Elements
+
+Register once with `defineVillageElements(village)` (from `@villagehq/sdk/elements`).
+
+| Element              | Attributes                                                        | Shows                                                                                                 |
+| -------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `<village-connect>`  | none                                                              | The connect button, sync progress, or its default slot when ready (fallback text "Village connected") |
+| `<village-facepile>` | `company` (domain, URL or LinkedIn company URL)                   | Avatars of people who can introduce you, `+N`, and the strength label                                 |
+| `<village-paths>`    | `company` or `person` (LinkedIn URL or slug), `limit` (default 5) | A list of introducers; each is a button                                                               |
+
+Every element sets `state` and `data-state` to its current state: `loading`, `signed_out`, `not_connected`, `not_synced`, `out_of_credits`, `none`, `found`, `error` (`<village-connect>` uses the user statuses). Its root is an `aria-live` region; images carry the person's name as `alt`.
+
+**Customize**, in increasing control:
+
+```css
+village-facepile {
+  --village-avatar-size: 32px;
+  --village-accent: #0f766e; /* buttons, initials, focus ring */
+  --village-radius: 6px; /* buttons and list items */
+  --village-font: inherit; /* the default */
+}
+village-facepile::part(avatar) {
+  border-radius: 6px;
+}
+village-paths::part(item):hover {
+  background: #f4f4f5;
+}
+village-facepile[state='none'] {
+  display: none;
+}
+village-facepile:not(:defined) {
+  display: inline-block;
+  min-height: 32px;
+} /* no layout shift */
+```
+
+Parts: `root`, `avatar`, `more`, `label`, `button`, `item`, `name`, `reason`.
+
+Slots (replace the default content):
+
+| Slot         | When                                                         |
+| ------------ | ------------------------------------------------------------ |
+| `loading`    | `loading`                                                    |
+| `signed-out` | `signed_out` and `not_connected` (default: a connect button) |
+| `action`     | The connect button's label                                   |
+| `empty`      | `none`                                                       |
+
+Events (bubbling, composed `CustomEvent`s):
+
+| Event                 | `detail`                                                                                                                                                            |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `village-path-select` | `{ person, introducer, degree, reason }`; `introducer` is `null` for someone the user knows directly. Each person is `{ name, initials, avatar_url, linkedin_url }` |
+| `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:
+
+```tsx
+<village-facepile
+  company="stripe.com"
+  className="[--village-accent:var(--color-teal-700)] [&::part(avatar)]:rounded-md"
+  onvillage-error={(event) => console.error(event.detail.error)}
+>
+  <span slot="empty" className="text-sm text-muted-foreground">
+    No warm intros yet
+  </span>
+</village-facepile>
+```
+
+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.
+
+### Stores, for your own UI
+
+Every element is built on a store. Use them for fully custom UI in any framework.
+
+```ts
+const intros = village.paths.check('stripe.com'); // facepile data
+const paths = village.paths.company('stripe.com', { limit: 10 });
+const personPaths = village.paths.person('linkedin.com/in/satyanadella');
+
+const stop = intros.subscribe((state) => render(state)); // called right away, then on every change
+intros.get(); // the current state, same object until it changes
+intros.refresh(); // fetch again
+stop();
+```
+
+```ts
+type PathsCheckState =
+  | { kind: 'loading' }
+  | { kind: 'signed_out' }
+  | { kind: 'not_connected' }
+  | { kind: 'not_synced' }
+  | { kind: 'out_of_credits'; payer: 'app' | 'user'; topupUrl: string | null }
+  | { kind: 'none' }
+  | { kind: 'found'; people: FacepilePerson[]; more: number; strength: number | null; strength_label: string | null }
+  | { kind: 'error'; error: VillageError };
+// paths.person / paths.company: the same, with { kind: 'found'; paths } instead.
+```
+
+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.
+
+React:
+
+```tsx
+import { useVillage } from '@villagehq/sdk/react';
+
+function IntroBadge({ company }: { company: string }) {
+  const state = useVillage(village.paths.check(company));
+  if (state.kind === 'found') return <span>{state.people.length + state.more} warm intros</span>;
+  if (state.kind === 'signed_out' || state.kind === 'not_connected') return <ConnectButton />;
+  return null;
+}
+```
+
+Also `useVillageUser(village)` → `{ user, status, isLoading, error, refresh }`, `useVillageConnect(village)` → `{ connect, isConnecting }`, and `<VillageGate village fallback>`.
+
+Vue:
+
+```ts
+import { onScopeDispose, shallowRef } from 'vue';
+import type { VillageStore } from '@villagehq/sdk';
+
+export function useVillageStore<State>(store: VillageStore<State>) {
+  const state = shallowRef(store.get());
+  onScopeDispose(store.subscribe((next) => (state.value = next)));
+  return state;
+}
+```
+
+Svelte (stores follow the Svelte store contract):
+
+```svelte
+<script>
+  const intros = village.paths.check('stripe.com');
+</script>
+{#if $intros.kind === 'found'}{$intros.strength_label}{/if}
+```
+
+Vanilla:
+
+```ts
+village.paths.check('stripe.com').subscribe((state) => {
+  badge.dataset.state = state.kind;
+  badge.textContent = state.kind === 'found' ? `${state.people.length + state.more} warm intros` : '';
+});
+```
+
+### Other calls
+
+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
+await village.companies.search({ prompt: 'fintech in NYC', scope: 'global' });
+await village.people.paths('satyanadella'); // null when Village doesn't know them
+await village.companies.paths('stripe.com', { degrees: [2, 3] });
+await village.people.enrich('satyanadella');
+await village.companies.enrich('stripe.com');
+```
+
+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.
+
+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.
+
+### Content Security Policy and popups
+
+```
+connect-src https://api.village.ai;
+img-src https:;                        # avatars come from several CDNs
+frame-src https://village.ai;          # payer app: the sync modal
+script-src https://esm.sh;             # only for the CDN import
+```
+
+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`.