@kmlckj/licos-platform-sdk 0.6.0 → 0.6.2

package/README.md

@@ -1,39 +1,45 @@
 # @kmlckj/licos-platform-sdk
 
-LICOS 平台对象存储预览 / 下载 SDK，兼容前端和后端调用。
+LICOS platform SDK for server-side project runtime code.
 
-## 后端模式
+## Runtime Configuration
 
-- `baseUrl` / `token` 不传时，会回退读取 `LICOS_*` 环境变量
-- 后端默认读取 `LICOS_ORCHESTRATOR_API_BASE_URL`
-- 这些存储接口实际挂在调度器 `/api/v1/public/storage/*`
-- `download(url, outputPath)` 会把文件写到本地路径
-- 预览 / 下载都要求鉴权；`download(...)` 会自动带上 `token` 或 `LICOS_RUNTIME_TOKEN`
+Server-side helpers call platform Studio runtime APIs. Project code does not
+pass API base URLs, project IDs, tokens, or environment scopes. The SDK loads
+them from runtime environment variables injected by LICOS:
 
-```js
-import { download, downloadUrl } from '@kmlckj/licos-platform-sdk';
-
-const url = downloadUrl('demo-bucket', 'folder/report.pdf');
-await download(url, '/tmp/report-downloaded.pdf');
-```
+- `LICOS_PLATFORM_API_BASE_URL`
+- `LICOS_RUNTIME_TOKEN` or `LICOS_USER_TOKEN`
+- `LICOS_PROJECT_ID` or `AGENT_PROJECT_ID`
+- `LICOS_WORKSPACE_ID` or `AGENT_WORKSPACE_ID`
+- `LICOS_PROJECT_ENV`, mapped internally to `dev` or `prod`
 
-## 前端模式
+## Database
 
-- 默认走同源相对地址；也可以显式传 `baseUrl`
-- `download(url)` 返回 `Blob`
-- TypeScript 前端可显式导入浏览器入口 `@kmlckj/licos-platform-sdk/browser`，拿到浏览器专用类型
-- 预览 / 下载接口同样要求传 `token`
+Database helpers call the runtime database data plane only. They do not expose
+database control-plane or service deletion APIs.
 
 ```js
-import { download, previewUrl } from '@kmlckj/licos-platform-sdk';
-
-const url = previewUrl('demo-bucket', 'images/demo.png');
-const blob = await download(url, { token: runtimeToken });
+import { database } from '@kmlckj/licos-platform-sdk';
+
+const rows = await database
+  .table('todos')
+  .select('id', 'title')
+  .eq('done', false)
+  .order('created_at', { desc: true })
+  .limit(10)
+  .execute();
 ```
 
