@valtrix/sdk 0.0.1 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Valtrix
+
+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,13 +1,76 @@
-# valtrix
+# @valtrix/sdk
 
-The Valtrix SDK: a typed client and codegen CLI for the Valtrix data plane.
+Typed client and codegen CLI for the Valtrix Tables API.
 
-This package is under active development. The first usable release will provide:
+Your data team publishes tables in the Valtrix workspace; this package turns those tables into a typed client for your application. The schema they publish is the contract: column names, types, nullability, and descriptions flow straight into your editor.
 
-```sh
-export VALTRIX_API_KEY=vlt_live_...
-npm install valtrix
+## Quickstart
+
+```bash
+export VALTRIX_API_KEY=vlt_live_...   # from your console, under Developers
+npm install @valtrix/sdk
 npx valtrix generate
 ```
 
-`valtrix generate` reads your published table schemas and emits a client typed against your columns.
+`valtrix generate` reads your published table schemas and writes `valtrix/client.ts` into your project. Commit it: it is ordinary TypeScript source, and regenerating after a schema change is a reviewable diff.
+
+## Reading tables
+
+```ts
+import { valtrix } from './valtrix/client'
+
+const vips = await valtrix.customersClean.findMany({
+    where: { lifetime_value: { gte: 10_000 }, email: { not: null } },
+    orderBy: { lifetime_value: 'desc' },
+    limit: 50,
+})
+
+for await (const row of valtrix.customersClean.iterate()) {
+    process(row)
+}
+```
+
+Rows come from every organization you hold an active grant for. Pass `org` to narrow to one organization. Filters, ordering, and pagination run server side.
+
+## Writing records
+
+Writes create records, not rows. They flow through your published transformation like any other source, so they arrive in your tables cleaned, deduped, and quality checked.
+
+```ts
+await valtrix.records.customer.upsert({
+    org: 'org_acme',
+    externalId: 'usr_8f2',
+    data: { name: 'Jane Cooper', email: 'JANE@ACME.COM' },
+})
+```
+
+The response includes the derived table rows, so you read your write already transformed. A row that fails an error-severity quality rule is reported as quarantined instead of landing in the table.
+
+## Syncing changes
+
+```ts
+for await (const change of valtrix.customersClean.changes({ cursor })) {
+    if (change.type === 'upsert') await warehouse.upsert(change.row)
+    else await warehouse.remove(change.recordId)
+    cursor = change.cursor
+}
+```
+
+The feed is ordered and resumable. Store the cursor and pick up where you left off.
+
+## Staying in sync with the schema
+
+The generated client is pinned to the schema version it was built from. When your data team publishes a new version, the runtime logs a warning, and `valtrix generate --check` exits non-zero, so add it to CI next to your typecheck:
+
+```bash
+npx valtrix generate --check
+```
+
+## Configuration
+
+| Variable | Purpose |
+| --- | --- |
+| `VALTRIX_API_KEY` | Partner API key, required |
+| `VALTRIX_API_URL` | API base URL, defaults to the hosted API |
+
+Both can also be passed to `createClient` directly. The client retries rate limits and transient server errors with backoff, and throws typed errors (`ValtrixError`, `ValtrixAuthError`, `ValtrixRateLimitError`, `ValtrixCursorExpiredError`) otherwise.

package/bin/valtrix.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { fileURLToPath } from 'node:url'
+import path from 'node:path'
+
+const distCli = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'dist', 'cli.js')
+
+let runCli
+try {
+    ;({ runCli } = await import(distCli))
+} catch {
+    process.stderr.write('valtrix: the CLI build is missing. Reinstall the package or run "pnpm build" in valtrix-sdk.\n')
+    process.exit(1)
+}
+
+const code = await runCli(process.argv.slice(2), process.env, {
+    log: message => process.stdout.write(`${message}\n`),
+    error: message => process.stderr.write(`${message}\n`),
+})
+process.exit(code)

package/dist/cli.d.ts

@@ -0,0 +1,6 @@
+export type CliIo = {
+    log: (message: string) => void;
+    error: (message: string) => void;
+    fetchImpl?: typeof fetch;
+};
+export declare function runCli(argv: string[], env: Record<string, string | undefined>, io: CliIo): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,91 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { emitClientSource } from './codegen.js';
+const DEFAULT_OUT = path.join('valtrix', 'client.ts');
+const DEFAULT_BASE_URL = 'https://api.valtrix.vojtadrmota.com';
+function parseArgs(argv) {
+    const flags = new Map();
+    let command = null;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg.startsWith('--')) {
+            const name = arg.slice(2);
+            const next = argv[index + 1];
+            if (next !== undefined && !next.startsWith('--')) {
+                flags.set(name, next);
+                index += 1;
+            }
+            else {
+                flags.set(name, true);
+            }
+        }
+        else if (!command) {
+            command = arg;
+        }
+    }
+    return { command, flags };
+}
+export async function runCli(argv, env, io) {
+    const { command, flags } = parseArgs(argv);
+    if (!command || command === 'help' || flags.has('help')) {
+        io.log('Usage: valtrix generate [--check] [--out <path>] [--url <base url>]');
+        io.log('');
+        io.log('Reads your published table schemas and writes a typed client.');
+        io.log('Environment: VALTRIX_API_KEY (required), VALTRIX_API_URL (optional).');
+        return command ? 0 : 1;
+    }
+    if (command !== 'generate') {
+        io.error(`Unknown command "${command}". Run "valtrix help".`);
+        return 1;
+    }
+    const apiKey = env.VALTRIX_API_KEY;
+    if (!apiKey) {
+        io.error('Set VALTRIX_API_KEY to a key from your Valtrix console (Developers, API Keys).');
+        return 1;
+    }
+    const baseUrl = flags.get('url') ?? env.VALTRIX_API_URL ?? DEFAULT_BASE_URL;
+    const outPath = flags.get('out') ?? DEFAULT_OUT;
+    const checkOnly = flags.get('check') === true;
+    const fetchImpl = io.fetchImpl ?? fetch;
+    let schema;
+    try {
+        const response = await fetchImpl(new URL('/v1/schema', baseUrl).toString(), {
+            headers: { authorization: `Bearer ${apiKey}` },
+        });
+        if (!response.ok) {
+            const body = (await response.json().catch(() => null));
+            io.error(`Schema request failed (${response.status}): ${body?.error ?? 'unexpected response'}`);
+            return 1;
+        }
+        schema = (await response.json());
+    }
+    catch (error) {
+        io.error(`Could not reach ${baseUrl}: ${error instanceof Error ? error.message : String(error)}`);
+        return 1;
+    }
+    const generated = emitClientSource(schema);
+    if (checkOnly) {
+        let existing = null;
+        try {
+            existing = await readFile(outPath, 'utf8');
+        }
+        catch {
+            existing = null;
+        }
+        if (existing === generated.source) {
+            io.log(`${outPath} is up to date.`);
+            return 0;
+        }
+        io.error(`${outPath} is out of date. Run "valtrix generate" and commit the result.`);
+        return 1;
+    }
+    await mkdir(path.dirname(outPath), { recursive: true });
+    await writeFile(outPath, generated.source, 'utf8');
+    const tableCount = schema.tables.length;
+    io.log(`Pulled ${tableCount} ${tableCount === 1 ? 'table' : 'tables'} from your workspace`);
+    for (const table of generated.tableProperties) {
+        io.log(`  valtrix.${table.property} (${table.table})`);
+    }
+    io.log(`Wrote ${outPath}, fully typed`);
+    return 0;
+}

package/dist/client.d.ts

@@ -0,0 +1,155 @@
+import { Http } from './http.js';
+import type { ApiSchema, ApiTableOutcome } from './protocol.js';
+export type MetaFields = {
+    _record_id: string;
+    _org_id: string;
+    _synced_at: string;
+};
+export type WhereOperators<V> = {
+    eq?: V;
+    neq?: V;
+    gt?: V;
+    gte?: V;
+    lt?: V;
+    lte?: V;
+    in?: V[];
+    not?: null;
+};
+export type WhereValue<V> = V | null | WhereOperators<NonNullable<V>>;
+export type Where<Row> = {
+    [K in keyof Row]?: WhereValue<Row[K]>;
+};
+export type OrderBy<Row> = {
+    [K in keyof Row]?: 'asc' | 'desc';
+};
+export type FindManyQuery<Row> = {
+    where?: Where<Row>;
+    orderBy?: OrderBy<Row>;
+    select?: Array<keyof Row & string>;
+    limit?: number;
+    cursor?: string;
+    org?: string;
+};
+export type RowsPage<Row> = {
+    rows: Array<Row & MetaFields>;
+    nextCursor: string | null;
+};
+export type TableChange<Row> = {
+    type: 'upsert';
+    cursor: string;
+    occurredAt: string;
+    recordId: string;
+    orgId: string;
+    row: Row & MetaFields;
+} | {
+    type: 'delete';
+    cursor: string;
+    occurredAt: string;
+    recordId: string;
+    orgId: string;
+    row: null;
+};
+export type TableWriteOutcome = ApiTableOutcome;
+export type UpsertResult<Fields> = {
+    created: boolean;
+    record: {
+        id: string;
+        externalId: string;
+        orgId: string;
+        data: Partial<Fields>;
+        syncedAt: string;
+    };
+    tables: TableWriteOutcome[];
+};
+export declare class TableHandle<Row> {
+    private readonly http;
+    private readonly tableName;
+    private readonly pinnedVersion;
+    private driftWarned;
+    constructor(http: Http, tableName: string, pinnedVersion: string | null);
+    private checkDrift;
+    private buildQuery;
+    page(query?: FindManyQuery<Row>): Promise<RowsPage<Row>>;
+    findMany(query?: FindManyQuery<Row>): Promise<Array<Row & MetaFields>>;
+    iterate(query?: Omit<FindManyQuery<Row>, 'cursor'>): AsyncGenerator<Row & MetaFields>;
+    changes(options?: {
+        cursor?: string;
+        org?: string;
+        limit?: number;
+    }): AsyncGenerator<TableChange<Row>>;
+}
+export declare class RecordHandle<Fields> {
+    private readonly http;
+    private readonly entityType;
+    constructor(http: Http, entityType: string);
+    upsert(input: {
+        org: string;
+        externalId: string;
+        data: Partial<Fields>;
+    }): Promise<UpsertResult<Fields>>;
+    get(input: {
+        org: string;
+        externalId: string;
+    }): Promise<{
+        record: {
+            id: string;
+            externalId: string;
+            orgId: string;
+            data: Partial<Fields>;
+            syncedAt: string;
+        };
+        tables: Array<{
+            table: string;
+            row: Record<string, unknown> | null;
+        }>;
+    }>;
+    delete(input: {
+        org: string;
+        externalId: string;
+    }): Promise<{
+        deleted: boolean;
+        tables: TableWriteOutcome[];
+    }>;
+}
+export declare class ConnectApi {
+    private readonly http;
+    constructor(http: Http);
+    createSession(input?: {
+        orgDisplayName?: string;
+        org?: string;
+        connector?: string;
+        redirectUri?: string;
+        scope?: {
+            entityTypes: string[];
+        };
+    }): Promise<{
+        connectUrl: string;
+        expiresAt: string;
+    }>;
+}
+export type ClientShape = {
+    tables: Record<string, object>;
+    records: Record<string, object>;
+};
+export type ValtrixClient<S extends ClientShape> = {
+    [K in keyof S['tables']]: TableHandle<S['tables'][K]>;
+} & {
+    records: {
+        [K in keyof S['records']]: RecordHandle<S['records'][K]>;
+    };
+    connect: ConnectApi;
+    schema: () => Promise<ApiSchema>;
+};
+export type CreateClientConfig<S extends ClientShape> = {
+    tables: {
+        [K in keyof S['tables']]: string;
+    };
+    records: Array<keyof S['records'] & string>;
+    schemaVersions?: Record<string, string>;
+    apiKey?: string;
+    baseUrl?: string;
+    fetch?: typeof fetch;
+    onWarning?: (message: string) => void;
+    maxRetries?: number;
+};
+export declare function createClient<S extends ClientShape>(config: CreateClientConfig<S>): ValtrixClient<S>;

package/dist/client.js

@@ -0,0 +1,229 @@
+import { Http } from './http.js';
+function serializeScalar(value) {
+    if (typeof value === 'boolean')
+        return value ? 'true' : 'false';
+    return String(value);
+}
+function whereToParams(where, params) {
+    for (const [column, condition] of Object.entries(where)) {
+        if (condition === undefined)
+            continue;
+        if (condition === null) {
+            params.append(column, 'is.null');
+            continue;
+        }
+        if (typeof condition === 'object' && !Array.isArray(condition)) {
+            const operators = condition;
+            for (const [op, value] of Object.entries(operators)) {
+                if (value === undefined)
+                    continue;
+                if (op === 'not') {
+                    params.append(column, 'not.null');
+                }
+                else if (op === 'in' && Array.isArray(value)) {
+                    params.append(column, `in.(${value.map(serializeScalar).join(',')})`);
+                }
+                else {
+                    params.append(column, `${op}.${serializeScalar(value)}`);
+                }
+            }
+            continue;
+        }
+        params.append(column, `eq.${serializeScalar(condition)}`);
+    }
+}
+export class TableHandle {
+    http;
+    tableName;
+    pinnedVersion;
+    driftWarned = false;
+    constructor(http, tableName, pinnedVersion) {
+        this.http = http;
+        this.tableName = tableName;
+        this.pinnedVersion = pinnedVersion;
+    }
+    checkDrift(serverVersion) {
+        if (this.driftWarned || !this.pinnedVersion || !serverVersion)
+            return;
+        if (serverVersion !== this.pinnedVersion) {
+            this.driftWarned = true;
+            this.http.warn(`valtrix: table "${this.tableName}" is on schema ${serverVersion} but your client was generated against ${this.pinnedVersion}. Run "valtrix generate" to update your types.`);
+        }
+    }
+    buildQuery(query) {
+        const params = new URLSearchParams();
+        if (query.where)
+            whereToParams(query.where, params);
+        if (query.orderBy) {
+            const [entry] = Object.entries(query.orderBy);
+            if (entry)
+                params.set('order', `${entry[0]}.${entry[1]}`);
+        }
+        if (query.select?.length)
+            params.set('select', query.select.join(','));
+        if (query.limit !== undefined)
+            params.set('limit', String(query.limit));
+        if (query.cursor)
+            params.set('cursor', query.cursor);
+        if (query.org)
+            params.set('org', query.org);
+        return params;
+    }
+    async page(query = {}) {
+        const response = await this.http.request('GET', `/v1/tables/${this.tableName}/rows`, {
+            query: this.buildQuery(query),
+        });
+        this.checkDrift(response.schema_version);
+        return { rows: response.rows, nextCursor: response.next_cursor };
+    }
+    async findMany(query = {}) {
+        const { rows } = await this.page(query);
+        return rows;
+    }
+    async *iterate(query = {}) {
+        let cursor;
+        for (;;) {
+            const { rows, nextCursor } = await this.page({ ...query, cursor });
+            for (const row of rows)
+                yield row;
+            if (!nextCursor)
+                return;
+            cursor = nextCursor;
+        }
+    }
+    async *changes(options = {}) {
+        let cursor = options.cursor;
+        for (;;) {
+            const params = new URLSearchParams();
+            if (cursor)
+                params.set('cursor', cursor);
+            if (options.org)
+                params.set('org', options.org);
+            if (options.limit !== undefined)
+                params.set('limit', String(options.limit));
+            const response = await this.http.request('GET', `/v1/tables/${this.tableName}/changes`, {
+                query: params,
+            });
+            this.checkDrift(response.schema_version);
+            if (!response.changes.length)
+                return;
+            for (const change of response.changes) {
+                if (change.type === 'upsert') {
+                    yield {
+                        type: 'upsert',
+                        cursor: change.cursor,
+                        occurredAt: change.occurred_at,
+                        recordId: change.record_id,
+                        orgId: change.org_id,
+                        row: { ...(change.row ?? {}), _record_id: change.record_id, _org_id: change.org_id },
+                    };
+                }
+                else {
+                    yield {
+                        type: 'delete',
+                        cursor: change.cursor,
+                        occurredAt: change.occurred_at,
+                        recordId: change.record_id,
+                        orgId: change.org_id,
+                        row: null,
+                    };
+                }
+            }
+            cursor = response.next_cursor ?? cursor;
+            if (!response.next_cursor)
+                return;
+        }
+    }
+}
+export class RecordHandle {
+    http;
+    entityType;
+    constructor(http, entityType) {
+        this.http = http;
+        this.entityType = entityType;
+    }
+    async upsert(input) {
+        const response = await this.http.request('POST', `/v1/records/${this.entityType}`, {
+            body: { org: input.org, external_id: input.externalId, data: input.data },
+        });
+        return {
+            created: response.created,
+            record: {
+                id: response.record.id,
+                externalId: response.record.external_id,
+                orgId: response.record.org_id,
+                data: response.record.data,
+                syncedAt: response.record.synced_at,
+            },
+            tables: response.tables,
+        };
+    }
+    async get(input) {
+        const params = new URLSearchParams({ org: input.org });
+        const response = await this.http.request('GET', `/v1/records/${this.entityType}/${encodeURIComponent(input.externalId)}`, { query: params });
+        return {
+            record: {
+                id: response.record.id,
+                externalId: response.record.external_id,
+                orgId: response.record.org_id,
+                data: response.record.data,
+                syncedAt: response.record.synced_at,
+            },
+            tables: response.tables,
+        };
+    }
+    async delete(input) {
+        const params = new URLSearchParams({ org: input.org });
+        const response = await this.http.request('DELETE', `/v1/records/${this.entityType}/${encodeURIComponent(input.externalId)}`, { query: params });
+        return { deleted: response.deleted, tables: response.tables };
+    }
+}
+export class ConnectApi {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    async createSession(input = {}) {
+        const response = await this.http.request('POST', '/v1/connect/sessions', {
+            body: {
+                org_display_name: input.orgDisplayName,
+                org: input.org,
+                connector: input.connector,
+                redirect_uri: input.redirectUri,
+                scope: input.scope,
+            },
+        });
+        return { connectUrl: response.connect_url, expiresAt: response.expires_at };
+    }
+}
+const DEFAULT_BASE_URL = 'https://api.valtrix.vojtadrmota.com';
+function resolveEnv(name) {
+    if (typeof process === 'undefined')
+        return undefined;
+    return process.env?.[name];
+}
+export function createClient(config) {
+    const apiKey = config.apiKey ?? resolveEnv('VALTRIX_API_KEY');
+    if (!apiKey) {
+        throw new Error('valtrix: set VALTRIX_API_KEY or pass apiKey to createClient.');
+    }
+    const http = new Http({
+        baseUrl: config.baseUrl ?? resolveEnv('VALTRIX_API_URL') ?? DEFAULT_BASE_URL,
+        apiKey,
+        fetchImpl: config.fetch,
+        onWarning: config.onWarning,
+        maxRetries: config.maxRetries,
+    });
+    const client = {};
+    for (const [property, tableName] of Object.entries(config.tables)) {
+        client[property] = new TableHandle(http, tableName, config.schemaVersions?.[tableName] ?? null);
+    }
+    const records = {};
+    for (const entityType of config.records) {
+        records[entityType] = new RecordHandle(http, entityType);
+    }
+    client.records = records;
+    client.connect = new ConnectApi(http);
+    client.schema = () => http.request('GET', '/v1/schema');
+    return client;
+}

package/dist/codegen.d.ts

@@ -0,0 +1,14 @@
+import type { ApiSchema } from './protocol.js';
+export declare function camelCase(name: string): string;
+export declare function pascalCase(name: string): string;
+export type GeneratedClient = {
+    source: string;
+    tableProperties: Array<{
+        property: string;
+        table: string;
+        interfaceName: string;
+    }>;
+};
+export declare function emitClientSource(schema: ApiSchema, options?: {
+    packageName?: string;
+}): GeneratedClient;

package/dist/codegen.js

@@ -0,0 +1,103 @@
+const RESERVED_PROPERTIES = new Set(['records', 'connect', 'schema']);
+export function camelCase(name) {
+    return name.replace(/[_-]+([a-zA-Z0-9])/g, (_, char) => char.toUpperCase()).replace(/[_-]+$/g, '');
+}
+export function pascalCase(name) {
+    const camel = camelCase(name);
+    return camel.charAt(0).toUpperCase() + camel.slice(1);
+}
+function tsType(column) {
+    switch (column.type) {
+        case 'number':
+            return 'number';
+        case 'boolean':
+            return 'boolean';
+        case 'json':
+            return 'unknown';
+        default:
+            return 'string';
+    }
+}
+function docComment(description, extra, indent) {
+    const lines = [...(description ? [description] : []), ...extra];
+    if (!lines.length)
+        return '';
+    if (lines.length === 1)
+        return `${indent}/** ${lines[0]} */\n`;
+    return `${indent}/**\n${lines.map(line => `${indent} * ${line}`).join('\n')}\n${indent} */\n`;
+}
+function columnDoc(column, indent) {
+    const extra = [];
+    if (column.type === 'date')
+        extra.push('ISO 8601 date string.');
+    if (column.writable)
+        extra.push('Writable through valtrix.records.');
+    return docComment(column.description, extra, indent);
+}
+export function emitClientSource(schema, options = {}) {
+    const packageName = options.packageName ?? '@valtrix/sdk';
+    const tables = [...schema.tables].sort((a, b) => a.name.localeCompare(b.name));
+    const records = [...schema.records].sort((a, b) => a.entity_type.localeCompare(b.entity_type));
+    const usedProperties = new Set(RESERVED_PROPERTIES);
+    const tableProperties = tables.map(table => {
+        let property = camelCase(table.name);
+        if (!property)
+            property = 'table';
+        while (usedProperties.has(property))
+            property = `${property}Table`;
+        usedProperties.add(property);
+        return { property, table: table.name, interfaceName: pascalCase(table.name) };
+    });
+    const parts = [];
+    parts.push(`import { createClient } from '${packageName}'`);
+    parts.push('');
+    tables.forEach((table, index) => {
+        const { interfaceName } = tableProperties[index];
+        const header = docComment(`Table "${table.name}" (${table.entity_type}), schema ${table.schema_version ?? 'unpublished'}.`, [], '');
+        parts.push(`${header}export interface ${interfaceName} {`);
+        for (const column of table.columns) {
+            const doc = columnDoc(column, '    ');
+            const nullable = column.nullable ? ' | null' : '';
+            parts.push(`${doc}    ${column.key}: ${tsType(column)}${nullable}`);
+        }
+        parts.push('}');
+        parts.push('');
+    });
+    records.forEach(record => {
+        const interfaceName = `${pascalCase(record.entity_type)}Record`;
+        parts.push(`${docComment(`Writable fields for the "${record.entity_type}" entity type.`, [], '')}export interface ${interfaceName} {`);
+        for (const column of record.columns) {
+            const doc = docComment(column.description, column.type === 'date' ? ['ISO 8601 date string.'] : [], '    ');
+            parts.push(`${doc}    ${column.key}?: ${tsType({ type: column.type })} | null`);
+        }
+        parts.push('}');
+        parts.push('');
+    });
+    parts.push('export const valtrix = createClient<{');
+    parts.push('    tables: {');
+    tableProperties.forEach(({ property, interfaceName }) => {
+        parts.push(`        ${property}: ${interfaceName}`);
+    });
+    parts.push('    }');
+    parts.push('    records: {');
+    records.forEach(record => {
+        parts.push(`        ${record.entity_type}: ${pascalCase(record.entity_type)}Record`);
+    });
+    parts.push('    }');
+    parts.push('}>({');
+    parts.push('    tables: {');
+    tableProperties.forEach(({ property, table }) => {
+        parts.push(`        ${property}: '${table}',`);
+    });
+    parts.push('    },');
+    parts.push(`    records: [${records.map(record => `'${record.entity_type}'`).join(', ')}],`);
+    parts.push('    schemaVersions: {');
+    tables.forEach(table => {
+        if (table.schema_version)
+            parts.push(`        ${JSON.stringify(table.name)}: '${table.schema_version}',`);
+    });
+    parts.push('    },');
+    parts.push('})');
+    parts.push('');
+    return { source: parts.join('\n'), tableProperties };
+}

package/dist/errors.d.ts

@@ -0,0 +1,21 @@
+export type FieldIssue = {
+    field: string;
+    error: string;
+};
+export declare class ValtrixError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly fields: FieldIssue[];
+    constructor(status: number, code: string, message: string, fields?: FieldIssue[]);
+}
+export declare class ValtrixAuthError extends ValtrixError {
+    constructor(status: number, code: string, message: string);
+}
+export declare class ValtrixRateLimitError extends ValtrixError {
+    readonly retryAfterSeconds: number;
+    constructor(message: string, retryAfterSeconds: number);
+}
+export declare class ValtrixCursorExpiredError extends ValtrixError {
+    constructor(message: string);
+}
+export declare function errorFromResponse(status: number, body: unknown): ValtrixError;

package/dist/errors.js

@@ -0,0 +1,42 @@
+export class ValtrixError extends Error {
+    status;
+    code;
+    fields;
+    constructor(status, code, message, fields = []) {
+        super(message);
+        this.name = 'ValtrixError';
+        this.status = status;
+        this.code = code;
+        this.fields = fields;
+    }
+}
+export class ValtrixAuthError extends ValtrixError {
+    constructor(status, code, message) {
+        super(status, code, message);
+        this.name = 'ValtrixAuthError';
+    }
+}
+export class ValtrixRateLimitError extends ValtrixError {
+    retryAfterSeconds;
+    constructor(message, retryAfterSeconds) {
+        super(429, 'rate_limited', message);
+        this.name = 'ValtrixRateLimitError';
+        this.retryAfterSeconds = retryAfterSeconds;
+    }
+}
+export class ValtrixCursorExpiredError extends ValtrixError {
+    constructor(message) {
+        super(410, 'cursor_expired', message);
+        this.name = 'ValtrixCursorExpiredError';
+    }
+}
+export function errorFromResponse(status, body) {
+    const parsed = (typeof body === 'object' && body !== null ? body : {});
+    const code = parsed.code ?? 'unknown_error';
+    const message = parsed.error ?? `Request failed with status ${status}.`;
+    if (status === 401 || status === 403)
+        return new ValtrixAuthError(status, code, message);
+    if (status === 410 && code === 'cursor_expired')
+        return new ValtrixCursorExpiredError(message);
+    return new ValtrixError(status, code, message, parsed.fields ?? []);
+}

package/dist/http.d.ts

@@ -0,0 +1,16 @@
+export type HttpConfig = {
+    baseUrl: string;
+    apiKey: string;
+    fetchImpl?: typeof fetch;
+    maxRetries?: number;
+    onWarning?: (message: string) => void;
+};
+export declare class Http {
+    private readonly config;
+    constructor(config: HttpConfig);
+    warn(message: string): void;
+    request<T>(method: string, path: string, options?: {
+        query?: URLSearchParams;
+        body?: unknown;
+    }): Promise<T>;
+}

package/dist/http.js

@@ -0,0 +1,76 @@
+import { errorFromResponse, ValtrixError, ValtrixRateLimitError } from './errors.js';
+const DEFAULT_MAX_RETRIES = 3;
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+export class Http {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    warn(message) {
+        const handler = this.config.onWarning ?? ((text) => console.warn(text));
+        handler(message);
+    }
+    async request(method, path, options = {}) {
+        const fetchImpl = this.config.fetchImpl ?? fetch;
+        const maxRetries = this.config.maxRetries ?? DEFAULT_MAX_RETRIES;
+        const url = new URL(path, this.config.baseUrl);
+        if (options.query) {
+            for (const [key, value] of options.query)
+                url.searchParams.append(key, value);
+        }
+        let lastError = null;
+        for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
+            let response;
+            try {
+                response = await fetchImpl(url.toString(), {
+                    method,
+                    headers: {
+                        authorization: `Bearer ${this.config.apiKey}`,
+                        ...(options.body !== undefined ? { 'content-type': 'application/json' } : {}),
+                    },
+                    body: options.body !== undefined ? JSON.stringify(options.body) : undefined,
+                });
+            }
+            catch (error) {
+                lastError = error;
+                if (attempt < maxRetries) {
+                    await sleep(250 * 2 ** attempt);
+                    continue;
+                }
+                throw new ValtrixError(0, 'network_error', error instanceof Error ? error.message : String(error));
+            }
+            if (response.status === 429) {
+                const retryAfter = Number(response.headers.get('retry-after') ?? '1');
+                const waitSeconds = Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter : 1;
+                if (attempt < maxRetries) {
+                    await sleep(Math.min(waitSeconds, 30) * 1000);
+                    continue;
+                }
+                throw new ValtrixRateLimitError('Rate limit exceeded.', waitSeconds);
+            }
+            if (response.status >= 500) {
+                lastError = errorFromResponse(response.status, await safeJson(response));
+                if (attempt < maxRetries) {
+                    await sleep(250 * 2 ** attempt);
+                    continue;
+                }
+                throw lastError;
+            }
+            const body = await safeJson(response);
+            if (!response.ok)
+                throw errorFromResponse(response.status, body);
+            return body;
+        }
+        throw lastError instanceof Error ? lastError : new ValtrixError(0, 'network_error', 'Request failed.');
+    }
+}
+async function safeJson(response) {
+    try {
+        return await response.json();
+    }
+    catch {
+        return null;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { ConnectApi, createClient, RecordHandle, TableHandle, } from './client.js';
+export type { ClientShape, CreateClientConfig, FindManyQuery, MetaFields, OrderBy, RowsPage, TableChange, TableWriteOutcome, UpsertResult, ValtrixClient, Where, WhereOperators, WhereValue, } from './client.js';
+export { errorFromResponse, ValtrixAuthError, ValtrixCursorExpiredError, ValtrixError, ValtrixRateLimitError, } from './errors.js';
+export type { FieldIssue } from './errors.js';
+export { camelCase, emitClientSource, pascalCase } from './codegen.js';
+export type { GeneratedClient } from './codegen.js';
+export { runCli } from './cli.js';
+export type { ApiChange, ApiChangesResponse, ApiColumn, ApiConnectSessionResponse, ApiRecordType, ApiRowsResponse, ApiSchema, ApiTable, ApiUpsertResponse, } from './protocol.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { ConnectApi, createClient, RecordHandle, TableHandle, } from './client.js';
+export { errorFromResponse, ValtrixAuthError, ValtrixCursorExpiredError, ValtrixError, ValtrixRateLimitError, } from './errors.js';
+export { camelCase, emitClientSource, pascalCase } from './codegen.js';
+export { runCli } from './cli.js';

package/dist/protocol.d.ts

@@ -0,0 +1,82 @@
+export type ApiColumn = {
+    key: string;
+    type: 'string' | 'number' | 'boolean' | 'date' | 'json';
+    nullable: boolean;
+    description: string;
+    writable: boolean;
+};
+export type ApiTable = {
+    name: string;
+    entity_type: string;
+    status: string;
+    row_count: number;
+    last_built_at: string | null;
+    schema_version: string | null;
+    columns: ApiColumn[];
+};
+export type ApiRecordType = {
+    entity_type: string;
+    label: string;
+    title_key: string;
+    columns: Array<{
+        key: string;
+        type: string;
+        description: string;
+    }>;
+};
+export type ApiSchema = {
+    tables: ApiTable[];
+    records: ApiRecordType[];
+};
+export type ApiRowsResponse = {
+    rows: Array<Record<string, unknown>>;
+    next_cursor: string | null;
+    schema_version: string | null;
+};
+export type ApiChange = {
+    type: 'upsert' | 'delete';
+    cursor: string;
+    occurred_at: string;
+    record_id: string;
+    org_id: string;
+    row: Record<string, unknown> | null;
+};
+export type ApiChangesResponse = {
+    changes: ApiChange[];
+    next_cursor: string | null;
+    schema_version: string | null;
+};
+export type ApiTableOutcome = {
+    table: string;
+    status: 'applied' | 'removed' | 'quarantined' | 'filtered' | 'pending';
+    row: Record<string, unknown> | null;
+    quarantined_by: string[];
+};
+export type ApiRecord = {
+    id: string;
+    entity_type: string;
+    external_id: string;
+    org_id: string;
+    data: Record<string, unknown>;
+    synced_at: string;
+};
+export type ApiUpsertResponse = {
+    created: boolean;
+    record: ApiRecord;
+    tables: ApiTableOutcome[];
+};
+export type ApiDeleteResponse = {
+    deleted: boolean;
+    tables: ApiTableOutcome[];
+};
+export type ApiRecordResponse = {
+    record: ApiRecord;
+    tables: Array<{
+        table: string;
+        row: Record<string, unknown> | null;
+    }>;
+};
+export type ApiConnectSessionResponse = {
+    connect_url: string;
+    expires_at: string;
+};

package/dist/protocol.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,17 +1,47 @@
 {
   "name": "@valtrix/sdk",
-  "version": "0.0.1",
-  "publishConfig": {
-    "access": "public"
+  "version": "0.1.1",
+  "description": "Typed client and codegen CLI for the Valtrix Tables API. Run valtrix generate to get a client typed against your published tables.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "valtrix": "./bin/valtrix.mjs"
   },
-  "description": "Valtrix SDK - typed client and codegen CLI for the Valtrix data plane (coming soon)",
-  "license": "UNLICENSED",
-  "main": "index.js",
   "files": [
-    "index.js",
-    "README.md"
+    "bin",
+    "dist"
   ],
   "keywords": [
-    "valtrix"
-  ]
-}
+    "valtrix",
+    "sdk",
+    "typed-client",
+    "codegen",
+    "data-api"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.8",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.17",
+    "@valtrix/tsconfig": "1.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest",
+    "test:run": "vitest run"
+  }
+}

package/index.js

@@ -1 +0,0 @@
-module.exports = {};