@acontext/acontext 0.0.1

package/README.md

@@ -0,0 +1,80 @@
+# acontext client for TypeScript
+
+TypeScript SDK for interacting with the Acontext REST API.
+
+## Installation
+
+```bash
+npm install @acontext/acontext
+```
+
+## Quickstart
+
+```typescript
+import { AcontextClient, MessagePart } from '@acontext/acontext';
+
+const client = new AcontextClient({ apiKey: 'sk_project_token' });
+
+// List spaces for the authenticated project
+const spaces = await client.spaces.list();
+
+// Create a session bound to the first space
+const session = await client.sessions.create({ spaceId: spaces.items[0].id });
+
+// Send a text message to the session
+await client.sessions.sendMessage(
+  session.id,
+  {
+    role: 'user',
+    parts: [MessagePart.textPart('Hello from TypeScript!')],
+  },
+  { format: 'acontext' }
+);
+```
+
+See the inline documentation for the full list of helpers covering sessions, spaces, disks, and artifact uploads.
+
+## Managing disks and artifacts
+
+Artifacts now live under project disks. Create a disk first, then upload files through the disk-scoped helper:
+
+```typescript
+import { AcontextClient, FileUpload } from '@acontext/acontext';
+
+const client = new AcontextClient({ apiKey: 'sk_project_token' });
+
+const disk = await client.disks.create();
+await client.disks.artifacts.upsert(
+  disk.id,
+  {
+    file: new FileUpload({
+      filename: 'retro_notes.md',
+      content: Buffer.from('# Retro Notes\nWe shipped file uploads successfully!\n'),
+      contentType: 'text/markdown',
+    }),
+    filePath: '/notes/',
+    meta: { source: 'readme-demo' },
+  }
+);
+```
+
+## Working with blocks
+
+```typescript
+import { AcontextClient } from '@acontext/acontext';
+
+const client = new AcontextClient({ apiKey: 'sk_project_token' });
+
+const space = await client.spaces.create();
+const page = await client.blocks.create(space.id, {
+  blockType: 'page',
+  title: 'Kick-off Notes',
+});
+await client.blocks.create(space.id, {
+  parentId: page.id,
+  blockType: 'text',
+  title: 'First block',
+  props: { text: 'Plan the sprint goals' },
+});
+```
+

package/dist/client-types.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Common typing helpers used by resource modules to avoid circular imports.
+ */
+export interface RequesterProtocol {
+    request<T = unknown>(method: string, path: string, options?: {
+        params?: Record<string, string | number>;
+        jsonData?: unknown;
+        data?: Record<string, string>;
+        files?: Record<string, {
+            filename: string;
+            content: Buffer | NodeJS.ReadableStream;
+            contentType: string;
+        }>;
+        unwrap?: boolean;
+    }): Promise<T>;
+}

package/dist/client-types.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * Common typing helpers used by resource modules to avoid circular imports.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/client.d.ts

@@ -0,0 +1,41 @@
+/**
+ * High-level synchronous client for the Acontext API.
+ */
+import { BlocksAPI } from './resources/blocks';
+import { DisksAPI } from './resources/disks';
+import { SessionsAPI } from './resources/sessions';
+import { SpacesAPI } from './resources/spaces';
+import { RequesterProtocol } from './client-types';
+export interface AcontextClientOptions {
+    apiKey?: string | null;
+    baseUrl?: string | null;
+    timeout?: number | null;
+    userAgent?: string | null;
+}
+export declare class AcontextClient implements RequesterProtocol {
+    private _baseUrl;
+    private _apiKey;
+    private _timeout;
+    private _userAgent;
+    spaces: SpacesAPI;
+    sessions: SessionsAPI;
+    disks: DisksAPI;
+    artifacts: DisksAPI['artifacts'];
+    blocks: BlocksAPI;
+    constructor(options?: AcontextClientOptions);
+    get baseUrl(): string;
+    request<T = unknown>(method: string, path: string, options?: {
+        params?: Record<string, string | number>;
+        jsonData?: unknown;
+        data?: Record<string, string>;
+        files?: Record<string, {
+            filename: string;
+            content: Buffer | NodeJS.ReadableStream;
+            contentType: string;
+        }>;
+        unwrap?: boolean;
+    }): Promise<T>;
+    private handleResponse;
+    private getFetch;
+    private getFormData;
+}

package/dist/client.js