-```ts
-import { download, previewUrl } from '@kmlckj/licos-platform-sdk/browser';
+## Object Storage
 
-const url = previewUrl('demo-bucket', 'images/demo.png');
-const blob = await download(url, { token: runtimeToken });
+```js
+import { storage } from '@kmlckj/licos-platform-sdk';
+
+await storage.createFolder('reports');
+const file = await storage.uploadFile('/tmp/report.pdf');
+const link = await storage.shareUrl(file.id);
 ```
+
+The browser entry does not export object storage helpers because runtime tokens
+must not be bundled into public frontend code.

package/package.json

@@ -1,45 +1,45 @@
-{
-  "name": "@kmlckj/licos-platform-sdk",
-  "version": "0.6.0",
-  "description": "LICOS platform SDK for storage download and preview in browser and Node runtimes",
-  "author": "kmlckj",
-  "type": "module",
-  "main": "./src/index.js",
-  "browser": "./src/browser.js",
-  "types": "./src/index.d.ts",
-  "typesVersions": {
-    "*": {
-      "browser": [
-        "src/browser.d.ts"
-      ]
-    }
-  },
-  "exports": {
-    ".": {
-      "browser": {
-        "types": "./src/browser.d.ts",
-        "default": "./src/browser.js"
-      },
-      "types": "./src/index.d.ts",
-      "import": "./src/index.js",
-      "default": "./src/index.js"
-    },
-    "./browser": {
-      "types": "./src/browser.d.ts",
-      "import": "./src/browser.js",
-      "default": "./src/browser.js"
-    }
-  },
-  "files": [
-    "src",
-    "README.md"
-  ],
-  "scripts": {
-    "test": "node --test"
-  },
-  "license": "MIT",
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org"
-  }
-}
+{
+  "name": "@kmlckj/licos-platform-sdk",
+  "version": "0.6.2",
+  "description": "LICOS platform SDK package shell for browser and Node runtimes",
+  "author": "kmlckj",
+  "type": "module",
+  "main": "./src/index.js",
+  "browser": "./src/browser.js",
+  "types": "./src/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "browser": [
+        "src/browser.d.ts"
+      ]
+    }
+  },
+  "exports": {
+    ".": {
+      "browser": {
+        "types": "./src/browser.d.ts",
+        "default": "./src/browser.js"
+      },
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./browser": {
+      "types": "./src/browser.d.ts",
+      "import": "./src/browser.js",
+      "default": "./src/browser.js"
+    }
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}

package/src/browser.d.ts

@@ -1,11 +1,3 @@
-export interface StorageClientOptions {
-  baseUrl?: string;
-  token?: string;
-  fetch?: typeof fetch;
-  headers?: HeadersInit;
-  credentials?: RequestCredentials;
-}
-
 export class PlatformSdkError extends Error {
   status?: number;
   code?: number;
@@ -14,22 +6,3 @@ export class PlatformSdkError extends Error {
 
 export class ConfigurationError extends PlatformSdkError {}
 export class ApiError extends PlatformSdkError {}
-
-export class StorageClient {
-  constructor(options?: StorageClientOptions);
-  previewUrl(bucket: string, objectKey: string): string;
-  downloadUrl(bucket: string, objectKey: string): string;
-  download(url: string): Promise<Blob>;
-}
-
-export function previewUrl(
-  bucket: string,
-  objectKey: string,
-  options?: StorageClientOptions,
-): string;
-export function downloadUrl(
-  bucket: string,
-  objectKey: string,
-  options?: StorageClientOptions,
-): string;
-export function download(url: string, options?: StorageClientOptions): Promise<Blob>;

package/src/browser.js

@@ -1,64 +1 @@
-import {
-  ApiError,
-  ConfigurationError,
-  PlatformSdkError,
-  downloadBlob,
-  encodeObjectKey,
-  encodeStorageSegment,
-  normalizeBaseUrl,
-} from './shared.js';
-
-export class StorageClient {
-  constructor(options = {}) {
-    this.baseUrl = options.baseUrl;
-    this.token = options.token;
-    this.fetchImpl = options.fetch ?? fetch;
-    this.headers = options.headers;
-    this.credentials = options.credentials;
-  }
-
-  previewUrl(bucket, objectKey) {
-    const baseUrl = normalizeBaseUrl(this.baseUrl);
-    return `${baseUrl}/api/v1/public/storage/${encodeStorageSegment(bucket)}/${encodeObjectKey(objectKey)}`;
-  }
-
-  downloadUrl(bucket, objectKey) {
-    return `${this.previewUrl(bucket, objectKey)}?download=1`;
-  }
-
-  async download(url, outputPath) {
-    if (outputPath !== undefined) {
-      throw new ConfigurationError(
-        'Front-end mode does not support downloading directly to a filesystem path. Omit outputPath to receive a Blob.',
-      );
-    }
-    return downloadBlob(this.fetchImpl, url, {
-      token: this.token,
-      headers: this.headers,
-      credentials: this.credentials,
-    });
-  }
-}
-
-function defaultClient(options = {}) {
-  return new StorageClient(options);
-}
-
-export function previewUrl(bucket, objectKey, options = {}) {
-  return defaultClient(options).previewUrl(bucket, objectKey);
-}
-
-export function downloadUrl(bucket, objectKey, options = {}) {
-  return defaultClient(options).downloadUrl(bucket, objectKey);
-}
-
-export async function download(url, outputPathOrOptions, maybeOptions = {}) {
-  if (typeof outputPathOrOptions === 'string') {
-    throw new ConfigurationError(
-      'Front-end mode does not support downloading directly to a filesystem path. Omit outputPath to receive a Blob.',
-    );
-  }
-  return defaultClient(outputPathOrOptions ?? maybeOptions).download(url);
-}
-
-export { PlatformSdkError, ConfigurationError, ApiError };
+export { PlatformSdkError, ConfigurationError, ApiError } from './shared.js';

package/src/database.js

@@ -0,0 +1,255 @@
+import { ApiError } from './shared.js';
+import { authHeaders, runtimeConfig } from './runtime.js';
+
+function databaseConfig() {
+  return runtimeConfig();
+}
+
+function databaseUrl(config, route) {
+  return `${config.baseUrl}/api/v1/studio/runtime/database/projects/${encodeURIComponent(config.projectId)}${route}`;
+}
+
+function compactObject(value) {
+  return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined && item !== null));
+}
+
+function normalizeSelect(select) {
+  if (select === undefined || select === null) return undefined;
+  if (typeof select === 'string') {
+    return select.split(',').map((item) => item.trim()).filter(Boolean);
+  }
+  return Array.from(select).map((item) => String(item));
+}
+
+async function decodeResponse(response) {
+  const text = await response.text();
+  const payload = text ? JSON.parse(text) : null;
+  if (!response.ok) {
+    throw new ApiError(text || `platform database API returned ${response.status}`, {
+      status: response.status,
+      details: payload,
+    });
+  }
+  if (!payload || typeof payload !== 'object') return payload;
+  if ((payload.code !== undefined && payload.code !== 0) || payload.success === false) {
+    throw new ApiError(payload.message || 'platform database API failed', {
+      status: response.status,
+      code: typeof payload.code === 'number' ? payload.code : undefined,
+      details: payload,
+    });
+  }
+  return payload.data;
+}
+
+async function requestJson(route, body) {
+  const config = databaseConfig();
+  const payload = { environment: config.environment, ...compactObject(body) };
+  const response = await fetch(databaseUrl(config, route), {
+    method: 'POST',
+    headers: authHeaders(config),
+    body: JSON.stringify(payload),
+  });
+  return decodeResponse(response);
+}
+
+export async function query(table, options = {}) {
+  return requestJson('/query', {
+    table,
+    select: normalizeSelect(options.select),
+    filters: options.filters?.length ? options.filters : undefined,
+    orderBy: options.orderBy?.length ? options.orderBy : undefined,
+    range: options.range,
+    limit: options.limit,
+    offset: options.offset,
+    count: options.count,
+    head: options.head,
+  });
+}
+
+export async function single(table, options = {}) {
+  return requestJson('/single', {
+    table,
+    select: normalizeSelect(options.select),
+    filters: options.filters?.length ? options.filters : undefined,
+    orderBy: options.orderBy?.length ? options.orderBy : undefined,
+    mode: options.maybe ? 'maybe_single' : 'single',
+  });
+}
+
+export async function maybeSingle(table, options = {}) {
+  return single(table, { ...options, maybe: true });
+}
+
+export async function aggregate(table, aggregateName, options = {}) {
+  return requestJson('/aggregate', {
+    table,
+    filters: options.filters?.length ? options.filters : undefined,
+    aggregate: aggregateName,
+    field: options.field,
+    groupBy: options.groupBy?.length ? options.groupBy : undefined,
+  });
+}
+
+export async function insert(table, options = {}) {
+  return requestJson('/insert', {
+    table,
+    row: options.row,
+    rows: options.rows,
+    returning: options.returning ?? true,
+  });
+}
+
+export async function updateRows(table, options = {}) {
+  return requestJson('/update', {
+    table,
+    values: options.values,
+    filters: options.filters?.length ? options.filters : undefined,
+    updates: options.updates?.length ? options.updates : undefined,
+    returning: options.returning ?? true,
+  });
+}
+
+export async function deleteRows(table, options = {}) {
+  return requestJson('/delete', {
+    table,
+    filters: options.filters?.length ? options.filters : undefined,
+    deletes: options.deletes?.length ? options.deletes : undefined,
+    returning: options.returning ?? true,
+  });
+}
+
+export async function upsert(table, options = {}) {
+  return requestJson('/upsert', {
+    table,
+    row: options.row,
+    rows: options.rows,
+    conflictKeys: options.conflictKeys?.length ? options.conflictKeys : undefined,
+    returning: options.returning ?? true,
+  });
+}
+
+export async function transaction(operations) {
+  const config = databaseConfig();
+  const normalized = operations.map((operation) => ({
+    type: operation.type,
+    request: {
+      ...operation.request,
+      environment: config.environment,
+    },
+  }));
+  return requestJson('/transaction', { operations: normalized });
+}
+
+export async function rpc(functionName, args = {}) {
+  return requestJson(`/rpc/${encodeURIComponent(functionName)}`, { args });
+}
+
+export function table(name) {
+  return new TableQuery(name);
+}
+
+class TableQuery {
+  constructor(name) {
+    this.name = name;
+    this._select = undefined;
+    this._filters = [];
+    this._orderBy = [];
+    this._range = undefined;
+    this._limit = undefined;
+    this._offset = undefined;
+    this._count = undefined;
+    this._head = undefined;
+  }
+
+  select(...fields) {
+    this._select = fields.length === 1 && fields[0].includes(',') ? normalizeSelect(fields[0]) : fields;
+    return this;
+  }
+
+  filter(field, op, value) {
+    this._filters.push({ field, op, value });
+    return this;
+  }
+
+  eq(field, value) { return this.filter(field, 'eq', value); }
+  neq(field, value) { return this.filter(field, 'neq', value); }
+  gt(field, value) { return this.filter(field, 'gt', value); }
+  gte(field, value) { return this.filter(field, 'gte', value); }
+  lt(field, value) { return this.filter(field, 'lt', value); }
+  lte(field, value) { return this.filter(field, 'lte', value); }
+  in(field, value) { return this.filter(field, 'in', value); }
+  notIn(field, value) { return this.filter(field, 'not_in', value); }
+  isNull(field) { return this.filter(field, 'is_null'); }
+  isNotNull(field) { return this.filter(field, 'is_not_null'); }
+  like(field, value) { return this.filter(field, 'like', value); }
+  ilike(field, value) { return this.filter(field, 'ilike', value); }
+
+  order(field, options = {}) {
+    this._orderBy.push({ field, direction: options.desc ? 'desc' : 'asc' });
+    return this;
+  }
+
+  range(from, to) {
+    this._range = { from, to };
+    return this;
+  }
+
+  limit(value) {
+    this._limit = value;
+    return this;
+  }
+
+  offset(value) {
+    this._offset = value;
+    return this;
+  }
+
+  withCount(options = {}) {
+    this._count = true;
+    this._head = Boolean(options.head);
+    return this;
+  }
+
+  execute() {
+    return query(this.name, {
+      select: this._select,
+      filters: this._filters,
+      orderBy: this._orderBy,
+      range: this._range,
+      limit: this._limit,
+      offset: this._offset,
+      count: this._count,
+      head: this._head,
+    });
+  }
+
+  single() {
+    return single(this.name, {
+      select: this._select,
+      filters: this._filters,
+      orderBy: this._orderBy,
+    });
+  }
+
+  maybeSingle() {
+    return maybeSingle(this.name, {
+      select: this._select,
+      filters: this._filters,
+      orderBy: this._orderBy,
+    });
+  }
+}
+
+export const database = {
+  query,
+  single,
+  maybeSingle,
+  aggregate,
+  insert,
+  updateRows,
+  deleteRows,
+  upsert,
+  transaction,
+  rpc,
+  table,
+};

package/src/index.d.ts

@@ -1,11 +1,3 @@
-export interface StorageClientOptions {
-  baseUrl?: string;
-  token?: string;
-  fetch?: typeof fetch;
-  headers?: HeadersInit;
-  credentials?: RequestCredentials;
-}
-
 export class PlatformSdkError extends Error {
   status?: number;
   code?: number;
@@ -15,27 +7,200 @@ export class PlatformSdkError extends Error {
 export class ConfigurationError extends PlatformSdkError {}
 export class ApiError extends PlatformSdkError {}
 
-export class StorageClient {
-  constructor(options?: StorageClientOptions);
-  previewUrl(bucket: string, objectKey: string): string;
-  downloadUrl(bucket: string, objectKey: string): string;
-  download(url: string): Promise<Blob>;
-  download(url: string, outputPath: string): Promise<string>;
-}
-
-export function previewUrl(
-  bucket: string,
-  objectKey: string,
-  options?: StorageClientOptions,
-): string;
-export function downloadUrl(
-  bucket: string,
-  objectKey: string,
-  options?: StorageClientOptions,
-): string;
-export function download(url: string, options?: StorageClientOptions): Promise<Blob>;
-export function download(
-  url: string,
-  outputPath: string,
-  options?: StorageClientOptions,
-): Promise<string>;
+export interface DatabaseFilter {
+  field: string;
+  op: 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'is_null' | 'is_not_null' | 'like' | 'ilike' | string;
+  value?: unknown;
+}
+
+export interface DatabaseOrderBy {
+  field: string;
+  direction?: 'asc' | 'desc';
+}
+
+export interface DatabaseRange {
+  from: number;
+  to: number;
+}
+
+export interface DatabaseResponse {
+  data?: Record<string, unknown>[];
+  count?: number;
+  affectedRows?: number;
+  message?: string;
+  [key: string]: unknown;
+}
+
+export interface DatabaseQueryOptions {
+  select?: string | string[];
+  filters?: DatabaseFilter[];
+  orderBy?: DatabaseOrderBy[];
+  range?: DatabaseRange;
+  limit?: number;
+  offset?: number;
+  count?: boolean;
+  head?: boolean;
+}
+
+export interface DatabaseMutationOptions {
+  row?: Record<string, unknown>;
+  rows?: Record<string, unknown>[];
+  values?: Record<string, unknown>;
+  filters?: DatabaseFilter[];
+  updates?: Array<{ filters?: DatabaseFilter[]; values?: Record<string, unknown> }>;
+  deletes?: Array<{ filters?: DatabaseFilter[] }>;
+  conflictKeys?: string[];
+  returning?: boolean;
+}
+
+export interface DatabaseOperation {
+  type: 'query' | 'insert' | 'update' | 'delete' | 'upsert' | string;
+  request: Record<string, unknown>;
+}
+
+export interface TableQuery {
+  select(...fields: string[]): TableQuery;
+  filter(field: string, op: string, value?: unknown): TableQuery;
+  eq(field: string, value: unknown): TableQuery;
+  neq(field: string, value: unknown): TableQuery;
+  gt(field: string, value: unknown): TableQuery;
+  gte(field: string, value: unknown): TableQuery;
+  lt(field: string, value: unknown): TableQuery;
+  lte(field: string, value: unknown): TableQuery;
+  in(field: string, value: unknown[]): TableQuery;
+  notIn(field: string, value: unknown[]): TableQuery;
+  isNull(field: string): TableQuery;
+  isNotNull(field: string): TableQuery;
+  like(field: string, value: string): TableQuery;
+  ilike(field: string, value: string): TableQuery;
+  order(field: string, options?: { desc?: boolean }): TableQuery;
+  range(from: number, to: number): TableQuery;
+  limit(value: number): TableQuery;
+  offset(value: number): TableQuery;
+  withCount(options?: { head?: boolean }): TableQuery;
+  execute(): Promise<DatabaseResponse>;
+  single(): Promise<DatabaseResponse>;
+  maybeSingle(): Promise<DatabaseResponse>;
+}
+
+export function query(table: string, options?: DatabaseQueryOptions): Promise<DatabaseResponse>;
+export function single(table: string, options?: DatabaseQueryOptions & { maybe?: boolean }): Promise<DatabaseResponse>;
+export function maybeSingle(table: string, options?: DatabaseQueryOptions): Promise<DatabaseResponse>;
+export function aggregate(table: string, aggregateName: string, options?: { field?: string; groupBy?: string[]; filters?: DatabaseFilter[] }): Promise<DatabaseResponse>;
+export function insert(table: string, options?: DatabaseMutationOptions): Promise<DatabaseResponse>;
+export function updateRows(table: string, options?: DatabaseMutationOptions): Promise<DatabaseResponse>;
+export function deleteRows(table: string, options?: DatabaseMutationOptions): Promise<DatabaseResponse>;
+export function upsert(table: string, options?: DatabaseMutationOptions): Promise<DatabaseResponse>;
+export function transaction(operations: DatabaseOperation[]): Promise<DatabaseResponse[]>;
+export function rpc(functionName: string, args?: Record<string, unknown>): Promise<DatabaseResponse>;
+export function table(name: string): TableQuery;
+
+export const database: {
+  query: typeof query;
+  single: typeof single;
+  maybeSingle: typeof maybeSingle;
+  aggregate: typeof aggregate;
+  insert: typeof insert;
+  updateRows: typeof updateRows;
+  deleteRows: typeof deleteRows;
+  upsert: typeof upsert;
+  transaction: typeof transaction;
+  rpc: typeof rpc;
+  table: typeof table;
+};
+
+export interface StorageSummary {
+  workspaceId?: string;
+  projectId?: string;
+  scope?: string;
+  bucketName?: string;
+  usedSizeBytes?: number;
+  fileCount?: number;
+  folderCount?: number;
+  serviceEnabled?: boolean;
+  [key: string]: unknown;
+}
+
+export interface StorageFolder {
+  id?: string;
+  workspaceId?: string;
+  projectId?: string;
+  scope?: string;
+  parentId?: string | null;
+  folderName?: string;
+  folderPath?: string;
+  createdAt?: string;
+  updatedAt?: string;
+  [key: string]: unknown;
+}
+
+export interface StorageFile {
+  id?: string;
+  workspaceId?: string;
+  projectId?: string;
+  scope?: string;
+  folderId?: string | null;
+  folderPath?: string;
+  fileName?: string;
+  contentType?: string;
+  sizeBytes?: number;
+  storageBucket?: string;
+  storageKey?: string;
+  downloadUrl?: string;
+  createdAt?: string;
+  updatedAt?: string;
+  [key: string]: unknown;
+}
+
+export interface StorageEntries {
+  currentFolderId?: string | null;
+  currentFolderName?: string;
+  currentFolderPath?: string;
+  breadcrumbs?: unknown[];
+  folders?: StorageFolder[];
+  files?: StorageFile[];
+  [key: string]: unknown;
+}
+
+export interface UploadFileOptions {
+  folderId?: string;
+  fileName?: string;
+  contentType?: string;
+}
+
+export interface ShareUrlOptions {
+  expirySeconds?: number;
+}
+
+export function summary(): Promise<StorageSummary>;
+export function listFolders(): Promise<StorageFolder[]>;
+export function listEntries(options?: { folderId?: string }): Promise<StorageEntries>;
+export function listFiles(): Promise<StorageFile[]>;
+export function createFolder(folderName: string, options?: { parentId?: string }): Promise<StorageFolder>;
+export function renameFolder(folderId: string, folderName: string): Promise<StorageFolder>;
+export function deleteFolder(folderId: string): Promise<void>;
+export function uploadFile(
+  input: string | Blob | Buffer | Uint8Array,
+  options?: UploadFileOptions,
+): Promise<StorageFile>;
+export function renameFile(fileId: string, fileName: string): Promise<StorageFile>;
+export function moveFile(fileId: string, options?: { folderId?: string }): Promise<StorageFile>;
+export function shareUrl(fileId: string, options?: ShareUrlOptions): Promise<{ url?: string; expiresAt?: string; [key: string]: unknown }>;
+export function objectExists(options?: { fileId?: string; objectKey?: string }): Promise<{ fileId?: string; bucketName?: string; objectKey?: string; exists?: boolean; [key: string]: unknown }>;
+export function deleteFile(fileId: string): Promise<void>;
+
+export const storage: {
+  summary: typeof summary;
+  listFolders: typeof listFolders;
+  listEntries: typeof listEntries;
+  listFiles: typeof listFiles;
+  createFolder: typeof createFolder;
+  renameFolder: typeof renameFolder;
+  deleteFolder: typeof deleteFolder;
+  uploadFile: typeof uploadFile;
+  renameFile: typeof renameFile;
+  moveFile: typeof moveFile;
+  shareUrl: typeof shareUrl;
+  objectExists: typeof objectExists;
+  deleteFile: typeof deleteFile;
+};

package/src/index.js

@@ -1,68 +1,3 @@
-import fs from 'node:fs/promises';
-import path from 'node:path';
-
-import {
-  ApiError,
-  ConfigurationError,
-  PlatformSdkError,
-  downloadBlob,
-  encodeObjectKey,
-  encodeStorageSegment,
-  normalizeBaseUrl,
-} from './shared.js';
-
-export class StorageClient {
-  constructor(options = {}) {
-    this.baseUrl = options.baseUrl;
-    this.token = options.token;
-    this.fetchImpl = options.fetch ?? fetch;
-    this.headers = options.headers;
-    this.credentials = options.credentials;
-  }
-
-  previewUrl(bucket, objectKey) {
-    const baseUrl = normalizeBaseUrl(this.baseUrl);
-    return `${baseUrl}/api/v1/public/storage/${encodeStorageSegment(bucket)}/${encodeObjectKey(objectKey)}`;
-  }
-
-  downloadUrl(bucket, objectKey) {
-    return `${this.previewUrl(bucket, objectKey)}?download=1`;
-  }
-
-  async download(url, outputPath) {
-    const blob = await downloadBlob(this.fetchImpl, url, {
-      token: this.token,
-      headers: this.headers,
-      credentials: this.credentials,
-    });
-    if (outputPath === undefined) {
-      return blob;
-    }
-    const buffer = Buffer.from(await blob.arrayBuffer());
-    await fs.mkdir(path.dirname(outputPath), { recursive: true });
-    await fs.writeFile(outputPath, buffer);
-    return outputPath;
-  }
-
-}
-
-function defaultClient(options = {}) {
-  return new StorageClient(options);
-}
-
-export function previewUrl(bucket, objectKey, options = {}) {
-  return defaultClient(options).previewUrl(bucket, objectKey);
-}
-
-export function downloadUrl(bucket, objectKey, options = {}) {
-  return defaultClient(options).downloadUrl(bucket, objectKey);
-}
-
-export async function download(url, outputPathOrOptions, maybeOptions = {}) {
-  if (typeof outputPathOrOptions === 'string') {
-    return defaultClient(maybeOptions).download(url, outputPathOrOptions);
-  }
-  return defaultClient(outputPathOrOptions ?? {}).download(url);
-}
-
-export { PlatformSdkError, ConfigurationError, ApiError };
+export { PlatformSdkError, ConfigurationError, ApiError } from './shared.js';
+export * from './database.js';
+export * from './storage.js';

package/src/runtime.js

@@ -0,0 +1,70 @@
+import { ConfigurationError } from './shared.js';
+
+export function env(name) {
+  const value = process.env[name];
+  if (typeof value !== 'string') return undefined;
+  const trimmed = value.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+function normalizeBaseUrl(value) {
+  let trimmed = value.trim().replace(/\/+$/, '');
+  if (trimmed.endsWith('/api/v1')) {
+    trimmed = trimmed.slice(0, -'/api/v1'.length);
+  }
+  return trimmed.replace(/\/+$/, '');
+}
+
+function serviceBaseUrl(hostEnv, portEnv, defaultPort) {
+  const host = env(hostEnv);
+  if (!host) return undefined;
+  return `http://${host}:${env(portEnv) || defaultPort}`;
+}
+
+export function platformBaseUrl() {
+  const value =
+    env('LICOS_PLATFORM_API_BASE_URL') ||
+    serviceBaseUrl('AIOS_PLATFORM_SERVICE_HOST', 'AIOS_PLATFORM_SERVICE_PORT', '9100') ||
+    serviceBaseUrl('LICOS_PLATFORM_SERVICE_HOST', 'LICOS_PLATFORM_SERVICE_PORT', '9100') ||
+    serviceBaseUrl('PLATFORM_SERVICE_HOST', 'PLATFORM_SERVICE_PORT', '9100');
+  if (!value) {
+    throw new ConfigurationError('LICOS_PLATFORM_API_BASE_URL is not configured');
+  }
+  return normalizeBaseUrl(value);
+}
+
+export function projectEnvironment(overrideEnvName) {
+  const explicit = ((overrideEnvName ? env(overrideEnvName) : undefined) || '').toLowerCase();
+  if (explicit === 'dev' || explicit === 'prod') return explicit;
+  const projectEnv = (env('LICOS_PROJECT_ENV') || env('AGENT_ENV') || '').toLowerCase();
+  return ['prod', 'production', 'release'].includes(projectEnv) ? 'prod' : 'dev';
+}
+
+export function runtimeConfig({ environmentOverrideEnv } = {}) {
+  const projectId = env('LICOS_PROJECT_ID') || env('AGENT_PROJECT_ID');
+  if (!projectId) {
+    throw new ConfigurationError('LICOS_PROJECT_ID or AGENT_PROJECT_ID is not configured');
+  }
+  const token = env('LICOS_RUNTIME_TOKEN') || env('LICOS_USER_TOKEN');
+  if (!token) {
+    throw new ConfigurationError('LICOS_RUNTIME_TOKEN or LICOS_USER_TOKEN is not configured');
+  }
+  return {
+    baseUrl: platformBaseUrl(),
+    projectId,
+    environment: projectEnvironment(environmentOverrideEnv),
+    token,
+    workspaceId: env('LICOS_WORKSPACE_ID') || env('AGENT_WORKSPACE_ID'),
+    userId: env('LICOS_USER_ID') || env('AGENT_USER_ID'),
+  };
+}
+
+export function authHeaders(config, contentType = 'application/json') {
+  const result = {
+    Authorization: `Bearer ${config.token}`,
+  };
+  if (contentType) result['Content-Type'] = contentType;
+  if (config.workspaceId) result['X-Workspace-Id'] = config.workspaceId;
+  if (config.userId) result['X-User-Id'] = config.userId;
+  return result;
+}

