@kmlckj/licos-platform-sdk 0.1.0

package/README.md

@@ -0,0 +1,3 @@
+# @kmlckj/licos-platform-sdk
+
+Node.js SDK for LICOS platform storage upload, download, and preview APIs.

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@kmlckj/licos-platform-sdk",
+  "version": "0.1.0",
+  "description": "LICOS platform SDK for storage upload, download, and preview",
+  "author": "kmlckj",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,64 @@
+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 StorageClientOptions {
+  baseUrl?: string;
+  token?: string;
+  userId?: string;
+  projectId?: string;
+  fetch?: typeof fetch;
+}
+
+export interface UploadProjectOptions extends StorageClientOptions {
+  userId?: string;
+  projectId?: string;
+}
+
+export class PlatformSdkError extends Error {
+  status?: number;
+  code?: number;
+  details?: unknown;
+}
+
+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(filePath: string): Promise<UploadResult>;
+  uploadProject(filePath: string, options?: UploadProjectOptions): Promise<UploadResult>;
+  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 uploadUser(
+  filePath: string,
+  options?: StorageClientOptions,
+): Promise<UploadResult>;
+export function uploadProject(
+  filePath: string,
+  options?: UploadProjectOptions,
+): Promise<UploadResult>;
+export function download(
+  url: string,
+  outputPath: string,
+  options?: StorageClientOptions,
+): Promise<string>;

package/src/index.js

@@ -0,0 +1,178 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export class PlatformSdkError extends Error {
+  constructor(message, options = {}) {
+    super(message);
+    this.name = new.target.name;
+    this.status = options.status;
+    this.code = options.code;
+    this.details = options.details;
+  }
+}
+
+export class ConfigurationError extends PlatformSdkError {}
+export class ApiError extends PlatformSdkError {}
+
+function requireEnv(name) {
+  const value = process.env[name];
+  if (value) {
+    return value;
+  }
+  throw new ConfigurationError(`Missing required environment variable: ${name}`);
+}
+
+function normalizeBaseUrl(baseUrl) {
+  return (baseUrl ?? requireEnv('LICOS_API_BASE_URL')).replace(/\/+$/, '');
+}
+
+function resolveToken(token) {
+  return token ?? requireEnv('LICOS_USER_TOKEN');
+}
+
+function resolveUserId(userId) {
+  return userId ?? requireEnv('LICOS_USER_ID');
+}
+
+function resolveProjectId(projectId) {
+  return projectId ?? requireEnv('LICOS_PROJECT_ID');
+}
+
+function encodeStorageSegment(value) {
+  return encodeURIComponent(value);
+}
+
+function encodeObjectKey(value) {
+  return value.split('/').map(encodeStorageSegment).join('/');
+}
+
+function guessContentType(filePath) {
+  switch (path.extname(filePath).toLowerCase()) {
+    case '.txt':
+      return 'text/plain';
+    case '.json':
+      return 'application/json';
+    case '.pdf':
+      return 'application/pdf';
+    case '.png':
+      return 'image/png';
+    case '.jpg':
+    case '.jpeg':
+      return 'image/jpeg';
+    default:
+      return 'application/octet-stream';
+  }
+}
+
+async function readJsonEnvelope(response) {
+  let payload;
+  try {
+    payload = await response.json();
+  } catch (error) {
+    throw new ApiError('Platform API returned non-JSON response', {
+      status: response.status,
+      details: error instanceof Error ? error.message : String(error),
+    });
+  }
+
+  if (!response.ok || payload?.code !== 0) {
+    throw new ApiError(payload?.message ?? `Platform API failed: HTTP ${response.status}`, {
+      status: response.status,
+      code: payload?.code,
+      details: payload?.data ?? payload,
+    });
+  }
+  return payload.data;
+}
+
+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;
+  }
+
+  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(filePath) {
+    const baseUrl = normalizeBaseUrl(this.baseUrl);
+    return this.#upload(`${baseUrl}/api/v1/storage/upload/user`, filePath);
+  }
+
+  async uploadProject(filePath, options = {}) {
+    const baseUrl = normalizeBaseUrl(this.baseUrl);
+    const userId = resolveUserId(options.userId ?? this.userId);
+    const projectId = resolveProjectId(options.projectId ?? this.projectId);
+    return this.#upload(
+      `${baseUrl}/api/v1/storage/upload/project/${encodeStorageSegment(userId)}/${encodeStorageSegment(projectId)}`,
+      filePath,
+    );
+  }
+
+  async download(url, outputPath) {
+    const response = await this.fetchImpl(url, { method: 'GET' });
+    if (!response.ok) {
+      throw new ApiError(`Platform download failed: HTTP ${response.status}`, {
+        status: response.status,
+      });
+    }
+    const buffer = Buffer.from(await response.arrayBuffer());
+    await fs.mkdir(path.dirname(outputPath), { recursive: true });
+    await fs.writeFile(outputPath, buffer);
+    return outputPath;
+  }
+
+  async #upload(url, filePath) {
+    const token = resolveToken(this.token);
+    const fileBuffer = await fs.readFile(filePath);
+    const fileName = path.basename(filePath);
+    const formData = new FormData();
+    formData.append(
+      'file',
+      new Blob([fileBuffer], { type: guessContentType(filePath) }),
+      fileName,
+    );
+
+    const response = await this.fetchImpl(url, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${token}`,
+      },
+      body: formData,
+    });
+    return readJsonEnvelope(response);
+  }
+}
+
+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(filePath, options = {}) {
+  return defaultClient(options).uploadUser(filePath);
+}
+
+export async function uploadProject(filePath, options = {}) {
+  return defaultClient(options).uploadProject(filePath, options);
+}
+
+export async function download(url, outputPath, options = {}) {
+  return defaultClient(options).download(url, outputPath);
+}