@@ -0,0 +1,283 @@
+"use strict";
+/**
+ * High-level synchronous client for the Acontext API.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AcontextClient = void 0;
+const errors_1 = require("./errors");
+const blocks_1 = require("./resources/blocks");
+const disks_1 = require("./resources/disks");
+const sessions_1 = require("./resources/sessions");
+const spaces_1 = require("./resources/spaces");
+const constants_1 = require("./constants");
+class AcontextClient {
+    constructor(options = {}) {
+        // Priority: explicit parameters > environment variables > defaults
+        // Load apiKey from parameter or environment variable
+        this._apiKey =
+            options.apiKey ||
+                (typeof process !== 'undefined' && process.env?.ACONTEXT_API_KEY) ||
+                '';
+        if (!this._apiKey || !this._apiKey.trim()) {
+            throw new Error("apiKey is required. Provide it either as a parameter (apiKey='...') " +
+                "or set the ACONTEXT_API_KEY environment variable.");
+        }
+        // Load other parameters from environment variables if not provided
+        this._baseUrl =
+            options.baseUrl ||
+                (typeof process !== 'undefined' && process.env?.ACONTEXT_BASE_URL) ||
+                constants_1.DEFAULT_BASE_URL;
+        this._baseUrl = this._baseUrl.replace(/\/$/, '');
+        this._userAgent =
+            options.userAgent ||
+                (typeof process !== 'undefined' && process.env?.ACONTEXT_USER_AGENT) ||
+                constants_1.DEFAULT_USER_AGENT;
+        this._timeout =
+            options.timeout ??
+                (typeof process !== 'undefined' && process.env?.ACONTEXT_TIMEOUT
+                    ? parseFloat(process.env.ACONTEXT_TIMEOUT)
+                    : 10000);
+        this.spaces = new spaces_1.SpacesAPI(this);
+        this.sessions = new sessions_1.SessionsAPI(this);
+        this.disks = new disks_1.DisksAPI(this);
+        this.artifacts = this.disks.artifacts;
+        this.blocks = new blocks_1.BlocksAPI(this);
+    }
+    get baseUrl() {
+        return this._baseUrl;
+    }
+    async request(method, path, options) {
+        const unwrap = options?.unwrap !== false;
+        const url = `${this._baseUrl}${path}`;
+        try {
+            // Build headers
+            const headers = {
+                Authorization: `Bearer ${this._apiKey}`,
+                Accept: 'application/json',
+                'User-Agent': this._userAgent,
+            };
+            // Build request options
+            let body;
+            let requestHeaders = headers;
+            if (options?.files) {
+                // Use FormData for file uploads
+                const FormDataClass = await this.getFormData();
+                const formData = new FormDataClass();
+                // Add regular form fields
+                if (options.data) {
+                    for (const [key, value] of Object.entries(options.data)) {
+                        formData.append(key, value);
+                    }
+                }
+                // Add files
+                for (const [key, file] of Object.entries(options.files)) {
+                    // Handle Buffer: convert to Blob in browser, use directly in Node.js
+                    if (file.content instanceof Buffer) {
+                        // Check if we're in a browser environment (has Blob constructor)
+                        if (typeof Blob !== 'undefined') {
+                            // Browser environment: convert Buffer to Blob via Uint8Array
+                            const uint8Array = new Uint8Array(file.content);
+                            const blob = new Blob([uint8Array], { type: file.contentType });
+                            formData.append(key, blob, file.filename);
+                        }
+                        else {
+                            // Node.js environment: form-data package accepts Buffer directly
+                            // form-data's append signature differs from browser FormData
+                            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                            formData.append(key, file.content, {
+                                filename: file.filename,
+                                contentType: file.contentType,
+                            });
+                        }
+                    }
+                    else {
+                        // ReadableStream: pass as-is (form-data handles it)
+                        // form-data's append signature differs from browser FormData
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        formData.append(key, file.content, {
+                            filename: file.filename,
+                            contentType: file.contentType,
+                        });
+                    }
+                }
+                // FormData type differs between browser and Node.js (form-data package)
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                body = formData;
+                // Don't set Content-Type for FormData, let the browser/Node set it with boundary
+                delete requestHeaders['Content-Type'];
+            }
+            else if (options?.jsonData) {
+                body = JSON.stringify(options.jsonData);
+                requestHeaders['Content-Type'] = 'application/json';
+            }
+            else if (options?.data) {
+                // For URL-encoded form data
+                const FormDataClass = await this.getFormData();
+                const formData = new FormDataClass();
+                for (const [key, value] of Object.entries(options.data)) {
+                    formData.append(key, value);
+                }
+                // FormData type differs between browser and Node.js (form-data package)
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                body = formData;
+                delete requestHeaders['Content-Type'];
+            }
+            // Build URL with query parameters
+            let finalUrl = url;
+            if (options?.params && Object.keys(options.params).length > 0) {
+                const searchParams = new URLSearchParams();
+                for (const [key, value] of Object.entries(options.params)) {
+                    searchParams.append(key, String(value));
+                }
+                finalUrl = `${url}?${searchParams.toString()}`;
+            }
+            // Make the request
+            const fetchImpl = await this.getFetch();
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), this._timeout);
+            try {
+                const response = await fetchImpl(finalUrl, {
+                    method,
+                    headers: requestHeaders,
+                    body,
+                    signal: controller.signal,
+                });
+                clearTimeout(timeoutId);
+                return await this.handleResponse(response, unwrap);
+            }
+            catch (error) {
+                clearTimeout(timeoutId);
+                if (error instanceof Error && error.name === 'AbortError') {
+                    throw new errors_1.TransportError(`Request timeout after ${this._timeout}ms`);
+                }
+                throw error;
+            }
+        }
+        catch (error) {
+            if (error instanceof errors_1.APIError || error instanceof errors_1.TransportError) {
+                throw error;
+            }
+            throw new errors_1.TransportError(error instanceof Error ? error.message : String(error));
+        }
+    }
+    async handleResponse(response, unwrap) {
+        const contentType = response.headers.get('content-type') || '';
+        let parsed = null;
+        if (contentType.includes('application/json')) {
+            try {
+                parsed = await response.json();
+            }
+            catch {
+                parsed = null;
+            }
+        }
+        if (response.status >= 400) {
+            const payload = parsed;
+            let message = response.statusText;
+            let code;
+            let error;
+            if (payload && typeof payload === 'object') {
+                message = String(payload.msg || payload.message || message);
+                error = payload.error;
+                const codeVal = payload.code;
+                if (typeof codeVal === 'number') {
+                    code = codeVal;
+                }
+            }
+            throw new errors_1.APIError({
+                statusCode: response.status,
+                code,
+                message,
+                error,
+                payload,
+            });
+        }
+        if (parsed === null) {
+            if (unwrap) {
+                return (await response.text());
+            }
+            return {
+                code: response.status,
+                data: await response.text(),
+                msg: response.statusText,
+            };
+        }
+        const payload = parsed;
+        const appCode = payload.code;
+        if (typeof appCode === 'number' && appCode >= 400) {
+            throw new errors_1.APIError({
+                statusCode: response.status,
+                code: appCode,
+                message: String(payload.msg || response.statusText),
+                error: payload.error,
+                payload,
+            });
+        }
+        return (unwrap ? payload.data : payload);
+    }
+    async getFetch() {
+        // Try to use global fetch if available (Node 18+, modern browsers)
+        if (typeof fetch !== 'undefined') {
+            return fetch;
+        }
+        // Fallback to node-fetch for older Node versions
+        try {
+            // node-fetch is an optional peer dependency, use dynamic import with type assertion
+            const nodeFetch = await Promise.resolve(`${'node-fetch'}`).then(s => __importStar(require(s)));
+            return nodeFetch.default;
+        }
+        catch {
+            throw new Error('fetch is not available. Please use Node.js 18+ or install node-fetch');
+        }
+    }
+    async getFormData() {
+        // Try to use global FormData if available
+        if (typeof FormData !== 'undefined') {
+            return FormData;
+        }
+        // Fallback to form-data for older Node versions
+        try {
+            // form-data is an optional peer dependency, use dynamic import with type assertion
+            const FormDataModule = await Promise.resolve(`${'form-data'}`).then(s => __importStar(require(s)));
+            // form-data package has different API than browser FormData, but compatible enough
+            return FormDataModule.default;
+        }
+        catch {
+            throw new Error('FormData is not available. Please use Node.js 18+ or install form-data');
+        }
+    }
+}
+exports.AcontextClient = AcontextClient;

package/dist/constants.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Internal constants shared across the TypeScript SDK.
+ */
+export declare const DEFAULT_BASE_URL = "https://api.acontext.io/api/v1";
+export declare const DEFAULT_USER_AGENT = "acontext-ts/0.0.1";

