@suphark/files-client 0.0.0-stage → 0.3.0

package/README.md

@@ -1,3 +1,98 @@
-# Temporary Holding Version
+# @suphark/files-client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+SDK ของ Pi Files (`files.suphark.com`) สำหรับ Next.js/React — ไม่มี runtime dependency
+
+```bash
+pnpm add @suphark/files-client
+```
+
+## 1. server client (`@suphark/files-client`)
+
+```ts
+import { createPiFiles } from "@suphark/files-client";
+
+export const piFiles = createPiFiles({
+  baseUrl: process.env.PI_FILES_URL!, // https://files.suphark.com
+  appKey: process.env.PI_FILES_APP_KEY!, // pfk_… (ownerType APP)
+});
+
+// อัปโหลดจาก server (Buffer/Blob) ครบวงจร
+const file = await piFiles.upload(buffer, {
+  filename: "รายงาน.pdf",
+  mimeType: "application/pdf",
+  sizeBytes: buffer.byteLength,
+  featureKey: "REPORT",
+  reference: { featureKey: "REPORT", entityType: "Project", entityId: "p1", role: "main" },
+});
+
+await piFiles.references.attach(file.id, {
+  featureKey: "REPORT",
+  entityType: "Project",
+  entityId: "p2",
+  role: "copy",
+});
+const mine = await piFiles.references.byEntity("Project", "p1");
+const { url } = await piFiles.files.contentUrl(file.id, { download: true }); // presigned อายุสั้น
+await piFiles.files.delete(file.id); // 409 FILE_REFERENCED ถ้ายังมี reference
+```
+
+`piFiles.withUser(accessToken)` → client เดียวกันแต่ใช้ Pi Auth JWT ของผู้ใช้ (ไฟล์ `ownerType USER`)
+
+### linked source (โฟลเดอร์ Google Drive เดิม) — 0.3.0
+
+```ts
+const src = await piFiles.sources.link({ folder: "https://drive.google.com/drive/folders/<id>" });
+const tree = await piFiles.folders.contents(src.folderId, { recursive: true }); // relativePath, md5, modifiedTime, providerFileId
+const set = await piFiles.folders.ensurePath(src.folderId, ["01_Docs", "ชุด A"]); // สร้างใน Drive จริง
+const access = await piFiles.files.access(fileId); // ใครเปิดได้ใน Drive + ทำลิงก์สาธารณะได้ไหม
+```
+webhook `file.created|updated|moved|deleted|missing`, `folder.*` มี `source.ancestorFolderIds` — ดู `docs/guides/connect-app.md` §6.1
+
+## 2. Next.js route handlers (`@suphark/files-client/next`)
+
+```ts
+// src/lib/pi-files.ts
+import { createPiFiles, createPiFilesNext } from "@suphark/files-client/next";
+export const piFiles = createPiFiles({ baseUrl, appKey });
+export const piFilesNext = createPiFilesNext({ client: piFiles });
+
+// app/api/files/uploads/[[...path]]/route.ts — proxy อัปโหลด (browser ไม่ถือ key)
+export const { POST, DELETE } = piFilesNext.handlers.uploads({
+  authorize: async (request, action) => {
+    const user = await piAuth.getCurrentUser();
+    if (!user) return null;                       // 401
+    if (action.kind !== "create") return {};
+    return { input: { featureKey: "REPORT", onBehalfOfUserId: user.id, reference: {...} } };
+  },
+});
+
+// app/api/files/[id]/content/route.ts — URL same-origin ที่ browser ใช้
+export const GET = piFilesNext.handlers.content({
+  strategy: "redirect",                           // หรือ "stream" (Range passthrough)
+  resolve: async (request, params) => {
+    const user = await piAuth.getCurrentUser();
+    if (!user) return new Response(null, { status: 401 });
+    if (!(await canView(user, params.id))) return null; // 404
+    return { fileId: String(params.id), download: request.url.includes("download=1") };
+  },
+});
+```
+
+## 3. React (`@suphark/files-client/react`)
+
+```tsx
+"use client";
+import { useUpload, useUploadQueue } from "@suphark/files-client/react";
+
+const { upload, cancel, status, progress, error } = useUpload({ endpoint: "/api/files/uploads" });
+await upload(file); // single PUT หรือ multipart (8 MiB/part, 3 ขนาน, resume หลัง refresh)
+
+const { items, enqueue, cancel } = useUploadQueue({ endpoint: "/api/files/uploads", parallel: 2 });
+enqueue(files);
+```
+
+`endpoint` มีรูปแบบเดียวกับ `/api/v1/uploads` ของ Pi Files: `POST` (ticket), `POST /:id/parts`, `POST /:id/complete`, `DELETE /:id`
+
+## Errors
+
+ทุก method โยน `PiFilesError { status, code, message, problem }` — code เช่น `UNAUTHENTICATED`, `PERMISSION_DENIED`, `NOT_FOUND`, `QUOTA_EXCEEDED`, `UNSUPPORTED_MEDIA_TYPE`, `PAYLOAD_TOO_LARGE`, `FILE_REFERENCED`, `SIZE_MISMATCH`, `UPLOAD_INCOMPLETE`, `ABORTED`

