@valtrix/sdk 0.2.0 → 0.4.0

package/dist/cli.d.ts

@@ -3,6 +3,5 @@ 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

@@ -1,31 +1,9 @@
 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';
-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) {

package/dist/client.d.ts

@@ -133,17 +133,65 @@ 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 RecordLookupResult = {
+    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]>;
+    } & {
+        get: (recordId: string) => Promise<RecordLookupResult>;
     };
     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');
@@ -222,8 +296,23 @@ export function createClient(config) {
     for (const entityType of config.records) {
         records[entityType] = new RecordHandle(http, entityType);
     }
+    records.get = async (recordId) => {
+        const response = await http.request('GET', `/v1/records/${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.records = records;
     client.connect = new ConnectApi(http);
+    client.orgs = new OrgsApi(http);
     client.schema = () => http.request('GET', '/v1/schema');
     return client;
 }

package/dist/codegen.js

@@ -30,6 +30,8 @@ function columnDoc(column, indent) {
     const extra = [];
     if (column.type === 'date')
         extra.push('ISO 8601 date string.');
+    if (column.type === 'reference')
+        extra.push('Valtrix record ID of the referenced record.');
     if (column.writable)
         extra.push('Writable through valtrix.records.');
     return docComment(column.description, extra, indent);
@@ -53,7 +55,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 (rec_ prefix) resolves via records.get().'
+            : 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 record (rec_ prefix) and synthetic (syn_ prefix) ids; only record ids resolve via records.get().'
+                    : '';
+        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, RecordIdFilter, 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, ApiDeleteResponse, ApiRecord, ApiRecordResponse, ApiRecordType, ApiRowsResponse, ApiSchema, ApiTable, ApiTableOutcome, 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

@@ -1,6 +1,6 @@
 export type ApiColumn = {
     key: string;
-    type: 'string' | 'number' | 'boolean' | 'date' | 'json';
+    type: 'string' | 'number' | 'boolean' | 'date' | 'json' | 'reference';
     nullable: boolean;
     description: string;
     writable: boolean;
@@ -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,6 +1,6 @@
 {
   "name": "@valtrix/sdk",
-  "version": "0.2.0",
+  "version": "0.4.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",