package/dist/constants.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Internal constants shared across the TypeScript SDK.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_USER_AGENT = exports.DEFAULT_BASE_URL = void 0;
+exports.DEFAULT_BASE_URL = 'https://api.acontext.io/api/v1';
+exports.DEFAULT_USER_AGENT = 'acontext-ts/0.0.1';

package/dist/errors.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Custom exceptions raised by the acontext TypeScript client.
+ */
+/**
+ * Base exception for all errors raised by `acontext`.
+ */
+export declare class AcontextError extends Error {
+    constructor(message: string);
+}
+/**
+ * Raised when the server returns an error response.
+ */
+export declare class APIError extends AcontextError {
+    statusCode: number;
+    code?: number;
+    message: string;
+    error?: string;
+    payload?: unknown;
+    constructor(options: {
+        statusCode: number;
+        code?: number;
+        message?: string;
+        error?: string;
+        payload?: unknown;
+    });
+}
+/**
+ * Raised when the underlying HTTP transport failed before receiving a response.
+ */
+export declare class TransportError extends AcontextError {
+    constructor(message: string);
+}

package/dist/errors.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * Custom exceptions raised by the acontext TypeScript client.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransportError = exports.APIError = exports.AcontextError = void 0;
+/**
+ * Base exception for all errors raised by `acontext`.
+ */
+class AcontextError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AcontextError';
+        Object.setPrototypeOf(this, AcontextError.prototype);
+    }
+}
+exports.AcontextError = AcontextError;
+/**
+ * Raised when the server returns an error response.
+ */
+class APIError extends AcontextError {
+    constructor(options) {
+        const details = options.message || options.error || 'API request failed';
+        super(`${options.statusCode}: ${details}`);
+        this.name = 'APIError';
+        this.statusCode = options.statusCode;
+        this.code = options.code;
+        this.message = details;
+        this.error = options.error;
+        this.payload = options.payload;
+        Object.setPrototypeOf(this, APIError.prototype);
+    }
+}
+exports.APIError = APIError;
+/**
+ * Raised when the underlying HTTP transport failed before receiving a response.
+ */
+class TransportError extends AcontextError {
+    constructor(message) {
+        super(message);
+        this.name = 'TransportError';
+        Object.setPrototypeOf(this, TransportError.prototype);
+    }
+}
+exports.TransportError = TransportError;

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * TypeScript SDK for the Acontext API.
+ */
+export { AcontextClient } from './client';
+export type { AcontextClientOptions } from './client';
+export { FileUpload } from './uploads';
+export { MessagePart, AcontextMessage, buildAcontextMessage } from './messages';
+export { APIError, TransportError, AcontextError } from './errors';
+export * from './types';
+export * from './resources';