package/dist/chunk-5VLU7KXC.js

@@ -0,0 +1,169 @@
+import {
+  performUpload,
+  request
+} from "./chunk-YZSJOMM6.js";
+
+// src/core/client.ts
+var q = (o) => o ?? {};
+function createPiFiles(options) {
+  const o = options;
+  const call = (path, init) => request(o, path, init);
+  const uploads = {
+    create: (input) => call("/api/v1/uploads", { method: "POST", body: input }),
+    partUrls: (uploadId, partNumbers) => call(`/api/v1/uploads/${uploadId}/parts`, {
+      method: "POST",
+      body: { partNumbers }
+    }),
+    complete: (uploadId, parts) => call(`/api/v1/uploads/${uploadId}/complete`, {
+      method: "POST",
+      body: { parts }
+    }),
+    abort: (uploadId) => call(`/api/v1/uploads/${uploadId}`, { method: "DELETE" })
+  };
+  const uploadApi = {
+    partUrls: uploads.partUrls,
+    complete: uploads.complete,
+    abort: uploads.abort
+  };
+  const files = {
+    get: (id) => call(`/api/v1/files/${id}`),
+    /** ตำแหน่งจริง + สิทธิ์ที่ต้นทาง (Google Drive) + แชร์สาธารณะได้ไหม — ใช้ตอบ "ไฟล์นี้ส่งให้ใครได้บ้าง" */
+    access: (id) => call(`/api/v1/files/${id}/access`),
+    list: (query) => call("/api/v1/files", {
+      query: q(query)
+    }),
+    search: (query) => call("/api/v1/search", {
+      query: q(query)
+    }),
+    update: (id, patch) => call(`/api/v1/files/${id}`, { method: "PATCH", body: patch }),
+    trash: (id) => call(`/api/v1/files/${id}`, { method: "DELETE" }),
+    delete: (id) => call(`/api/v1/files/${id}`, { method: "DELETE", query: { permanent: 1 } }),
+    restore: (id) => call(`/api/v1/files/${id}/restore`, { method: "POST" }),
+    batch: (input) => call("/api/v1/files/batch", { method: "POST", body: input }),
+    /** URL ที่ browser ใช้ได้ทันที (อายุสั้น) — server ของ consumer เรียกแล้วส่งต่อ/redirect */
+    contentUrl: (id, opts = {}) => call(`/api/v1/files/${id}/content`, {
+      query: { mode: "url", download: opts.download ? 1 : void 0, ttl: opts.ttl }
+    }),
+    /** stream ผ่าน Pi Files (รองรับ Range) — คืน Response ดิบให้ proxy ต่อ */
+    stream: (id, opts = {}) => call(`/api/v1/files/${id}/content`, {
+      raw: true,
+      query: { mode: "stream", download: opts.download ? 1 : void 0 },
+      headers: opts.range ? { range: opts.range } : void 0,
+      signal: opts.signal
+    }),
+    /** path relative ต่อ baseUrl สำหรับ mode=redirect (ใช้ในลิงก์ที่ browser มี token/cookie ของ Pi Files) */
+    contentPath: (id, opts = {}) => `/api/v1/files/${id}/content${opts.download ? "?download=1" : ""}`,
+    /**
+     * ภาพตัวอย่าง webp (sm 256px / lg 1024px) แบบ stream — ใช้ฝั่ง server ของ consumer
+     * ฝั่ง browser ของ consumer ใช้ `handlers.preview` ของ `/next`; ไฟล์ที่ไม่มีตัวอย่าง (`previewPath` null) ตอบ 404
+     */
+    preview: (id, opts = {}) => call(`/api/v1/files/${id}/preview`, {
+      raw: true,
+      query: { size: opts.size },
+      signal: opts.signal
+    }),
+    /** ticket สำหรับอัปโหลดเนื้อหาใหม่ทับไฟล์เดิม (id/ชื่อ/แชร์/reference คงเดิม) — ใช้ `replace()` ครบวงจรแทนได้ */
+    replace: (id, input) => call(`/api/v1/files/${id}/replace`, { method: "POST", body: input }),
+    /** ฉบับปัจจุบัน + เวอร์ชันเก่า (ใหม่ → เก่า) */
+    versions: (id) => call(`/api/v1/files/${id}/versions`),
+    /** เวอร์ชันเก่ากลับมาเป็นฉบับปัจจุบัน (ฉบับปัจจุบันเดิมเก็บเป็นประวัติ) */
+    restoreVersion: (id, versionNo) => call(`/api/v1/files/${id}/versions/${versionNo}/restore`, { method: "POST" }),
+    deleteVersion: (id, versionNo) => call(`/api/v1/files/${id}/versions/${versionNo}`, { method: "DELETE" }),
+    versionContentUrl: (id, versionNo, opts = {}) => call(`/api/v1/files/${id}/versions/${versionNo}/content`, {
+      query: { mode: "url", download: opts.download ? 1 : void 0, ttl: opts.ttl }
+    })
+  };
+  const references = {
+    attach: (fileId, ref) => call(`/api/v1/files/${fileId}/references`, { method: "POST", body: ref }),
+    detach: (fileId, ref) => call(`/api/v1/files/${fileId}/references`, {
+      method: "DELETE",
+      body: ref
+    }),
+    listOf: (fileId) => call(`/api/v1/files/${fileId}/references`),
+    /** ย้าย reference แบบ atomic เช่น draft → ระเบียนจริง (ไฟล์ไม่กลายเป็นกำพร้าระหว่างทาง) */
+    move: (fileId, from, to) => call(`/api/v1/files/${fileId}/references/move`, {
+      method: "POST",
+      body: { from, to }
+    }),
+    byEntity: (entityType, entityId, featureKey) => call("/api/v1/references", {
+      query: { entityType, entityId, featureKey }
+    })
+  };
+  const grant = (fileId, input = {}) => call(`/api/v1/files/${fileId}/grants`, { method: "POST", body: input });
+  const manifest = {
+    sync: (input) => call("/api/v1/app/manifest", { method: "PUT", body: input })
+  };
+  const migration = {
+    /** รับ object ที่มีอยู่แล้วใน bucket เข้าทะเบียน ณ ที่เดิม (ไม่คัดลอก) — idempotent ด้วย externalSource+externalId */
+    adopt: (input) => call("/api/v1/migration/adopt", { method: "POST", body: input })
+  };
+  const folders = {
+    get: (id = "root") => call(`/api/v1/folders/${id}`),
+    tree: (root, depth) => call("/api/v1/folders/tree", { query: { root, depth } }),
+    create: (input) => call("/api/v1/folders", { method: "POST", body: input }),
+    update: (id, patch) => call(`/api/v1/folders/${id}`, { method: "PATCH", body: patch }),
+    trash: (id) => call(`/api/v1/folders/${id}`, { method: "DELETE" }),
+    restore: (id) => call(`/api/v1/folders/${id}/restore`, { method: "POST" }),
+    /** ไฟล์ + โฟลเดอร์ใต้โฟลเดอร์ (recursive) พร้อม relativePath/md5/modifiedTime/providerFileId — ใช้ทำ fingerprint */
+    contents: (id, opts = {}) => call(`/api/v1/folders/${id}/contents`, {
+      query: { recursive: opts.recursive ? "1" : void 0 }
+    }),
+    /** หา/สร้างโฟลเดอร์ตามชื่อ (ใต้ linked source = สร้างใน Google Drive จริง) */
+    ensurePath: (id, names) => call(`/api/v1/folders/${id}/ensure-path`, { method: "POST", body: { names } })
+  };
+  const sources = {
+    /** ผูก (idempotent — ผูกซ้ำ = source เดิม) แล้ว sync ทั้งต้นทันที */
+    link: (input) => call("/api/v1/sources", { method: "POST", body: input }),
+    list: () => call("/api/v1/sources"),
+    get: (id) => call(`/api/v1/sources/${id}`),
+    /** sync ทั้งต้นตอนนี้ (ปกติ Pi Files ตามการเปลี่ยนแปลงใน Drive ให้ทุก 5 นาที + webhook) */
+    sync: (id) => call(`/api/v1/sources/${id}/sync`, { method: "POST" }),
+    /** เลิกผูก — ไม่แตะ Google Drive; ไฟล์ที่ยังมี reference = 409 SOURCE_REFERENCED */
+    unlink: (id) => call(`/api/v1/sources/${id}`, {
+      method: "DELETE"
+    })
+  };
+  const quota = {
+    get: (scope = "user") => call("/api/v1/quota", { query: { scope } })
+  };
+  async function upload(source, input, opts = {}) {
+    const ticket = await uploads.create(input);
+    try {
+      return await performUpload(uploadApi, ticket, source, input.mimeType, opts);
+    } catch (error) {
+      await uploads.abort(ticket.uploadId).catch(() => {
+      });
+      throw error;
+    }
+  }
+  async function replace(fileId, source, input, opts = {}) {
+    const ticket = await files.replace(fileId, input);
+    try {
+      return await performUpload(uploadApi, ticket, source, input.mimeType, opts);
+    } catch (error) {
+      await uploads.abort(ticket.uploadId).catch(() => {
+      });
+      throw error;
+    }
+  }
+  return {
+    options: o,
+    uploads,
+    uploadApi,
+    upload,
+    replace,
+    files: { ...files, grant },
+    references,
+    folders,
+    sources,
+    quota,
+    manifest,
+    migration,
+    /** client เดิมแต่ใช้ token ของผู้ใช้แทน appKey (user-context ต่อ request) */
+    withUser: (token) => createPiFiles({ ...o, getUserToken: () => token })
+  };
+}
+
+export {
+  createPiFiles
+};

