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

package/AGENTS.md

@@ -0,0 +1,433 @@
+# 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`. The npm package `village` belongs to another company; never install it.
+- 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
+
+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.
+
+|                                   | 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                                |
+
+## 2. Set up
+
+```bash
+npm install @villagehq/sdk
+npx @villagehq/sdk init --name "Acme" --origin http://localhost:3000 --payer user   # or --payer app
+```
+
+`init` prints a URL and opens it. Your human signs in to Village and approves the app. Then `init`:
+
+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.
+
+It never prints a key. Don't paste keys into chat; read them from the environment.
+
+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`.
+
+**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.
+
+## 3. 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
+
+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:
+
+```ts
+// app/api/village/token/route.ts
+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) {
+  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,
+    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
+  return (
+    <>
+      <village-connect />
+      <village-facepile company={company} />
+    </>
+  );
+}
+```
+
+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.
+
+### 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';
+
+  const village = createVillage({ publishableKey: 'pk_test_…' }); // 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 });
+}
+```
+
+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.
+
+## 4. 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.
+
+## 5. 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 (section 6). Elements render in the browser only, which is fine: this data is per user.
+
+## 6. 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` : '';
+});
+```
+
+## 7. Other calls
+
+Each returns once, and throws a `VillageError`:
+
+```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');
+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
+
+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'));
+```
+
+## 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
+
+```
+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
+```
+
+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`.