@valtrix/sdk 0.1.0 → 0.2.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,6 @@ export type CliIo = {
     error: (message: string) => void;
     fetchImpl?: typeof fetch;
 };
+export declare function parseEnvFile(content: string): Record<string, string>;
+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

@@ -2,7 +2,42 @@ 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.com';
+const DEFAULT_BASE_URL = 'https://api.valtrix.vojtadrmota.com';
+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;
+}
+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 +67,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';

package/dist/client.js

@@ -196,7 +196,7 @@ export class ConnectApi {
         return { connectUrl: response.connect_url, expiresAt: response.expires_at };
     }
 }
-const DEFAULT_BASE_URL = 'https://api.valtrix.com';
+const DEFAULT_BASE_URL = 'https://api.valtrix.vojtadrmota.com';
 function resolveEnv(name) {
     if (typeof process === 'undefined')
         return undefined;

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 type { ClientShape, CreateClientConfig, FindManyQuery, MetaFields, OrderBy, 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, ApiRecord, ApiRecordResponse, ApiRecordType, ApiRowsResponse, ApiSchema, ApiTable, ApiTableOutcome, ApiUpsertResponse, } from './protocol.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valtrix/sdk",
-  "version": "0.1.0",
+  "version": "0.2.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",