@awesomate/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 IT Mooti Pty Ltd t/a Awesomate
+
+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

@@ -0,0 +1,58 @@
+# @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.
+
+```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'] });
+```
+
+## 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. Sign-in for your own app's users comes in a later version.
+
+MIT licence.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+/**
+ * npx @awesomate/sdk types [--out awesomate.d.ts] [--profile <name>] [--base <url>]
+ *
+ * Writes the account's readable kinds as TypeScript. The token comes from AWESOMATE_TOKEN, or
+ * else from ~/.awesomate/credentials.json (the file the Awesomate MCP keeps): --profile, then
+ * AWESOMATE_ACCOUNT, then its defaultProfile. The account is printed, so a wrong one is obvious.
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { AwesomateError, createClient } from './index.js';
+function arg(name) {
+    const i = process.argv.indexOf(`--${name}`);
+    return i > 0 ? process.argv[i + 1] : undefined;
+}
+function credentials() {
+    if (process.env.AWESOMATE_TOKEN) {
+        return { token: process.env.AWESOMATE_TOKEN, baseUrl: arg('base') ?? process.env.AWESOMATE_BASE_URL, account: 'from AWESOMATE_TOKEN' };
+    }
+    let creds;
+    try {
+        creds = JSON.parse(readFileSync(join(homedir(), '.awesomate', 'credentials.json'), 'utf8'));
+    }
+    catch {
+        throw new Error('No token: set AWESOMATE_TOKEN, or connect the Awesomate MCP so ~/.awesomate/credentials.json exists.');
+    }
+    const name = arg('profile') ?? process.env.AWESOMATE_ACCOUNT ?? creds.defaultProfile;
+    const p = name ? creds.profiles?.[name] : undefined;
+    if (!p?.pat)
+        throw new Error(`No profile ${name ?? '(none)'} with a token in ~/.awesomate/credentials.json.`);
+    return { token: p.pat, baseUrl: arg('base') ?? p.apiBase, account: p.slug ?? name };
+}
+async function main() {
+    const cmd = process.argv[2];
+    if (cmd !== 'types') {
+        console.log('Usage: npx @awesomate/sdk types [--out awesomate.d.ts] [--profile <name>] [--base <url>]');
+        process.exit(cmd === undefined || cmd === '--help' || cmd === '-h' ? 0 : 1);
+    }
+    const { token, baseUrl, account } = credentials();
+    console.error(`account: ${account}`);
+    const r = await createClient({ token, baseUrl }).types();
+    const out = resolve(arg('out') ?? r.file);
+    writeFileSync(out, r.content);
+    console.log(`wrote ${out}`);
+}
+main().catch((err) => {
+    console.error(err instanceof AwesomateError ? `${err.code}: ${err.message}` : err.message);
+    process.exit(1);
+});

package/dist/index.d.ts

@@ -0,0 +1,182 @@
+/**
+ * @awesomate/sdk: read a client's own Awesomate data from Node (v0: the contact list).
+ *
+ *   import { createClient } from '@awesomate/sdk';
+ *   import './awesomate'; // the file `npx @awesomate/sdk types` wrote: types every query below
+ *   const db = createClient({ token: process.env.AWESOMATE_TOKEN! });
+ *   const { rows, next } = await db.query('contact', { where: { created_at: { gte: '$YEAR_BEGIN' } }, limit: 50 });
+ *
+ * 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.
+ */
+export declare const VERSION = "0.1.0";
+/** Augmented by the generated awesomate.d.ts, so each kind's rows are typed. */
+export interface Kinds {
+}
+export type KindName = [keyof Kinds] extends [never] ? string : Extract<keyof Kinds, string>;
+export type RowOf<K> = K extends keyof Kinds ? Kinds[K] : Record<string, unknown>;
+type TextOps<V extends string> = {
+    eq?: V | null;
+    neq?: V | null;
+    in?: V[];
+    nin?: V[];
+    contains?: string;
+    startsWith?: string;
+    like?: string;
+    ilike?: string;
+    gt?: string;
+    gte?: string;
+    lt?: string;
+    lte?: string;
+    isNull?: boolean;
+};
+type NumberOps = {
+    eq?: number | null;
+    neq?: number | null;
+    gt?: number;
+    gte?: number;
+    lt?: number;
+    lte?: number;
+    in?: number[];
+    nin?: number[];
+    isNull?: boolean;
+};
+type BoolOps = {
+    eq?: boolean | null;
+    neq?: boolean | null;
+    isNull?: boolean;
+};
+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;
+export type Where<T> = {
+    [C in keyof T]?: ColumnFilter<NonNullable<T[C]>>;
+} & {
+    and?: Where<T>[];
+    or?: Where<T>[];
+    not?: Where<T>;
+};
+/** Columns that can be sorted by: anything but a list. */
+export type SortableColumn<T> = Extract<{
+    [C in keyof T]: NonNullable<T[C]> extends unknown[] ? never : C;
+}[keyof T], string>;
+export interface QueryOptions<T, S extends keyof T = keyof T> {
+    where?: Where<T>;
+    /** One sort column; id breaks ties. Default: created_at, newest first. */
+    orderBy?: [SortableColumn<T>, 'asc' | 'desc'];
+    /** Rows per page, 1 to 1,000. Default 50. */
+    limit?: number;
+    /** The previous page's next. Repeat the same orderBy. */
+    after?: string;
+    select?: S[];
+    /** IANA zone for dates and time variables. Default Australia/Sydney. */
+    tz?: string;
+}
+export interface Applied {
+    order_by: [string, 'asc' | 'desc'];
+    limit: number;
+    timezone: string;
+    time_variables: Record<string, string>;
+    defaults: string[];
+}
+export interface Page<R> {
+    rows: R[];
+    next: string | null;
+    count: number;
+    /** What the hub assumed; repeat it to whoever asked. */
+    applied: Applied;
+    hidden: {
+        not_readable_by_ai: number;
+        sensitive: number;
+    };
+    asAt: string;
+}
+export type ErrorCode = 'unauthenticated' | 'forbidden' | 'not_found' | 'validation' | 'consent_blocked' | 'rate_limited' | 'conflict' | 'unavailable';
+export declare class AwesomateError extends Error {
+    readonly code: ErrorCode;
+    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, 
+    /** The column or parameter a validation error is about. */
+    field?: string | undefined, 
+    /** The hub's own code, unmapped. */
+    serverCode?: string | undefined);
+}
+export interface ClientOptions {
+    /** The account's hosting token (amt_pat_...) with crm:read. */
+    token: string;
+    baseUrl?: string;
+    fetch?: typeof fetch;
+}
+export declare class AwesomateClient {
+    private readonly opts;
+    private readonly base;
+    private readonly doFetch;
+    constructor(opts: ClientOptions);
+    private call;
+    /** The kinds this token can read, their columns, operators and examples. */
+    schema(): Promise<{
+        kinds: Array<{
+            kind: string;
+            label: string;
+            columns: Array<{
+                name: string;
+                label: string;
+                type: string;
+                operators: string[];
+            }>;
+        }>;
+    }>;
+    /** The readable kinds as a TypeScript file (what the types command writes). */
+    types(): Promise<{
+        file: string;
+        content: string;
+        as_at: string;
+    }>;
+    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'> & {
+        maxRows?: number;
+    }): AsyncGenerator<Pick<RowOf<K>, S>>;
+    /** One row by id, or null when there is none this token can read. */
+    get<K extends KindName>(kind: K, id: string, options?: {
+        tz?: string;
+    }): Promise<RowOf<K> | null>;
+    /** Grouped numbers (counts, sums) in the Business Data API's shape. */
+    aggregate(request: {
+        measures: Array<{
+            column: string;
+            agg?: 'count' | 'sum' | 'avg' | 'min' | 'max';
+        }>;
+        dimensions?: string[];
+        filters?: Array<{
+            column: string;
+            op?: string;
+            value: unknown;
+        }>;
+        time?: {
+            grain?: string;
+            preset?: string;
+            from?: string;
+            to?: string;
+            anchor?: string;
+            tz?: string;
+        };
+        order_by?: Array<{
+            field: string;
+            dir?: 'asc' | 'desc';
+        }>;
+        limit?: number;
+    }): Promise<Record<string, unknown>>;
+}
+export declare function createClient(options: ClientOptions): AwesomateClient;
+export {};