package/dist/chunk-YZSJOMM6.js

@@ -0,0 +1,225 @@
+// src/core/http.ts
+var PiFilesError = class extends Error {
+  constructor(status, code, message, problem) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.problem = problem;
+    this.name = "PiFilesError";
+  }
+  status;
+  code;
+  problem;
+};
+async function resolveAuthHeader(opts) {
+  const token = opts.getUserToken ? await opts.getUserToken() : null;
+  if (token) return { authorization: `Bearer ${token}` };
+  if (opts.appKey) return { authorization: `Bearer ${opts.appKey}` };
+  return {};
+}
+function buildUrl(baseUrl, path, query) {
+  const url = new URL(path.replace(/^\//, ""), `${baseUrl.replace(/\/?$/, "/")}`);
+  for (const [k, v] of Object.entries(query ?? {})) {
+    if (v !== void 0) url.searchParams.set(k, String(v));
+  }
+  return url.toString();
+}
+var MAX_RATE_LIMIT_RETRIES = 3;
+var MAX_RETRY_WAIT_MS = 3e4;
+async function fetchWithRateLimitRetry(doFetch, url, init) {
+  for (let attempt = 0; ; attempt++) {
+    const res = await doFetch(url, init);
+    if (res.status !== 429 || attempt >= MAX_RATE_LIMIT_RETRIES) return res;
+    const waitMs = Math.min(MAX_RETRY_WAIT_MS, await retryAfterSeconds(res) * 1e3);
+    await sleep(waitMs, init.signal ?? void 0);
+  }
+}
+async function retryAfterSeconds(res) {
+  const header = Number(res.headers.get("retry-after"));
+  if (header > 0) return header;
+  const body = await res.json().catch(() => null);
+  return body?.retryAfterSeconds && body.retryAfterSeconds > 0 ? body.retryAfterSeconds : 2;
+}
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(signal.reason);
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        reject(signal.reason);
+      },
+      { once: true }
+    );
+  });
+}
+async function parseProblem(res) {
+  let problem;
+  try {
+    const json = await res.json();
+    if (json && typeof json === "object" && "status" in json) problem = json;
+  } catch {
+  }
+  return new PiFilesError(
+    res.status,
+    problem?.code ?? `HTTP_${res.status}`,
+    problem?.detail ?? problem?.title ?? `Pi Files \u0E15\u0E2D\u0E1A ${res.status}`,
+    problem
+  );
+}
+async function request(opts, path, init = {}) {
+  const doFetch = opts.fetch ?? fetch;
+  const headers = {
+    accept: "application/json",
+    ...await resolveAuthHeader(opts),
+    ...init.headers ?? {}
+  };
+  if (init.body !== void 0) headers["content-type"] = "application/json";
+  const res = await fetchWithRateLimitRetry(doFetch, buildUrl(opts.baseUrl, path, init.query), {
+    method: init.method ?? "GET",
+    headers,
+    body: init.body === void 0 ? void 0 : JSON.stringify(init.body),
+    signal: init.signal,
+    credentials: opts.credentials,
+    redirect: init.manualRedirect ? "manual" : "follow",
+    cache: "no-store"
+  });
+  if (init.raw) return res;
+  if (!res.ok) throw await parseProblem(res);
+  if (res.status === 204) return void 0;
+  const text = await res.text();
+  return text ? JSON.parse(text) : null;
+}
+
+// src/core/upload.ts
+function toBlob(source, type) {
+  if (source instanceof Blob) return source;
+  const bytes = source instanceof ArrayBuffer ? new Uint8Array(source) : source;
+  return new Blob([bytes], { type });
+}
+function hasXhr() {
+  return typeof XMLHttpRequest !== "undefined";
+}
+function etagFromBody(text) {
+  try {
+    const parsed = JSON.parse(text);
+    return typeof parsed.etag === "string" ? parsed.etag : null;
+  } catch {
+    return null;
+  }
+}
+function putBytes(url, body, headers, onProgress, signal, method = "PUT") {
+  if (!hasXhr()) {
+    return fetch(url, { method, headers, body, signal }).then(async (res) => {
+      if (!res.ok)
+        throw new PiFilesError(res.status, "STORAGE_PUT_FAILED", `storage \u0E15\u0E2D\u0E1A ${res.status}`);
+      onProgress(body.size);
+      return { etag: res.headers.get("etag") ?? etagFromBody(await res.text()) };
+    });
+  }
+  return new Promise((resolve, reject) => {
+    const xhr = new XMLHttpRequest();
+    xhr.open(method, url);
+    for (const [k, v] of Object.entries(headers)) xhr.setRequestHeader(k, v);
+    xhr.upload.onprogress = (e) => onProgress(e.loaded);
+    xhr.onload = () => {
+      if (xhr.status >= 200 && xhr.status < 300) {
+        resolve({ etag: xhr.getResponseHeader("ETag") ?? etagFromBody(xhr.responseText) });
+      } else
+        reject(new PiFilesError(xhr.status, "STORAGE_PUT_FAILED", `storage \u0E15\u0E2D\u0E1A ${xhr.status}`));
+    };
+    xhr.onerror = () => reject(new PiFilesError(0, "NETWORK", "\u0E2D\u0E31\u0E1B\u0E42\u0E2B\u0E25\u0E14\u0E44\u0E1B storage \u0E44\u0E21\u0E48\u0E2A\u0E33\u0E40\u0E23\u0E47\u0E08 (\u0E15\u0E23\u0E27\u0E08 CORS \u0E02\u0E2D\u0E07 bucket)"));
+    xhr.onabort = () => reject(new PiFilesError(0, "ABORTED", "\u0E22\u0E01\u0E40\u0E25\u0E34\u0E01"));
+    signal?.addEventListener("abort", () => xhr.abort(), { once: true });
+    xhr.send(body);
+  });
+}
+async function performUpload(api, ticket, source, mimeType, options = {}) {
+  const blob = toBlob(source, mimeType);
+  const total = blob.size;
+  const report = (loaded) => options.onProgress?.({ loaded, total, fraction: total ? Math.min(loaded / total, 1) : 1 });
+  if (ticket.kind === "put") {
+    await putBytes(ticket.url, blob, ticket.headers, report, options.signal);
+    return api.complete(ticket.uploadId);
+  }
+  if (ticket.kind === "multipart") {
+    const done = new Map(
+      (options.completedParts ?? []).map((p) => [p.partNumber, p.etag])
+    );
+    const loadedByPart = /* @__PURE__ */ new Map();
+    for (const n of done.keys()) loadedByPart.set(n, partSize(n, ticket.partSizeBytes, total));
+    const sum = () => [...loadedByPart.values()].reduce((a, b) => a + b, 0);
+    report(sum());
+    const pending = Array.from({ length: ticket.partCount }, (_, i) => i + 1).filter(
+      (n) => !done.has(n)
+    );
+    let cursor = 0;
+    const worker = async () => {
+      while (cursor < pending.length) {
+        const partNumber = pending[cursor++];
+        const start = (partNumber - 1) * ticket.partSizeBytes;
+        const chunk = blob.slice(start, Math.min(start + ticket.partSizeBytes, total), mimeType);
+        const { parts } = await api.partUrls(ticket.uploadId, [partNumber]);
+        const part = parts[0];
+        if (!part?.url) throw new PiFilesError(500, "NO_PART_URL", "\u0E44\u0E21\u0E48\u0E44\u0E14\u0E49 URL \u0E02\u0E2D\u0E07 part");
+        let attempt = 0;
+        for (; ; ) {
+          try {
+            const { etag } = await putBytes(
+              part.url,
+              chunk,
+              part.headers ?? {},
+              (loaded) => {
+                loadedByPart.set(partNumber, loaded);
+                report(sum());
+              },
+              options.signal,
+              part.method ?? "PUT"
+            );
+            if (!etag) {
+              throw new PiFilesError(
+                0,
+                "NO_ETAG",
+                "storage \u0E44\u0E21\u0E48\u0E2A\u0E48\u0E07 ETag (\u0E15\u0E31\u0E49\u0E07 CORS ExposeHeaders: ETag)"
+              );
+            }
+            const clean = etag.replaceAll('"', "");
+            done.set(partNumber, clean);
+            options.onPartDone?.({ partNumber, etag: clean });
+            break;
+          } catch (error) {
+            const code = error.code;
+            if (++attempt >= 3 || code === "ABORTED" || code === "NO_ETAG") throw error;
+            await new Promise((r) => setTimeout(r, 500 * 2 ** attempt));
+          }
+        }
+      }
+    };
+    const concurrency = Math.min(options.concurrency ?? 3, Math.max(pending.length, 1));
+    await Promise.all(Array.from({ length: concurrency }, worker));
+    return api.complete(
+      ticket.uploadId,
+      [...done.entries()].map(([partNumber, etag]) => ({ partNumber, etag }))
+    );
+  }
+  throw new PiFilesError(500, "UNKNOWN_TICKET", `ticket \u0E0A\u0E19\u0E34\u0E14\u0E17\u0E35\u0E48\u0E44\u0E21\u0E48\u0E23\u0E39\u0E49\u0E08\u0E31\u0E01: ${String(ticket)}`);
+}
+function partSize(partNumber, size, total) {
+  const start = (partNumber - 1) * size;
+  return Math.max(0, Math.min(size, total - start));
+}
+function fileFingerprint(file) {
+  return `${file.name}|${file.size}|${file.lastModified ?? 0}`;
+}
+
+export {
+  PiFilesError,
+  resolveAuthHeader,
+  buildUrl,
+  fetchWithRateLimitRetry,
+  request,
+  putBytes,
+  performUpload,
+  fileFingerprint
+};