@permute/sdk 0.1.0

package/dist/client.js

@@ -0,0 +1,553 @@
+import { Ajv } from 'ajv';
+import { createHash } from 'node:crypto';
+import { publicApiRoutes } from './generated/runtime-contract.js';
+const DEFAULT_BASE_URL = 'https://api.permute.ai';
+const DEFAULT_POLL_TIMEOUT_MS = 20 * 60 * 1000;
+export class PermuteApiError extends Error {
+    status;
+    code;
+    details;
+    requestId;
+    constructor(input) {
+        super(input.message);
+        this.name = 'PermuteApiError';
+        this.status = input.status;
+        this.code = input.code;
+        this.details = input.details;
+        this.requestId = input.requestId;
+    }
+}
+function routeFor(operationId) {
+    const route = publicApiRoutes[operationId];
+    if (!route) {
+        throw new PermuteApiError({
+            status: 0,
+            code: 'missing_route',
+            message: `Missing API route for ${operationId}`,
+        });
+    }
+    return route;
+}
+function buildPath(route, pathParams = {}) {
+    return route.path.replace(/\{([^}]+)\}/g, (_match, key) => {
+        const value = pathParams[key];
+        if (!value) {
+            throw new PermuteApiError({
+                status: 0,
+                code: 'missing_path_param',
+                message: `Missing path parameter: ${key}`,
+            });
+        }
+        return encodeURIComponent(value);
+    });
+}
+function parseJsonResponse(response) {
+    return response.text().then((text) => {
+        if (!text)
+            return {};
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new PermuteApiError({
+                status: response.status,
+                code: 'invalid_json',
+                message: 'API response was not valid JSON',
+            });
+        }
+    });
+}
+function isErrorEnvelope(value) {
+    return (!!value &&
+        typeof value === 'object' &&
+        'error' in value &&
+        !!value.error &&
+        typeof value.error.code === 'string' &&
+        typeof value.error.message === 'string');
+}
+function isSuccessEnvelope(value) {
+    return !!value && typeof value === 'object' && 'data' in value;
+}
+function validationError(operationId, kind, errors) {
+    return new PermuteApiError({
+        status: 0,
+        code: `invalid_${kind}`,
+        message: `Invalid ${kind} for ${operationId}`,
+        details: errors?.map(({ instancePath, schemaPath, keyword, message, params }) => ({
+            instancePath,
+            schemaPath,
+            keyword,
+            message,
+            params,
+        })),
+    });
+}
+const ajv = new Ajv({ allErrors: true, strict: false, validateFormats: false });
+const validators = new WeakMap();
+function validatorFor(schema) {
+    const existing = validators.get(schema);
+    if (existing)
+        return existing;
+    const validator = ajv.compile(schema);
+    validators.set(schema, validator);
+    return validator;
+}
+function inferUploadSize(data) {
+    if (typeof data === 'string')
+        return new TextEncoder().encode(data).byteLength;
+    if (data instanceof ArrayBuffer)
+        return data.byteLength;
+    if (ArrayBuffer.isView(data))
+        return data.byteLength;
+    if (typeof Blob !== 'undefined' && data instanceof Blob)
+        return data.size;
+    return undefined;
+}
+const DATASET_WRITE_CHUNK_ROWS = 500;
+function encodeDatasetWrite(request) {
+    const entries = request.mode === 'replace' ? Object.entries(request.tables) : [[request.tableName, request.rows]];
+    const parts = [];
+    const hash = createHash('sha256');
+    const addChunk = (tableName, rows) => {
+        const line = `${JSON.stringify({ tableName, rows })}\n`;
+        parts.push(line);
+        hash.update(line);
+    };
+    for (const [tableName, rows] of entries) {
+        if (rows.length === 0)
+            addChunk(tableName, []);
+        for (let offset = 0; offset < rows.length; offset += DATASET_WRITE_CHUNK_ROWS) {
+            addChunk(tableName, rows.slice(offset, offset + DATASET_WRITE_CHUNK_ROWS));
+        }
+    }
+    const data = new Blob(parts, { type: 'application/x-ndjson' });
+    return {
+        data,
+        contentHash: hash.digest('hex'),
+        tables: entries.map(([name, rows]) => ({ name, rowCount: rows.length })),
+    };
+}
+function pollingDeadline(options) {
+    const timeoutMs = options?.pollTimeoutMs ?? DEFAULT_POLL_TIMEOUT_MS;
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        throw new PermuteApiError({
+            status: 0,
+            code: 'invalid_poll_timeout',
+            message: 'pollTimeoutMs must be a positive number',
+        });
+    }
+    return Date.now() + timeoutMs;
+}
+function waitForPoll(delayMs, deadline, signal) {
+    if (signal?.aborted) {
+        return Promise.reject(new PermuteApiError({ status: 0, code: 'request_aborted', message: 'Request was aborted' }));
+    }
+    const remainingMs = deadline - Date.now();
+    if (remainingMs <= 0) {
+        return Promise.reject(new PermuteApiError({ status: 0, code: 'poll_timeout', message: 'Durable operation timed out' }));
+    }
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            clearTimeout(timeout);
+            reject(new PermuteApiError({ status: 0, code: 'request_aborted', message: 'Request was aborted' }));
+        };
+        const timeout = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            if (Date.now() >= deadline) {
+                reject(new PermuteApiError({ status: 0, code: 'poll_timeout', message: 'Durable operation timed out' }));
+            }
+            else {
+                resolve();
+            }
+        }, Math.min(delayMs, remainingMs));
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+function requireCustomDataset(dataset) {
+    if (dataset.type === 'custom')
+        return dataset;
+    throw new PermuteApiError({
+        status: 0,
+        code: 'invalid_dataset_type',
+        message: `Dataset ${dataset.id} is a file dataset and does not support table writes`,
+    });
+}
+function requireFileDataset(dataset) {
+    if (dataset.type === 'file')
+        return dataset;
+    throw new PermuteApiError({
+        status: 0,
+        code: 'invalid_dataset_type',
+        message: `Dataset ${dataset.id} is a custom dataset and does not expose a file upload`,
+    });
+}
+export class PermuteDataset {
+    writeTables;
+    readDataset;
+    type = 'custom';
+    snapshot;
+    constructor(snapshot, writeTables, readDataset) {
+        this.writeTables = writeTables;
+        this.readDataset = readDataset;
+        this.snapshot = snapshot;
+    }
+    get data() {
+        return this.snapshot;
+    }
+    get id() {
+        return this.snapshot.id;
+    }
+    get sourceId() {
+        return this.snapshot.sourceId;
+    }
+    get key() {
+        return this.snapshot.key;
+    }
+    get name() {
+        return this.snapshot.name;
+    }
+    get context() {
+        return this.snapshot.context;
+    }
+    get status() {
+        return this.snapshot.status;
+    }
+    get version() {
+        return this.snapshot.version;
+    }
+    async replace(tables, options) {
+        this.snapshot = await this.writeTables(this.id, { tables, mode: 'replace' }, options);
+        return this;
+    }
+    async replaceTable(tableName, rows, options) {
+        this.snapshot = await this.writeTables(this.id, { tableName, rows, mode: 'replaceTable' }, options);
+        return this;
+    }
+    async appendTable(tableName, rows, options) {
+        const { batchId, ...requestOptions } = options;
+        this.snapshot = await this.writeTables(this.id, { tableName, rows, batchId, mode: 'appendTable' }, requestOptions);
+        return this;
+    }
+    async refresh(options) {
+        this.snapshot = requireCustomDataset(await this.readDataset(this.id, options));
+        return this;
+    }
+}
+export class PermuteFileDataset {
+    readDataset;
+    type = 'file';
+    snapshot;
+    constructor(snapshot, readDataset) {
+        this.readDataset = readDataset;
+        this.snapshot = snapshot;
+    }
+    get data() {
+        return this.snapshot;
+    }
+    get id() {
+        return this.snapshot.id;
+    }
+    get sourceId() {
+        return this.snapshot.sourceId;
+    }
+    get name() {
+        return this.snapshot.name;
+    }
+    get status() {
+        return this.snapshot.status;
+    }
+    async refresh(options) {
+        this.snapshot = requireFileDataset(await this.readDataset(this.id, options));
+        return this;
+    }
+}
+export class PermuteClient {
+    workspaces;
+    sources;
+    datasets;
+    apiKey;
+    baseUrl;
+    /** Workspace selected for workspace-scoped API operations. */
+    workspaceId;
+    defaultHeaders;
+    fetchImpl;
+    constructor(options) {
+        if (!options.apiKey) {
+            throw new PermuteApiError({
+                status: 0,
+                code: 'missing_api_key',
+                message: 'apiKey is required',
+            });
+        }
+        const fetchImpl = options.fetch ?? globalThis.fetch;
+        if (!fetchImpl) {
+            throw new PermuteApiError({
+                status: 0,
+                code: 'missing_fetch',
+                message: 'A fetch implementation is required',
+            });
+        }
+        this.apiKey = options.apiKey;
+        this.baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+        this.workspaceId = options.workspaceId;
+        this.defaultHeaders = options.headers ?? {};
+        this.fetchImpl = fetchImpl.bind(globalThis);
+        this.workspaces = {
+            list: (requestOptions) => this.request('workspacesList', {}, requestOptions),
+            create: (request, requestOptions) => this.request('workspacesCreate', { body: request }, requestOptions),
+            get: (workspaceId, requestOptions) => this.request('workspacesGet', { pathParams: { workspaceId } }, requestOptions),
+            update: (workspaceId, request, requestOptions) => this.request('workspacesUpdate', { pathParams: { workspaceId }, body: request }, requestOptions),
+            delete: (workspaceId, requestOptions) => this.request('workspacesDelete', { pathParams: { workspaceId } }, requestOptions),
+        };
+        this.sources = {
+            list: (requestOptions) => this.request('sourcesList', {}, requestOptions),
+            get: (sourceId, requestOptions) => this.request('sourcesGet', { pathParams: { sourceId } }, requestOptions),
+        };
+        const readDataset = (datasetId, requestOptions) => this.request('datasetsGet', { pathParams: { datasetId } }, requestOptions);
+        const writeDatasetTables = async (datasetId, request, requestOptions) => {
+            const encoded = encodeDatasetWrite(request);
+            const body = request.mode === 'replace'
+                ? {
+                    mode: request.mode,
+                    tables: encoded.tables,
+                    sizeBytes: encoded.data.size,
+                    contentHash: encoded.contentHash,
+                }
+                : request.mode === 'replaceTable'
+                    ? {
+                        mode: request.mode,
+                        tableName: request.tableName,
+                        rowCount: request.rows.length,
+                        sizeBytes: encoded.data.size,
+                        contentHash: encoded.contentHash,
+                    }
+                    : {
+                        mode: request.mode,
+                        tableName: request.tableName,
+                        rowCount: request.rows.length,
+                        sizeBytes: encoded.data.size,
+                        contentHash: encoded.contentHash,
+                        batchId: request.batchId,
+                    };
+            const initialized = await this.request('datasetsWriteTables', { pathParams: { datasetId }, body }, requestOptions);
+            if (initialized.write.status === 'completed')
+                return initialized.dataset;
+            if (!initialized.upload) {
+                throw new PermuteApiError({ status: 0, code: 'missing_upload', message: 'Dataset write has no upload target' });
+            }
+            const uploadResponse = await this.fetchImpl(initialized.upload.url, {
+                method: initialized.upload.method,
+                headers: initialized.upload.headers,
+                body: encoded.data,
+                signal: requestOptions?.signal,
+            });
+            if (!uploadResponse.ok) {
+                throw new PermuteApiError({
+                    status: uploadResponse.status,
+                    code: 'upload_failed',
+                    message: uploadResponse.statusText || 'Dataset write upload failed',
+                });
+            }
+            const deadline = pollingDeadline(requestOptions);
+            while (true) {
+                await waitForPoll(initialized.pollAfterMs, deadline, requestOptions?.signal);
+                const dataset = requireCustomDataset(await readDataset(datasetId, requestOptions));
+                if (dataset.write?.id !== initialized.write.id) {
+                    if (dataset.version > initialized.dataset.version)
+                        return dataset;
+                    continue;
+                }
+                if (dataset.write.status === 'completed')
+                    return dataset;
+                if (dataset.write.status === 'failed') {
+                    throw new PermuteApiError({
+                        status: 0,
+                        code: 'dataset_write_failed',
+                        message: dataset.write.error ?? 'Dataset write failed',
+                    });
+                }
+            }
+        };
+        const wrapDataset = (dataset) => dataset.type === 'custom'
+            ? new PermuteDataset(dataset, writeDatasetTables, readDataset)
+            : new PermuteFileDataset(dataset, readDataset);
+        const createDataset = async (request, requestOptions) => {
+            if (request.type === 'custom') {
+                const dataset = await this.request('datasetsCreate', { body: request }, requestOptions);
+                return new PermuteDataset(requireCustomDataset(dataset), writeDatasetTables, readDataset);
+            }
+            const { data, headers, sizeBytes: declaredSize, ...createRequest } = request;
+            const inferredSize = inferUploadSize(data);
+            if (declaredSize !== undefined && inferredSize !== undefined && declaredSize !== inferredSize) {
+                throw new PermuteApiError({
+                    status: 0,
+                    code: 'invalid_file_size',
+                    message: `sizeBytes was ${declaredSize}, but the upload body contains ${inferredSize} bytes`,
+                });
+            }
+            const sizeBytes = declaredSize ?? inferredSize;
+            if (sizeBytes === undefined) {
+                throw new PermuteApiError({
+                    status: 0,
+                    code: 'missing_file_size',
+                    message: 'sizeBytes is required when the SDK cannot determine the upload body size',
+                });
+            }
+            const response = await this.request('datasetsCreate', { body: { ...createRequest, sizeBytes } }, requestOptions);
+            const dataset = new PermuteFileDataset(requireFileDataset(response), readDataset);
+            const target = dataset.data.upload;
+            if (!target) {
+                throw new PermuteApiError({
+                    status: 0,
+                    code: 'missing_upload_target',
+                    message: `Dataset ${dataset.id} did not include a file upload target`,
+                });
+            }
+            const uploadResponse = await this.fetchImpl(target.url, {
+                method: target.method,
+                headers: { ...headers, ...target.headers },
+                body: data,
+                signal: requestOptions?.signal,
+            });
+            if (!uploadResponse.ok) {
+                throw new PermuteApiError({
+                    status: uploadResponse.status,
+                    code: 'upload_failed',
+                    message: uploadResponse.statusText || `Upload failed with status ${uploadResponse.status}`,
+                });
+            }
+            return dataset;
+        };
+        this.datasets = {
+            create: createDataset,
+            getByKey: async (key, requestOptions) => {
+                const dataset = await this.request('datasetsGetByKey', { query: { key } }, requestOptions);
+                return wrapDataset(dataset);
+            },
+            get: async (datasetId, requestOptions) => {
+                const dataset = await readDataset(datasetId, requestOptions);
+                return wrapDataset(dataset);
+            },
+        };
+    }
+    async search(request, options) {
+        return await this.request('searchCreate', { body: request }, options);
+    }
+    async answer(request, options) {
+        let job = await this.answerJobs(request, options);
+        const deadline = pollingDeadline(options);
+        while (job.status === 'queued' || job.status === 'running') {
+            await waitForPoll(job.pollAfterMs ?? 1500, deadline, options?.signal);
+            job = await this.getAnswerJob(job.answerJobId, options);
+        }
+        if (job.status === 'completed') {
+            if (job.result)
+                return job.result;
+            throw new PermuteApiError({
+                status: 0,
+                code: 'answer_missing_result',
+                message: `Answer job ${job.answerJobId} completed without a result`,
+            });
+        }
+        throw new PermuteApiError({
+            status: 0,
+            code: `answer_${job.status}`,
+            message: job.error ?? `Answer job ${job.status}`,
+        });
+    }
+    async answerJobs(request, options) {
+        return await this.request('answerJobsCreate', { body: request }, options);
+    }
+    async getAnswerJob(answerJobId, options) {
+        return await this.request('answerJobsGet', { pathParams: { answerJobId } }, options);
+    }
+    withWorkspace(workspaceId) {
+        if (!workspaceId.trim()) {
+            throw new PermuteApiError({ status: 0, code: 'missing_workspace_id', message: 'workspaceId is required' });
+        }
+        return new PermuteClient({
+            apiKey: this.apiKey,
+            baseUrl: this.baseUrl,
+            workspaceId,
+            fetch: this.fetchImpl,
+            headers: this.defaultHeaders,
+        });
+    }
+    async query(request, options) {
+        return await this.request('queriesCreate', { body: request }, options);
+    }
+    async request(operationId, input, options) {
+        const route = routeFor(operationId);
+        const body = this.validateRequestBody(route, operationId, input.body);
+        const query = this.validateRequestQuery(route, operationId, input.query);
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            ...this.defaultHeaders,
+            ...options?.headers,
+        };
+        const workspaceId = options?.workspaceId ?? this.workspaceId;
+        if (route.scope === 'workspace' && workspaceId) {
+            headers['X-Workspace-Id'] = workspaceId;
+        }
+        if (body !== undefined) {
+            headers['Content-Type'] = 'application/json';
+        }
+        const url = new URL(`${this.baseUrl.replace(/\/+$/, '')}${buildPath(route, input.pathParams)}`);
+        for (const [key, value] of Object.entries(query))
+            url.searchParams.set(key, value);
+        const response = await this.fetchImpl(url.toString(), {
+            method: route.method,
+            headers,
+            signal: options?.signal,
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        });
+        const payload = await parseJsonResponse(response);
+        if (!response.ok) {
+            if (isErrorEnvelope(payload)) {
+                throw new PermuteApiError({
+                    status: response.status,
+                    code: payload.error.code,
+                    message: payload.error.message,
+                    details: payload.error.details,
+                    requestId: payload.error.requestId,
+                });
+            }
+            throw new PermuteApiError({
+                status: response.status,
+                code: 'request_failed',
+                message: response.statusText || `Request failed with status ${response.status}`,
+            });
+        }
+        if (!isSuccessEnvelope(payload)) {
+            throw new PermuteApiError({
+                status: response.status,
+                code: 'invalid_response',
+                message: 'API response did not include a data envelope',
+            });
+        }
+        const responseValidator = validatorFor(route.responseSchema);
+        if (!responseValidator(payload.data)) {
+            throw validationError(operationId, 'response', responseValidator.errors);
+        }
+        return payload.data;
+    }
+    validateRequestBody(route, operationId, body) {
+        if (!route.bodySchema)
+            return undefined;
+        const requestValidator = validatorFor(route.bodySchema);
+        if (!requestValidator(body)) {
+            throw validationError(operationId, 'request', requestValidator.errors);
+        }
+        return body;
+    }
+    validateRequestQuery(route, operationId, query) {
+        if (!route.querySchema)
+            return {};
+        const requestQuery = query ?? {};
+        const queryValidator = validatorFor(route.querySchema);
+        if (!queryValidator(requestQuery)) {
+            throw validationError(operationId, 'request', queryValidator.errors);
+        }
+        return requestQuery;
+    }
+}