@alloy-cx/sdk 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alloy Systems
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,82 @@
-# Temporary Holding Version
+# @alloy-cx/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Node.js client for the Alloy private API: organization storage and storage databases. No runtime dependencies;
+Node.js 18+. Works with both `require` and `import`, and ships TypeScript types.
+
+```bash
+npm install @alloy-cx/sdk
+```
+
+## Authentication
+
+Code that Alloy runs for a user (the `run_code` workflow step, the `programming.run_code` tool, and commands in an
+AI teammate's sandbox) gets `ALLOY_API_URL` and a temporary `ALLOY_API_TOKEN` with that user's rights in its
+environment, so the client needs no arguments there:
+
+```js
+const { AlloyClient } = require('@alloy-cx/sdk')
+
+const client = new AlloyClient()
+```
+
+Elsewhere, pass a personal access token from Organization Settings → API Tokens:
+
+```js
+const client = new AlloyClient({ token: 'alloy_pat_...', baseUrl: 'https://api.alloy.cx/api/private' })
+```
+
+Never print the token or write it to a file.
+
+## Storage
+
+Paths are relative to the storage root.
+
+```js
+await client.storage.list('reports')                          // direct children of a folder
+await client.storage.upload('summary.csv', 'a,b\n1,2\n', 'reports')
+await client.storage.meta('reports/summary.csv')              // size, hash, timestamps, MIME type
+await client.storage.download('reports/summary.csv')          // Uint8Array
+await client.storage.downloadText('reports/summary.csv')      // string
+await client.storage.createFolder('2026', 'reports')          // returns the new folder's path
+await client.storage.rename('reports/summary.csv', 'q1.csv')  // returns the new path
+await client.storage.move('reports/q1.csv', 'archive')        // moves into the folder, returns the new path
+await client.storage.delete('archive/q1.csv')
+```
+
+## Databases
+
+```js
+await client.databases.list()
+await client.databases.tables('crm')
+await client.databases.table('crm', 'deals')                  // schema
+
+const { rows, total } = await client.databases.rows('crm', 'deals', {
+    limit: 50,
+    orderBy: 'amount',
+    direction: 'DESC',
+    filters: [{ column: 'stage', operator: 'equals', value: 'won' }],
+})
+
+const ids = await client.databases.insert('crm', 'deals', [{ title: 'Acme', amount: 1200 }])
+const row = await client.databases.row('crm', 'deals', ids[0])
+await client.databases.update('crm', 'deals', row.id, { amount: 1500 }, row.version)
+await client.databases.updateMany('crm', 'deals', [{ id: ids[0], values: { stage: 'won' } }])
+await client.databases.delete('crm', 'deals', ids)
+
+await client.databases.query('crm', 'SELECT stage, SUM(amount) FROM deals WHERE amount > ? GROUP BY stage', [100])
+```
+
+`match: 'any'` returns rows matching any filter instead of all of them. `query` accepts only `SELECT` and
+`WITH ... SELECT`.
+
+## Errors
+
+A failed request throws `AlloyApiError` with `status`, `message`, and the response `body`. With an expected version,
+an update of a row changed since that version fails with status `409`.
+
+## Development
+
+```bash
+npm install
+npm test
+```

package/dist/databases.d.ts

@@ -0,0 +1,25 @@
+import type { HttpClient } from './http';
+import type { CellValue, Database, ListRowsOptions, QueryResult, Row, RowPage, RowUpdate, Table } from './types';
+/** The organization's storage databases: tables, rows, and read-only SQL. */
+export declare class DatabasesApi {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(): Promise<Database[]>;
+    tables(database: string): Promise<Table[]>;
+    table(database: string, table: string): Promise<Table>;
+    rows(database: string, table: string, options?: ListRowsOptions): Promise<RowPage>;
+    row(database: string, table: string, id: number): Promise<Row>;
+    /** Inserts rows and returns their ids, in order. */
+    insert(database: string, table: string, rows: Array<Record<string, CellValue>>): Promise<number[]>;
+    /**
+     * Updates one row. With `expectedVersion` the update fails with a 409 when the row changed since
+     * that version; without it the last write wins.
+     */
+    update(database: string, table: string, id: number, values: Record<string, CellValue>, expectedVersion?: number): Promise<boolean>;
+    /** Updates several rows, all or none, and returns how many changed. */
+    updateMany(database: string, table: string, updates: RowUpdate[]): Promise<number>;
+    /** Deletes rows by id and returns how many were deleted. */
+    delete(database: string, table: string, ids: number[]): Promise<number>;
+    /** Runs a read-only `SELECT` (or `WITH ... SELECT`), with `?` placeholders bound to `params`. */
+    query(database: string, sql: string, params?: CellValue[]): Promise<QueryResult>;
+}

package/dist/databases.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DatabasesApi = void 0;
+/** The organization's storage databases: tables, rows, and read-only SQL. */
+class DatabasesApi {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    async list() {
+        const data = await this.http.request('GET', '/databases');
+        return data.databases;
+    }
+    async tables(database) {
+        const data = await this.http.request('GET', `/databases/${segment(database)}/tables`);
+        return data.tables;
+    }
+    async table(database, table) {
+        const data = await this.http.request('GET', tablePath(database, table));
+        return data.table;
+    }
+    async rows(database, table, options = {}) {
+        return await this.http.request('GET', `${tablePath(database, table)}/rows`, {
+            query: {
+                limit: options.limit,
+                offset: options.offset,
+                order_by: options.orderBy,
+                direction: options.direction,
+                match: options.match,
+                filters: options.filters ? JSON.stringify(options.filters) : undefined,
+            },
+        });
+    }
+    async row(database, table, id) {
+        const data = await this.http.request('GET', `${tablePath(database, table)}/rows/${id}`);
+        return data.row;
+    }
+    /** Inserts rows and returns their ids, in order. */
+    async insert(database, table, rows) {
+        const data = await this.http.request('POST', `${tablePath(database, table)}/rows`, { json: { rows } });
+        return data.ids;
+    }
+    /**
+     * Updates one row. With `expectedVersion` the update fails with a 409 when the row changed since
+     * that version; without it the last write wins.
+     */
+    async update(database, table, id, values, expectedVersion) {
+        const data = await this.http.request('PATCH', `${tablePath(database, table)}/rows/${id}`, {
+            json: { values, ...(expectedVersion === undefined ? {} : { expected_version: expectedVersion }) },
+        });
+        return data.updated;
+    }
+    /** Updates several rows, all or none, and returns how many changed. */
+    async updateMany(database, table, updates) {
+        const data = await this.http.request('PATCH', `${tablePath(database, table)}/rows`, {
+            json: {
+                updates: updates.map(update => ({
+                    id: update.id,
+                    values: update.values,
+                    ...(update.expectedVersion === undefined ? {} : { expected_version: update.expectedVersion }),
+                })),
+            },
+        });
+        return data.updated;
+    }
+    /** Deletes rows by id and returns how many were deleted. */
+    async delete(database, table, ids) {
+        const data = await this.http.request('DELETE', `${tablePath(database, table)}/rows`, { json: { ids } });
+        return data.deleted;
+    }
+    /** Runs a read-only `SELECT` (or `WITH ... SELECT`), with `?` placeholders bound to `params`. */
+    async query(database, sql, params = []) {
+        return await this.http.request('POST', `/databases/${segment(database)}/query`, { json: { sql, params } });
+    }
+}
+exports.DatabasesApi = DatabasesApi;
+function segment(value) {
+    return encodeURIComponent(value);
+}
+function tablePath(database, table) {
+    return `/databases/${segment(database)}/tables/${segment(table)}`;
+}

package/dist/http.d.ts

@@ -0,0 +1,26 @@
+import type { JsonValue } from './types';
+/** A non-2xx answer from the API. `body` is the parsed response, or its text when it is not JSON. */
+export declare class AlloyApiError extends Error {
+    readonly status: number;
+    readonly body: JsonValue;
+    constructor(status: number, message: string, body: JsonValue);
+}
+type QueryValue = string | number | boolean | undefined;
+export interface RequestOptions {
+    query?: Record<string, QueryValue>;
+    json?: JsonValue;
+    form?: FormData;
+}
+export declare class HttpClient {
+    private readonly baseUrl;
+    private readonly token;
+    private readonly fetchImpl;
+    constructor(baseUrl: string, token: string, fetchImpl: typeof fetch);
+    /** Sends a request and returns the `data` of the JSON envelope. */
+    request<T>(method: string, path: string, options?: RequestOptions): Promise<T>;
+    /** Sends a request and returns the raw response body. */
+    requestBytes(method: string, path: string, options?: RequestOptions): Promise<Uint8Array>;
+    private send;
+    private readBody;
+}
+export {};

package/dist/http.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpClient = exports.AlloyApiError = void 0;
+/** A non-2xx answer from the API. `body` is the parsed response, or its text when it is not JSON. */
+class AlloyApiError extends Error {
+    status;
+    body;
+    constructor(status, message, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = 'AlloyApiError';
+    }
+}
+exports.AlloyApiError = AlloyApiError;
+/** Reads the message out of either error shape the API answers with. */
+function errorMessage(body, status) {
+    if (body && typeof body === 'object' && !Array.isArray(body)) {
+        const { message, error } = body;
+        if (typeof message === 'string')
+            return message;
+        if (typeof error === 'string')
+            return error;
+        if (error && typeof error === 'object' && !Array.isArray(error) && typeof error['message'] === 'string') {
+            return error['message'];
+        }
+    }
+    return typeof body === 'string' && body ? body : `Request failed with status ${status}`;
+}
+class HttpClient {
+    baseUrl;
+    token;
+    fetchImpl;
+    constructor(baseUrl, token, fetchImpl) {
+        this.baseUrl = baseUrl;
+        this.token = token;
+        this.fetchImpl = fetchImpl;
+    }
+    /** Sends a request and returns the `data` of the JSON envelope. */
+    async request(method, path, options = {}) {
+        const response = await this.send(method, path, options);
+        const body = await this.readBody(response);
+        if (!response.ok) {
+            throw new AlloyApiError(response.status, errorMessage(body, response.status), body);
+        }
+        return body.data;
+    }
+    /** Sends a request and returns the raw response body. */
+    async requestBytes(method, path, options = {}) {
+        const response = await this.send(method, path, options);
+        if (!response.ok) {
+            const body = await this.readBody(response);
+            throw new AlloyApiError(response.status, errorMessage(body, response.status), body);
+        }
+        return new Uint8Array(await response.arrayBuffer());
+    }
+    async send(method, path, options) {
+        const url = new URL(this.baseUrl.replace(/\/+$/, '') + path);
+        for (const [name, value] of Object.entries(options.query ?? {})) {
+            if (value !== undefined)
+                url.searchParams.set(name, String(value));
+        }
+        const headers = { Authorization: `Bearer ${this.token}` };
+        let body;
+        if (options.form) {
+            body = options.form;
+        }
+        else if (options.json !== undefined) {
+            headers['Content-Type'] = 'application/json';
+            body = JSON.stringify(options.json);
+        }
+        return await this.fetchImpl(url, { method, headers, ...(body === undefined ? {} : { body }) });
+    }
+    async readBody(response) {
+        const text = await response.text();
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+}
+exports.HttpClient = HttpClient;

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+import { DatabasesApi } from './databases';
+import { StorageApi } from './storage';
+export { AlloyApiError } from './http';
+export { DatabasesApi } from './databases';
+export { StorageApi } from './storage';
+export type * from './types';
+export interface AlloyClientOptions {
+    /** Defaults to the `ALLOY_API_TOKEN` environment variable. */
+    token?: string;
+    /** The private API base URL, for example `https://api.alloy.cx/api/private`. Defaults to `ALLOY_API_URL`. */
+    baseUrl?: string;
+    /** Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+}
+/**
+ * Client for the Alloy private API. Inside an Alloy sandbox it needs no arguments: the token and
+ * URL come from the environment, and every call runs with the rights of the user the code runs for.
+ */
+export declare class AlloyClient {
+    readonly storage: StorageApi;
+    readonly databases: DatabasesApi;
+    constructor(options?: AlloyClientOptions);
+}

package/dist/index.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AlloyClient = exports.StorageApi = exports.DatabasesApi = exports.AlloyApiError = void 0;
+const databases_1 = require("./databases");
+const http_1 = require("./http");
+const storage_1 = require("./storage");
+var http_2 = require("./http");
+Object.defineProperty(exports, "AlloyApiError", { enumerable: true, get: function () { return http_2.AlloyApiError; } });
+var databases_2 = require("./databases");
+Object.defineProperty(exports, "DatabasesApi", { enumerable: true, get: function () { return databases_2.DatabasesApi; } });
+var storage_2 = require("./storage");
+Object.defineProperty(exports, "StorageApi", { enumerable: true, get: function () { return storage_2.StorageApi; } });
+/**
+ * Client for the Alloy private API. Inside an Alloy sandbox it needs no arguments: the token and
+ * URL come from the environment, and every call runs with the rights of the user the code runs for.
+ */
+class AlloyClient {
+    storage;
+    databases;
+    constructor(options = {}) {
+        const token = options.token ?? process.env['ALLOY_API_TOKEN'];
+        const baseUrl = options.baseUrl ?? process.env['ALLOY_API_URL'];
+        if (!token || !baseUrl) {
+            throw new Error('Alloy API token and URL are required: pass token and baseUrl, or set ALLOY_API_TOKEN and ALLOY_API_URL');
+        }
+        const http = new http_1.HttpClient(baseUrl, token, options.fetch ?? fetch);
+        this.storage = new storage_1.StorageApi(http);
+        this.databases = new databases_1.DatabasesApi(http);
+    }
+}
+exports.AlloyClient = AlloyClient;

package/dist/storage.d.ts

@@ -0,0 +1,25 @@
+import type { HttpClient } from './http';
+import type { FileMeta, StorageItem, UploadedFile } from './types';
+/** Organization storage, with the rights of the token's user. Paths are relative to the storage root. */
+export declare class StorageApi {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Lists the direct children of a folder; the root by default. */
+    list(path?: string): Promise<StorageItem[]>;
+    /**
+     * Uploads a file named `name` into `folder` (the root by default), overwriting a file of the
+     * same name.
+     */
+    upload(name: string, content: Uint8Array | string, folder?: string): Promise<UploadedFile>;
+    meta(path: string): Promise<FileMeta>;
+    download(path: string): Promise<Uint8Array>;
+    downloadText(path: string): Promise<string>;
+    /** Deletes a file or a folder with everything in it. */
+    delete(path: string): Promise<void>;
+    /** Creates folder `name` inside `parent` (the root by default) and returns its path. */
+    createFolder(name: string, parent?: string): Promise<string>;
+    /** Renames a file or folder in place and returns its new path. */
+    rename(path: string, newName: string): Promise<string>;
+    /** Moves a file or folder into the folder `destination` and returns its new path. */
+    move(path: string, destination: string): Promise<string>;
+}

package/dist/storage.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StorageApi = void 0;
+/** Organization storage, with the rights of the token's user. Paths are relative to the storage root. */
+class StorageApi {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /** Lists the direct children of a folder; the root by default. */
+    async list(path = '/') {
+        return await this.http.request('GET', '/storage', { query: { path } });
+    }
+    /**
+     * Uploads a file named `name` into `folder` (the root by default), overwriting a file of the
+     * same name.
+     */
+    async upload(name, content, folder) {
+        const form = new FormData();
+        if (folder !== undefined)
+            form.append('path', folder);
+        // Copied so a view over a SharedArrayBuffer, which Blob refuses, still uploads.
+        form.append('file', new Blob([typeof content === 'string' ? content : new Uint8Array(content)]), name);
+        return await this.http.request('POST', '/storage/upload', { form });
+    }
+    async meta(path) {
+        return await this.http.request('GET', '/storage/meta', { query: { path } });
+    }
+    async download(path) {
+        return await this.http.requestBytes('GET', '/storage/download', { query: { path } });
+    }
+    async downloadText(path) {
+        return new TextDecoder().decode(await this.download(path));
+    }
+    /** Deletes a file or a folder with everything in it. */
+    async delete(path) {
+        await this.http.request('DELETE', '/storage/file', { query: { path } });
+    }
+    /** Creates folder `name` inside `parent` (the root by default) and returns its path. */
+    async createFolder(name, parent) {
+        const data = await this.http.request('POST', '/storage/folder', {
+            json: { name, ...(parent === undefined ? {} : { path: parent }) },
+        });
+        return data.path;
+    }
+    /** Renames a file or folder in place and returns its new path. */
+    async rename(path, newName) {
+        const data = await this.http.request('POST', '/storage/rename', { json: { path, new_name: newName } });
+        return data.path;
+    }
+    /** Moves a file or folder into the folder `destination` and returns its new path. */
+    async move(path, destination) {
+        const data = await this.http.request('POST', '/storage/move', {
+            json: { source_path: path, dest_path: destination },
+        });
+        return data.path;
+    }
+}
+exports.StorageApi = StorageApi;

package/dist/types.d.ts

@@ -0,0 +1,91 @@
+/** Any value a JSON response can hold. */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** A storage entry, as `storage.list` returns it. */
+export interface StorageItem {
+    id: string;
+    name: string;
+    type: 'file' | 'folder';
+    /** Human-readable size of a file, for example `"1.2 KB"`. */
+    size?: string;
+    /** Number of entries in a folder. */
+    items?: number;
+    created: string;
+    modified: string;
+}
+export interface UploadedFile {
+    path: string;
+    name: string;
+    size: number;
+    mimetype: string;
+}
+export interface FileMeta {
+    path: string;
+    name: string;
+    size: number;
+    created_at: string;
+    modified_at: string;
+    hash: string;
+    mime_type: string | null;
+}
+/** A cell of a database row. */
+export type CellValue = string | number | boolean | null;
+export interface Database {
+    alias: string;
+    displayName: string;
+    description: string;
+    sizeBytes: number;
+    createdAt: string;
+    storagePath: string | null;
+}
+export interface Column {
+    name: string;
+    type: 'TEXT' | 'INTEGER' | 'REAL' | 'BOOLEAN' | 'TIMESTAMP';
+    nullable?: boolean;
+    unique?: boolean;
+    defaultValue?: CellValue;
+}
+export interface Table {
+    name: string;
+    columns: Column[];
+    rowCount: number;
+}
+export interface Row {
+    id: number;
+    /** Send it back as `expectedVersion` to update only if nobody changed the row since. */
+    version: number;
+    values: Record<string, CellValue>;
+}
+export interface RowPage {
+    rows: Row[];
+    /** Rows matching the filters, ignoring limit and offset. */
+    total: number;
+}
+export type FilterOperator = 'equals' | 'not_equals' | 'contains' | 'starts_with' | 'ends_with' | 'greater_than' | 'greater_or_equal' | 'less_than' | 'less_or_equal' | 'is_empty' | 'is_not_empty';
+export interface RowFilter {
+    column: string;
+    operator: FilterOperator;
+    value?: CellValue;
+}
+export interface ListRowsOptions {
+    /** 1 to 1000. */
+    limit?: number;
+    offset?: number;
+    orderBy?: string;
+    direction?: 'ASC' | 'DESC';
+    /** Whether a row must match all filters (the default) or any of them. */
+    match?: 'all' | 'any';
+    filters?: RowFilter[];
+}
+export interface RowUpdate {
+    id: number;
+    values: Record<string, CellValue>;
+    expectedVersion?: number;
+}
+export interface QueryResult {
+    columns: string[];
+    rows: CellValue[][];
+    /** Set when the result was cut at the row limit. */
+    truncated: boolean;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@alloy-cx/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Client for the Alloy private API: organization storage and databases",
+  "license": "MIT",
+  "author": "Alloy Systems",
+  "homepage": "https://alloy.cx",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Alloy-Systems/backend.git",
+    "directory": "sdk/node"
+  },
+  "keywords": ["alloy", "sdk", "storage", "database"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "prepublishOnly": "npm test"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0"
+  }
+}