@clidey/whodb-sdk 0.0.0

package/dist/hydrate.js

@@ -0,0 +1,83 @@
+import { hydrationRules, hydrationDefault } from './generated/hydration.js';
+/** Coerces one stringly-typed cell into its native type per the shared rules. */
+export function coerceValue(raw, columnType) {
+    if (raw === null || raw === undefined)
+        return null;
+    const kind = hydrationRules[columnType.toLowerCase()] ?? hydrationDefault;
+    switch (kind) {
+        case 'int': {
+            const parsed = Number.parseInt(raw, 10);
+            return Number.isNaN(parsed) ? raw : parsed;
+        }
+        case 'float': {
+            const parsed = Number.parseFloat(raw);
+            return Number.isNaN(parsed) ? raw : parsed;
+        }
+        case 'bool':
+            return raw === 'true' || raw === 't' || raw === '1';
+        case 'timestamp':
+        case 'date': {
+            const parsed = new Date(raw);
+            return Number.isNaN(parsed.getTime()) ? raw : parsed;
+        }
+        case 'json': {
+            try {
+                return JSON.parse(raw);
+            }
+            catch {
+                return raw;
+            }
+        }
+        default:
+            return raw;
+    }
+}
+/**
+ * Normalizes the two wire result shapes to one:
+ * - DatasetQueryResult: { columns: string[] (names only), rows, total }
+ * - RowsResult (CE-derived): { Columns: {Name,Type}[], Rows, TotalCount }
+ * DatasetQueryResult carries no column types — coercion for it comes from
+ * ontology property metadata (dataType), falling back to string.
+ */
+function normalize(result) {
+    const any = result;
+    if (Array.isArray(any.columns)) {
+        return {
+            columns: any.columns.map(name => ({ name, type: '' })),
+            rows: any.rows ?? [],
+            totalCount: any.total ?? null,
+        };
+    }
+    return {
+        columns: (any.Columns ?? []).map(c => ({ name: c.Name, type: c.Type })),
+        rows: (any.Rows ?? []),
+        totalCount: any.TotalCount ?? null,
+    };
+}
+/** Builds a property-type map from ontology entity metadata. */
+export function propertyTypesOf(entity) {
+    const map = new Map();
+    for (const property of entity.properties ?? []) {
+        if (property?.apiName && property?.dataType) {
+            map.set(property.apiName, property.dataType);
+        }
+    }
+    return map;
+}
+/**
+ * Hydrates a stringly-typed result into native-typed row objects. Ontology
+ * property metadata, when supplied, overrides the wire column type — the
+ * ontology's dataType is more precise than the storage column type.
+ */
+export function hydrateRows(result, propertyTypes) {
+    const { columns, rows, totalCount } = normalize(result);
+    const hydrated = rows.map(cells => {
+        const row = {};
+        columns.forEach((column, index) => {
+            const type = propertyTypes?.get(column.name) ?? column.type;
+            row[column.name] = coerceValue(cells[index] ?? null, type);
+        });
+        return row;
+    });
+    return { rows: hydrated, totalCount: totalCount ?? null };
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export { WhoDB } from './client.js';
+export type { WhoDBConfig } from './config.js';
+export type { Transport } from './transport.js';
+export { IpcTransport } from './transport-ipc.js';
+export type { CredentialProvider } from './auth.js';
+export { apiKeyProvider, tokenProvider, cliProvider } from './auth.js';
+export { WhoDBError, AuthError, NotFoundError, ValidationError, WhoDBVersionError, CliCredentialsError, TransportCapabilityError, PlatformError, } from './errors.js';
+export type { Row } from './hydrate.js';
+export type { Page } from './pagination.js';
+export { ListCall } from './pagination.js';
+export { OntologyHandle } from './ontology.js';
+export { DatasetHandle } from './dataset.js';
+export { SourceHandle } from './source.js';
+export { FilesHandle } from './files.js';

package/dist/index.js

@@ -0,0 +1,9 @@
+export { WhoDB } from './client.js';
+export { IpcTransport } from './transport-ipc.js';
+export { apiKeyProvider, tokenProvider, cliProvider } from './auth.js';
+export { WhoDBError, AuthError, NotFoundError, ValidationError, WhoDBVersionError, CliCredentialsError, TransportCapabilityError, PlatformError, } from './errors.js';
+export { ListCall } from './pagination.js';
+export { OntologyHandle } from './ontology.js';
+export { DatasetHandle } from './dataset.js';
+export { SourceHandle } from './source.js';
+export { FilesHandle } from './files.js';

package/dist/manifest-check.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Emits the two-tier versioning-policy warnings for an operation, once per
+ * process (SDK_DESIGN.md §2.3): deprecated → upgrade-before-sunset warning;
+ * behaviorChanged → semantics-changed warning. Actually-removed operations
+ * surface as WhoDBVersionError from interpretServerError below.
+ */
+export declare function warnIfFlagged(operationName: string): void;
+/**
+ * Detects the server rejecting an operation this SDK was generated with —
+ * the operation was removed after this SDK release. Converts the low-level
+ * validation error into the actionable upgrade error.
+ */
+export declare function interpretServerError(error: unknown, sdkVersion: string): unknown;
+/** Test hook: clears the once-per-process warning memory. */
+export declare function resetWarnings(): void;

package/dist/manifest-check.js

@@ -0,0 +1,43 @@
+import { embeddedManifest } from './generated/manifest.js';
+import { WhoDBVersionError } from './errors.js';
+const warned = new Set();
+/**
+ * Emits the two-tier versioning-policy warnings for an operation, once per
+ * process (SDK_DESIGN.md §2.3): deprecated → upgrade-before-sunset warning;
+ * behaviorChanged → semantics-changed warning. Actually-removed operations
+ * surface as WhoDBVersionError from interpretServerError below.
+ */
+export function warnIfFlagged(operationName) {
+    const entry = embeddedManifest[operationName];
+    if (!entry || warned.has(operationName))
+        return;
+    if (entry.deprecated) {
+        warned.add(operationName);
+        console.warn(`[whodb] ${operationName} is deprecated${entry.sunsetAt ? ` and will be removed after ${entry.sunsetAt}` : ''} — upgrade @clidey/whodb-sdk before then.${entry.note ? ` ${entry.note}` : ''}`);
+    }
+    else if (entry.behaviorChanged) {
+        warned.add(operationName);
+        console.warn(`[whodb] ${operationName}'s behavior changed in this platform release — results may differ from previous SDK versions.${entry.note ? ` ${entry.note}` : ''}`);
+    }
+}
+const UNKNOWN_OPERATION_PATTERNS = [
+    /Cannot query field/i,
+    /Unknown field/i,
+    /Unknown type/i,
+    /has no field/i,
+];
+/**
+ * Detects the server rejecting an operation this SDK was generated with —
+ * the operation was removed after this SDK release. Converts the low-level
+ * validation error into the actionable upgrade error.
+ */
+export function interpretServerError(error, sdkVersion) {
+    if (error instanceof Error && UNKNOWN_OPERATION_PATTERNS.some(p => p.test(error.message))) {
+        return new WhoDBVersionError(`this SDK (${sdkVersion}) was built for an older WhoDB platform API; upgrade the @clidey/whodb-sdk package`);
+    }
+    return error;
+}
+/** Test hook: clears the once-per-process warning memory. */
+export function resetWarnings() {
+    warned.clear();
+}

package/dist/ontology.d.ts

@@ -0,0 +1,73 @@
+import type { Transport } from './transport.js';
+import type { OntologyDescription, OntologyFastLookup, OntologyObjectType, OntologyStatsResult, OntologySimilarInput, OntologySimilarityResult, OntologyQueryInput, OntologyQuerySortInput, OntologyAggregateMetricInput, WhereCondition, SortCondition, OntologyAddRowsResult } from './generated/types.js';
+import { type Row } from './hydrate.js';
+import { ListCall } from './pagination.js';
+/** Options for list-shaped ontology reads. `where` is a JSON filter object
+ * (property → { eq/gt/lt/in/... }) serialized into OntologyQuery.whereJson. */
+export interface ListOptions {
+    where?: Record<string, unknown>;
+    sort?: OntologyQuerySortInput[];
+    pageSize?: number;
+}
+/** Options for the flexible query surface (search, joins, grouping). */
+export interface QueryOptions extends Omit<OntologyQueryInput, 'entity'> {
+}
+/** Options for aggregations. */
+export interface AggregateOptions {
+    groupBy: string[];
+    metrics?: OntologyAggregateMetricInput[];
+    where?: WhereCondition;
+    sort?: SortCondition[];
+    pageSize?: number;
+}
+/**
+ * OntologyHandle is the `whodb.ontology("User")` facade: reads and record
+ * writes for one ontology entity, addressed by apiName. Entity metadata is
+ * fetched once per handle and reused for pk lookups and row hydration.
+ */
+export declare class OntologyHandle {
+    private readonly transport;
+    private readonly projectId;
+    private readonly apiName;
+    private entityCache;
+    constructor(transport: Transport, projectId: () => Promise<string>, apiName: string);
+    /** Resolves and caches the entity metadata backing this handle. */
+    entityMeta(): Promise<OntologyObjectType>;
+    private propertyTypes;
+    /** Describes the entity: schema, properties, links, sample queries. */
+    describe(): Promise<OntologyDescription>;
+    /** Fetches a single record by primary key, or null when absent. */
+    get(pk: string | number): Promise<Row | null>;
+    /** Lists records with optional filter/sort; supports .pages() iteration. */
+    list(options?: ListOptions): ListCall;
+    /** Flexible query: text search, joins, grouping, metrics. */
+    query(options: QueryOptions): Promise<Row[]>;
+    /** Aggregates records grouped by properties with metric functions. */
+    aggregate(options: AggregateOptions): Promise<Row[]>;
+    /** Statistical summary of one property. */
+    stats(property: string, options?: {
+        where?: WhereCondition;
+    }): Promise<OntologyStatsResult>;
+    /** Embedding-based similarity search over this entity's records. */
+    similar(input: Omit<OntologySimilarInput, 'entityId'>): Promise<OntologySimilarityResult>;
+    /** Follows an outgoing link from one record to its related records. */
+    followLink(pk: string | number, linkApiName: string, options?: {
+        pageSize?: number;
+    }): ListCall;
+    /** Follows a link inbound from another entity's records to this record. */
+    followIncomingLink(pk: string | number, sourceEntityApiName: string, linkApiName: string, options?: {
+        pageSize?: number;
+    }): ListCall;
+    /** Lists the entity's fast lookups. */
+    fastLookups(): Promise<OntologyFastLookup[]>;
+    /** Inserts one record. Values are field name/value pairs. */
+    create(values: Record<string, unknown>): Promise<void>;
+    /** Inserts many records; idempotencyKey makes safe retries possible. */
+    createMany(rows: Array<Record<string, unknown>>, options?: {
+        idempotencyKey?: string;
+    }): Promise<OntologyAddRowsResult>;
+    /** Updates one record identified by primary key. */
+    update(pk: string | number, values: Record<string, unknown>): Promise<void>;
+    /** Deletes one record identified by primary key. */
+    delete(pk: string | number): Promise<void>;
+}

package/dist/ontology.js

@@ -0,0 +1,240 @@
+import * as ops from './generated/operations.js';
+import { hydrateRows, propertyTypesOf } from './hydrate.js';
+import { ListCall } from './pagination.js';
+import { warnIfFlagged } from './manifest-check.js';
+import { NotFoundError, ValidationError } from './errors.js';
+const DEFAULT_PAGE_SIZE = 100;
+/**
+ * OntologyHandle is the `whodb.ontology("User")` facade: reads and record
+ * writes for one ontology entity, addressed by apiName. Entity metadata is
+ * fetched once per handle and reused for pk lookups and row hydration.
+ */
+export class OntologyHandle {
+    transport;
+    projectId;
+    apiName;
+    entityCache = null;
+    constructor(transport, projectId, apiName) {
+        this.transport = transport;
+        this.projectId = projectId;
+        this.apiName = apiName;
+    }
+    /** Resolves and caches the entity metadata backing this handle. */
+    async entityMeta() {
+        if (this.entityCache)
+            return this.entityCache;
+        warnIfFlagged('OntologyEntities');
+        const entities = await ops.ontologyEntities(this.transport, { projectId: await this.projectId() });
+        const entity = entities.find(e => e.apiName === this.apiName);
+        if (!entity) {
+            throw new NotFoundError(`ontology entity "${this.apiName}" not found in this project`);
+        }
+        this.entityCache = entity;
+        return entity;
+    }
+    async propertyTypes() {
+        return propertyTypesOf(await this.entityMeta());
+    }
+    /** Describes the entity: schema, properties, links, sample queries. */
+    async describe() {
+        await this.entityMeta(); // NotFoundError for unknown entities
+        warnIfFlagged('OntologyDescribe');
+        return ops.ontologyDescribe(this.transport, {
+            projectId: await this.projectId(),
+            input: { entities: [this.apiName], includeInferred: true },
+        });
+    }
+    /** Fetches a single record by primary key, or null when absent. */
+    async get(pk) {
+        const entity = await this.entityMeta();
+        if (!entity.primaryKey) {
+            throw new ValidationError(`entity "${this.apiName}" has no primary key — use list() with a where filter`);
+        }
+        warnIfFlagged('OntologyQuery');
+        const result = await ops.ontologyQuery(this.transport, {
+            projectId: await this.projectId(),
+            input: {
+                entity: this.apiName,
+                whereJson: JSON.stringify({ [entity.primaryKey]: { eq: String(pk) } }),
+                pageSize: 1,
+                offset: 0,
+            },
+        });
+        const { rows } = hydrateRows(result, await this.propertyTypes());
+        return rows[0] ?? null;
+    }
+    /** Lists records with optional filter/sort; supports .pages() iteration. */
+    list(options = {}) {
+        const pageSize = options.pageSize ?? DEFAULT_PAGE_SIZE;
+        return new ListCall(async (pageOffset) => {
+            // Resolve entity metadata first: hydration types come from it, and an
+            // unknown entity should fail with NotFoundError before any query runs.
+            const propertyTypes = await this.propertyTypes();
+            warnIfFlagged('OntologyQuery');
+            // OntologyQuery (not OntologyRows) is the list path: it supports
+            // filter + sort, and addresses the entity by apiName directly.
+            const result = await ops.ontologyQuery(this.transport, {
+                projectId: await this.projectId(),
+                input: {
+                    entity: this.apiName,
+                    whereJson: options.where ? JSON.stringify(options.where) : null,
+                    sort: options.sort ?? null,
+                    pageSize,
+                    offset: pageOffset,
+                },
+            });
+            const { rows, totalCount } = hydrateRows(result, propertyTypes);
+            return { rows, totalCount, pageOffset };
+        }, pageSize);
+    }
+    /** Flexible query: text search, joins, grouping, metrics. */
+    async query(options) {
+        warnIfFlagged('OntologyQuery');
+        const result = await ops.ontologyQuery(this.transport, {
+            projectId: await this.projectId(),
+            input: { ...options, entity: this.apiName },
+        });
+        return hydrateRows(result, await this.propertyTypes()).rows;
+    }
+    /** Aggregates records grouped by properties with metric functions. */
+    async aggregate(options) {
+        const entity = await this.entityMeta();
+        warnIfFlagged('OntologyAggregate');
+        const result = await ops.ontologyAggregate(this.transport, {
+            projectId: await this.projectId(),
+            id: entity.id,
+            groupBy: options.groupBy,
+            metrics: options.metrics ?? [],
+            where: options.where ?? null,
+            sort: options.sort ?? null,
+            pageSize: options.pageSize ?? DEFAULT_PAGE_SIZE,
+            pageOffset: 0,
+        });
+        return hydrateRows(result).rows;
+    }
+    /** Statistical summary of one property. */
+    async stats(property, options = {}) {
+        const entity = await this.entityMeta();
+        warnIfFlagged('OntologyStats');
+        return ops.ontologyStats(this.transport, {
+            projectId: await this.projectId(),
+            id: entity.id,
+            property,
+            where: options.where ?? null,
+        });
+    }
+    /** Embedding-based similarity search over this entity's records. */
+    async similar(input) {
+        const entity = await this.entityMeta();
+        warnIfFlagged('OntologySimilar');
+        return ops.ontologySimilar(this.transport, {
+            projectId: await this.projectId(),
+            input: { ...input, entityId: entity.id },
+        });
+    }
+    /** Follows an outgoing link from one record to its related records. */
+    followLink(pk, linkApiName, options = {}) {
+        const pageSize = options.pageSize ?? DEFAULT_PAGE_SIZE;
+        return new ListCall(async (pageOffset) => {
+            const entity = await this.entityMeta();
+            warnIfFlagged('OntologyFollowLink');
+            const result = await ops.ontologyFollowLink(this.transport, {
+                projectId: await this.projectId(),
+                entityId: entity.id,
+                pk: String(pk),
+                linkApiName,
+                pageSize,
+                pageOffset,
+            });
+            const { rows, totalCount } = hydrateRows(result);
+            return { rows, totalCount, pageOffset };
+        }, pageSize);
+    }
+    /** Follows a link inbound from another entity's records to this record. */
+    followIncomingLink(pk, sourceEntityApiName, linkApiName, options = {}) {
+        const pageSize = options.pageSize ?? DEFAULT_PAGE_SIZE;
+        return new ListCall(async (pageOffset) => {
+            const entity = await this.entityMeta();
+            warnIfFlagged('OntologyEntities');
+            const sourceEntities = await ops.ontologyEntities(this.transport, { projectId: await this.projectId() });
+            const source = sourceEntities.find(e => e.apiName === sourceEntityApiName);
+            if (!source)
+                throw new NotFoundError(`ontology entity "${sourceEntityApiName}" not found in this project`);
+            warnIfFlagged('OntologyFollowIncomingLink');
+            const result = await ops.ontologyFollowIncomingLink(this.transport, {
+                projectId: await this.projectId(),
+                entityId: entity.id,
+                pk: String(pk),
+                sourceEntityId: source.id,
+                linkApiName,
+                pageSize,
+                pageOffset,
+            });
+            const { rows, totalCount } = hydrateRows(result);
+            return { rows, totalCount, pageOffset };
+        }, pageSize);
+    }
+    /** Lists the entity's fast lookups. */
+    async fastLookups() {
+        const entity = await this.entityMeta();
+        warnIfFlagged('OntologyFastLookups');
+        return ops.ontologyFastLookups(this.transport, {
+            projectId: await this.projectId(),
+            entityId: entity.id,
+        });
+    }
+    /** Inserts one record. Values are field name/value pairs. */
+    async create(values) {
+        const entity = await this.entityMeta();
+        warnIfFlagged('OntologyAddRow');
+        await ops.ontologyAddRow(this.transport, {
+            projectId: await this.projectId(),
+            entityId: entity.id,
+            values: toRecordInputs(values),
+        });
+    }
+    /** Inserts many records; idempotencyKey makes safe retries possible. */
+    async createMany(rows, options = {}) {
+        const entity = await this.entityMeta();
+        warnIfFlagged('OntologyAddRows');
+        return ops.ontologyAddRows(this.transport, {
+            projectId: await this.projectId(),
+            entityId: entity.id,
+            rows: rows.map(row => ({ values: toRecordInputs(row) })),
+            idempotencyKey: options.idempotencyKey ?? null,
+        });
+    }
+    /** Updates one record identified by primary key. */
+    async update(pk, values) {
+        const entity = await this.entityMeta();
+        if (!entity.primaryKey) {
+            throw new ValidationError(`entity "${this.apiName}" has no primary key — updates are not supported`);
+        }
+        warnIfFlagged('OntologyUpdateRow');
+        await ops.ontologyUpdateRow(this.transport, {
+            projectId: await this.projectId(),
+            entityId: entity.id,
+            values: toRecordInputs({ ...values, [entity.primaryKey]: String(pk) }),
+            updatedColumns: Object.keys(values),
+        });
+    }
+    /** Deletes one record identified by primary key. */
+    async delete(pk) {
+        const entity = await this.entityMeta();
+        if (!entity.primaryKey) {
+            throw new ValidationError(`entity "${this.apiName}" has no primary key — deletes are not supported`);
+        }
+        warnIfFlagged('OntologyDeleteRow');
+        await ops.ontologyDeleteRow(this.transport, {
+            projectId: await this.projectId(),
+            entityId: entity.id,
+            values: toRecordInputs({ [entity.primaryKey]: String(pk) }),
+        });
+    }
+}
+function toRecordInputs(values) {
+    return Object.entries(values).map(([key, value]) => ({
+        Key: key,
+        Value: value === null || value === undefined ? '' : typeof value === 'object' ? JSON.stringify(value) : String(value),
+    }));
+}

package/dist/pagination.d.ts

@@ -0,0 +1,21 @@
+import type { Row } from './hydrate.js';
+/** One page of hydrated rows. */
+export interface Page {
+    rows: Row[];
+    totalCount: number | null;
+    pageOffset: number;
+}
+/**
+ * ListCall is the thenable returned by paginated facade methods: `await`
+ * yields the first page's rows; `.pages()` iterates all pages.
+ */
+export declare class ListCall implements PromiseLike<Row[]> {
+    private readonly fetchPage;
+    private readonly pageSize;
+    constructor(fetchPage: (pageOffset: number) => Promise<Page>, pageSize: number);
+    then<TResult1 = Row[], TResult2 = never>(onfulfilled?: ((value: Row[]) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): PromiseLike<TResult1 | TResult2>;
+    /** Iterates pages until a short page signals the end of the result set. */
+    pages(): AsyncGenerator<Page>;
+    /** Iterates individual rows across all pages. */
+    [Symbol.asyncIterator](): AsyncGenerator<Row>;
+}

package/dist/pagination.js

@@ -0,0 +1,33 @@
+/**
+ * ListCall is the thenable returned by paginated facade methods: `await`
+ * yields the first page's rows; `.pages()` iterates all pages.
+ */
+export class ListCall {
+    fetchPage;
+    pageSize;
+    constructor(fetchPage, pageSize) {
+        this.fetchPage = fetchPage;
+        this.pageSize = pageSize;
+    }
+    then(onfulfilled, onrejected) {
+        return this.fetchPage(0).then(page => page.rows).then(onfulfilled, onrejected);
+    }
+    /** Iterates pages until a short page signals the end of the result set. */
+    async *pages() {
+        let offset = 0;
+        for (;;) {
+            const page = await this.fetchPage(offset);
+            yield page;
+            if (page.rows.length < this.pageSize)
+                return;
+            offset += this.pageSize;
+        }
+    }
+    /** Iterates individual rows across all pages. */
+    async *[Symbol.asyncIterator]() {
+        for await (const page of this.pages()) {
+            for (const row of page.rows)
+                yield row;
+        }
+    }
+}

package/dist/source.d.ts

@@ -0,0 +1,31 @@
+import type { Transport } from './transport.js';
+import type { Column, PlatformSource, SourceObject, SourceObjectRefInput, WhereCondition, SortCondition } from './generated/types.js';
+import { ListCall } from './pagination.js';
+/** Options for source row reads. */
+export interface SourceRowsOptions {
+    where?: WhereCondition;
+    sort?: SortCondition[];
+    pageSize?: number;
+}
+/**
+ * SourceHandle is the `whodb.source("src_...")` facade: browse and read a
+ * connected data source by ID.
+ */
+export declare class SourceHandle {
+    private readonly transport;
+    private readonly projectId;
+    private readonly sourceId;
+    constructor(transport: Transport, projectId: () => Promise<string>, sourceId: string);
+    /** Lists browsable objects (schemas, tables, collections...). */
+    objects(options?: {
+        parent?: SourceObjectRefInput;
+        pageSize?: number;
+        pageOffset?: number;
+    }): Promise<SourceObject[]>;
+    /** Lists the columns of one object (table/collection). */
+    columns(ref: SourceObjectRefInput): Promise<Column[]>;
+    /** Reads rows from one object; supports .pages() iteration. */
+    rows(ref: SourceObjectRefInput, options?: SourceRowsOptions): ListCall;
+}
+/** Lists the project's sources. */
+export declare function listSources(transport: Transport, projectId: string): Promise<PlatformSource[]>;

package/dist/source.js

@@ -0,0 +1,63 @@
+import * as ops from './generated/operations.js';
+import { hydrateRows } from './hydrate.js';
+import { ListCall } from './pagination.js';
+import { warnIfFlagged } from './manifest-check.js';
+const DEFAULT_PAGE_SIZE = 100;
+/**
+ * SourceHandle is the `whodb.source("src_...")` facade: browse and read a
+ * connected data source by ID.
+ */
+export class SourceHandle {
+    transport;
+    projectId;
+    sourceId;
+    constructor(transport, projectId, sourceId) {
+        this.transport = transport;
+        this.projectId = projectId;
+        this.sourceId = sourceId;
+    }
+    /** Lists browsable objects (schemas, tables, collections...). */
+    async objects(options = {}) {
+        warnIfFlagged('PlatformSourceObjects');
+        return ops.platformSourceObjects(this.transport, {
+            projectId: await this.projectId(),
+            sourceId: this.sourceId,
+            parent: options.parent ?? null,
+            kinds: null,
+            pageSize: options.pageSize ?? null,
+            pageOffset: options.pageOffset ?? null,
+        });
+    }
+    /** Lists the columns of one object (table/collection). */
+    async columns(ref) {
+        warnIfFlagged('PlatformSourceColumns');
+        return ops.platformSourceColumns(this.transport, {
+            projectId: await this.projectId(),
+            sourceId: this.sourceId,
+            ref,
+        });
+    }
+    /** Reads rows from one object; supports .pages() iteration. */
+    rows(ref, options = {}) {
+        const pageSize = options.pageSize ?? DEFAULT_PAGE_SIZE;
+        return new ListCall(async (pageOffset) => {
+            warnIfFlagged('PlatformSourceRows');
+            const result = await ops.platformSourceRows(this.transport, {
+                projectId: await this.projectId(),
+                sourceId: this.sourceId,
+                ref,
+                where: options.where ?? null,
+                sort: options.sort ?? null,
+                pageSize,
+                pageOffset,
+            });
+            const { rows, totalCount } = hydrateRows(result);
+            return { rows, totalCount, pageOffset };
+        }, pageSize);
+    }
+}
+/** Lists the project's sources. */
+export async function listSources(transport, projectId) {
+    warnIfFlagged('ProjectSources');
+    return ops.projectSources(transport, { projectId });
+}

package/dist/transport-http.d.ts

@@ -0,0 +1,22 @@
+import type { Transport } from './transport.js';
+import type { CredentialProvider } from './auth.js';
+/** Options for the default GraphQL-over-HTTP transport. */
+export interface HttpTransportOptions {
+    host: string;
+    credentials: CredentialProvider;
+    orgId?: string;
+    projectId?: string;
+}
+/**
+ * HttpTransport posts operations to `<host>/api/query` with bearer
+ * credentials and workspace headers. It retries once on a transient 5xx and
+ * once after refreshing credentials on a 401.
+ */
+export declare class HttpTransport implements Transport {
+    private readonly options;
+    constructor(options: HttpTransportOptions);
+    /** Sets the workspace scope headers used on subsequent requests. */
+    setWorkspace(orgId: string | undefined, projectId: string | undefined): void;
+    execute(operationName: string, document: string, variables: Record<string, unknown>): Promise<Record<string, unknown>>;
+    private post;
+}