target-supabase-sdk 0.1.0

package/src/file/file-manager.ts

@@ -0,0 +1,145 @@
+import type { FileDetails, FilePreview } from "./file.interface";
+
+const FILE_MANIFEST_VERSION = 1;
+const PREVIEW_MANIFEST_VERSION = 1;
+
+export class FileManagerError extends Error {
+    constructor(
+        message: string,
+        cause?: unknown
+    ) {
+        super(message, { cause });
+        this.name = "FileManagerError";
+    }
+}
+
+export interface CreatePreviewProps {
+    refTargetId: string;
+}
+
+function createPreviewV0(props: CreatePreviewProps): FilePreview {
+    return {
+        manifestVersion: PREVIEW_MANIFEST_VERSION,
+        refTargetId: props.refTargetId,
+    };
+}
+
+export interface CreateFileProps {
+    manifestVersion: 0
+    /** "abc.1" */
+    value: string;
+    filePath: string;
+    needParcel: boolean;
+}
+
+async function sha256Hex(buffer: ArrayBuffer): Promise<string> {
+    try {
+        const hashBuffer = await globalThis.crypto.subtle.digest("SHA-256", buffer);
+        const bytes = new Uint8Array(hashBuffer);
+        return Array.from(bytes)
+            .map((byte) => byte.toString(16).padStart(2, "0"))
+            .join("");
+    } catch (error) {
+        throw new FileManagerError("FileManager.sha256Hex: 計算文件 hash 失敗", error);
+    }
+}
+
+function isLikelyLocalPath(path: string): boolean {
+    // Windows: C:\foo\bar.txt / \\server\share ; POSIX absolute: /foo/bar
+    return /^[a-zA-Z]:[\\/]/.test(path) || path.startsWith("\\\\") || path.startsWith("/");
+}
+
+function isFetchableResource(path: string): boolean {
+    return /^(https?:|blob:|data:)/.test(path) || path.startsWith("./") || path.startsWith("../");
+}
+
+function getBaseName(path: string): string {
+    const parts = path.split(/[\\/]/).filter(Boolean);
+    return parts.at(-1) ?? "unknown";
+}
+
+async function readLocalFileByPicker(filePath: string): Promise<ArrayBuffer> {
+    try {
+        if (!("showOpenFilePicker" in globalThis) || typeof globalThis.showOpenFilePicker !== "function") {
+            throw new FileManagerError(
+                "FileManager.readLocalFileByPicker: 當前瀏覽器不支持 File System Access API",
+                { filePath }
+            );
+        }
+
+        const [handle] = await globalThis.showOpenFilePicker({
+            multiple: false,
+        });
+        const file = await handle.getFile();
+        const expectedName = getBaseName(filePath);
+        if (expectedName !== "unknown" && file.name !== expectedName) {
+            throw new FileManagerError(
+                "FileManager.readLocalFileByPicker: 選擇的文件與目標路徑不一致",
+                { expectedName, actualName: file.name, filePath }
+            );
+        }
+        return file.arrayBuffer();
+    } catch (error) {
+        throw new FileManagerError("FileManager.readLocalFileByPicker: 本地文件讀取失敗", error);
+    }
+}
+
+async function readFileBufferFromPath(filePath: string): Promise<ArrayBuffer> {
+    try {
+        if (isLikelyLocalPath(filePath) && !isFetchableResource(filePath)) {
+            return readLocalFileByPicker(filePath);
+        }
+
+        const response = await fetch(filePath);
+        if (!response.ok) {
+            throw new FileManagerError(
+                `FileManager.readFileBufferFromPath: 無法讀取文件內容 (${response.status})`,
+                { status: response.status, statusText: response.statusText, filePath }
+            );
+        }
+        return response.arrayBuffer();
+    } catch (error) {
+        throw new FileManagerError("FileManager.readFileBufferFromPath: 讀取文件失敗", error);
+    }
+}
+
+async function createFileV0(props: CreateFileProps): Promise<FileDetails> {
+    try {
+        const fileBuffer = await readFileBufferFromPath(props.filePath);
+        const contentHash = await sha256Hex(fileBuffer);
+
+        return {
+            manifestVersion: props.manifestVersion ?? FILE_MANIFEST_VERSION,
+            value: props.value,
+            // Hash file bytes directly so checksum can be verified by re-hashing the same content.
+            hash: contentHash,
+            preview: null,
+            url: props.needParcel ? null : props.filePath,
+            parcelId: null,
+        };
+    } catch (error) {
+        throw new FileManagerError("FileManager.createFile: 建立文件 metadata 失敗", error);
+    }
+}
+
+async function verifyFileHash(filePath: string, expectedHash: string): Promise<boolean> {
+    try {
+        const normalizedExpected = expectedHash.trim().toLowerCase();
+        const fileBuffer = await readFileBufferFromPath(filePath);
+        const actualHash = await sha256Hex(fileBuffer);
+        return actualHash === normalizedExpected;
+    } catch (error) {
+        throw new FileManagerError("FileManager.verifyFileHash: 文件 hash 驗證失敗", error);
+    }
+}
+
+const createFile = createFileV0;
+const createPreview = createPreviewV0;
+
+const FileManager = {
+    createFile,
+    createPreview,
+    verifyFileHash,
+};
+
+export default FileManager;

