@awesomate/sdk 0.12.0 → 0.13.0

package/README.md

@@ -1,215 +1,48 @@
 # @awesomate/sdk
 
-Read your own Awesomate data from Node. Version 0.1 reads your **contact list**: query it,
-page through it, count it, with TypeScript types generated from your own fields.
+Build apps on your own Awesomate data. Sign your customers in, show them their records as they change, and let them act, with the rules about who sees what kept in your own database.
+
+**Docs: https://hub.awesomate.ai/docs/sdk/** (a quickstart, a tutorial that builds a customer portal, guides, and a reference generated from this package's code). For AI tools: [llms.txt](https://hub.awesomate.ai/docs/sdk/llms.txt).
 
 ```bash
 npm install @awesomate/sdk
-npx @awesomate/sdk types --out awesomate.d.ts   # uses your Awesomate MCP connection, or AWESOMATE_TOKEN
-```
-
-```ts
-import { createClient } from '@awesomate/sdk';
-import './awesomate'; // the generated file: every query below is typed
-
-const db = createClient({ token: process.env.AWESOMATE_TOKEN! });
-
-// People who joined this year, newest first
-const { rows, next, applied } = await db.query('contact', {
-  where: { created_at: { gte: '$YEAR_BEGIN' } },
-  orderBy: ['created_at', 'desc'],
-  limit: 50,
-});
-
-// Everyone tagged VIP in one suburb, a page at a time
-for await (const person of db.queryAll('contact', { where: { tags: 'VIP', suburb: 'Carindale' }, select: ['first_name', 'email'] })) {
-  console.log(person.first_name, person.email);
-}
-
-const one = await db.get('contact', rows[0].id); // null if there is none
-const byPlan = await db.aggregate({ measures: [{ column: 'people', agg: 'count' }], dimensions: ['plan'] });
 ```
 
-## The business itself
-
-```js
-const biz = await db.business();
-biz.name;                                  // 'Acme Plumbing'
-for (const g of biz.groups) for (const f of g.facts) console.log(g.title, f.label, f.value, f.status, f.source);
-biz.completeness;                          // { core_set: 7, core_total: 8, missing_core: ['logo'] }
-const waiting = await db.businessSuggestions(); // details waiting for the owner's yes
-```
-
-The details Awesomate keeps about the business: name, what it does, voice, colours, how customers reach it. Each one says where it came from. `confirmed` details are the ones agents and automations use. A `suggestion` waits for the owner, who confirms it on Knowledge, Your business in the hub. This needs the account's token, on every plan, never an app key.
-
-## Writing app data (Support Plus and above)
-
-Define the tables an app keeps, then write to them. There's no migration and no SQL; every value is
-checked against the kind (types, choices, required attributes and links).
-
-```ts
-await db.defineKind({
-  key: 'job', label: 'Job', label_plural: 'Jobs',
-  attributes: [
-    { key: 'title', type: 'text', required: true, readable_by_ai: true },
-    { key: 'status', type: 'choice', choices: ['open', 'booked', 'done'], readable_by_ai: true },
-  ],
-  links: [{ key: 'customer', to: 'contact' }],
-});
-const id = await db.write('job', { title: 'Possum in the roof', status: 'open' }, { links: { customer: contactId } });
-await db.write('job', { status: 'booked' }, { id });            // values not given stay
-const jobs = await db.query('job', { where: { customer_id: contactId } });
-await db.archive('job', id);
-```
-
-Only attributes marked `readable_by_ai` come back from `query` and `get`; a `sensitive` attribute
-can never be readable. Contacts themselves are not written this way: the contact list keeps its
-own consent rules.
-
-## What you can read
-
-The built-in contact details (name, email, phone, company, tags, when they were added) and only
-the fields you have marked **readable by AI** under Contacts, Your fields in the hub. A field
-marked sensitive is never readable. `db.schema()` lists the columns and says how many are hidden.
-
-## The where grammar
-
-`{ column: value }` means equals; `{ column: { op: value } }` uses an operator: `eq`, `neq`, `gt`,
-`gte`, `lt`, `lte`, `in`, `nin`, `contains`, `startsWith`, `like`, `ilike`, `isNull`, and for lists
-(tags) `has`, `hasAny`, `hasAll`, `isEmpty`. Combine with `and: [...]`, `or: [...]`, `not: {...}`.
-A date (`'2026-09-30'`) against a timestamp means that whole day in your time zone; time
-variables `$TODAY`, `$WEEK_BEGIN`, `$MONTH_BEGIN`, `$QUARTER_BEGIN`, `$YEAR_BEGIN` and `$FY_BEGIN`
-(1 July) take an offset in their own unit (`$MONTH_BEGIN-1` is the start of last month).
-
-## Errors
-
-Every failure is an `AwesomateError` with a `code`: `unauthenticated`, `forbidden`, `not_found`,
-`validation` (with `field`), `consent_blocked`, `rate_limited`, `conflict` or `unavailable`.
-
-## Keep the token on a server
-
-The token is your account's hosting token. Use it in a server, a script or a scheduled job, never
-in a browser. For a browser, sign your app's own users in (below).
-
-## Your app's server: a key of its own
-
-An app's own server, or an n8n workflow, should not carry the account's token. Give it a server
-key instead: Claude makes one with `awesomate_crm_apps` (`create_key`), read or write, for every
-kind or only the ones it names. The key is shown once; put it in the server's environment.
-
-```ts
-const db = createClient({ token: process.env.AWESOMATE_APP_KEY! }); // ak_...
-const { rows } = await db.query('job', { where: { status: 'booked' } });
-await db.write('job', { status: 'done' }, { id: rows[0].id });
-await db.call('book_job', { customer, title: 'Gutter clean', status: 'booked' });
-```
-
-A key reads and writes records and runs saved queries and recipes, only for its kinds (a recipe
-that writes anything else is refused). It reads every attribute of an app kind, and the contact
-list only as Claude does. Writes need Support Plus and above. It cannot change kinds, rules,
-queries or recipes, and it never works from a browser. Revoking a key stops it at once; switching
-the app off stops all of them. From n8n, send it as `Authorization: Bearer ak_...` to
-`https://hub.awesomate.ai/api/sdk/v1/server/rows/query` (and `/call`, `/queries/<key>/run`).
-
-## Your app's users sign in (Pro and above)
-
-Set the app up first (Claude Code: `awesomate_crm_apps`): its name, the origins it runs on, and
-whether anyone may sign up or only people you add. That gives you a publishable key, which is not a
-secret. Then say who may read and change each kind (`awesomate_crm_kinds`, `set_access`), for
-example members read jobs whose customer is them and the memos on those jobs.
+## In a web page: your app's people (Pro and above)
 
 ```ts
 import { createAppClient } from '@awesomate/sdk';
 
-const app = createAppClient({ publishableKey: 'pk_...' });
+const app = createAppClient({ publishableKey: 'pk_...' }); // not a secret
 
-// Render on every change of person: signed in, signed out, a new role.
-app.auth.onChange((u) => render(u));
-app.auth.onSignInError((err) => showMessage(err.message));
-
-// The sign-in page: an email link, no password. The answer is the same for any address.
+app.auth.onChange((user) => render(user));
+render(await app.auth.user()); // someone already signed in on this device
 await app.auth.signInWithLink(email, { redirectTo: location.href });
 
-// Everywhere else: the same calls as the server client, as this person.
-const { rows } = await app.query('job', { orderBy: ['created_at', 'desc'] });
-await app.write('forum_post', { body: 'Booked for Tuesday' }, { links: { job: rows[0].id } });
-await app.auth.signOut();
-```
-
-The link signs them in by itself. In a browser the client takes the link from the address bar,
-on load or when it arrives in a tab that is already open (only the part after `#` changes, so
-the page does not reload), clears it at once and tells `onChange`. A link that has expired or
-was already used goes to `onSignInError`. `await app.auth.completeSignIn()` still works and
-returns the same sign-in, never a second exchange. Pass `handleSignInLinks: false` to take links
-yourself. `onChange` hears about people, not tokens: the routine token refresh is silent.
-
-### Lists that keep themselves current
-
-```ts
-const stop = app.live('job', { orderBy: ['created_at', 'desc'], limit: 50 }, (rows) => render(rows));
-// later: stop();
+// As the signed-in person: the database applies the account's rules.
+const stop = app.live('job', { orderBy: ['created_at', 'desc'] }, (rows) => render(rows));
+await app.call('accept_quote', { job: job.id });
 ```
 