package/dist/index.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * TypeScript SDK for the Acontext API.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AcontextError = exports.TransportError = exports.APIError = exports.buildAcontextMessage = exports.AcontextMessage = exports.MessagePart = exports.FileUpload = exports.AcontextClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "AcontextClient", { enumerable: true, get: function () { return client_1.AcontextClient; } });
+var uploads_1 = require("./uploads");
+Object.defineProperty(exports, "FileUpload", { enumerable: true, get: function () { return uploads_1.FileUpload; } });
+var messages_1 = require("./messages");
+Object.defineProperty(exports, "MessagePart", { enumerable: true, get: function () { return messages_1.MessagePart; } });
+Object.defineProperty(exports, "AcontextMessage", { enumerable: true, get: function () { return messages_1.AcontextMessage; } });
+Object.defineProperty(exports, "buildAcontextMessage", { enumerable: true, get: function () { return messages_1.buildAcontextMessage; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "APIError", { enumerable: true, get: function () { return errors_1.APIError; } });
+Object.defineProperty(exports, "TransportError", { enumerable: true, get: function () { return errors_1.TransportError; } });
+Object.defineProperty(exports, "AcontextError", { enumerable: true, get: function () { return errors_1.AcontextError; } });
+__exportStar(require("./types"), exports);
+__exportStar(require("./resources"), exports);

package/dist/messages.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Support for constructing session messages.
+ */
+import { z } from 'zod';
+export declare const MessagePartSchema: z.ZodObject<{
+    type: z.ZodString;
+    text: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    meta: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    file_field: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type MessagePartInput = z.infer<typeof MessagePartSchema>;
+export declare class MessagePart {
+    type: string;
+    text?: string | null;
+    meta?: Record<string, unknown> | null;
+    file_field?: string | null;
+    constructor(data: MessagePartInput);
+    static textPart(text: string, options?: {
+        meta?: Record<string, unknown> | null;
+    }): MessagePart;
+    static fileFieldPart(fileField: string, options?: {
+        meta?: Record<string, unknown> | null;
+    }): MessagePart;
+    toJSON(): MessagePartInput;
+}
+export declare const AcontextMessageSchema: z.ZodObject<{
+    role: z.ZodEnum<{
+        user: "user";
+        assistant: "assistant";
+        system: "system";
+    }>;
+    parts: z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        text: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        meta: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        file_field: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>;
+    meta: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+}, z.core.$strip>;
+export type AcontextMessageInput = z.infer<typeof AcontextMessageSchema>;
+export declare class AcontextMessage {
+    role: 'user' | 'assistant' | 'system';
+    parts: MessagePart[];
+    meta?: Record<string, unknown> | null;
+    constructor(data: AcontextMessageInput);
+    toJSON(): AcontextMessageInput;
+}
+export declare function buildAcontextMessage(options: {
+    role: 'user' | 'assistant' | 'system';
+    parts: (MessagePart | string | MessagePartInput)[];
+    meta?: Record<string, unknown> | null;
+}): AcontextMessage;