@valtrix/sdk 0.1.1 → 0.3.0

package/README.md

@@ -32,6 +32,12 @@ for await (const row of valtrix.customersClean.iterate()) {
 
 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.
 
+Every row carries a stable `_record_id`. Store it and you can fetch the same row back later as a point lookup:
+
+```ts
+const [invoice] = await valtrix.invoicesClean.findMany({ where: { _record_id: 'rec_9f2k7d' } })
+```
+
 ## 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.
@@ -46,12 +52,14 @@ await valtrix.records.customer.upsert({
 
 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
+## Reacting to changes
+
+Your tables are the database, so there is nothing to copy or keep in sync. The change feed is how you react when data changes: kick off a workflow, notify someone, refresh something you derived.
 
 ```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)
+    if (change.type === 'upsert') await notifyAccountManager(change.row)
+    else await closeOpenTasks(change.recordId)
     cursor = change.cursor
 }
 ```

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -1,8 +1,21 @@
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { emitClientSource } from './codegen.js';
+import { ENV_FILES, parseEnvFile } from './env.js';
 const DEFAULT_OUT = path.join('valtrix', 'client.ts');
 const DEFAULT_BASE_URL = 'https://api.valtrix.vojtadrmota.com';
+export async function loadEnvFiles(cwd) {
+    const merged = {};
+    for (const file of ENV_FILES) {
+        try {
+            Object.assign(merged, parseEnvFile(await readFile(path.join(cwd, file), 'utf8')));
+        }
+        catch {
+            continue;
+        }
+    }
+    return merged;
+}
 function parseArgs(argv) {
     const flags = new Map();
     let command = null;
@@ -32,18 +45,21 @@ export async function runCli(argv, env, io) {
         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).');
+        io.log('Both are read from the shell, or from .env.local / .env in the current directory.');
         return command ? 0 : 1;
     }
     if (command !== 'generate') {
         io.error(`Unknown command "${command}". Run "valtrix help".`);
         return 1;
     }
-    const apiKey = env.VALTRIX_API_KEY;
+    const fileEnv = await loadEnvFiles(process.cwd());
+    const apiKey = env.VALTRIX_API_KEY ?? fileEnv.VALTRIX_API_KEY;
     if (!apiKey) {
         io.error('Set VALTRIX_API_KEY to a key from your Valtrix console (Developers, API Keys).');
+        io.error('Export it, or put it in a gitignored .env.local or .env next to your project.');
         return 1;
     }
-    const baseUrl = flags.get('url') ?? env.VALTRIX_API_URL ?? DEFAULT_BASE_URL;
+    const baseUrl = flags.get('url') ?? env.VALTRIX_API_URL ?? fileEnv.VALTRIX_API_URL ?? DEFAULT_BASE_URL;
     const outPath = flags.get('out') ?? DEFAULT_OUT;
     const checkOnly = flags.get('check') === true;
     const fetchImpl = io.fetchImpl ?? fetch;

package/dist/client.d.ts

@@ -16,8 +16,14 @@ export type WhereOperators<V> = {
     not?: null;
 };
 export type WhereValue<V> = V | null | WhereOperators<NonNullable<V>>;
+export type RecordIdFilter = string | {
+    eq?: string;
+    in?: string[];
+};
 export type Where<Row> = {
     [K in keyof Row]?: WhereValue<Row[K]>;
+} & {
+    _record_id?: RecordIdFilter;
 };
 export type OrderBy<Row> = {
     [K in keyof Row]?: 'asc' | 'desc';
@@ -127,17 +133,64 @@ export declare class ConnectApi {
         expiresAt: string;
     }>;
 }
+export type OrgStatus = 'active' | 'revoked' | 'expired';
+export type Org = {
+    id: string;
+    displayName: string;
+    status: OrgStatus;
+    entityTypes: string[];
+    connections: Array<{
+        connector: string;
+        status: string;
+    }>;
+    connectedAt: string;
+    expiresAt: string | null;
+    revokedAt: string | null;
+};
+export type OrgsQuery = {
+    status?: OrgStatus;
+    limit?: number;
+    cursor?: string;
+};
+export type OrgsPage = {
+    orgs: Org[];
+    nextCursor: string | null;
+};
+export declare class OrgsApi {
+    private readonly http;
+    constructor(http: Http);
+    page(query?: OrgsQuery): Promise<OrgsPage>;
+    list(query?: Omit<OrgsQuery, 'cursor'>): Promise<Org[]>;
+    iterate(query?: Omit<OrgsQuery, 'cursor'>): AsyncGenerator<Org>;
+    get(orgId: string): Promise<Org>;
+}
 export type ClientShape = {
     tables: Record<string, object>;
     records: Record<string, object>;
 };
+export type RecordByIdResult = {
+    record: {
+        id: string;
+        entityType: string;
+        externalId: string;
+        orgId: string;
+        data: Record<string, unknown>;
+        syncedAt: string;
+    };
+    tables: Array<{
+        table: string;
+        row: Record<string, unknown> | null;
+    }>;
+};
 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]>;
     };
+    recordById: (recordId: string) => Promise<RecordByIdResult>;
     connect: ConnectApi;
+    orgs: OrgsApi;
     schema: () => Promise<ApiSchema>;
 };
 export type CreateClientConfig<S extends ClientShape> = {

package/dist/client.js

@@ -1,3 +1,4 @@
+import { ENV_FILES, parseEnvFile } from './env.js';
 import { Http } from './http.js';
 function serializeScalar(value) {
     if (typeof value === 'boolean')
@@ -196,11 +197,84 @@ export class ConnectApi {
         return { connectUrl: response.connect_url, expiresAt: response.expires_at };
     }
 }
+function mapOrg(org) {
+    return {
+        id: org.id,
+        displayName: org.display_name,
+        status: org.status,
+        entityTypes: org.scope.entity_types,
+        connections: org.connections.map(connection => ({ connector: connection.connector, status: connection.status })),
+        connectedAt: org.connected_at,
+        expiresAt: org.expires_at,
+        revokedAt: org.revoked_at,
+    };
+}
+export class OrgsApi {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    async page(query = {}) {
+        const params = new URLSearchParams();
+        if (query.status)
+            params.set('status', query.status);
+        if (query.limit !== undefined)
+            params.set('limit', String(query.limit));
+        if (query.cursor)
+            params.set('cursor', query.cursor);
+        const response = await this.http.request('GET', '/v1/orgs', { query: params });
+        return { orgs: response.orgs.map(mapOrg), nextCursor: response.next_cursor };
+    }
+    async list(query = {}) {
+        const { orgs } = await this.page(query);
+        return orgs;
+    }
+    async *iterate(query = {}) {
+        let cursor;
+        for (;;) {
+            const { orgs, nextCursor } = await this.page({ ...query, cursor });
+            for (const org of orgs)
+                yield org;
+            if (!nextCursor)
+                return;
+            cursor = nextCursor;
+        }
+    }
+    async get(orgId) {
+        const response = await this.http.request('GET', `/v1/orgs/${encodeURIComponent(orgId)}`);
+        return mapOrg(response);
+    }
+}
 const DEFAULT_BASE_URL = 'https://api.valtrix.vojtadrmota.com';
+let cachedFileEnv = null;
+function fileEnv(name) {
+    if (typeof process === 'undefined' || !process.getBuiltinModule)
+        return undefined;
+    const cwd = process.cwd();
+    if (!cachedFileEnv || cachedFileEnv.cwd !== cwd) {
+        const values = {};
+        try {
+            const fs = process.getBuiltinModule('node:fs');
+            for (const file of ENV_FILES) {
+                try {
+                    Object.assign(values, parseEnvFile(fs.readFileSync(`${cwd}/${file}`, 'utf8')));
+                }
+                catch {
+                    continue;
+                }
+            }
+        }
+        catch {
+            return undefined;
+        }
+        cachedFileEnv = { cwd, values };
+    }
+    return cachedFileEnv.values[name];
+}
 function resolveEnv(name) {
     if (typeof process === 'undefined')
         return undefined;
-    return process.env?.[name];
+    return process.env?.[name] ?? fileEnv(name);
 }
 export function createClient(config) {
     const apiKey = config.apiKey ?? resolveEnv('VALTRIX_API_KEY');
@@ -223,7 +297,22 @@ export function createClient(config) {
         records[entityType] = new RecordHandle(http, entityType);
     }
     client.records = records;
+    client.recordById = async (recordId) => {
+        const response = await http.request('GET', `/v1/records/by-id/${encodeURIComponent(recordId)}`);
+        return {
+            record: {
+                id: response.record.id,
+                entityType: response.record.entity_type,
+                externalId: response.record.external_id,
+                orgId: response.record.org_id,
+                data: response.record.data,
+                syncedAt: response.record.synced_at,
+            },
+            tables: response.tables,
+        };
+    };
     client.connect = new ConnectApi(http);
+    client.orgs = new OrgsApi(http);
     client.schema = () => http.request('GET', '/v1/schema');
     return client;
 }

package/dist/codegen.js

@@ -53,7 +53,14 @@ export function emitClientSource(schema, options = {}) {
     parts.push('');
     tables.forEach((table, index) => {
         const { interfaceName } = tableProperties[index];
-        const header = docComment(`Table "${table.name}" (${table.entity_type}), schema ${table.schema_version ?? 'unpublished'}.`, [], '');
+        const identityNote = table.row_identity === 'record'
+            ? ' Rows keep their source record ids; _record_id resolves via recordById().'
+            : table.row_identity === 'synthetic'
+                ? ' Rows are derived aggregates; _record_id is synthetic (syn_ prefix) and does not resolve to a record.'
+                : table.row_identity === 'mixed'
+                    ? ' Rows mix source record ids and synthetic (syn_ prefixed) ids; only record ids resolve via recordById().'
+                    : '';
+        const header = docComment(`Table "${table.name}" (${table.entity_type}), schema ${table.schema_version ?? 'unpublished'}.${identityNote}`, [], '');
         parts.push(`${header}export interface ${interfaceName} {`);
         for (const column of table.columns) {
             const doc = columnDoc(column, '    ');

package/dist/env.d.ts

@@ -0,0 +1,2 @@
+export declare const ENV_FILES: string[];
+export declare function parseEnvFile(content: string): Record<string, string>;

package/dist/env.js

@@ -0,0 +1,23 @@
+export const ENV_FILES = ['.env', '.env.local'];
+export function parseEnvFile(content) {
+    const values = {};
+    for (const line of content.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const withoutExport = trimmed.startsWith('export ') ? trimmed.slice(7).trim() : trimmed;
+        const separator = withoutExport.indexOf('=');
+        if (separator === -1)
+            continue;
+        const key = withoutExport.slice(0, separator).trim();
+        if (!key)
+            continue;
+        let value = withoutExport.slice(separator + 1).trim();
+        const quote = value[0];
+        if ((quote === '"' || quote === "'") && value.endsWith(quote) && value.length >= 2) {
+            value = value.slice(1, -1);
+        }
+        values[key] = value;
+    }
+    return values;
+}

package/dist/index.d.ts

@@ -1,8 +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 { ConnectApi, createClient, OrgsApi, RecordHandle, TableHandle, } from './client.js';
+export type { ClientShape, CreateClientConfig, FindManyQuery, MetaFields, OrderBy, Org, OrgsPage, OrgsQuery, OrgStatus, RecordIdFilter, 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';
+export type { ApiChange, ApiChangesResponse, ApiColumn, ApiConnectSessionResponse, ApiDeleteResponse, ApiOrg, ApiOrgConnection, ApiOrgsResponse, ApiRecord, ApiRecordResponse, ApiRecordType, ApiRowsResponse, ApiSchema, ApiTable, ApiTableOutcome, ApiUpsertResponse, } from './protocol.js';

package/dist/index.js

@@ -1,4 +1,4 @@
-export { ConnectApi, createClient, RecordHandle, TableHandle, } from './client.js';
+export { ConnectApi, createClient, OrgsApi, 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

@@ -10,6 +10,7 @@ export type ApiTable = {
     entity_type: string;
     status: string;
     row_count: number;
+    row_identity: 'record' | 'synthetic' | 'mixed' | null;
     last_built_at: string | null;
     schema_version: string | null;
     columns: ApiColumn[];
@@ -80,3 +81,23 @@ export type ApiConnectSessionResponse = {
     connect_url: string;
     expires_at: string;
 };
+export type ApiOrgConnection = {
+    connector: string;
+    status: string;
+};
+export type ApiOrg = {
+    id: string;
+    display_name: string;
+    status: 'active' | 'revoked' | 'expired';
+    scope: {
+        entity_types: string[];
+    };
+    connections: ApiOrgConnection[];
+    connected_at: string;
+    expires_at: string | null;
+    revoked_at: string | null;
+};
+export type ApiOrgsResponse = {
+    orgs: ApiOrg[];
+    next_cursor: string | null;
+};

package/package.json

@@ -1,47 +1,53 @@
 {
-  "name": "@valtrix/sdk",
-  "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"
+    "name": "@valtrix/sdk",
+    "version": "0.3.0",
+    "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": "src/index.ts",
+    "types": "src/index.ts",
+    "exports": {
+        ".": "./src/index.ts"
+    },
+    "bin": {
+        "valtrix": "./bin/valtrix.mjs"
+    },
+    "files": [
+        "bin",
+        "dist"
+    ],
+    "keywords": [
+        "valtrix",
+        "sdk",
+        "typed-client",
+        "codegen",
+        "data-api"
+    ],
+    "engines": {
+        "node": ">=18.17"
+    },
+    "publishConfig": {
+        "access": "public",
+        "main": "./dist/index.js",
+        "types": "./dist/index.d.ts",
+        "exports": {
+            ".": {
+                "types": "./dist/index.d.ts",
+                "import": "./dist/index.js"
+            }
+        }
+    },
+    "scripts": {
+        "build": "tsc -p tsconfig.build.json",
+        "prepublishOnly": "pnpm build && pnpm test:run",
+        "typecheck": "tsc --noEmit",
+        "test": "vitest",
+        "test:run": "vitest run"
+    },
+    "devDependencies": {
+        "@types/node": "^25.0.8",
+        "@valtrix/tsconfig": "workspace:*",
+        "typescript": "^5.9.3",
+        "vitest": "^4.0.17"
     }
-  },
-  "bin": {
-    "valtrix": "./bin/valtrix.mjs"
-  },
-  "files": [
-    "bin",
-    "dist"
-  ],
-  "keywords": [
-    "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/src/index.ts

@@ -0,0 +1,56 @@
+export {
+    ConnectApi,
+    createClient,
+    OrgsApi,
+    RecordHandle,
+    TableHandle,
+} from './client.js'
+export type {
+    ClientShape,
+    CreateClientConfig,
+    FindManyQuery,
+    MetaFields,
+    OrderBy,
+    Org,
+    OrgsPage,
+    OrgsQuery,
+    OrgStatus,
+    RecordIdFilter,
+    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,
+    ApiDeleteResponse,
+    ApiOrg,
+    ApiOrgConnection,
+    ApiOrgsResponse,
+    ApiRecord,
+    ApiRecordResponse,
+    ApiRecordType,
+    ApiRowsResponse,
+    ApiSchema,
+    ApiTable,
+    ApiTableOutcome,
+    ApiUpsertResponse,
+} from './protocol.js'