-`live()` calls you with the whole list at first and again whenever a row in it is added, changed,
-removed, or stops being one this person may read (a job moved to another customer leaves their
-list, with its memos). Changes made anywhere reach the list: in this app, by your team in Claude
-Code, by an n8n workflow. One connection serves every list on the client; it reconnects by itself
-and takes a fresh copy when it does. Up to 200 rows a list and 20 lists a connection. Pass
-`{ onRows, onError }` to hear about a list the server refused (a column that does not exist).
-Outside a browser, give it a WebSocket: `createAppClient({ publishableKey, WebSocket })`.
-
-While a list is open in a browser, the connection also tells the hub whether the tab is in front.
-If the account switched on reply emails, someone looking at the app isn't emailed about a reply,
-but a tab left open in the background doesn't count as looking, and closing the last one counts as
-leaving straight away.
-
-A conversation can also show who else has it open and who is typing:
+## On a server: your account's data
 
 ```ts
-const room = app.here(job.id, (people) => showWhoIsHere(people)); // [{ user, role, name, typing, assistant? }]
-messageBox.oninput = () => room.typing(true);   // sent at most every few seconds
-messageBox.onblur = () => room.typing(false);
-// later: room.leave();
-```
-
-Everyone else with that record open and their tab in front is listed once, and the app's
-assistant appears while it writes a reply. The hub checks this person may read the record, and
-keeps checking; a refusal goes to the optional third argument, `onError`. Nothing is stored.
-
-### Staff find a customer
+import { createClient } from '@awesomate/sdk';
 
-People in an app read no contacts but their own, so by default staff cannot put a job under a
-customer. Switch it on per app for the roles that need it (`awesomate_crm_apps`,
-`customer_lookup`, never the role customers sign in with). Those roles can then search by name or
-email and point a record at any customer:
+const db = createClient({ token: process.env.AWESOMATE_TOKEN! }); // a secret: never in a browser
 
-```ts
-const [jo] = await app.lookupCustomers({ q: 'jo' });           // or { ids: [...] }, up to 50
-await app.write('job', { title: 'Gutters' }, { links: { customer: jo.id } });
+const { rows, next } = await db.query('contact', { where: { created_at: { gte: '$YEAR_BEGIN' } }, limit: 50 });
+await db.write('job', { title: 'Possum in the roof', status: 'open' }, { links: { customer: rows[0].id } });
 ```
 
-Name, email and phone only, and nothing the owner marked sensitive. Anyone else is refused.
-
-An attribute can also be visible to some roles only (`awesomate_crm_kinds`, `set_visibility`, for
-example a cost only `staff` see). For everyone else it comes back `null` and a write that sets it
-is refused, whatever the app asks for.
-
-Some things a customer should do without being able to edit the record: accept their quote, say.
-Save it as a write recipe and open it to their role (`awesomate_crm_recipes`, `run_by`, Pro and
-above), then:
+Types for your own account's kinds, saved queries and recipes:
 
