@clidey/whodb-sdk 0.0.0

package/README.md

@@ -0,0 +1,81 @@
+# @clidey/whodb-sdk
+
+Official TypeScript/JavaScript SDK for the [WhoDB](https://whodb.com) hosted
+platform — your ontology, datasets, and sources as in-code function APIs.
+
+## Install
+
+```bash
+npm install @clidey/whodb-sdk
+```
+
+Requires Node.js ≥ 20.
+
+## Quickstart
+
+```ts
+import { WhoDB } from '@clidey/whodb-sdk';
+
+// Production: API key (create one in org settings → API keys).
+// The key carries its org; the project auto-resolves when the key
+// has access to exactly one project.
+const whodb = new WhoDB({ apiKey: process.env.WHODB_API_KEY });
+
+// Local development: zero config — reuses your `whodb login` session.
+// const whodb = new WhoDB();
+
+const users = whodb.ontology('User');
+
+const user = await users.get('u_123');
+const active = await users.list({ where: { status: { eq: 'active' } }, pageSize: 100 });
+await users.create({ email: 'a@b.co' });
+await users.createMany(rows, { idempotencyKey: 'import-42' });
+await users.update('u_123', { plan: 'pro' });
+const orders = await users.followLink('u_123', 'orders');
+
+// Iterate everything, page by page:
+for await (const page of users.list({ pageSize: 500 }).pages()) {
+  console.log(page.rows.length);
+}
+
+// Datasets and sources:
+const kpis = await whodb.dataset('weekly_kpis').rows();
+const raw = await whodb.source('src_...').rows({ Kind: 'Table', Locator: 'events' });
+```
+
+## Authentication
+
+Credential precedence:
+
+1. `new WhoDB({ apiKey })` / `{ token }` / `{ credentials }` constructor options
+2. `WHODB_API_KEY` environment variable
+3. The `whodb` CLI's stored login (`whodb login`), gcloud-ADC-style — ideal
+   for local development
+
+Workspace (`org` / `project`) is optional with an API key; pass `{ project }`
+or set `WHODB_PROJECT` when the key has access to more than one project.
+
+## Typed clients
+
+Generate typed entity classes from your project's ontology:
+
+```bash
+whodb sdk generate --language ts --out src/whodb-gen/
+```
+
+```ts
+import { createClient } from './whodb-gen/whodb.generated.js';
+
+const { ontology } = createClient({ apiKey: process.env.WHODB_API_KEY });
+const user = await ontology.User.get('u_123'); // fully typed
+```
+
+## Versioning
+
+Each SDK release is generated against one WhoDB platform release. Deprecated
+operations warn once per process with their removal date; operations removed
+from the platform raise `WhoDBVersionError` — upgrade the package to resolve.
+
+## License
+
+Apache-2.0

package/dist/auth.d.ts

@@ -0,0 +1,26 @@
+/**
+ * CredentialProvider yields a bearer credential for platform requests.
+ * refresh() is invoked once after a 401 before the request is retried.
+ */
+export interface CredentialProvider {
+    token(): Promise<string>;
+    refresh?(): Promise<void>;
+    /** Workspace defaults carried by the credential source, if any. */
+    defaults?(): Promise<WorkspaceDefaults>;
+}
+/** Workspace defaults resolved from a credential source (CLI helper). */
+export interface WorkspaceDefaults {
+    host?: string;
+    orgId?: string;
+    projectId?: string;
+}
+/** Static API-key credentials (production/headless usage). */
+export declare function apiKeyProvider(apiKey: string): CredentialProvider;
+/** Static OIDC token or caller-managed token callback. */
+export declare function tokenProvider(source: string | (() => Promise<string>)): CredentialProvider;
+/**
+ * CLI credentials: exec `whodb auth print-token --format json` and cache the
+ * token until shortly before its expiry — the gcloud-ADC pattern for local
+ * development. Requires the whodb CLI on PATH and a prior `whodb login`.
+ */
+export declare function cliProvider(command?: string): CredentialProvider;

package/dist/auth.js

@@ -0,0 +1,65 @@
+import { execFile } from 'node:child_process';
+import { AuthError, CliCredentialsError } from './errors.js';
+/** Static API-key credentials (production/headless usage). */
+export function apiKeyProvider(apiKey) {
+    return {
+        token: async () => apiKey,
+    };
+}
+/** Static OIDC token or caller-managed token callback. */
+export function tokenProvider(source) {
+    if (typeof source === 'string') {
+        return { token: async () => source };
+    }
+    return { token: source };
+}
+const CLI_REFRESH_SKEW_MS = 60_000;
+/**
+ * CLI credentials: exec `whodb auth print-token --format json` and cache the
+ * token until shortly before its expiry — the gcloud-ADC pattern for local
+ * development. Requires the whodb CLI on PATH and a prior `whodb login`.
+ */
+export function cliProvider(command = 'whodb') {
+    let cached = null;
+    const exec = () => new Promise((resolvePromise, rejectPromise) => {
+        execFile(command, ['auth', 'print-token', '--format', 'json'], { timeout: 15_000 }, (error, stdout, stderr) => {
+            if (error) {
+                if (error.code === 'ENOENT') {
+                    rejectPromise(new CliCredentialsError(`whodb CLI not found — install it or set WHODB_API_KEY`));
+                    return;
+                }
+                rejectPromise(new CliCredentialsError(`whodb auth print-token failed: ${stderr.trim() || error.message}`));
+                return;
+            }
+            try {
+                resolvePromise(JSON.parse(stdout));
+            }
+            catch {
+                rejectPromise(new CliCredentialsError('whodb auth print-token returned invalid JSON'));
+            }
+        });
+    });
+    const isFresh = (entry) => {
+        if (!entry.expires_at)
+            return false; // no expiry info — re-exec every call
+        return new Date(entry.expires_at).getTime() - Date.now() > CLI_REFRESH_SKEW_MS;
+    };
+    return {
+        async token() {
+            if (cached && isFresh(cached))
+                return cached.access_token;
+            cached = await exec();
+            if (!cached.access_token)
+                throw new AuthError('whodb CLI returned an empty access token');
+            return cached.access_token;
+        },
+        async refresh() {
+            cached = null;
+        },
+        async defaults() {
+            if (!cached)
+                cached = await exec();
+            return { host: cached.host, orgId: cached.org_id, projectId: cached.project_id };
+        },
+    };
+}

package/dist/client.d.ts

@@ -0,0 +1,51 @@
+import type { Transport } from './transport.js';
+import { type WhoDBConfig } from './config.js';
+import { OntologyHandle } from './ontology.js';
+import { DatasetHandle } from './dataset.js';
+import { SourceHandle } from './source.js';
+import { FilesHandle } from './files.js';
+import type { OntologyObjectType, PlatformSource } from './generated/types.js';
+/**
+ * WhoDB is the platform client. Configure with an API key (headless), a raw
+ * token, or nothing at all — local development falls back to `whodb login`
+ * credentials via the CLI helper.
+ *
+ * ```ts
+ * const whodb = new WhoDB({ apiKey: process.env.WHODB_API_KEY, org: "acme", project: "growth" });
+ * const user = await whodb.ontology("User").get("u_123");
+ * ```
+ */
+export declare class WhoDB {
+    /** SHA-256 of the platform manifest this SDK release was generated from. */
+    static readonly manifestHash = "4b84678f5fe7d777fbd4c4b2a93dff64f4c8951978ce68006ddc3a0e25c6942f";
+    /** This SDK package's version. */
+    static readonly version = "0.0.0";
+    private readonly transport;
+    private readonly httpTransport;
+    private readonly filesHandle;
+    private readonly orgInput?;
+    private readonly projectInput?;
+    private workspacePromise;
+    constructor(config?: WhoDBConfig, transportOverride?: Transport);
+    private cliDefaults;
+    private skipWorkspaceResolution;
+    private usingApiKey;
+    /**
+     * Resolves org/project slugs or IDs to IDs, once, and stamps the workspace
+     * headers onto the transport. IDs pass through without a lookup.
+     */
+    private workspace;
+    private projectId;
+    /** Returns a handle for one ontology entity, addressed by apiName. */
+    ontology(name: string): OntologyHandle;
+    /** Lists all ontology entities in the project. */
+    ontologyEntities(): Promise<OntologyObjectType[]>;
+    /** Returns a handle for one dataset, addressed by name. */
+    dataset(name: string): DatasetHandle;
+    /** Returns a handle for one connected source, addressed by ID. */
+    source(id: string): SourceHandle;
+    /** Lists the project's connected sources. */
+    sources(): Promise<PlatformSource[]>;
+    /** File upload/download over the platform's bulk HTTP endpoints. */
+    get files(): FilesHandle;
+}

package/dist/client.js

@@ -0,0 +1,157 @@
+import { HttpTransport } from './transport-http.js';
+import { IpcTransport } from './transport-ipc.js';
+import { resolveConfig, DEFAULT_HOST } from './config.js';
+import { OntologyHandle } from './ontology.js';
+import { DatasetHandle } from './dataset.js';
+import { SourceHandle, listSources } from './source.js';
+import { FilesHandle } from './files.js';
+import * as ops from './generated/operations.js';
+import { manifestHash } from './generated/manifest.js';
+import { ValidationError } from './errors.js';
+import { SDK_VERSION } from './version.js';
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * WhoDB is the platform client. Configure with an API key (headless), a raw
+ * token, or nothing at all — local development falls back to `whodb login`
+ * credentials via the CLI helper.
+ *
+ * ```ts
+ * const whodb = new WhoDB({ apiKey: process.env.WHODB_API_KEY, org: "acme", project: "growth" });
+ * const user = await whodb.ontology("User").get("u_123");
+ * ```
+ */
+export class WhoDB {
+    /** SHA-256 of the platform manifest this SDK release was generated from. */
+    static manifestHash = manifestHash;
+    /** This SDK package's version. */
+    static version = SDK_VERSION;
+    transport;
+    httpTransport;
+    filesHandle;
+    orgInput;
+    projectInput;
+    workspacePromise = null;
+    constructor(config = {}, transportOverride) {
+        // Functions runtime autodetect: no explicit transport/credentials and the
+        // IPC env vars are present → route through the in-container IPC server.
+        if (!transportOverride &&
+            !config.credentials && !config.apiKey && !config.token &&
+            !process.env.WHODB_API_KEY && process.env.WHODB_IPC_TOKEN) {
+            transportOverride = new IpcTransport();
+        }
+        const resolved = resolveConfig(config);
+        this.orgInput = resolved.org;
+        this.projectInput = resolved.project;
+        this.usingApiKey = resolved.usingApiKey;
+        if (transportOverride) {
+            // Custom transports (IPC in the functions runtime, mocks in tests) skip
+            // slug resolution: org/project inputs are taken as IDs verbatim.
+            this.transport = transportOverride;
+            this.httpTransport = null;
+            this.filesHandle = null;
+            this.skipWorkspaceResolution = true;
+            return;
+        }
+        const host = resolved.host ?? DEFAULT_HOST;
+        const httpTransport = new HttpTransport({ host, credentials: resolved.credentials });
+        this.transport = httpTransport;
+        this.httpTransport = httpTransport;
+        this.filesHandle = new FilesHandle({
+            host,
+            credentials: resolved.credentials,
+            orgId: async () => (await this.workspace()).orgId,
+            projectId: async () => (await this.workspace()).projectId,
+        });
+        // Workspace headers must be present before the first scoped call; resolve
+        // lazily but wire the transport update into the resolution.
+        if (resolved.usingCliCredentials) {
+            this.cliDefaults = async () => {
+                const defaults = await resolved.credentials.defaults?.();
+                return { orgId: defaults?.orgId, projectId: defaults?.projectId };
+            };
+        }
+    }
+    cliDefaults = null;
+    skipWorkspaceResolution = false;
+    usingApiKey = false;
+    /**
+     * Resolves org/project slugs or IDs to IDs, once, and stamps the workspace
+     * headers onto the transport. IDs pass through without a lookup.
+     */
+    workspace() {
+        this.workspacePromise ??= (async () => {
+            let orgInput = this.orgInput;
+            let projectInput = this.projectInput;
+            if ((!orgInput || !projectInput) && this.cliDefaults) {
+                const defaults = await this.cliDefaults();
+                orgInput ??= defaults.orgId;
+                projectInput ??= defaults.projectId;
+            }
+            if ((!orgInput || !projectInput) && this.usingApiKey) {
+                // API keys carry their org, and the platform auto-resolves the
+                // project when the key has exactly one grant — discover both.
+                const mine = await ops.myWorkspace(this.transport, {});
+                orgInput ??= mine.orgId ?? undefined;
+                projectInput ??= mine.projectId ?? undefined;
+                if (!projectInput) {
+                    throw new ValidationError('this API key has access to multiple (or zero) projects — pass { project } to the WhoDB constructor or set WHODB_PROJECT');
+                }
+            }
+            if (!orgInput || !projectInput) {
+                throw new ValidationError('org and project are required — pass { org, project } to the WhoDB constructor, set WHODB_ORG/WHODB_PROJECT, or run: whodb use');
+            }
+            if (this.skipWorkspaceResolution) {
+                return { orgId: orgInput, projectId: projectInput };
+            }
+            let orgId = orgInput;
+            if (!UUID_PATTERN.test(orgInput)) {
+                const orgs = await ops.myOrganizations(this.transport, {});
+                const match = orgs.find(o => o.slug === orgInput || o.name === orgInput);
+                if (!match)
+                    throw new ValidationError(`organization "${orgInput}" not found for this account`);
+                orgId = match.id;
+            }
+            // Project resolution needs the org header in place.
+            this.httpTransport?.setWorkspace(orgId, undefined);
+            let projectId = projectInput;
+            if (!UUID_PATTERN.test(projectInput)) {
+                const projects = await ops.projects(this.transport, { orgId });
+                const match = projects.find(p => p.slug === projectInput || p.name === projectInput);
+                if (!match)
+                    throw new ValidationError(`project "${projectInput}" not found in this organization`);
+                projectId = match.id;
+            }
+            this.httpTransport?.setWorkspace(orgId, projectId);
+            return { orgId, projectId };
+        })();
+        return this.workspacePromise;
+    }
+    projectId = async () => (await this.workspace()).projectId;
+    /** Returns a handle for one ontology entity, addressed by apiName. */
+    ontology(name) {
+        return new OntologyHandle(this.transport, this.projectId, name);
+    }
+    /** Lists all ontology entities in the project. */
+    async ontologyEntities() {
+        return ops.ontologyEntities(this.transport, { projectId: await this.projectId() });
+    }
+    /** Returns a handle for one dataset, addressed by name. */
+    dataset(name) {
+        return new DatasetHandle(this.transport, this.projectId, name);
+    }
+    /** Returns a handle for one connected source, addressed by ID. */
+    source(id) {
+        return new SourceHandle(this.transport, this.projectId, id);
+    }
+    /** Lists the project's connected sources. */
+    async sources() {
+        return listSources(this.transport, await this.projectId());
+    }
+    /** File upload/download over the platform's bulk HTTP endpoints. */
+    get files() {
+        if (!this.filesHandle) {
+            throw new ValidationError('files are not available over a custom transport');
+        }
+        return this.filesHandle;
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,37 @@
+import { type CredentialProvider } from './auth.js';
+/** Constructor options for the WhoDB client. */
+export interface WhoDBConfig {
+    /** Platform API key (whodb_sk_...). Highest-precedence credential. */
+    apiKey?: string;
+    /** Raw OIDC access token or an async token callback. */
+    token?: string | (() => Promise<string>);
+    /** Fully custom credential provider. */
+    credentials?: CredentialProvider;
+    /** Organization slug or ID. */
+    org?: string;
+    /** Project slug or ID. */
+    project?: string;
+    /** Platform host. Defaults to https://app.whodb.com. */
+    host?: string;
+}
+export declare const DEFAULT_HOST = "https://app.whodb.com";
+/** Resolved client configuration after applying the precedence rules. */
+export interface ResolvedConfig {
+    credentials: CredentialProvider;
+    /** True when credentials came from the CLI helper (workspace defaults apply). */
+    usingCliCredentials: boolean;
+    /** True for API keys: the key carries its org, and the platform
+     * auto-resolves the project when the key has exactly one grant — so
+     * org/project config is optional. */
+    usingApiKey: boolean;
+    host?: string;
+    org?: string;
+    project?: string;
+}
+/**
+ * Applies the credential precedence from SDK_DESIGN.md §5.3:
+ * constructor args → WHODB_API_KEY env → CLI helper (local-dev default).
+ * Workspace/host: explicit args → WHODB_ORG/WHODB_PROJECT/WHODB_HOST env →
+ * CLI helper's saved defaults (only when using CLI credentials).
+ */
+export declare function resolveConfig(config: WhoDBConfig, env?: NodeJS.ProcessEnv): ResolvedConfig;

package/dist/config.js

@@ -0,0 +1,39 @@
+import { apiKeyProvider, cliProvider, tokenProvider } from './auth.js';
+export const DEFAULT_HOST = 'https://app.whodb.com';
+/**
+ * Applies the credential precedence from SDK_DESIGN.md §5.3:
+ * constructor args → WHODB_API_KEY env → CLI helper (local-dev default).
+ * Workspace/host: explicit args → WHODB_ORG/WHODB_PROJECT/WHODB_HOST env →
+ * CLI helper's saved defaults (only when using CLI credentials).
+ */
+export function resolveConfig(config, env = process.env) {
+    let credentials;
+    let usingCliCredentials = false;
+    let usingApiKey = false;
+    if (config.credentials) {
+        credentials = config.credentials;
+    }
+    else if (config.apiKey) {
+        credentials = apiKeyProvider(config.apiKey);
+        usingApiKey = true;
+    }
+    else if (config.token) {
+        credentials = tokenProvider(config.token);
+    }
+    else if (env.WHODB_API_KEY) {
+        credentials = apiKeyProvider(env.WHODB_API_KEY);
+        usingApiKey = true;
+    }
+    else {
+        credentials = cliProvider();
+        usingCliCredentials = true;
+    }
+    return {
+        credentials,
+        usingCliCredentials,
+        usingApiKey,
+        host: config.host ?? env.WHODB_HOST,
+        org: config.org ?? env.WHODB_ORG,
+        project: config.project ?? env.WHODB_PROJECT,
+    };
+}

package/dist/dataset.d.ts

@@ -0,0 +1,26 @@
+import type { Transport } from './transport.js';
+import type { Dataset } from './generated/types.js';
+import { type Row } from './hydrate.js';
+/** Options for dataset row reads. */
+export interface DatasetRowsOptions {
+    pageSize?: number;
+    pageOffset?: number;
+}
+/**
+ * DatasetHandle is the `whodb.dataset("weekly_kpis")` facade, addressed by
+ * dataset name.
+ */
+export declare class DatasetHandle {
+    private readonly transport;
+    private readonly projectId;
+    private readonly name;
+    private datasetCache;
+    constructor(transport: Transport, projectId: () => Promise<string>, name: string);
+    /** Resolves and caches the dataset metadata backing this handle. */
+    meta(): Promise<Dataset>;
+    /** Queries dataset rows with optional filter/sort/paging. */
+    rows(options?: DatasetRowsOptions): Promise<{
+        rows: Row[];
+        totalCount: number | null;
+    }>;
+}

package/dist/dataset.js

@@ -0,0 +1,45 @@
+import * as ops from './generated/operations.js';
+import { hydrateRows } from './hydrate.js';
+import { warnIfFlagged } from './manifest-check.js';
+import { NotFoundError } from './errors.js';
+/**
+ * DatasetHandle is the `whodb.dataset("weekly_kpis")` facade, addressed by
+ * dataset name.
+ */
+export class DatasetHandle {
+    transport;
+    projectId;
+    name;
+    datasetCache = null;
+    constructor(transport, projectId, name) {
+        this.transport = transport;
+        this.projectId = projectId;
+        this.name = name;
+    }
+    /** Resolves and caches the dataset metadata backing this handle. */
+    async meta() {
+        if (this.datasetCache)
+            return this.datasetCache;
+        warnIfFlagged('ProjectDatasets');
+        const datasets = await ops.projectDatasets(this.transport, { projectId: await this.projectId() });
+        const dataset = datasets.find(d => d.name === this.name);
+        if (!dataset)
+            throw new NotFoundError(`dataset "${this.name}" not found in this project`);
+        this.datasetCache = dataset;
+        return dataset;
+    }
+    /** Queries dataset rows with optional filter/sort/paging. */
+    async rows(options = {}) {
+        const dataset = await this.meta();
+        warnIfFlagged('QueryDataset');
+        const result = await ops.queryDataset(this.transport, {
+            input: {
+                projectId: await this.projectId(),
+                datasetId: dataset.id,
+                pageSize: options.pageSize ?? 100,
+                pageOffset: options.pageOffset ?? 0,
+            },
+        });
+        return hydrateRows(result);
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,43 @@
+/** Base class for all errors thrown by the WhoDB SDK. */
+export declare class WhoDBError extends Error {
+    constructor(message: string);
+}
+/** Authentication failed: missing, invalid, expired, or revoked credentials. */
+export declare class AuthError extends WhoDBError {
+}
+/** The requested resource does not exist or the caller cannot see it. */
+export declare class NotFoundError extends WhoDBError {
+}
+/** The request was rejected as invalid before execution. */
+export declare class ValidationError extends WhoDBError {
+}
+/**
+ * This SDK release was generated against an older platform API and the
+ * operation no longer exists. The only fix is upgrading the package.
+ */
+export declare class WhoDBVersionError extends WhoDBError {
+}
+/** The whodb CLI credential helper is unavailable or not logged in. */
+export declare class CliCredentialsError extends WhoDBError {
+}
+/** An operation is not available over the current transport (e.g. IPC). */
+export declare class TransportCapabilityError extends WhoDBError {
+}
+/** Any other platform-reported error, carrying the GraphQL error code. */
+export declare class PlatformError extends WhoDBError {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+interface GraphQLErrorShape {
+    message: string;
+    extensions?: {
+        code?: string;
+    };
+}
+/**
+ * Maps a GraphQL errors array to the SDK error taxonomy. The first error
+ * decides the type; its code is preserved on PlatformError for callers that
+ * need to branch on specifics.
+ */
+export declare function mapGraphQLErrors(errors: GraphQLErrorShape[]): WhoDBError;
+export {};

package/dist/errors.js

@@ -0,0 +1,59 @@
+/** Base class for all errors thrown by the WhoDB SDK. */
+export class WhoDBError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+/** Authentication failed: missing, invalid, expired, or revoked credentials. */
+export class AuthError extends WhoDBError {
+}
+/** The requested resource does not exist or the caller cannot see it. */
+export class NotFoundError extends WhoDBError {
+}
+/** The request was rejected as invalid before execution. */
+export class ValidationError extends WhoDBError {
+}
+/**
+ * This SDK release was generated against an older platform API and the
+ * operation no longer exists. The only fix is upgrading the package.
+ */
+export class WhoDBVersionError extends WhoDBError {
+}
+/** The whodb CLI credential helper is unavailable or not logged in. */
+export class CliCredentialsError extends WhoDBError {
+}
+/** An operation is not available over the current transport (e.g. IPC). */
+export class TransportCapabilityError extends WhoDBError {
+}
+/** Any other platform-reported error, carrying the GraphQL error code. */
+export class PlatformError extends WhoDBError {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+    }
+}
+/**
+ * Maps a GraphQL errors array to the SDK error taxonomy. The first error
+ * decides the type; its code is preserved on PlatformError for callers that
+ * need to branch on specifics.
+ */
+export function mapGraphQLErrors(errors) {
+    const first = errors[0] ?? { message: 'unknown platform error' };
+    const code = first.extensions?.code ?? '';
+    const message = first.message;
+    switch (code) {
+        case 'UNAUTHENTICATED':
+            return new AuthError(message);
+        case 'FORBIDDEN':
+            return new AuthError(message);
+        case 'NOT_FOUND':
+            return new NotFoundError(message);
+        case 'BAD_USER_INPUT':
+        case 'GRAPHQL_VALIDATION_FAILED':
+            return new ValidationError(message);
+        default:
+            return new PlatformError(message, code);
+    }
+}

package/dist/files.d.ts

@@ -0,0 +1,25 @@
+import type { CredentialProvider } from './auth.js';
+/** Options for the files facade. */
+export interface FilesOptions {
+    host: string;
+    credentials: CredentialProvider;
+    orgId: () => Promise<string>;
+    projectId: () => Promise<string>;
+}
+/** Metadata returned after uploading a file. */
+export interface UploadedFile {
+    id: string;
+    name: string;
+}
+/**
+ * FilesHandle wraps the platform's file HTTP endpoints — bulk payloads are
+ * deliberately not squeezed through GraphQL (SDK_DESIGN.md §4).
+ */
+export declare class FilesHandle {
+    private readonly options;
+    constructor(options: FilesOptions);
+    /** Uploads a file (multipart) into the project's file storage. */
+    upload(name: string, content: Blob | Uint8Array | string, folderId?: string): Promise<UploadedFile>;
+    /** Downloads a project file's raw bytes. */
+    download(fileId: string): Promise<Uint8Array>;
+}