@kmlckj/licos-platform-sdk 0.5.0 → 0.6.1

package/README.md

@@ -1,47 +1,45 @@
 # @kmlckj/licos-platform-sdk
 
-LICOS 平台对象存储 SDK，兼容前端和后端调用。
+LICOS platform SDK for server-side project runtime code.
 
-## 后端模式
+## Runtime Configuration
 
-- `baseUrl` / `token` / `userId` / `projectId` 不传时，会回退读取 `LICOS_*` 环境变量
-- 后端默认读取 `LICOS_ORCHESTRATOR_API_BASE_URL`
-- 这些存储接口实际挂在调度器 `/api/v1/storage/*` 和 `/api/v1/public/storage/*`
-- `uploadUser` / `uploadProject` 支持直接传本地文件路径
-- `download(url, outputPath)` 会把文件写到本地路径
-- 上传、预览、下载都要求鉴权；`download(...)` 会自动带上 `token` 或 `LICOS_USER_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 { uploadProject, download } from '@kmlckj/licos-platform-sdk';
-
-const uploaded = await uploadProject('/tmp/report.pdf');
-await download(uploaded.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`
-- 上传支持 `File` / `Blob` / `ArrayBuffer` / TypedArray / `{ data, fileName, contentType }`
-- `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 { uploadUser, download } from '@kmlckj/licos-platform-sdk';
-
-const uploaded = await uploadUser(fileInput.files[0], {
-  token: userJwt,
-});
-
-const blob = await download(uploaded.download_url, { token: userJwt });
+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 { uploadUser, download } from '@kmlckj/licos-platform-sdk/browser';
+## Object Storage
 
-const uploaded = await uploadUser(fileInput.files![0], {
-  token: userJwt,
-});
+```js
+import { storage } from '@kmlckj/licos-platform-sdk';
 
-const blob = await download(uploaded.download_url, { token: userJwt });
+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.5.0",
-  "description": "LICOS platform SDK for storage upload, 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.1",
+  "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,48 +1,3 @@
-export interface UploadResult {
-  bucket: string;
-  object_key: string;
-  file_name: string;
-  content_type: string;
-  size_bytes: number;
-  preview_url: string;
-  download_url: string;
-}
-
-export interface BlobLike {
-  arrayBuffer(): Promise<ArrayBuffer>;
-  readonly size?: number;
-  readonly type?: string;
-  readonly name?: string;
-}
-
-export interface UploadBinaryDescriptor {
-  data?: ArrayBuffer | ArrayBufferView | BlobLike;
-  file?: ArrayBuffer | ArrayBufferView | BlobLike;
-  fileName?: string;
-  contentType?: string;
-}
-
-export type UploadSource =
-  | ArrayBuffer
-  | ArrayBufferView
-  | BlobLike
-  | UploadBinaryDescriptor;
-
-export interface StorageClientOptions {
-  baseUrl?: string;
-  token?: string;
-  userId?: string;
-  projectId?: string;
-  fetch?: typeof fetch;
-  headers?: HeadersInit;
-  credentials?: RequestCredentials;
-}
-
-export interface UploadProjectOptions extends StorageClientOptions {
-  userId?: string;
-  projectId?: string;
-}
-
 export class PlatformSdkError extends Error {
   status?: number;
   code?: number;
@@ -51,32 +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;
-  uploadUser(file: UploadSource): Promise<UploadResult>;
-  uploadProject(file: UploadSource, options?: UploadProjectOptions): Promise<UploadResult>;
-  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 uploadUser(
-  file: UploadSource,
-  options?: StorageClientOptions,
-): Promise<UploadResult>;
-export function uploadProject(
-  file: UploadSource,
-  options?: UploadProjectOptions,
-): Promise<UploadResult>;
-export function download(url: string, options?: StorageClientOptions): Promise<Blob>;

package/src/browser.js

@@ -1,102 +1 @@
-import {
-  ApiError,
-  ConfigurationError,
-  PlatformSdkError,
-  downloadBlob,
-  encodeObjectKey,
-  encodeStorageSegment,
-  normalizeBaseUrl,
-  resolveProjectId,
-  resolveUserId,
-  uploadFile,
-} from './shared.js';
-
-export class StorageClient {
-  constructor(options = {}) {
-    this.baseUrl = options.baseUrl;
-    this.token = options.token;
-    this.userId = options.userId;
-    this.projectId = options.projectId;
-    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 uploadUser(file) {
-    const baseUrl = normalizeBaseUrl(this.baseUrl);
-    return uploadFile(this.fetchImpl, `${baseUrl}/api/v1/storage/upload/user`, file, {
-      token: this.token,
-      headers: this.headers,
-      credentials: this.credentials,
-    });
-  }
-
-  async uploadProject(file, options = {}) {
-    const baseUrl = normalizeBaseUrl(this.baseUrl);
-    const userId = resolveUserId(options.userId ?? this.userId);
-    const projectId = resolveProjectId(options.projectId ?? this.projectId);
-    return uploadFile(
-      this.fetchImpl,
-      `${baseUrl}/api/v1/storage/upload/project/${encodeStorageSegment(userId)}/${encodeStorageSegment(projectId)}`,
-      file,
-      {
-        token: this.token,
-        headers: this.headers,
-        credentials: this.credentials,
-      },
-    );
-  }
-
-  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 uploadUser(file, options = {}) {
-  return defaultClient(options).uploadUser(file);
-}
-
-export async function uploadProject(file, options = {}) {
-  return defaultClient(options).uploadProject(file, options);
-}
-
-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({ environmentOverrideEnv: 'LICOS_DATABASE_ENVIRONMENT' });
+}
+
+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: 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,
+};