package/dist/index.js

@@ -0,0 +1,134 @@
+/**
+ * @awesomate/sdk: read a client's own Awesomate data from Node (v0: the contact list).
+ *
+ *   import { createClient } from '@awesomate/sdk';
+ *   import './awesomate'; // the file `npx @awesomate/sdk types` wrote: types every query below
+ *   const db = createClient({ token: process.env.AWESOMATE_TOKEN! });
+ *   const { rows, next } = await db.query('contact', { where: { created_at: { gte: '$YEAR_BEGIN' } }, limit: 50 });
+ *
+ * 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.
+ */
+export const VERSION = '0.1.0';
+const DEFAULT_BASE = 'https://hub.awesomate.ai';
+export class AwesomateError extends Error {
+    code;
+    status;
+    field;
+    serverCode;
+    constructor(code, message, status, 
+    /** The column or parameter a validation error is about. */
+    field, 
+    /** The hub's own code, unmapped. */
+    serverCode) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.field = field;
+        this.serverCode = serverCode;
+        this.name = 'AwesomateError';
+    }
+}
+function errorCode(status, server) {
+    if (server === 'validation' || server === 'invalid' || status === 422)
+        return 'validation';
+    if (status === 401)
+        return 'unauthenticated';
+    if (status === 403)
+        return server === 'consent_blocked' ? 'consent_blocked' : 'forbidden';
+    if (status === 429)
+        return 'rate_limited';
+    if (server === 'conflict')
+        return 'conflict';
+    if (status === 404 && server !== 'not_live')
+        return 'not_found';
+    return 'unavailable';
+}
+export class AwesomateClient {
+    opts;
+    base;
+    doFetch;
+    constructor(opts) {
+        this.opts = opts;
+        if (!opts?.token)
+            throw new Error('createClient needs a token (the account\'s hosting token with crm:read).');
+        this.base = (opts.baseUrl ?? DEFAULT_BASE).replace(/\/+$/, '');
+        this.doFetch = opts.fetch ?? globalThis.fetch;
+        if (!this.doFetch)
+            throw new Error('No fetch available: use Node 18 or later, or pass fetch.');
+    }
+    async call(method, path, body, retry = true) {
+        const res = await this.doFetch(`${this.base}${path}`, {
+            method,
+            headers: {
+                authorization: `Bearer ${this.opts.token}`,
+                'user-agent': `@awesomate/sdk/${VERSION}`,
+                ...(body === undefined ? {} : { 'content-type': 'application/json' }),
+            },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        const text = await res.text();
+        let json = {};
+        try {
+            json = text ? JSON.parse(text) : {};
+        }
+        catch { /* a proxy's HTML error page */ }
+        if (res.ok)
+            return json;
+        const server = typeof json.code === 'string' ? json.code : undefined;
+        const code = errorCode(res.status, server);
+        // The field list changed while the read ran (the view is rebuilt on every field edit): a read
+        // is safe to run again, once.
+        if (code === 'conflict' && retry)
+            return this.call(method, path, body, false);
+        const message = typeof json.error === 'string' ? json.error : `The hub answered ${res.status}.`;
+        throw new AwesomateError(code, message, res.status, typeof json.field === 'string' ? json.field : undefined, server);
+    }
+    /** The kinds this token can read, their columns, operators and examples. */
+    schema() {
+        return this.call('GET', '/api/my-crm/v1/rows/schema');
+    }
+    /** The readable kinds as a TypeScript file (what the types command writes). */
+    types() {
+        return this.call('GET', '/api/my-crm/v1/rows/types');
+    }
+    async query(kind, options = {}) {
+        const r = await this.call('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 };
+    }
+    /** Every matching row, a page at a time. maxRows guards against reading a whole list by accident. */
+    async *queryAll(kind, options = {}) {
+        const { maxRows = 10_000, ...rest } = options;
+        let after;
+        let seen = 0;
+        do {
+            const page = await this.query(kind, { limit: 1000, ...rest, ...(after ? { after } : {}) });
+            for (const row of page.rows) {
+                if (seen++ >= maxRows)
+                    return;
+                yield row;
+            }
+            after = page.next ?? undefined;
+        } while (after);
+    }
+    /** One row by id, or null when there is none this token can read. */
+    async get(kind, id, options = {}) {
+        try {
+            const qs = options.tz ? `?tz=${encodeURIComponent(options.tz)}` : '';
+            const r = await this.call('GET', `/api/my-crm/v1/rows/${encodeURIComponent(kind)}/${encodeURIComponent(id)}${qs}`);
+            return r.row;
+        }
+        catch (err) {
+            if (err instanceof AwesomateError && err.code === 'not_found')
+                return null;
+            throw err;
+        }
+    }
+    /** Grouped numbers (counts, sums) in the Business Data API's shape. */
+    aggregate(request) {
+        return this.call('POST', '/api/my-crm/v1/data/query', request);
+    }
+}
+export function createClient(options) {
+    return new AwesomateClient(options);
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@awesomate/sdk",
+  "version": "0.1.0",
+  "description": "Read your own Awesomate data from Node: query and page through your contact list with types generated from your fields",
+  "license": "MIT",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "awesomate-sdk": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "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",
+    "prepublishOnly": "npm run typecheck && npm test"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.0",
+    "typescript": "^5.7.2"
+  }
+}