package/src/shared.js

@@ -10,90 +10,3 @@ export class PlatformSdkError extends Error {
 
 export class ConfigurationError extends PlatformSdkError {}
 export class ApiError extends PlatformSdkError {}
-
-export function isNodeRuntime() {
-  return typeof process !== 'undefined' && !!process?.versions?.node;
-}
-
-function readEnv(name) {
-  if (typeof process === 'undefined' || !process?.env) {
-    return undefined;
-  }
-  const value = process.env[name];
-  return value ? value : undefined;
-}
-
-export function normalizeBaseUrl(baseUrl) {
-  if (typeof baseUrl === 'string') {
-    return baseUrl.replace(/\/+$/, '');
-  }
-
-  const envBaseUrl = readEnv('LICOS_ORCHESTRATOR_API_BASE_URL');
-  if (envBaseUrl) {
-    return envBaseUrl.replace(/\/+$/, '');
-  }
-
-  if (!isNodeRuntime()) {
-    return '';
-  }
-
-  throw new ConfigurationError(
-    'Missing required environment variable: LICOS_ORCHESTRATOR_API_BASE_URL',
-  );
-}
-
-export function encodeStorageSegment(value) {
-  return encodeURIComponent(value);
-}
-
-export function encodeObjectKey(value) {
-  return value.split('/').map(encodeStorageSegment).join('/');
-}
-
-function headersFromInit(headersInit) {
-  return new Headers(headersInit ?? undefined);
-}
-
-export function buildRequestHeaders(options = {}, { authenticated = false } = {}) {
-  const headers = headersFromInit(options.headers);
-  if (authenticated && !headers.has('Authorization')) {
-    const resolvedToken = options.token ?? readEnv('LICOS_RUNTIME_TOKEN');
-    if (resolvedToken) {
-      headers.set('Authorization', `Bearer ${resolvedToken}`);
-    } else if (isNodeRuntime()) {
-      throw new ConfigurationError(
-        'Missing authentication token. Pass options.token, provide an Authorization header, or set LICOS_RUNTIME_TOKEN.',
-      );
-    }
-  }
-  return headers;
-}
-
-export function buildRequestInit(options = {}, init = {}) {
-  const requestInit = { ...init };
-  if (options.credentials) {
-    requestInit.credentials = options.credentials;
-  }
-  return requestInit;
-}
-
-export async function downloadBlob(fetchImpl, url, options = {}) {
-  const response = await fetchImpl(
-    url,
-    buildRequestInit(options, {
-      method: 'GET',
-      headers: buildRequestHeaders(options, { authenticated: true }),
-    }),
-  );
-  if (!response.ok) {
-    throw new ApiError(`Platform download failed: HTTP ${response.status}`, {
-      status: response.status,
-    });
-  }
-  if (typeof response.blob === 'function') {
-    return response.blob();
-  }
-  return new Blob([await response.arrayBuffer()], {
-    type: response.headers.get('content-type') ?? undefined,
-  });
-}

package/src/storage.js

@@ -0,0 +1,155 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { ApiError } from './shared.js';
+import { authHeaders, runtimeConfig } from './runtime.js';
+
+function storageConfig() {
+  return runtimeConfig({ environmentOverrideEnv: 'LICOS_STORAGE_SCOPE' });
+}
+
+function query(config, params = {}) {
+  const search = new URLSearchParams();
+  search.set('projectId', config.projectId);
+  search.set('scope', config.environment);
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== undefined && value !== null) search.set(key, String(value));
+  }
+  return search.toString();
+}
+
+function storageUrl(config, route, params) {
+  return `${config.baseUrl}/api/v1/studio/storage${route}?${query(config, params)}`;
+}
+
+async function decodeResponse(response) {
+  const text = await response.text();
+  const payload = text ? JSON.parse(text) : null;
+  if (!response.ok) {
+    throw new ApiError(text || `platform storage API returned ${response.status}`, {
+      status: response.status,
+      details: payload,
+    });
+  }
+  if (!payload || typeof payload !== 'object') return payload;
+  if ((payload.code !== undefined && payload.code !== 0) || payload.success === false) {
+    throw new ApiError(payload.message || 'platform storage API failed', {
+      status: response.status,
+      code: typeof payload.code === 'number' ? payload.code : undefined,
+      details: payload,
+    });
+  }
+  return payload.data;
+}
+
+async function requestJson(method, route, { params, body } = {}) {
+  const config = storageConfig();
+  const response = await fetch(storageUrl(config, route, params), {
+    method,
+    headers: authHeaders(config),
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  return decodeResponse(response);
+}
+
+async function filePart(input, options = {}) {
+  if (typeof input === 'string') {
+    const data = await readFile(input);
+    return {
+      blob: new Blob([data], { type: options.contentType || 'application/octet-stream' }),
+      fileName: options.fileName || path.basename(input),
+    };
+  }
+  if (input instanceof Blob) {
+    return { blob: input, fileName: options.fileName || 'file' };
+  }
+  if (input instanceof Uint8Array || Buffer.isBuffer(input)) {
+    return {
+      blob: new Blob([input], { type: options.contentType || 'application/octet-stream' }),
+      fileName: options.fileName || 'file',
+    };
+  }
+  throw new TypeError('uploadFile input must be a file path, Blob, Buffer, or Uint8Array');
+}
+
+export async function summary() {
+  return requestJson('GET', '/summary');
+}
+
+export async function listFolders() {
+  return (await requestJson('GET', '/folders')) || [];
+}
+
+export async function listEntries({ folderId } = {}) {
+  return requestJson('GET', '/entries', { params: { folderId } });
+}
+
+export async function listFiles() {
+  return (await requestJson('GET', '/files')) || [];
+}
+
+export async function createFolder(folderName, { parentId } = {}) {
+  return requestJson('POST', '/folders', { body: { folderName, parentId } });
+}
+
+export async function renameFolder(folderId, folderName) {
+  return requestJson('PUT', `/folders/${encodeURIComponent(folderId)}`, { body: { folderName } });
+}
+
+export async function deleteFolder(folderId) {
+  await requestJson('DELETE', `/folders/${encodeURIComponent(folderId)}`);
+}
+
+export async function uploadFile(input, options = {}) {
+  const config = storageConfig();
+  const { blob, fileName } = await filePart(input, options);
+  const form = new FormData();
+  form.set('projectId', config.projectId);
+  form.set('scope', config.environment);
+  if (options.folderId) form.set('folderId', options.folderId);
+  form.set('file', blob, fileName);
+  const response = await fetch(`${config.baseUrl}/api/v1/studio/storage/files/upload`, {
+    method: 'POST',
+    headers: authHeaders(config, undefined),
+    body: form,
+  });
+  return decodeResponse(response);
+}
+
+export async function renameFile(fileId, fileName) {
+  return requestJson('PUT', `/files/${encodeURIComponent(fileId)}/rename`, { body: { fileName } });
+}
+
+export async function moveFile(fileId, { folderId } = {}) {
+  return requestJson('PUT', `/files/${encodeURIComponent(fileId)}/move`, { body: { folderId } });
+}
+
+export async function shareUrl(fileId, { expirySeconds } = {}) {
+  return requestJson('POST', `/files/${encodeURIComponent(fileId)}/share-url`, {
+    body: { expirySeconds },
+  });
+}
+
+export async function objectExists({ fileId, objectKey } = {}) {
+  return requestJson('POST', '/objects/exists', { body: { fileId, objectKey } });
+}
+
+export async function deleteFile(fileId) {
+  await requestJson('DELETE', `/files/${encodeURIComponent(fileId)}`);
+}
+
+export const storage = {
+  summary,
+  listFolders,
+  listEntries,
+  listFiles,
+  createFolder,
+  renameFolder,
+  deleteFolder,
+  uploadFile,
+  renameFile,
+  moveFile,
+  shareUrl,
+  objectExists,
+  deleteFile,
+};