-```ts
-await app.call('accept_quote', { job: job.id });
+```bash
+npx @awesomate/sdk types --out awesomate.d.ts
 ```
 
-The database lets them do exactly the recipe's steps: only its params take their values, every
-other value is fixed, and an existing record must be one they can already read. A recipe not
-opened to their role is "not found".
+## What changed
 
-The rules are kept in your own database, which applies them to every read and write, so a mistake
-in the app cannot show anyone more than their role allows. A disabled person is refused on their
-next call. Sessions are kept in `localStorage`; in a Capacitor app pass `storage` (Preferences) and
-call `completeSignIn(url)` with the deep link that opened the app. Your own server can verify
-`await app.auth.accessToken()` against `https://hub.awesomate.ai/api/sdk/v1/jwks.json`.
+See the [changelog](https://hub.awesomate.ai/docs/sdk/changelog/).
 
 MIT licence.

package/dist/index.d.ts

@@ -18,15 +18,19 @@
  *   const stop = app.live('job', {}, (rows) => render(rows)); // and kept current as they change
  *
  * The account's token (a hosting PAT with crm:read) is a secret: use it on a server, never in a
- * browser. End-user sign-in for browser apps comes in a later version. Reading and running saved
- * queries works on every plan; writing app data (kinds, records, saved queries, recipes) needs
- * crm:write, Support Plus and above.
+ * browser. Reading and running saved queries works on every plan; writing app data (kinds,
+ * records, saved queries, recipes) needs crm:write, Support Plus and above.
+ *
+ * Docs: https://hub.awesomate.ai/docs/sdk/
  */
-export declare const VERSION = "0.7.0";
+/** This package's version, sent to the hub with every server call. */
+export declare const VERSION = "0.13.0";
 /** Augmented by the generated awesomate.d.ts, so each kind's rows are typed. */
 export interface Kinds {
 }
+/** A kind's name: one of yours once the generated types are imported, any string before then. */
 export type KindName = [keyof Kinds] extends [never] ? string : Extract<keyof Kinds, string>;
+/** A row of kind K: typed from the generated file, or a plain record before then. */
 export type RowOf<K> = K extends keyof Kinds ? Kinds[K] : Record<string, unknown>;
 /** Augmented by the generated awesomate.d.ts: each saved query's params and row. */
 export interface Queries {
@@ -34,18 +38,24 @@ export interface Queries {
 /** Augmented by the generated awesomate.d.ts: each write recipe's args. */
 export interface Recipes {
 }
+/** A saved query's key: one of yours once the generated types are imported, any string before then. */
 export type QueryName = [keyof Queries] extends [never] ? string : Extract<keyof Queries, string>;
+/** The parameters saved query Q takes. */
 export type ParamsOf<Q> = Q extends keyof Queries ? (Queries[Q] extends {
     params: infer P;
 } ? P : never) : Record<string, unknown>;
+/** The row saved query Q returns. */
 export type QueryRowOf<Q> = Q extends keyof Queries ? (Queries[Q] extends {
     row: infer R;
 } ? R : never) : Record<string, unknown>;
+/** A write recipe's key: one of yours once the generated types are imported, any string before then. */
 export type RecipeName = [keyof Recipes] extends [never] ? string : Extract<keyof Recipes, string>;
+/** The arguments recipe R takes. */
 export type ArgsOf<R> = R extends keyof Recipes ? (Recipes[R] extends {
     args: infer A;
 } ? A : never) : Record<string, unknown>;
-type TextOps<V extends string> = {
+/** Filters on a text column. gt/gte/lt/lte also take time variables such as `$YEAR_BEGIN` on dates. */
+export type TextOps<V extends string> = {
     eq?: V | null;
     neq?: V | null;
     in?: V[];
@@ -60,7 +70,8 @@ type TextOps<V extends string> = {
     lte?: string;
     isNull?: boolean;
 };
-type NumberOps = {
+/** Filters on a number column. */
+export type NumberOps = {
     eq?: number | null;
     neq?: number | null;
     gt?: number;
@@ -71,20 +82,29 @@ type NumberOps = {
     nin?: number[];
     isNull?: boolean;
 };
-type BoolOps = {
+/** Filters on a yes/no column. */
+export type BoolOps = {
     eq?: boolean | null;
     neq?: boolean | null;
     isNull?: boolean;
 };
-type ListOps<E> = {
+/** Filters on a list column (tags, choices): has one, any or all, or is empty. */
+export type ListOps<E> = {
     has?: E;
     hasAny?: E[];
     hasAll?: E[];
     isEmpty?: boolean;
     isNull?: boolean;
 };
-/** What one column accepts in a where clause: a bare value means equals (a list means in, or has all for a list column). */
-export type ColumnFilter<V> = V extends Array<infer E> ? E | E[] | ListOps<E> : V extends number ? V | V[] | null | NumberOps : V extends boolean ? V | null | BoolOps : V extends string ? V | V[] | null | TextOps<V> : unknown;
+/**
+ * What one column accepts in a where clause: a bare value means equals (a list means in, or has
+ * all for a list column). The checks are wrapped in [ ] so a choice column ('open' | 'booked')
+ * is taken whole: `{ in: ['open', 'booked'] }` is one filter, not one per choice.
+ */
+export type ColumnFilter<V> = [
+    V
+] extends [Array<infer E>] ? E | E[] | ListOps<E> : [V] extends [number] ? V | V[] | null | NumberOps : [V] extends [boolean] ? V | null | BoolOps : [V] extends [string] ? V | V[] | null | TextOps<V> : unknown;
+/** A where clause: a filter per column, combined with and, or and not. */
 export type Where<T> = {
     [C in keyof T]?: ColumnFilter<NonNullable<T[C]>>;
 } & {
@@ -96,7 +116,9 @@ export type Where<T> = {
 export type SortableColumn<T> = Extract<{
     [C in keyof T]: NonNullable<T[C]> extends unknown[] ? never : C;
 }[keyof T], string>;
+/** How a query picks, orders, pages and narrows rows. */
 export interface QueryOptions<T, S extends keyof T = keyof T> {
+    /** Which rows: a filter per column. */
     where?: Where<T>;
     /** One sort column; id breaks ties. Default: created_at, newest first. */
     orderBy?: [SortableColumn<T>, 'asc' | 'desc'];
@@ -104,10 +126,12 @@ export interface QueryOptions<T, S extends keyof T = keyof T> {
     limit?: number;
     /** The previous page's next. Repeat the same orderBy. */
     after?: string;
+    /** Only these columns. Default: every column this caller may read. */
     select?: S[];
     /** IANA zone for dates and time variables. Default Australia/Sydney. */
     tz?: string;
 }
+/** What the hub assumed for a query (order, limit, time zone, what each time variable meant), so it can be said back. */
 export interface Applied {
     order_by: [string, 'asc' | 'desc'];
     limit: number;
@@ -115,33 +139,58 @@ export interface Applied {
     time_variables: Record<string, string>;
     defaults: string[];
 }
+/** One page of rows. Pass `next` as `after` for the following page. */
 export interface Page<R> {
+    /** The rows on this page. */
     rows: R[];
+    /** Where the next page starts, or null on the last page. */
     next: string | null;
+    /** Rows on this page. */
     count: number;
     /** What the hub assumed; repeat it to whoever asked. */
     applied: Applied;
+    /** Columns left out: not marked readable by AI (to the account's token), or sensitive. */
     hidden: {
         not_readable_by_ai: number;
         sensitive: number;
     };
+    /** When the hub read the rows. */
     asAt: string;
 }
 declare const ERROR_CODES: readonly ["unauthenticated", "forbidden", "not_found", "validation", "consent_blocked", "rate_limited", "conflict", "unavailable"];
+/**
+ * Why a call failed, one of a fixed list: unauthenticated, forbidden, not_found, validation,
+ * consent_blocked, rate_limited, conflict, unavailable. The hub's own detail is in serverCode.
+ */
 export type ErrorCode = (typeof ERROR_CODES)[number];
+/**
+ * Every failure from the hub. `message` is for you, the developer; `personMessage`, when the hub
+ * sent one, is the sentence to show the person using your app.
+ */
 export declare class AwesomateError extends Error {
+    /** Why it failed. */
     readonly code: ErrorCode;
+    /** The HTTP status, or 0 when the SDK refused before sending. */
     readonly status: number;
     /** The column or parameter a validation error is about. */
     readonly field?: string | undefined;
     /** The hub's own code, unmapped. */
     readonly serverCode?: string | undefined;
-    constructor(code: ErrorCode, message: string, status: number, 
+    /** A sentence for the person using the app, when the hub sent one (a refused voice call: "You've used today's voice time"). */
+    readonly personMessage?: string | undefined;
+    constructor(
+    /** Why it failed. */
+    code: ErrorCode, message: string, 
+    /** The HTTP status, or 0 when the SDK refused before sending. */
+    status: number, 
     /** The column or parameter a validation error is about. */
     field?: string | undefined, 
     /** The hub's own code, unmapped. */
-    serverCode?: string | undefined);
+    serverCode?: string | undefined, 
+    /** A sentence for the person using the app, when the hub sent one (a refused voice call: "You've used today's voice time"). */
+    personMessage?: string | undefined);
 }
+/** Options for createClient(). */
 export interface ClientOptions {
     /**
      * The account's hosting token (amt_pat_...) with crm:read, or an app's server key (ak_...) from
@@ -149,9 +198,15 @@ export interface ClientOptions {
      * kinds it was made for; changing kinds, queries or recipes needs the account's token.
      */
     token: string;
+    /** Default https://hub.awesomate.ai. */
     baseUrl?: string;
+    /** Your own fetch. Default: the global one (Node 18 and later). */
     fetch?: typeof fetch;
 }
+/**
+ * The server client, from createClient(): reads and writes the account's data with its token or
+ * an app's server key. Keep it on a server; it never works in a browser.
+ */
 export declare class AwesomateClient {
     private readonly opts;
     private readonly base;
@@ -179,6 +234,16 @@ export declare class AwesomateClient {
         content: string;
         as_at: string;
     }>;
+    /**
+     * Rows of one kind that this token can read, a page at a time.
+     *
+     * @example
+     * const { rows, next } = await db.query('contact', {
+     *   where: { created_at: { gte: '$YEAR_BEGIN' } },
+     *   orderBy: ['created_at', 'desc'],
+     *   limit: 50,
+     * });
+     */
     query<K extends KindName, S extends keyof RowOf<K> = keyof RowOf<K>>(kind: K, options?: QueryOptions<RowOf<K>, S>): Promise<Page<Pick<RowOf<K>, S>>>;
     /** Every matching row, a page at a time. maxRows guards against reading a whole list by accident. */
     queryAll<K extends KindName, S extends keyof RowOf<K> = keyof RowOf<K>>(kind: K, options?: Omit<QueryOptions<RowOf<K>, S>, 'after'> & {
@@ -204,6 +269,7 @@ export declare class AwesomateClient {
      * stored, so a column it cannot read is refused now rather than when it runs.
      */
     saveQuery(spec: SavedQuerySpec): Promise<SavedQueryDescription>;
+    /** Archive a saved query by its key. */
     archiveQuery(key: string): Promise<void>;
     /** Run a saved query with its params. An optional param left out drops its condition. */
     run<Q extends QueryName>(query: Q, params?: ParamsOf<Q>, options?: {
@@ -218,6 +284,7 @@ export declare class AwesomateClient {
      * {"$param": "<name>"} takes a caller's value, {"$step": "<as>"} the id an earlier step wrote.
      */
     saveRecipe(spec: RecipeSpec): Promise<RecipeDescription>;
+    /** Archive a write recipe by its key. */
     archiveRecipe(key: string): Promise<void>;
     /**
      * Run a write recipe. Every step commits or none does; a refusal names the step and the field.
@@ -270,9 +337,13 @@ export interface BusinessFact {
     /** Where it came from, in words: "confirmed by the owner", "added by a team member", "website research"... */
     source: string;
 }
+/** The business, as business() returns it. */
 export interface BusinessIdentity {
+    /** The account's slug. */
     account: string;
+    /** The business's name, when known. */
     name: string | null;
+    /** The details, grouped for reading. */
     groups: Array<{
         id: string;
         title: string;
@@ -286,8 +357,10 @@ export interface BusinessIdentity {
     };
     /** Whether each source could be read: 'read', 'empty' or 'unavailable'. */
     sources: Record<'confirmed_details' | 'saved_details' | 'account_details' | 'website_research', string>;
+    /** Where the owner changes these details, in words. */
     how_to_change: string;
 }
+/** A detail waiting for the owner's yes. */
 export interface BusinessSuggestion {
     id: number;
     key: string;
@@ -297,6 +370,7 @@ export interface BusinessSuggestion {
     sourceRef: string | null;
     recordedAt: string;
 }
+/** One attribute (column) of a kind. */
 export interface AttributeSpec {
     key: string;
     label?: string;
@@ -307,6 +381,7 @@ export interface AttributeSpec {
     /** Default false. Only readable attributes reach query(), get() and the generated types. */
     readable_by_ai?: boolean;
 }
+/** A kind to define: a table an app keeps. */
 export interface KindSpec {
     key: string;
     label?: string;
@@ -321,6 +396,7 @@ export interface KindSpec {
         required?: boolean;
     }>;
 }
+/** A kind as the account has defined it. */
 export interface KindDescription extends Omit<KindSpec, 'attributes'> {
     storage: 'plain' | 'tracked';
     attributes: Array<Required<Pick<AttributeSpec, 'key' | 'label' | 'type' | 'required' | 'sensitivity' | 'readable_by_ai'>> & {
@@ -331,13 +407,16 @@ export interface KindDescription extends Omit<KindSpec, 'attributes'> {
         for_agents: string;
     };
 }
+/** Options for write(). */
 export interface WriteOptions {
     /** Change this record instead of creating one; values not given stay. */
     id?: string;
     /** Set a link by its key ('<id>'), or end it (null). */
     links?: Record<string, string | null>;
 }
+/** The type of a saved query's or recipe's parameter. */
 export type ParamType = 'text' | 'number' | 'date' | 'datetime' | 'boolean' | 'uuid' | 'text_list' | 'number_list';
+/** One parameter of a saved query or recipe. */
 export interface ParamSpec {
     name: string;
     /** Default text. */
@@ -350,6 +429,7 @@ export interface ParamSpec {
 export type Param = {
     $param: string;
 };
+/** A saved query to store with saveQuery(). */
 export interface SavedQuerySpec {
     key: string;
     label: string;
@@ -364,11 +444,13 @@ export interface SavedQuerySpec {
     };
     params?: ParamSpec[];
 }
+/** A saved query as stored. */
 export interface SavedQueryDescription extends Required<Omit<SavedQuerySpec, 'description' | 'params'>> {
     description: string | null;
     params: ParamSpec[];
     updated_at: string;
 }
+/** One step of a write recipe: write a record, or archive one. */
 export type RecipeStep = {
     op: 'write_record';
     kind: string;
@@ -385,6 +467,7 @@ export type RecipeStep = {
         $step: string;
     };
 };
+/** A write recipe to store with saveRecipe(). */
 export interface RecipeSpec {
     key: string;
     label: string;
@@ -392,11 +475,13 @@ export interface RecipeSpec {
     params?: ParamSpec[];
     steps: RecipeStep[];
 }
+/** A write recipe as stored. */
 export interface RecipeDescription extends Required<Omit<RecipeSpec, 'description' | 'params'>> {
     description: string | null;
     params: ParamSpec[];
     updated_at: string;
 }
+/** What a recipe run wrote. */
 export interface RecipeResult {
     /** The id each step named with `as` wrote. */
     ids: Record<string, string>;
@@ -405,15 +490,22 @@ export interface RecipeResult {
 }
 /** Where a session is kept: localStorage, Capacitor Preferences, or anything with these three. */
 export interface SessionStorageLike {
+    /** The stored value, or null. */
     getItem(key: string): string | null | Promise<string | null>;
+    /** Store a value. */
     setItem(key: string, value: string): void | Promise<void>;
+    /** Forget a value. */
     removeItem(key: string): void | Promise<void>;
 }
+/** The signed-in person. */
 export interface AppUser {
+    /** Their app user id. */
     id: string;
+    /** The address they sign in with. */
     email: string;
     /** owner, staff, member or one of the account's own; the database re-reads it on every call */
     role: string;
+    /** Their record in the account's Contacts, when linked. */
     contact_id: string | null;
 }
 /** A customer as lookupCustomers() returns them. A field the owner marked sensitive is null. */
@@ -423,10 +515,13 @@ export interface Customer {
     email: string | null;
     phone: string | null;
 }
+/** Options for createAppClient(). */
 export interface AppClientOptions {
     /** The app's publishable key (pk_...). Not a secret: it belongs in browser code. */
     publishableKey: string;
+    /** Default https://hub.awesomate.ai. */
     baseUrl?: string;
+    /** Your own fetch. Default: the global one. */
     fetch?: typeof fetch;
     /** Default: localStorage in a browser, memory elsewhere. In Capacitor, pass Preferences. */
     storage?: SessionStorageLike;
@@ -444,20 +539,28 @@ export interface AppClientOptions {
 /** The part of the WebSocket API live() uses: the browser's, Node 22's, or the ws package's. */
 export interface WebSocketLike {
     new (url: string): {
+        /** As the browser's WebSocket. */
         readyState: number;
+        /** As the browser's WebSocket. */
         send(data: string): void;
+        /** As the browser's WebSocket. */
         close(code?: number, reason?: string): void;
+        /** As the browser's WebSocket. */
         onopen: ((ev: unknown) => void) | null;
+        /** As the browser's WebSocket. */
         onmessage: ((ev: {
             data: unknown;
         }) => void) | null;
+        /** As the browser's WebSocket. */
         onclose: ((ev: {
             code: number;
             reason: string;
         }) => void) | null;
+        /** As the browser's WebSocket. */
         onerror: ((ev: unknown) => void) | null;
     };
 }
+/** What changed since onRows was last called. */
 export interface LiveChange<R> {
     /** Rows that are new or changed since the last call. */
     upserts: R[];
@@ -475,6 +578,7 @@ export interface HerePerson {
     /** The app's AI assistant, writing a reply. */
     assistant?: true;
 }
+/** From here(): say this person is typing, or close the record. */
 export interface HereHandle {
     /**
      * Say this person is typing (call it on each keystroke: it sends at most every few seconds) or has
@@ -484,6 +588,7 @@ export interface HereHandle {
     /** Close the record: the others stop seeing this person on it. */
     leave(): void;
 }
+/** What live() calls. */
 export interface LiveHandlers<R> {
     /** Called with the whole list, in the query's order, at first and after every change. */
     onRows: (rows: R[], change: LiveChange<R> | null) => void;
@@ -492,6 +597,24 @@ export interface LiveHandlers<R> {
 }
 /** The sign-in token a link carries, from a URL's fragment (#awesomate_token=...), or null. */
 export declare function signInTokenFrom(url: string): string | null;
+/** What AwesomateAgent.mount's session() returns: pass it through unchanged. */
+export interface VoiceSession {
+    session_id: string;
+    url: string;
+    token: string;
+    expires_at: string;
+    max_seconds: number;
+    agent_name: string;
+    pages: Array<{
+        label: string;
+        path: string;
+    }>;
+    say_as: Record<string, string>;
+}
+/**
+ * The browser client for one of the account's apps, from createAppClient(): sign-in is under
+ * `auth`, and every data call runs as the signed-in person, inside the account's access rules.
+ */
 export declare class AwesomateAppClient {
     private readonly opts;
     private readonly base;
@@ -533,6 +656,7 @@ export declare class AwesomateAppClient {
         onChange: (listener: (user: AppUser | null) => void) => (() => void);
         /** Called when a sign-in link could not be used (expired, already used, not this app's). */
         onSignInError: (listener: (err: AwesomateError) => void) => (() => void);
+        /** Sign out here and end the session at the hub. */
         signOut: () => Promise<void>;
         /** A current access token, for the app's own server to verify against the JWKS. */
         accessToken: () => Promise<string | null>;
@@ -549,7 +673,15 @@ export declare class AwesomateAppClient {
     private refresh;
     /** A data call as the signed-in user: refused once (a disable, a key change), it refreshes and tries again; refused twice, it signs out. */
     private data;
+    /**
+     * Rows of one kind that this person may read, a page at a time. The database applies the
+     * kind's read rule for their role: a customer gets their own jobs, staff whatever theirs allows.
+     *
+     * @example
+     * const { rows } = await app.query('job', { orderBy: ['created_at', 'desc'], limit: 20 });
+     */
     query<K extends KindName, S extends keyof RowOf<K> = keyof RowOf<K>>(kind: K, options?: QueryOptions<RowOf<K>, S>): Promise<Omit<Page<Pick<RowOf<K>, S>>, 'hidden'>>;
+    /** Every matching row this person may read, a page at a time. maxRows (default 10,000) guards against reading a whole list by accident. */
     queryAll<K extends KindName, S extends keyof RowOf<K> = keyof RowOf<K>>(kind: K, options?: Omit<QueryOptions<RowOf<K>, S>, 'after'> & {
         maxRows?: number;
     }): AsyncGenerator<Pick<RowOf<K>, S>>;
@@ -557,6 +689,7 @@ export declare class AwesomateAppClient {
     get<K extends KindName>(kind: K, id: string): Promise<RowOf<K> | null>;
     /** Create a record (returns its id) or change one with options.id, inside the kind's write rule for this user. */
     write<K extends KindName>(kind: K, data: Partial<RowOf<K>> | Record<string, unknown>, options?: WriteOptions): Promise<string>;
+    /** Archive a record, inside the kind's write rule for this person. */
     archive<K extends KindName>(kind: K, id: string): Promise<void>;
     /**
      * Run a recipe the account opened to this person's role: "accept this quote", something their
@@ -575,6 +708,19 @@ export declare class AwesomateAppClient {
         ids?: string[];
         limit?: number;
     }): Promise<Customer[]>;
+    /**
+     * The agent this app talks with by voice, or null when the account has not picked one. Pass it
+     * to AwesomateAgent.mount as agentId; the hub decides which agent answers, never the page.
+     */
+    voiceAgent(): Promise<string | null>;
+    /**
+     * A voice session with the app's agent, as this signed-in person:
+     * `AwesomateAgent.mount({ agentId, session: () => app.voiceSession() })`. The agent greets them
+     * by name and, when the app's assistant is set up, knows the recent conversations they can see, and nothing more. A refusal's serverCode says why:
+     * no_voice_agent (the app has none), plan_required, consent_required, person_daily, agent_daily;
+     * its personMessage is the sentence to show the person, which the AwesomateAgent widget shows.
+     */
+    voiceSession(): Promise<VoiceSession>;
     /**
      * A list kept current: onRows gets the whole list (up to 200 rows, the query's order) at first
      * and again whenever a row in it is added, changed, removed, or stops being one this person may
@@ -592,6 +738,23 @@ export declare class AwesomateAppClient {
      */
     here(recordId: string, onPeople: (people: HerePerson[]) => void, onError?: (err: AwesomateError) => void): HereHandle;
 }
+/**
+ * The browser client for one of the account's apps (Pro and above). Give it the app's publishable
+ * key, which is not a secret; never the account's token.
+ *
+ * @example
+ * const app = createAppClient({ publishableKey: 'pk_...' });
+ * app.auth.onChange((user) => render(user));
+ * await app.auth.signInWithLink(email, { redirectTo: location.href });
+ */
 export declare function createAppClient(options: AppClientOptions): AwesomateAppClient;
+/**
+ * The server client: the account's token (amt_pat_... with crm:read) or an app's server key
+ * (ak_...). Both are secrets: keep them on a server, never in a browser.
+ *
+ * @example
+ * const db = createClient({ token: process.env.AWESOMATE_TOKEN! });
+ * const { rows } = await db.query('contact', { limit: 10 });
+ */
 export declare function createClient(options: ClientOptions): AwesomateClient;
 export {};

package/dist/index.js

@@ -18,28 +18,42 @@
  *   const stop = app.live('job', {}, (rows) => render(rows)); // and kept current as they change
  *
  * The account's token (a hosting PAT with crm:read) is a secret: use it on a server, never in a
- * browser. End-user sign-in for browser apps comes in a later version. Reading and running saved
- * queries works on every plan; writing app data (kinds, records, saved queries, recipes) needs
- * crm:write, Support Plus and above.
+ * browser. Reading and running saved queries works on every plan; writing app data (kinds,
+ * records, saved queries, recipes) needs crm:write, Support Plus and above.
+ *
+ * Docs: https://hub.awesomate.ai/docs/sdk/
  */
-export const VERSION = '0.7.0';
+/** This package's version, sent to the hub with every server call. */
+export const VERSION = '0.13.0';
 const DEFAULT_BASE = 'https://hub.awesomate.ai';
 const ERROR_CODES = ['unauthenticated', 'forbidden', 'not_found', 'validation', 'consent_blocked', 'rate_limited', 'conflict', 'unavailable'];
+/**
+ * Every failure from the hub. `message` is for you, the developer; `personMessage`, when the hub
+ * sent one, is the sentence to show the person using your app.
+ */
 export class AwesomateError extends Error {
     code;
     status;
     field;
     serverCode;
-    constructor(code, message, status, 
+    personMessage;
+    constructor(
+    /** Why it failed. */
+    code, message, 
+    /** The HTTP status, or 0 when the SDK refused before sending. */
+    status, 
     /** The column or parameter a validation error is about. */
     field, 
     /** The hub's own code, unmapped. */
-    serverCode) {
+    serverCode, 
+    /** A sentence for the person using the app, when the hub sent one (a refused voice call: "You've used today's voice time"). */
+    personMessage) {
         super(message);
         this.code = code;
         this.status = status;
         this.field = field;
         this.serverCode = serverCode;
+        this.personMessage = personMessage;
         this.name = 'AwesomateError';
     }
 }
@@ -70,6 +84,10 @@ function keyPath(method, path) {
         return `/api/sdk/v1/server${rest}`;
     throw new AwesomateError('forbidden', 'An app key reads and writes records and runs saved queries and recipes. This needs the account\'s token.', 0);
 }
+/**
+ * The server client, from createClient(): reads and writes the account's data with its token or
+ * an app's server key. Keep it on a server; it never works in a browser.
+ */
 export class AwesomateClient {
     opts;
     base;
@@ -123,6 +141,16 @@ export class AwesomateClient {
     types() {
         return this.request('GET', '/api/my-crm/v1/rows/types');
     }
+    /**
+     * Rows of one kind that this token can read, a page at a time.
+     *
+     * @example
+     * const { rows, next } = await db.query('contact', {
+     *   where: { created_at: { gte: '$YEAR_BEGIN' } },
+     *   orderBy: ['created_at', 'desc'],
+     *   limit: 50,
+     * });
+     */
     async query(kind, options = {}) {
         const r = await this.request('POST', '/api/my-crm/v1/rows/query', { kind, ...options });
         return { rows: r.rows, next: r.next, count: r.count, applied: r.applied, hidden: r.hidden, asAt: r.as_at };
@@ -186,6 +214,7 @@ export class AwesomateClient {
     async saveQuery(spec) {
         return (await this.request('POST', '/api/my-crm/v1/queries', spec, false)).query;
     }
+    /** Archive a saved query by its key. */
     async archiveQuery(key) {
         await this.request('DELETE', `/api/my-crm/v1/queries/${encodeURIComponent(key)}`, undefined, false);
     }
@@ -205,6 +234,7 @@ export class AwesomateClient {
     async saveRecipe(spec) {
         return (await this.request('POST', '/api/my-crm/v1/recipes', spec, false)).recipe;
     }
+    /** Archive a write recipe by its key. */
     async archiveRecipe(key) {
         await this.request('DELETE', `/api/my-crm/v1/recipes/${encodeURIComponent(key)}`, undefined, false);
     }
@@ -254,6 +284,10 @@ export function signInTokenFrom(url) {
     return v && v.length >= 20 ? v : null;
 }
 const REFRESH_EARLY_MS = 30_000;
+/**
+ * The browser client for one of the account's apps, from createAppClient(): sign-in is under
+ * `auth`, and every data call runs as the signed-in person, inside the account's access rules.
+ */
 export class AwesomateAppClient {
     opts;
     base;
@@ -351,6 +385,7 @@ export class AwesomateAppClient {
             this.linkErrorListeners.add(listener);
             return () => { this.linkErrorListeners.delete(listener); };
         },
+        /** Sign out here and end the session at the hub. */
         signOut: async () => {
             const s = await this.load();
             await this.clear();
@@ -382,7 +417,7 @@ export class AwesomateAppClient {
             return json;
         const server = typeof json.code === 'string' ? json.code : undefined;
         const message = typeof json.error === 'string' ? json.error : `The hub answered ${res.status}.`;
-        throw new AwesomateError(errorCode(res.status, server), message, res.status, typeof json.field === 'string' ? json.field : undefined, server);
+        throw new AwesomateError(errorCode(res.status, server), message, res.status, typeof json.field === 'string' ? json.field : undefined, server, typeof json.message === 'string' ? json.message : undefined);
     }
     async read() {
         try {
@@ -488,10 +523,18 @@ export class AwesomateAppClient {
             return this.request(method, path, body, s.access_token);
         }
     }
+    /**
+     * Rows of one kind that this person may read, a page at a time. The database applies the
+     * kind's read rule for their role: a customer gets their own jobs, staff whatever theirs allows.
+     *
+     * @example
+     * const { rows } = await app.query('job', { orderBy: ['created_at', 'desc'], limit: 20 });
+     */
     async query(kind, options = {}) {
         const r = await this.data('POST', '/rows/query', { kind, ...options });
         return { rows: r.rows, next: r.next, count: r.count, applied: r.applied, asAt: r.as_at };
     }
+    /** Every matching row this person may read, a page at a time. maxRows (default 10,000) guards against reading a whole list by accident. */
     async *queryAll(kind, options = {}) {
         const { maxRows = 10_000, ...rest } = options;
         let after;
@@ -524,6 +567,7 @@ export class AwesomateAppClient {
         });
         return r.result.id;
     }
+    /** Archive a record, inside the kind's write rule for this person. */
     async archive(kind, id) {
         await this.data('POST', '/call', { fn: 'archive_record', args: { kind, id } });
     }
@@ -544,6 +588,23 @@ export class AwesomateAppClient {
     async lookupCustomers(options) {
         return (await this.data('POST', '/customers/lookup', options)).customers;
     }
+    /**
+     * The agent this app talks with by voice, or null when the account has not picked one. Pass it
+     * to AwesomateAgent.mount as agentId; the hub decides which agent answers, never the page.
+     */
+    async voiceAgent() {
+        return (await this.data('GET', '/me')).app.voice_agent_id ?? null;
+    }
+    /**
+     * A voice session with the app's agent, as this signed-in person:
+     * `AwesomateAgent.mount({ agentId, session: () => app.voiceSession() })`. The agent greets them
+     * by name and, when the app's assistant is set up, knows the recent conversations they can see, and nothing more. A refusal's serverCode says why:
+     * no_voice_agent (the app has none), plan_required, consent_required, person_daily, agent_daily;
+     * its personMessage is the sentence to show the person, which the AwesomateAgent widget shows.
+     */
+    async voiceSession() {
+        return this.data('POST', '/agents/sessions');
+    }
     /**
      * A list kept current: onRows gets the whole list (up to 200 rows, the query's order) at first
      * and again whenever a row in it is added, changed, removed, or stops being one this person may
@@ -855,9 +916,26 @@ class LiveSocket {
         this.failAll(new AwesomateError('unauthenticated', 'Signed out.', 401));
     }
 }
+/**
+ * The browser client for one of the account's apps (Pro and above). Give it the app's publishable
+ * key, which is not a secret; never the account's token.
+ *
+ * @example
+ * const app = createAppClient({ publishableKey: 'pk_...' });
+ * app.auth.onChange((user) => render(user));
+ * await app.auth.signInWithLink(email, { redirectTo: location.href });
+ */
 export function createAppClient(options) {
     return new AwesomateAppClient(options);
 }
+/**
+ * The server client: the account's token (amt_pat_... with crm:read) or an app's server key
+ * (ak_...). Both are secrets: keep them on a server, never in a browser.
+ *
+ * @example
+ * const db = createClient({ token: process.env.AWESOMATE_TOKEN! });
+ * const { rows } = await db.query('contact', { limit: 10 });
+ */
 export function createClient(options) {
     return new AwesomateClient(options);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awesomate/sdk",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Your own Awesomate data from Node and the browser: query contacts and app data with generated types, and sign your app's own users in",
   "license": "MIT",
   "type": "module",
@@ -28,11 +28,16 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p test/typing/tsconfig.json",
-    "test": "npm run build && node --test test/*.test.mjs && tsc -p test/typing/tsconfig.json",
+    "test": "npm run build && node --test test/*.test.mjs && tsc -p test/typing/tsconfig.json && npm run docs:check",
+    "docs": "node scripts/build-docs.mjs",
+    "docs:check": "node scripts/build-docs.mjs --check",
     "prepublishOnly": "npm run typecheck && npm test"
   },
   "devDependencies": {
     "@types/node": "^20.17.0",
+    "marked": "^18.0.14",
+    "shiki": "^4.5.0",
+    "typedoc": "^0.28.20",
     "typescript": "^5.7.2"
   }
 }