package/src/file/file.api.ts

@@ -0,0 +1,43 @@
+import { createTarget } from "../core.api";
+import { BaseValidator } from "../core.utils";
+import { File, CategoryFile, FileDetails } from "./file.interface";
+
+export interface PostFileCreatePayload {
+  name: File["name"];
+  value: File["value"];
+  category: File["category"];
+  details: FileDetails;
+}
+
+export class PostFileValidator extends BaseValidator<PostFileCreatePayload> {
+  protected requiredFields: (keyof PostFileCreatePayload)[] = ["name", "value", "category", "details"];
+  protected optionalFields: (keyof PostFileCreatePayload)[] = [];
+
+  constructor() {
+    super();
+    // Add custom
+    this.addCustomValidator((val) => {
+      return true;
+    });
+  }
+}
+
+
+
+export const postFileCreate = async (payload: PostFileCreatePayload) => {
+  return createTarget<File, PostFileCreatePayload>({
+    payload: payload,
+    validator: PostFileValidator,
+    createFn: (validPayload) => {
+      const { name, value, category, details } = validPayload;
+
+      return {
+        name,
+        category,
+        value,
+        tagList: [],
+        details,
+      };
+    },
+  });
+};

package/src/file/file.interface.ts

@@ -0,0 +1,30 @@
+import { Target } from "../core.interface";
+
+export enum CategoryFile {
+  VIDEO = "video",
+  IMAGE = "image",
+  TEXT = "text",
+}
+
+export interface File extends Target {
+  details: FileDetails;
+  category: CategoryFile;
+}
+
+export interface FileDetails {
+  manifestVersion: number;
+  /** "abc.1" 唯一键 */
+  value: string;
+  hash: string | null;
+  preview: FilePreview | null;
+  /** Quickly access the file */
+  url: string | null;
+  parcelId: string | null;
+  /** TODO 消費與改動歷史 */
+  // reviewList?: string[];
+};
+
+export interface FilePreview {
+  manifestVersion: number;
+  refTargetId: string;
+};

package/src/file-list/file-list.api.ts

@@ -0,0 +1,64 @@
+import { createTarget } from "../core.api";
+import { BaseValidator } from "../core.utils";
+import { FileList, CategoryFileList, FileListDetails } from "./file-list.interface";
+
+export class PostCreateFileListValidator extends BaseValidator<PostCreateFileListPayload> {
+  protected requiredFields: (keyof PostCreateFileListPayload)[] = ["name", "dirName", "dirSize", "storageUrl"];
+  protected optionalFields: (keyof PostCreateFileListPayload)[] = [];
+
+  constructor() {
+    super();
+    // Add custom
+    this.addValidator((val) => {
+      return true;
+    });
+  }
+}
+
+export interface PostCreateFileListPayload {
+  name: FileListDetails["name"];
+  dirName: FileListDetails["dirName"];
+  dirSize: FileListDetails["dirSize"];
+  storageUrl: FileListDetails["storageUrl"];
+}
+
+export const postCreateFileList = async (payload: PostCreateFileListPayload) => {
+  return createTarget<FileList, PostCreateFileListPayload>({
+    payload: payload,
+    validator: PostCreateFileListValidator,
+    checkRedundancyFilterList: [
+      {
+        field: "category",
+        operator: "eq",
+        value: CategoryFileList.FILE_LIST,
+      },
+      {
+        field: "details->>dirName",
+        operator: "eq",
+        value: payload.dirName,
+      },
+      {
+        field: "details->>storageUrl",
+        operator: "eq",
+        value: payload.storageUrl,
+      },
+    ],
+    createFn: (validPayload) => {
+      const { name, dirName, dirSize, storageUrl = "" } = validPayload;
+      const details: FileListDetails = {
+        name,
+        dirName,
+        dirSize,
+        storageUrl,
+      };
+
+      return {
+        name: validPayload.name,
+        category: CategoryFileList.FILE_LIST,
+        value: dirName,
+        tagList: [],
+        details,
+      };
+    },
+  });
+};

