@villagehq/sdk 0.0.0-stage → 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Village
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,254 @@
-# Temporary Holding Version
+# @villagehq/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Build apps on Village: who your users know, warm intro paths, people and company search, and network sync.
+
+```bash
+npm install @villagehq/sdk
+```
+
+## How it fits together
+
+Your server holds the secret key. It signs a token for each signed-in user. That token does everything else, from your server or from the browser.
+
+```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);
+  const { token } = await villageApp.tokens.create({ id: user.id, email: user.email });
+  return Response.json({ token });
+}
+```
+
+Get your keys from the [Village developer platform](https://village.ai/platform). `createVillageApp` refuses to run in a browser.
+
+In the browser, give the SDK a function that asks your server for that token:
+
+```ts
+async function readVillageToken() {
+  const response = await fetch('/api/village/token', { method: 'POST' });
+  if (!response.ok) throw new Error(`Token route answered ${response.status}`);
+  const { token } = await response.json();
+  return token;
+}
+```
+
+The SDK calls it once and again only when Village rejects the token. If it throws a `VillageError`, that error reaches your code as it is; anything else becomes `token_failed`.
+
+## The user's network
+
+Every Village feature depends on where the user's network is. Ask once, and the answer tells you what works:
+
+```ts
+import { createVillage } from '@villagehq/sdk';
+
+const village = createVillage({ token: readVillageToken });
+const user = await village.user.get();
+
+user.status; // 'not_connected' | 'syncing' | 'ready' | 'needs_attention'
+user.integrations; // [{ id, type: 'google', account: 'ada@gmail.com', status: 'needs_reauth', last_synced_at }]
+user.network_updated_at; // when intro paths were last rebuilt
+```
+
+| `status`          | What works                                                                                 | What to show                                                  |
+| ----------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------- |
+| `not_connected`   | Global people search. Enrichment too once `email` is set, meaning a Village user is linked | A "Connect your network" button that calls `village.sync()`   |
+| `syncing`         | Everything except intro paths. Network search may be partial                               | Progress, from `integrations`                                 |
+| `ready`           | Everything                                                                                 | The feature                                                   |
+| `needs_attention` | Everything, on older data                                                                  | "Reconnect" for the integration with `status: 'needs_reauth'` |
+
+`isNetworkReady(user)` is `true` for `ready` and `needs_attention`. Village can link your user to an account with a different email; compare `user.email` with the one you know if that matters.
+
+### Watch it change
+
+`village.user` works with whatever holds your state:
+
+```ts
+// Any JavaScript: checks every five seconds while the network syncs, and stops when nobody listens.
+const stop = village.user.subscribe(({ user, error }) => render(user));
+
+// A background job or an agent
+const user = await village.user.ready({ timeoutMs: 10 * 60_000 });
+
+// React Query or SWR
+useQuery({ queryKey: ['village-user'], queryFn: () => village.user.get() });
+useSWR('village-user', () => village.user.get());
+```
+
+### Network sync
+
+```ts
+const user = await village.sync();
+```
+
+Opens Village's sync modal and resolves with the fresh user when the modal closes. The user may have left before finishing, so check `user.status`. The modal needs a `full` token, which is the default. If your app reads status through its own server, call `openSyncModal({ token, appUrl })` and refresh your own way.
+
+## React
+
+`@villagehq/sdk/react` has no provider and no data library. Pass the client you created:
+
+```tsx
+import { createVillage } from '@villagehq/sdk';
+import { useVillageSync, useVillageUser, VillageGate } from '@villagehq/sdk/react';
+import { useState } from 'react';
+
+function createUserVillage() {
+  return createVillage({ token: readVillageToken });
+}
+
+// Render this only for a signed-in user, keyed by their id so a new user gets a new client.
+function VillageSection() {
+  const [village] = useState(createUserVillage);
+  return (
+    <VillageGate
+      village={village}
+      fallback={(user, error) => (error ? <Retry /> : <ConnectNetwork village={village} />)}
+    >
+      <IntroList village={village} company="stripe.com" />
+    </VillageGate>
+  );
+}
+
+function ConnectNetwork({ village }) {
+  const { status } = useVillageUser(village);
+  const sync = useVillageSync(village);
+  if (status === 'syncing') return <p>Importing your network…</p>;
+  return (
+    <button disabled={sync.isOpen} onClick={sync.open}>
+      Connect your network
+    </button>
+  );
+}
+```
+
+| Export                           | Returns                                                                                              |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `useVillageUser(village)`        | `user`, `status`, `isLoading`, `error`, `refresh()`. Follows `village.user`.                         |
+| `useVillageSync(village)`        | `open()`, `isOpen`. `open()` resolves with the fresh user.                                           |
+| `<VillageGate village fallback>` | Its children once the network is ready. `fallback` can be a function of the user and the last error. |
+
+Fetch everything else with your own data library and the client's methods. Calls that spend credits should keep their results and not retry on their own; in React Query that is `staleTime: Infinity, retry: false`.
+
+## Any JavaScript
+
+On your server, act as a user without passing tokens around:
+
+```ts
+const member = villageApp.as({ id: user.id, email: user.email });
+await member.user.get();
+```
+
+`token` takes a string or a function. A function is called once, and again if Village rejects the token. When the signed-in user or their grant changes, create a new client.
+
+### Search
+
+```ts
+const page = await village.people.search('CTOs in Berlin');
+
+page.results;
+page.hasMore;
+const nextPage = await page.next();
+
+for await (const person of page) {
+  // Every page, without repeats. Each page may spend credits.
+}
+```
+
+A string searches the user's network. Pass an object for anything else, such as `{ prompt, scope: 'global', limit: 25 }`. `village.companies.search` works the same way. `page.total` needs `include_counts: 'global'` in the request. Searches can take a minute, so the SDK waits up to two.
+
+### Intro paths
+
+Person and company arguments are plain strings.
+
+```ts
+await village.people.paths('linkedin.com/in/satyanadella'); // also a bare slug or a full URL
+await village.companies.checkPaths('stripe.com'); // fast: has_paths, count, score, avatars
+await village.companies.paths('stripe.com', { degrees: [2, 3], limit: 20 });
+```
+
+`people.paths` and `companies.paths` return `null` when Village doesn't know the person or company. `companies.checkPaths` returns `has_paths: false` instead.
+
+### Everything else
+
+```ts
+await village.people.enrich('satyanadella');
+await village.people.emails('satyanadella');
+await village.companies.enrich('stripe.com');
+
+await village.groups.create('Founders');
+await village.groups.join(inviteLink); // joining twice is fine
+await village.groups.leave(groupId); // 'left' | 'not_member' | 'admin_blocked'
+await village.relationships.import([{ identifier: linkedinUrl, score: 8 }]);
+
+const { data, error } = await village.api.GET('/v2/lists'); // any endpoint, fully typed
+```
+
+Responses keep the API's field names, so the [API reference](https://docs.village.ai) applies as written.
+
+### Helpers
+
+```ts
+import { initials, introducers, linkedinSlug, linkedinUrl, personName } from '@villagehq/sdk';
+```
+
+## Errors
+
+Every failure is a `VillageError`, except an abort you asked for.
+
+```ts
+import { isVillageError } from '@villagehq/sdk';
+
+try {
+  await village.people.paths(person);
+} catch (error) {
+  if (isVillageError(error, 'not_synced')) return <SyncPrompt />;
+  if (isVillageError(error, 'out_of_credits')) return <TopUp href={error.topupUrl} />;
+  throw error;
+}
+```
+
+| `code`                                         | Meaning                                              |
+| ---------------------------------------------- | ---------------------------------------------------- |
+| `not_connected`                                | The user hasn't connected Village. Call `sync()`.    |
+| `not_synced`                                   | The network sync hasn't finished.                    |
+| `out_of_credits`                               | The app is out of credits. See `error.topupUrl`.     |
+| `unauthorized`                                 | The key or token is invalid, or the app is inactive. |
+| `forbidden`                                    | The token can't do this.                             |
+| `not_found`, `conflict`, `bad_request`         | The API refused the request.                         |
+| `validation`                                   | The request is invalid. See `error.fields`.          |
+| `rate_limited`, `server`, `timeout`, `network` | Worth retrying. `error.isRetryable` is `true`.       |
+| `token_failed`                                 | Your token function threw. See `error.cause`.        |
+| `invalid_response`                             | Village returned an empty response.                  |
+
+`error.isExpected` is `true` for outcomes your UI should handle rather than report. Each error carries `requestId` and `traceId` for support.
+
+## Monitoring
+
+```ts
+createVillage({
+  token,
+  onRequest: ({ operation, status, durationMs, requestId, error }) => {
+    if (error && !error.isExpected) reportError(error, { operation, status, requestId });
+  },
+});
+```
+
+## Options
+
+| Option      | Default                  |                                  |
+| ----------- | ------------------------ | -------------------------------- |
+| `apiUrl`    | `https://api.village.ai` |                                  |
+| `appUrl`    | `https://village.ai`     | Where the sync modal loads from. |
+| `fetch`     | global `fetch`           | Takes a `Request`.               |
+| `onRequest` | none                     | Called for every request.        |
+
+`createVillageApp` takes the same options, with `secretKey` instead of `token`; its `appUrl` applies to the clients `as()` returns.
+
+Every method takes `{ signal, timeoutMs }` as its last argument.
+
+## Developing
+
+Regenerate the API types with `pnpm run generate` (live API) or `pnpm run generate:local` (this repo's backend, after `pnpm --dir ../../apps/backend-main run generate:openapi`). `pnpm run check:package` builds the package and type-checks a consumer against the output.

package/dist/core/display.d.ts

@@ -0,0 +1,20 @@
+import type { components } from '../generated/api.js';
+type Path = components['schemas']['Path'];
+type NamedPerson = {
+    full_name?: string | null;
+    first_name?: string | null;
+    last_name?: string | null;
+};
+export declare function personName({ full_name, first_name, last_name }: NamedPerson): string;
+export declare function initials(name: string): string;
+export declare function introducers(paths: readonly Path[]): {
+    name: string;
+    profile: {
+        first_name: string;
+        last_name: string;
+        linkedin_url: string;
+        headline: string;
+        avatar?: string;
+    };
+}[];
+export {};

package/dist/core/display.js

@@ -0,0 +1,27 @@
+const DIRECT_DEGREE = 1;
+const MAXIMUM_INITIALS = 2;
+export function personName({ full_name, first_name, last_name }) {
+    return full_name || [first_name, last_name].filter(Boolean).join(' ');
+}
+export function initials(name) {
+    return name
+        .trim()
+        .split(/\s+/)
+        .map((word) => word.charAt(0))
+        .join('')
+        .toUpperCase()
+        .slice(0, MAXIMUM_INITIALS);
+}
+export function introducers(paths) {
+    const seenIntroducers = new Set();
+    return paths.flatMap(({ degree, introducer }) => {
+        if (degree === DIRECT_DEGREE)
+            return [];
+        const name = personName(introducer.profile);
+        const introducerKey = introducer.profile.linkedin_url || name;
+        if (seenIntroducers.has(introducerKey))
+            return [];
+        seenIntroducers.add(introducerKey);
+        return [{ name, profile: introducer.profile }];
+    });
+}

package/dist/core/errors.d.ts

@@ -0,0 +1,31 @@
+export type VillageErrorCode = 'bad_request' | 'unauthorized' | 'out_of_credits' | 'forbidden' | 'not_connected' | 'not_found' | 'not_synced' | 'conflict' | 'validation' | 'rate_limited' | 'server' | 'timeout' | 'network' | 'token_failed' | 'invalid_response';
+export type VillageFieldError = {
+    field: string;
+    message: string;
+};
+type VillageErrorDetails = {
+    code: VillageErrorCode;
+    message: string;
+    status?: number | null;
+    requestId?: string | null;
+    traceId?: string | null;
+    fields?: VillageFieldError[];
+    topupUrl?: string | null;
+    syncUrl?: string | null;
+    cause?: unknown;
+};
+export declare class VillageError extends Error {
+    readonly code: VillageErrorCode;
+    readonly status: number | null;
+    readonly requestId: string | null;
+    readonly traceId: string | null;
+    readonly fields: VillageFieldError[];
+    readonly topupUrl: string | null;
+    readonly syncUrl: string | null;
+    constructor({ code, message, status, requestId, traceId, fields, topupUrl, syncUrl, cause, }: VillageErrorDetails);
+    get isExpected(): boolean;
+    get isRetryable(): boolean;
+}
+export declare function isVillageError(error: unknown, code?: VillageErrorCode): error is VillageError;
+export declare function toVillageError(response: Response, body: unknown): VillageError;
+export {};

package/dist/core/errors.js

@@ -0,0 +1,93 @@
+const EXPECTED_CODES = new Set([
+    'not_connected',
+    'not_found',
+    'not_synced',
+    'conflict',
+    'out_of_credits',
+]);
+const RETRYABLE_CODES = new Set(['rate_limited', 'server', 'timeout', 'network']);
+export class VillageError extends Error {
+    code;
+    status;
+    requestId;
+    traceId;
+    fields;
+    topupUrl;
+    syncUrl;
+    constructor({ code, message, status = null, requestId = null, traceId = null, fields = [], topupUrl = null, syncUrl = null, cause, }) {
+        super(message, { cause });
+        this.name = 'VillageError';
+        this.code = code;
+        this.status = status;
+        this.requestId = requestId;
+        this.traceId = traceId;
+        this.fields = fields;
+        this.topupUrl = topupUrl;
+        this.syncUrl = syncUrl;
+    }
+    get isExpected() {
+        return EXPECTED_CODES.has(this.code);
+    }
+    get isRetryable() {
+        return RETRYABLE_CODES.has(this.code);
+    }
+}
+export function isVillageError(error, code) {
+    if (!(error instanceof VillageError))
+        return false;
+    return code === undefined || error.code === code;
+}
+const CODE_BY_STATUS = {
+    400: 'bad_request',
+    401: 'unauthorized',
+    402: 'out_of_credits',
+    403: 'forbidden',
+    404: 'not_found',
+    409: 'conflict',
+    422: 'validation',
+    429: 'rate_limited',
+};
+const NOT_CONNECTED_DETAIL = /user not found or inactive|requires a registered village account/i;
+const NOT_SYNCED_TYPE = 'network_not_synced';
+const FIRST_SERVER_ERROR_STATUS = 500;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function readString(source, key) {
+    if (!isRecord(source))
+        return null;
+    const value = source[key];
+    return typeof value === 'string' ? value : null;
+}
+function readFields(apiError) {
+    if (!isRecord(apiError) || !Array.isArray(apiError.errors))
+        return [];
+    return apiError.errors.flatMap((fieldError) => {
+        const message = readString(fieldError, 'message');
+        return message === null ? [] : [{ field: readString(fieldError, 'field') ?? '', message }];
+    });
+}
+function readCode(status, type, detail) {
+    if (type === NOT_SYNCED_TYPE)
+        return 'not_synced';
+    if (detail !== null && NOT_CONNECTED_DETAIL.test(detail))
+        return 'not_connected';
+    if (status >= FIRST_SERVER_ERROR_STATUS)
+        return 'server';
+    return CODE_BY_STATUS[status] ?? 'bad_request';
+}
+export function toVillageError(response, body) {
+    const apiError = isRecord(body) ? body.error : null;
+    const detail = readString(apiError, 'detail') ?? readString(body, 'message') ?? `Village responded with ${response.status}.`;
+    const meta = isRecord(apiError) ? apiError.meta : null;
+    return new VillageError({
+        code: readCode(response.status, readString(apiError, 'type'), detail),
+        message: detail,
+        status: response.status,
+        requestId: response.headers.get('x-request-id'),
+        traceId: readString(apiError, 'trace_id'),
+        fields: readFields(apiError),
+        topupUrl: readString(body, 'topup_url'),
+        syncUrl: readString(meta, 'sync_url'),
+    });
+}

package/dist/core/identifiers.d.ts

@@ -0,0 +1,16 @@
+export type PersonIdentifier = {
+    linkedin_url: string;
+} | {
+    url: string;
+};
+export type CompanyIdentifier = {
+    domain: string;
+} | {
+    linkedin_url: string;
+} | {
+    url: string;
+};
+export declare function linkedinSlug(profile: string | null | undefined): string | null;
+export declare function linkedinUrl(slug: string): string;
+export declare function toPersonIdentifier(person: string): PersonIdentifier;
+export declare function toCompanyIdentifier(company: string): CompanyIdentifier;

package/dist/core/identifiers.js

@@ -0,0 +1,65 @@
+import { VillageError } from './errors.js';
+const LINKEDIN_HOST = 'linkedin.com';
+const LINKEDIN_PROFILE_PATH = /^\/in\/([^/]+)\/?$/;
+const BARE_DOMAIN_PATH = '/';
+function parseUrl(value) {
+    const trimmed = value.trim();
+    try {
+        return new URL(trimmed.includes('://') ? trimmed : `https://${trimmed}`);
+    }
+    catch {
+        return null;
+    }
+}
+function isLinkedinUrl(url) {
+    const host = url.hostname.toLowerCase();
+    return host === LINKEDIN_HOST || host.endsWith(`.${LINKEDIN_HOST}`);
+}
+function decodeSlug(encodedSlug) {
+    try {
+        return decodeURIComponent(encodedSlug);
+    }
+    catch {
+        return encodedSlug;
+    }
+}
+function requireValue(value, label) {
+    const trimmed = value.trim();
+    if (trimmed)
+        return trimmed;
+    throw new VillageError({ code: 'bad_request', message: `Enter a ${label}.` });
+}
+export function linkedinSlug(profile) {
+    if (!profile)
+        return null;
+    const url = parseUrl(profile);
+    if (!url || !isLinkedinUrl(url))
+        return null;
+    const encodedSlug = LINKEDIN_PROFILE_PATH.exec(url.pathname)?.[1];
+    return encodedSlug ? decodeSlug(encodedSlug).toLowerCase() : null;
+}
+export function linkedinUrl(slug) {
+    return `https://www.linkedin.com/in/${encodeURIComponent(slug)}`;
+}
+export function toPersonIdentifier(person) {
+    const value = requireValue(person, 'LinkedIn profile or URL');
+    const isBareSlug = !value.includes('.') && !value.includes('/');
+    if (isBareSlug)
+        return { linkedin_url: linkedinUrl(value) };
+    const url = parseUrl(value);
+    if (url && isLinkedinUrl(url))
+        return { linkedin_url: url.href };
+    return { url: url?.href ?? value };
+}
+export function toCompanyIdentifier(company) {
+    const value = requireValue(company, 'company domain or URL');
+    const url = parseUrl(value);
+    if (!url)
+        return { url: value };
+    if (isLinkedinUrl(url))
+        return { linkedin_url: url.href };
+    const isBareDomain = url.pathname === BARE_DOMAIN_PATH && !url.search && !url.hash;
+    if (isBareDomain)
+        return { domain: url.hostname.toLowerCase().replace(/^www\./, '') };
+    return { url: url.href };
+}

package/dist/core/pages.d.ts

@@ -0,0 +1,23 @@
+type PageResponse = {
+    pagination: {
+        cursor?: string | null;
+        has_next_page: boolean;
+    };
+};
+type PageSource<Response extends PageResponse, Result> = {
+    response: Response;
+    results: Result[];
+    total: number | null;
+    keyOf: (result: Result) => unknown;
+    fetchNext: (cursor: string) => Promise<Page<Response, Result>>;
+};
+export type Page<Response, Result> = AsyncIterable<Result> & {
+    response: Response;
+    results: Result[];
+    total: number | null;
+    cursor: string | null;
+    hasMore: boolean;
+    next: () => Promise<Page<Response, Result> | null>;
+};
+export declare function createPage<Response extends PageResponse, Result>({ response, results, total, keyOf, fetchNext, }: PageSource<Response, Result>): Page<Response, Result>;
+export {};

package/dist/core/pages.js

@@ -0,0 +1,28 @@
+export function createPage({ response, results, total, keyOf, fetchNext, }) {
+    const cursor = response.pagination.cursor || null;
+    const hasMore = response.pagination.has_next_page && cursor !== null;
+    const next = async () => (hasMore && cursor ? fetchNext(cursor) : null);
+    const page = {
+        response,
+        results,
+        total,
+        cursor,
+        hasMore,
+        next,
+        async *[Symbol.asyncIterator]() {
+            const seenKeys = new Set();
+            let current = page;
+            while (current) {
+                for (const result of current.results) {
+                    const key = keyOf(result);
+                    if (seenKeys.has(key))
+                        continue;
+                    seenKeys.add(key);
+                    yield result;
+                }
+                current = await current.next();
+            }
+        },
+    };
+    return page;
+}

package/dist/core/sync-modal.d.ts

@@ -0,0 +1,6 @@
+type SyncModalOptions = {
+    token: string;
+    appUrl: string;
+};
+export declare function openSyncModal(options: SyncModalOptions): Promise<void>;
+export {};