rubrkit 0.1.0

package/src/sdk.js

@@ -0,0 +1,443 @@
+// @ts-check
+
+import { DEFAULT_API_URL, normalizeApiUrl } from './config.js';
+
+const TERMINAL_JOB_STATES = new Set(['succeeded', 'failed', 'cancelled', 'paused']);
+
+/**
+ * @typedef {{
+ *   apiKey?: string | null,
+ *   apiUrl?: string,
+ *   fetchImpl?: typeof fetch,
+ *   userAgent?: string,
+ *   retryReads?: number
+ * }} RubrkitOptions
+ *
+ * @typedef {{
+ *   intervalMs?: number,
+ *   timeoutMs?: number,
+ *   signal?: AbortSignal,
+ *   onProgress?: (job: Record<string, any>) => void
+ * }} JobWaitOptions
+ */
+
+export class RubrkitError extends Error {
+    /**
+     * @param {string} message
+     * @param {{ code?: string, details?: unknown }} [options]
+     */
+    constructor(message, { code = 'rubrkit_error', details = undefined } = {}) {
+        super(message);
+        this.name = 'RubrkitError';
+        this.code = code;
+        this.details = details;
+    }
+}
+
+export class RubrkitApiError extends RubrkitError {
+    /**
+     * @param {string} message
+     * @param {{ code?: string, status?: number, requestId?: string | null, details?: unknown }} [options]
+     */
+    constructor(message, { code = 'api_request_failed', status = 0, requestId = null, details = undefined } = {}) {
+        super(message, { code, details });
+        this.name = 'RubrkitApiError';
+        this.status = status;
+        this.requestId = requestId;
+    }
+}
+
+export class RubrkitNetworkError extends RubrkitError {
+    /**
+     * @param {string} message
+     * @param {{ cause?: unknown }} [options]
+     */
+    constructor(message, { cause = undefined } = {}) {
+        super(message, { code: 'network_error', details: cause });
+        this.name = 'RubrkitNetworkError';
+        this.cause = cause;
+    }
+}
+
+export class Rubrkit {
+    /**
+     * @param {RubrkitOptions} [options]
+     */
+    constructor({
+        apiKey = process.env.RUBRKIT_API_KEY ?? null,
+        apiUrl = process.env.RUBRKIT_API_URL ?? DEFAULT_API_URL,
+        fetchImpl = globalThis.fetch,
+        userAgent = 'rubrkit-sdk/0.0.0-local',
+        retryReads = 0,
+    } = {}) {
+        this.apiKey = apiKey;
+        this.apiUrl = normalizeApiUrl(apiUrl);
+        this.fetchImpl = fetchImpl;
+        this.userAgent = userAgent;
+        this.retryReads = Math.max(0, Number(retryReads) || 0);
+
+        this.me = {
+            get: () => this.request('/me'),
+        };
+
+        this.artifactBundles = {
+            list: (params = {}) => this.request('/artifact-bundles', { query: { status: 'active', limit: 100, ...params } }),
+            create: (params = {}) => this.request('/artifact-bundles', { method: 'POST', body: params }),
+            get: (id) => this.request(`/artifact-bundles/${encodePath(id)}`),
+        };
+
+        this.artifacts = {
+            list: (params = {}) => {
+                const artifactBundleId = requireParam(params, 'artifactBundleId');
+                return this.request(`/artifact-bundles/${encodePath(artifactBundleId)}/files`, {
+                    query: omit(params, ['artifactBundleId']),
+                });
+            },
+            pull: (params = {}) => {
+                const artifactBundleId = requireParam(params, 'artifactBundleId');
+                const artifactId = params.artifactId ?? params.fileId;
+
+                if (artifactId) {
+                    return this.request(`/artifact-bundles/${encodePath(artifactBundleId)}/files/${encodePath(artifactId)}`);
+                }
+
+                return this.request(`/artifact-bundles/${encodePath(artifactBundleId)}/files`, {
+                    query: omit(params, ['artifactBundleId']),
+                });
+            },
+            upload: (params = {}) => {
+                const artifactBundleId = requireParam(params, 'artifactBundleId');
+                return this.request(`/artifact-bundles/${encodePath(artifactBundleId)}/files`, {
+                    method: 'POST',
+                    body: omit(params, ['artifactBundleId']),
+                });
+            },
+            test: (params = {}) => this.startArtifactTest(params),
+        };
+
+        this.audits = {
+            run: (params = {}) => {
+                const artifactBundleId = requireParam(params, 'artifactBundleId');
+                return this.request(`/artifact-bundles/${encodePath(artifactBundleId)}/audits`, {
+                    method: 'POST',
+                    body: normalizeAuditBody(omit(params, ['artifactBundleId'])),
+                });
+            },
+        };
+
+        this.evals = {
+            run: (params = {}) => {
+                const artifactBundleId = requireParam(params, 'artifactBundleId');
+                return this.request(`/artifact-bundles/${encodePath(artifactBundleId)}/evals`, {
+                    method: 'POST',
+                    body: omit(params, ['artifactBundleId']),
+                });
+            },
+        };
+
+        this.rubrFlow = {
+            convert: (params = {}) => {
+                const artifactBundleId = requireParam(params, 'artifactBundleId');
+                return this.request(`/artifact-bundles/${encodePath(artifactBundleId)}/rubr-flow/conversions`, {
+                    method: 'POST',
+                    body: omit(params, ['artifactBundleId']),
+                });
+            },
+        };
+
+        this.jobs = {
+            get: (id) => this.request(`/jobs/${encodePath(id)}`),
+            wait: (id, options = {}) => this.waitForJob(id, options),
+        };
+
+        this.proofReports = {
+            get: (idOrParams, options = {}) => {
+                const params = typeof idOrParams === 'object' && idOrParams !== null ? idOrParams : { proofReportId: idOrParams, ...options };
+                const artifactBundleId = requireParam(params, 'artifactBundleId');
+                const proofReportId = requireParam(params, 'proofReportId');
+                return this.request(`/artifact-bundles/${encodePath(artifactBundleId)}/proof-reports/${encodePath(proofReportId)}`);
+            },
+        };
+    }
+
+    /**
+     * @param {string} path
+     * @param {{ method?: string, query?: Record<string, unknown>, body?: unknown, signal?: AbortSignal }} [options]
+     */
+    async request(path, { method = 'GET', query = {}, body = undefined, signal = undefined } = {}) {
+        const url = buildUrl(this.apiUrl, path, query);
+        /** @type {Record<string, string>} */
+        const headers = {
+            accept: 'application/json',
+            'user-agent': this.userAgent,
+        };
+
+        if (this.apiKey) {
+            headers.authorization = `Bearer ${this.apiKey}`;
+        }
+
+        if (body !== undefined) {
+            headers['content-type'] = 'application/json';
+        }
+
+        const attempts = method === 'GET' ? this.retryReads + 1 : 1;
+        let lastError;
+
+        for (let attempt = 1; attempt <= attempts; attempt += 1) {
+            try {
+                const response = await this.fetchImpl(url, {
+                    method,
+                    headers,
+                    body: body === undefined ? undefined : JSON.stringify(body),
+                    signal,
+                });
+                return await parseResponse(response);
+            } catch (error) {
+                lastError = error;
+
+                if (error instanceof RubrkitApiError || attempt >= attempts) {
+                    throw error;
+                }
+            }
+        }
+
+        throw lastError;
+    }
+
+    /**
+     * @param {Record<string, any>} [params]
+     */
+    async startArtifactTest(params = {}) {
+        const files = Array.isArray(params.files) ? params.files : [];
+        let artifactBundleId = typeof params.artifactBundleId === 'string' && params.artifactBundleId.trim() ? params.artifactBundleId.trim() : null;
+        let artifactBundle = null;
+        let upload = null;
+
+        if (files.length > 0) {
+            if (!artifactBundleId) {
+                const created = await this.artifactBundles.create({
+                    name: params.name ?? inferArtifactTestBundleName(files),
+                    description: params.description ?? 'Created by a Rubrkit SDK or CLI remote test run.',
+                    customRubric: params.customRubric,
+                    settings: params.settings,
+                });
+                const createdRecord = asRecord(created);
+                artifactBundle = createdRecord.artifactBundle ?? createdRecord;
+                artifactBundleId = typeof asRecord(artifactBundle).id === 'string' ? asRecord(artifactBundle).id : null;
+            }
+
+            if (!artifactBundleId) {
+                throw new RubrkitError('Rubrkit API response did not include an artifact bundle ID.', { code: 'missing_artifact_bundle_id' });
+            }
+
+            upload = await this.artifacts.upload({
+                artifactBundleId,
+                files,
+            });
+        }
+
+        if (!artifactBundleId) {
+            artifactBundleId = requireParam(params, 'artifactBundleId');
+        }
+
+        const started = await this.audits.run({
+            artifactBundleId,
+            ...pickAuditParams(params),
+        });
+
+        return {
+            ...started,
+            artifactBundleId,
+            artifactBundle,
+            upload,
+            composedFrom: files.length > 0
+                ? ['artifact-bundles.create', 'artifact-bundles.files.upload', 'artifact-bundles.audits.create']
+                : ['artifact-bundles.audits.create'],
+        };
+    }
+
+    /**
+     * @param {string} id
+     * @param {JobWaitOptions} [options]
+     */
+    async waitForJob(id, { intervalMs = 1000, timeoutMs = 10 * 60 * 1000, signal = undefined, onProgress = undefined } = {}) {
+        const startedAt = Date.now();
+        let lastPhase = null;
+
+        while (true) {
+            if (signal?.aborted) {
+                throw new RubrkitError('Job wait was aborted.', { code: 'aborted' });
+            }
+
+            const data = await this.jobs.get(id);
+            const job = data.job ?? data;
+
+            if (job.phase !== lastPhase || TERMINAL_JOB_STATES.has(job.state)) {
+                onProgress?.(job);
+                lastPhase = job.phase;
+            }
+
+            if (TERMINAL_JOB_STATES.has(job.state)) {
+                return job;
+            }
+
+            if (Date.now() - startedAt > timeoutMs) {
+                throw new RubrkitError(`Timed out waiting for Rubrkit job ${id}.`, { code: 'job_wait_timeout', details: { jobId: id } });
+            }
+
+            await sleep(intervalMs);
+        }
+    }
+}
+
+/**
+ * @param {Response} response
+ */
+async function parseResponse(response) {
+    const text = await response.text();
+    const body = text ? parseJson(text) : {};
+    const requestId = body && typeof body === 'object' && typeof body.requestId === 'string' ? body.requestId : null;
+
+    if (!response.ok) {
+        const error = body && typeof body === 'object' && 'error' in body ? body.error : {};
+        const message =
+            error && typeof error === 'object' && typeof error.message === 'string'
+                ? error.message
+                : `Rubrkit API request failed with HTTP ${response.status}.`;
+        const code = error && typeof error === 'object' && typeof error.code === 'string' ? error.code : 'api_request_failed';
+
+        throw new RubrkitApiError(message, {
+            code,
+            status: response.status,
+            requestId,
+            details: error && typeof error === 'object' ? error.details : undefined,
+        });
+    }
+
+    return body && typeof body === 'object' && 'data' in body ? body.data : body;
+}
+
+/**
+ * @param {string} text
+ */
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    } catch (error) {
+        throw new RubrkitApiError('Rubrkit API returned invalid JSON.', {
+            code: 'invalid_api_response',
+            details: error,
+        });
+    }
+}
+
+/**
+ * @param {string} apiUrl
+ * @param {string} path
+ * @param {Record<string, unknown>} query
+ */
+function buildUrl(apiUrl, path, query) {
+    const url = new URL(`${apiUrl.replace(/\/+$/, '')}/${path.replace(/^\/+/, '')}`);
+
+    for (const [key, value] of Object.entries(query)) {
+        if (value === undefined || value === null || value === false) {
+            continue;
+        }
+
+        url.searchParams.set(key, String(value));
+    }
+
+    return url.toString();
+}
+
+/**
+ * @param {unknown} value
+ */
+function encodePath(value) {
+    return encodeURIComponent(String(value));
+}
+
+/**
+ * @param {Record<string, any>} params
+ * @param {string} name
+ */
+function requireParam(params, name) {
+    const value = params[name];
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new RubrkitError(`Missing required SDK parameter "${name}".`, { code: 'missing_sdk_parameter', details: { name } });
+    }
+
+    return value.trim();
+}
+
+/**
+ * @param {unknown} value
+ * @returns {Record<string, any>}
+ */
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? /** @type {Record<string, any>} */ (value) : {};
+}
+
+/**
+ * @param {Record<string, any>} params
+ */
+function pickAuditParams(params) {
+    const picked = {};
+
+    for (const key of ['artifact', 'artifactType', 'targetFileId', 'targetVersionNumber', 'artifactBundleVersionNumber', 'rubric', 'rubricKey', 'noAi']) {
+        if (params[key] !== undefined && params[key] !== null && params[key] !== '') {
+            picked[key] = params[key];
+        }
+    }
+
+    return normalizeAuditBody(picked);
+}
+
+/**
+ * @param {Record<string, any>} body
+ */
+function normalizeAuditBody(body) {
+    const normalized = { ...body };
+
+    if (normalized.rubric !== undefined && normalized.rubricKey === undefined) {
+        normalized.rubricKey = normalized.rubric;
+    }
+
+    delete normalized.rubric;
+    delete normalized.target;
+    delete normalized.ci;
+    delete normalized.files;
+    delete normalized.name;
+    delete normalized.description;
+    delete normalized.customRubric;
+    delete normalized.settings;
+
+    return normalized;
+}
+
+/**
+ * @param {Array<Record<string, any>>} files
+ */
+function inferArtifactTestBundleName(files) {
+    const firstPath = typeof files[0]?.path === 'string' && files[0].path.trim() ? files[0].path.trim() : 'artifact';
+    const suffix = files.length > 1 ? ` and ${files.length - 1} more` : '';
+    const name = `CLI test: ${firstPath}${suffix}`;
+
+    return name.length <= 120 ? name : `${name.slice(0, 117)}...`;
+}
+
+/**
+ * @param {Record<string, any>} params
+ * @param {string[]} keys
+ */
+function omit(params, keys) {
+    const blocked = new Set(keys);
+    return Object.fromEntries(Object.entries(params).filter(([key]) => !blocked.has(key)));
+}
+
+/**
+ * @param {number} ms
+ */
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}