package/src/file-list/file-list.interface.ts

@@ -0,0 +1,24 @@
+import { Target } from "../core.interface";
+
+/**
+ * Use storageUrl+dirName to identify the file list
+ * You can iterate all files in the directory
+ */
+export type FileListDetails = {
+  /** Human readable name, should be same to Target.name */
+  name: string;
+  /** unique path */
+  dirName: string;
+  dirSize: number;
+  /** where to store the file list */
+  storageUrl: string;
+};
+
+export enum CategoryFileList {
+  FILE_LIST = "file-list",
+}
+
+export interface FileList extends Target {
+  details: FileListDetails;
+  category: CategoryFileList;
+}

package/src/idea/idea.interface.ts

@@ -0,0 +1,28 @@
+import { Target } from "../core.interface";
+
+export enum CategoryIdea {
+    OPPORTUNITY = "opportunity",
+}
+
+export interface Idea extends Target {
+    /** 主題 */
+    value: string;
+    details: IdeaDetails;
+    category: CategoryIdea;
+}
+
+export interface IdeaDetails {
+    manifestVersion: number;
+    marketList: Market[];
+    reviewList: string[];
+    /** 切入點 */
+    point: string;
+};
+
+export enum Market {
+    NA = "NA",
+    EU = "EU",
+    JP = "JP",
+    CN = "CN",
+    TW = "TW",
+};

package/src/index.ts

@@ -0,0 +1,50 @@
+export { SupabaseInitializer } from "./supabase";
+export type { SupabaseInitializerParams } from "./supabase";
+export type { SupabaseClient } from "@supabase/supabase-js";
+
+import { SupabaseInitializer } from "./supabase";
+
+export const supabase = SupabaseInitializer.getInstance();
+
+export * from "./core.api";
+export * from "./core.interface";
+export * from "./core.utils";
+
+export * from "./auth/auth.api";
+
+export * from "./feed/feed.interface";
+export * from "./idea/idea.interface";
+export * from "./link/link.interface";
+
+export { CategoryParcel } from "./parcel/parcel.interface";
+export type {
+  Parcel,
+  ParcelDetails,
+  Chunk,
+  LifecycleStatus as ParcelLifecycleStatus,
+  Lifecycle as ParcelLifecycle,
+} from "./parcel/parcel.interface";
+export { default as ParcelManager } from "./parcel/parcel-manager";
+
+export * from "./file/file.interface";
+export * from "./file/file.api";
+export * from "./file/file-manager";
+
+export * from "./file-list/file-list.interface";
+export * from "./file-list/file-list.api";
+
+export * from "./question-list/question-list.interface";
+export * from "./question-list/question-list.api";
+
+export * from "./review/review.interface";
+export * from "./review/review.api";
+
+export type { ReviewV2, ReviewV2Details, ReviewResult } from "./review-v2/review.interface";
+export * from "./review-v2/review-setting.interface";
+export { postReview as postReviewV2, PostReviewValidator as PostReviewV2Validator } from "./review-v2/apis/post-review.api";
+export type { PostReviewPayload as PostReviewV2Payload } from "./review-v2/apis/post-review.api";
+export * from "./review-v2/apis/post-review-setting.api";
+
+export * from "./service/base.interface";
+export * from "./service/service.interface";
+export * from "./service/api.interface";

package/src/link/link.interface.ts

@@ -0,0 +1,21 @@
+import { Target } from "../core.interface";
+
+export enum CategoryLink {
+    LINK = "link",
+}
+
+export interface Link extends Target {
+    /** 鏈接名稱 */
+    name: string;
+    /** URL */
+    value: string;
+    details: LinkDetails;
+    category: CategoryLink;
+}
+
+export interface LinkDetails {
+    manifestVersion: number;
+    description: string;
+    iconUrl: string;
+};
+

package/src/parcel/parcel-manager.ts

@@ -0,0 +1,209 @@
+import type { Chunk, Parcel, ParcelDetails } from "./parcel.interface";
+
+const MANIFEST_VERSION = 1;
+const DEFAULT_CHUNK_SIZE = 256 * 1024; // 256KB
+const AES_GCM_IV_LENGTH = 12;
+const AES_GCM_TAG_LENGTH = 128;
+
+/** IV 存在 Parcel.extra 中的 JSON 键 */
+const EXTRA_IV_KEY = "iv";
+
+/** 可插拔的存储适配器：不同文件系统 */
+interface StorageAdapter {
+  /** 上传一段数据，返回可下载的 URL */
+  upload(data: ArrayBuffer, pathOrKey: string): Promise<{ url: string }>;
+}
+
+interface CreateOptions {
+  /** 每个 chunk 的字节数，默认 256KB */
+  chunkSize?: number;
+  /** AES-GCM 加密密钥；不传则生成并返回 */
+  key?: CryptoKey;
+}
+
+interface CreateResult {
+  /** 元数据，chunk 的 url 由 save 填充 */
+  details: ParcelDetails;
+  /** 已加密的 chunk 数据，供 save 上传 */
+  chunks: ArrayBuffer[];
+  /** Base64 编码的 IV，需在 save 时写入 Parcel.extra 供 reassembly 使用 */
+  ivBase64: string;
+  /** 若 create 时未传 key，则返回此处，调用方需妥善保存 */
+  key?: CryptoKey;
+}
+
+/** 调用方提供的 Target 基础字段，用于拼成完整 Parcel */
+type ParcelTargetBase = Pick<Parcel, "id" | "category" | "name" | "value" | "tagList" | "created_at">;
+
+function getCrypto(): Crypto {
+  if (typeof globalThis !== "undefined" && globalThis.crypto) return globalThis.crypto;
+  throw new Error("ParcelManager: crypto not available");
+}
+
+/** 计算 ArrayBuffer 的 SHA-256，返回 hex 字符串 */
+async function sha256Hex(buffer: ArrayBuffer): Promise<string> {
+  const crypto = getCrypto();
+  const hash = await crypto.subtle.digest("SHA-256", buffer);
+  return Array.from(new Uint8Array(hash))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+/** AES-GCM 加密 */
+async function encrypt(data: ArrayBuffer, key: CryptoKey, iv: Uint8Array): Promise<ArrayBuffer> {
+  const crypto = getCrypto();
+  const ivCopy = new Uint8Array(iv);
+  return crypto.subtle.encrypt({ name: "AES-GCM", iv: ivCopy, tagLength: AES_GCM_TAG_LENGTH }, key, data);
+}
+
+/** AES-GCM 解密 */
+async function decrypt(data: ArrayBuffer, key: CryptoKey, iv: Uint8Array): Promise<ArrayBuffer> {
+  const crypto = getCrypto();
+  const ivCopy = new Uint8Array(iv);
+  return crypto.subtle.decrypt({ name: "AES-GCM", iv: ivCopy, tagLength: AES_GCM_TAG_LENGTH }, key, data);
+}
+
+/** 生成 AES-GCM 密钥（256 位） */
+async function generateKey(): Promise<CryptoKey> {
+  const crypto = getCrypto();
+  return crypto.subtle.generateKey({ name: "AES-GCM", length: 256 }, true, ["encrypt", "decrypt"]);
+}
+
+/** 将文件加密后拆分成多个 chunk */
+async function create(file: ArrayBuffer, options: CreateOptions = {}): Promise<CreateResult> {
+  const chunkSize = options.chunkSize ?? DEFAULT_CHUNK_SIZE;
+  let key = options.key;
+  const generatedKey = !key;
+  if (!key) key = await generateKey();
+
+  const crypto = getCrypto();
+  const iv = crypto.getRandomValues(new Uint8Array(AES_GCM_IV_LENGTH));
+
+  const encrypted = await encrypt(file, key, iv);
+  const totalSize = encrypted.byteLength;
+
+  const chunks: ArrayBuffer[] = [];
+  const chunkList: Chunk[] = [];
+  let offset = 0;
+  let index = 0;
+
+  while (offset < totalSize) {
+    const end = Math.min(offset + chunkSize, totalSize);
+    const chunkBuffer = encrypted.slice(offset, end);
+    chunks.push(chunkBuffer);
+    const checksum = await sha256Hex(chunkBuffer);
+    chunkList.push({
+      index,
+      size: chunkBuffer.byteLength,
+      checksum,
+      url: "", // 由 save 填充
+    });
+    offset = end;
+    index += 1;
+  }
+
+  const checksum = await sha256Hex(file);
+
+  const details: ParcelDetails = {
+    manifestVersion: MANIFEST_VERSION,
+    chunkList: chunkList,
+    checksum,
+    size: file.byteLength,
+  };
+
+  const result: CreateResult = {
+    details,
+    chunks,
+    ivBase64: btoa(String.fromCharCode(...iv)),
+  };
+  if (generatedKey) result.key = key;
+  return result;
+}
+
+/** 将 chunk 均匀分布到不同文件系统并存储 */
+async function save(
+  createResult: CreateResult,
+  fileSystems: StorageAdapter[],
+  targetBase: ParcelTargetBase
+): Promise<Parcel> {
+  if (fileSystems.length === 0) throw new Error("ParcelManager.save: fileSystems 不能为空");
+  const { details, chunks, ivBase64 } = createResult;
+
+  const chunkListWithUrls: Chunk[] = [];
+  for (let i = 0; i < chunks.length; i++) {
+    const fs = fileSystems[i % fileSystems.length];
+    const pathOrKey = `chunk-${i}-${details.checksum.slice(0, 8)}`;
+    const { url } = await fs.upload(chunks[i], pathOrKey);
+    chunkListWithUrls.push({ ...details.chunkList[i], url });
+  }
+
+  const extra = JSON.stringify({ [EXTRA_IV_KEY]: ivBase64 });
+
+  return {
+    ...targetBase,
+    category: "parcel" as Parcel["category"],
+    details: {
+      ...details,
+      chunkList: chunkListWithUrls,
+    },
+    extra,
+  };
+}
+
+/** 根据 Parcel 下载各 chunk，重组并校验后返回原文件 */
+async function reassembly(parcel: Parcel, key: CryptoKey): Promise<ArrayBuffer> {
+  const { details } = parcel;
+  let ivBase64: string | undefined;
+  try {
+    const extra = parcel.extra ? JSON.parse(parcel.extra) : {};
+    ivBase64 = extra[EXTRA_IV_KEY];
+  } catch {
+    throw new Error("ParcelManager.reassembly: 无法从 extra 解析 IV");
+  }
+  if (!ivBase64 || typeof ivBase64 !== "string") {
+    throw new Error("ParcelManager.reassembly: Parcel.extra 中缺少 iv");
+  }
+
+  const iv = Uint8Array.from(atob(ivBase64), (c) => c.charCodeAt(0));
+  if (iv.length !== AES_GCM_IV_LENGTH) {
+    throw new Error("ParcelManager.reassembly: IV 长度无效");
+  }
+
+  const sortedChunks = [...details.chunkList].sort((a, b) => a.index - b.index);
+  const buffers: ArrayBuffer[] = [];
+
+  for (const chunkMeta of sortedChunks) {
+    const res = await fetch(chunkMeta.url);
+    if (!res.ok) throw new Error(`ParcelManager.reassembly: 下载 chunk ${chunkMeta.index} 失败: ${res.status}`);
+    const chunkBuffer = await res.arrayBuffer();
+    const chunkChecksum = await sha256Hex(chunkBuffer);
+    if (chunkChecksum !== chunkMeta.checksum) {
+      throw new Error(`ParcelManager.reassembly: chunk ${chunkMeta.index} 校验失败 (checksum 不一致)`);
+    }
+    buffers.push(chunkBuffer);
+  }
+
+  const totalEncryptedLength = buffers.reduce((s, b) => s + b.byteLength, 0);
+  const encrypted = new Uint8Array(totalEncryptedLength);
+  let offset = 0;
+  for (const b of buffers) {
+    encrypted.set(new Uint8Array(b), offset);
+    offset += b.byteLength;
+  }
+
+  const decrypted = await decrypt(encrypted.buffer, key, iv);
+  const fileChecksum = await sha256Hex(decrypted);
+  if (fileChecksum !== details.checksum) {
+    throw new Error("ParcelManager.reassembly: 重组后文件校验失败 (sha256 与 details.checksum 不一致)");
+  }
+
+  return decrypted;
+}
+
+const ParcelManager = {
+  create,
+  save,
+  reassembly,
+};
+
+export default ParcelManager;

package/src/parcel/parcel.interface.ts

@@ -0,0 +1,40 @@
+import { Target } from "../core.interface";
+
+export interface Parcel extends Target {
+  category: CategoryParcel;
+  details: ParcelDetails;
+}
+
+export enum CategoryParcel {
+  PARCEL = "parcel",
+}
+
+export interface ParcelDetails {
+  manifestVersion: number;
+  chunkList: Chunk[];
+  /** sha256 */
+  checksum: string;
+  size: number;
+}
+
+export enum LifecycleStatus {
+  STORED = "STORED",
+  SOFT_DELETED = "SOFT_DELETED",
+  HARD_DELETED = "HARD_DELETED",
+}
+
+export interface Lifecycle {
+  status: LifecycleStatus;
+  storedAt: string;
+  softDeletedAt: string | null;
+  hardDeletedAt: string | null;
+}
+
+export interface Chunk {
+  index: number;
+  /** TODO Storage service provider */
+  // shardKey: string;
+  size: number;
+  checksum: string;
+  url: string;
+}