@suphark/files-client 0.0.0-stage → 0.3.0

package/dist/next/index.d.ts

@@ -0,0 +1,746 @@
+import { UploadApi, UploadSource, PerformUploadOptions } from '../index.js';
+export { P as PiFilesError } from '../upload-D79TA4qU.js';
+import * as _pi_files_contracts from '@pi/files-contracts';
+import { CreateUploadInput, ReplaceFileInput } from '@pi/files-contracts';
+import { PiFilesClient, PiFilesOptions } from '../index.js';
+export { createPiFiles } from '../index.js';
+
+/**
+ * ตรวจลายเซ็น webhook ของ Pi Files (header `x-pi-files-signature: t=<unix>,v1=<hex>`)
+ * secret ของแอปขอจากผู้ดูแลแพลตฟอร์ม (GET /api/v1/admin/apps/:id/webhook-secret)
+ *
+ * ```ts
+ * export async function POST(req: Request) {
+ *   const body = await req.text();
+ *   if (!verifyWebhookSignature(body, req.headers.get("x-pi-files-signature"), process.env.PI_FILES_WEBHOOK_SECRET!)) {
+ *     return new Response("bad signature", { status: 401 });
+ *   }
+ *   const event = JSON.parse(body) as PiFilesWebhookEvent;
+ *   …
+ * }
+ * ```
+ */
+interface PiFilesWebhookEvent {
+    id: string;
+    event: "file.uploaded" | "file.replaced" | "file.trashed" | "file.restored" | "file.deleted" | "file.moved" | "file.missing" | "file.created" | "file.updated" | "folder.created" | "folder.updated" | "folder.deleted";
+    tenantId: string;
+    occurredAt: string;
+    /** ไม่มีในเหตุการณ์ folder.* */
+    file?: {
+        id: string;
+        filename: string;
+        mimeType: string;
+        sizeBytes: string;
+        versionCount: number | null;
+        module: string | null;
+    };
+    /** เฉพาะ folder.* */
+    folder?: {
+        id: string;
+        name: string;
+    };
+    /** เหตุการณ์จาก linked source — ancestorFolderIds = โฟลเดอร์ (id ของ Pi Files) จากจุดที่ผูกลงมา ใช้ map ไปชุดเอกสาร */
+    source?: {
+        id: string;
+        folderId?: string | null;
+        ancestorFolderIds: string[];
+        providerFileId?: string | null;
+    };
+    [extra: string]: unknown;
+}
+declare function verifyWebhookSignature(body: string, header: string | null | undefined, secret: string, { toleranceSeconds, now }?: {
+    toleranceSeconds?: number;
+    now?: number;
+}): boolean;
+
+type RouteCtx = {
+    params: Promise<Record<string, string | string[]>>;
+};
+/**
+ * helper สำหรับ Next.js route handlers ของ consumer app:
+ * - handlers.content  → GET /api/files/[id]/content  (browser ไม่เคยเห็น URL ของ Pi Files/R2)
+ * - handlers.preview  → GET /api/files/[id]/preview?size=sm|lg  (thumbnail webp ของไฟล์รูป)
+ * - handlers.uploads  → app/api/files/uploads/[[...path]]/route.ts  (proxy create/replace/parts/complete/abort ด้วย app key)
+ *   อัปโหลดเวอร์ชันใหม่ทับไฟล์เดิม = POST <endpoint>/replace/<fileId> (useReplace ใช้ path นี้เองเมื่อ endpoint ไม่ใช่ของ Pi Files)
+ * consumer เป็นคนตรวจ session/สิทธิ์ของตัวเองใน callback
+ */
+declare function createPiFilesNext(config: {
+    client: PiFilesClient;
+}): {
+    client: {
+        options: PiFilesOptions;
+        uploads: {
+            create: (input: CreateUploadInput) => Promise<{
+                kind: "put";
+                uploadId: string;
+                fileId: string;
+                url: string;
+                method: "PUT";
+                headers: Record<string, string>;
+                expiresAt: string;
+            } | {
+                kind: "multipart";
+                uploadId: string;
+                fileId: string;
+                partSizeBytes: number;
+                partCount: number;
+                expiresAt: string;
+            }>;
+            partUrls: (uploadId: string, partNumbers: number[]) => Promise<{
+                parts: {
+                    partNumber: number;
+                    url: string;
+                    expiresAt: string;
+                    method?: "PUT" | "POST" | undefined;
+                    headers?: Record<string, string> | undefined;
+                }[];
+            }>;
+            complete: (uploadId: string, parts?: _pi_files_contracts.CompleteUploadInput["parts"]) => Promise<{
+                id: string;
+                filename: string;
+                mimeType: string;
+                sizeBytes: string;
+                status: "UPLOADING" | "ACTIVE" | "ORPHAN_CANDIDATE" | "TRASHED" | "PENDING_DELETE" | "MISSING" | "DELETED" | "ERROR";
+                visibility: "PRIVATE" | "TENANT" | "PUBLIC";
+                ownerType: "USER" | "APP";
+                ownerId: string;
+                appKey: string | null;
+                folderId: string | null;
+                etag: string | null;
+                checksumSha256: string | null;
+                versionCount: number;
+                refCount: number;
+                metadata: Record<string, unknown>;
+                createdById: string | null;
+                createdAt: string;
+                updatedAt: string;
+                trashedAt: string | null;
+                contentPath: string;
+                previewPath: string | null;
+                publicUrl: string | null;
+                storage: {
+                    bucketKey: string;
+                    bucketLabel: string | null;
+                    kind: string;
+                    providerName: string;
+                    sourceUrl?: string | null | undefined;
+                    linked?: boolean | undefined;
+                } | null;
+            }>;
+            abort: (uploadId: string) => Promise<void>;
+        };
+        uploadApi: UploadApi;
+        upload: (source: UploadSource, input: CreateUploadInput, opts?: PerformUploadOptions) => Promise<_pi_files_contracts.FileAssetDto>;
+        replace: (fileId: string, source: UploadSource, input: ReplaceFileInput, opts?: PerformUploadOptions) => Promise<_pi_files_contracts.FileAssetDto>;
+        files: {
+            grant: (fileId: string, input?: Partial<_pi_files_contracts.CreateGrantInput>) => Promise<{
+                url: string;
+                expiresAt: string;
+            }>;
+            get: (id: string) => Promise<{
+                id: string;
+                filename: string;
+                mimeType: string;
+                sizeBytes: string;
+                status: "UPLOADING" | "ACTIVE" | "ORPHAN_CANDIDATE" | "TRASHED" | "PENDING_DELETE" | "MISSING" | "DELETED" | "ERROR";
+                visibility: "PRIVATE" | "TENANT" | "PUBLIC";
+                ownerType: "USER" | "APP";
+                ownerId: string;
+                appKey: string | null;
+                folderId: string | null;
+                etag: string | null;
+                checksumSha256: string | null;
+                versionCount: number;
+                refCount: number;
+                metadata: Record<string, unknown>;
+                createdById: string | null;
+                createdAt: string;
+                updatedAt: string;
+                trashedAt: string | null;
+                contentPath: string;
+                previewPath: string | null;
+                publicUrl: string | null;
+                storage: {
+                    bucketKey: string;
+                    bucketLabel: string | null;
+                    kind: string;
+                    providerName: string;
+                    sourceUrl?: string | null | undefined;
+                    linked?: boolean | undefined;
+                } | null;
+            }>;
+            access: (id: string) => Promise<{
+                provider: string;
+                bucketKey: string;
+                objectKey: string;
+                sourceUrl: string | null;
+                scope: "unknown" | "anyone" | "domain" | "restricted" | "pi-files";
+                domains: string[];
+                people: {
+                    email: string;
+                    role: string;
+                    name: string | null;
+                }[];
+                publicLinkAllowed: boolean;
+                reason: string | null;
+            }>;
+            list: (query?: Partial<_pi_files_contracts.ListFilesQuery>) => Promise<{
+                items: _pi_files_contracts.FileAssetDto[];
+                nextCursor: string | null;
+            }>;
+            search: (query: Partial<_pi_files_contracts.SearchQuery> & {
+                q: string;
+            }) => Promise<{
+                items: _pi_files_contracts.FileAssetDto[];
+                nextCursor: string | null;
+            }>;
+            update: (id: string, patch: _pi_files_contracts.UpdateFileInput) => Promise<{
+                id: string;
+                filename: string;
+                mimeType: string;
+                sizeBytes: string;
+                status: "UPLOADING" | "ACTIVE" | "ORPHAN_CANDIDATE" | "TRASHED" | "PENDING_DELETE" | "MISSING" | "DELETED" | "ERROR";
+                visibility: "PRIVATE" | "TENANT" | "PUBLIC";
+                ownerType: "USER" | "APP";
+                ownerId: string;
+                appKey: string | null;
+                folderId: string | null;
+                etag: string | null;
+                checksumSha256: string | null;
+                versionCount: number;
+                refCount: number;
+                metadata: Record<string, unknown>;
+                createdById: string | null;
+                createdAt: string;
+                updatedAt: string;
+                trashedAt: string | null;
+                contentPath: string;
+                previewPath: string | null;
+                publicUrl: string | null;
+                storage: {
+                    bucketKey: string;
+                    bucketLabel: string | null;
+                    kind: string;
+                    providerName: string;
+                    sourceUrl?: string | null | undefined;
+                    linked?: boolean | undefined;
+                } | null;
+            }>;
+            trash: (id: string) => Promise<{
+                id: string;
+                filename: string;
+                mimeType: string;
+                sizeBytes: string;
+                status: "UPLOADING" | "ACTIVE" | "ORPHAN_CANDIDATE" | "TRASHED" | "PENDING_DELETE" | "MISSING" | "DELETED" | "ERROR";
+                visibility: "PRIVATE" | "TENANT" | "PUBLIC";
+                ownerType: "USER" | "APP";
+                ownerId: string;
+                appKey: string | null;
+                folderId: string | null;
+                etag: string | null;
+                checksumSha256: string | null;
+                versionCount: number;
+                refCount: number;
+                metadata: Record<string, unknown>;
+                createdById: string | null;
+                createdAt: string;
+                updatedAt: string;
+                trashedAt: string | null;
+                contentPath: string;
+                previewPath: string | null;
+                publicUrl: string | null;
+                storage: {
+                    bucketKey: string;
+                    bucketLabel: string | null;
+                    kind: string;
+                    providerName: string;
+                    sourceUrl?: string | null | undefined;
+                    linked?: boolean | undefined;
+                } | null;
+            }>;
+            delete: (id: string) => Promise<{
+                id: string;
+                filename: string;
+                mimeType: string;
+                sizeBytes: string;
+                status: "UPLOADING" | "ACTIVE" | "ORPHAN_CANDIDATE" | "TRASHED" | "PENDING_DELETE" | "MISSING" | "DELETED" | "ERROR";
+                visibility: "PRIVATE" | "TENANT" | "PUBLIC";
+                ownerType: "USER" | "APP";
+                ownerId: string;
+                appKey: string | null;
+                folderId: string | null;
+                etag: string | null;
+                checksumSha256: string | null;
+                versionCount: number;
+                refCount: number;
+                metadata: Record<string, unknown>;
+                createdById: string | null;
+                createdAt: string;
+                updatedAt: string;
+                trashedAt: string | null;
+                contentPath: string;
+                previewPath: string | null;
+                publicUrl: string | null;
+                storage: {
+                    bucketKey: string;
+                    bucketLabel: string | null;
+                    kind: string;
+                    providerName: string;
+                    sourceUrl?: string | null | undefined;
+                    linked?: boolean | undefined;
+                } | null;
+            }>;
+            restore: (id: string) => Promise<{
+                id: string;
+                filename: string;
+                mimeType: string;
+                sizeBytes: string;
+                status: "UPLOADING" | "ACTIVE" | "ORPHAN_CANDIDATE" | "TRASHED" | "PENDING_DELETE" | "MISSING" | "DELETED" | "ERROR";
+                visibility: "PRIVATE" | "TENANT" | "PUBLIC";
+                ownerType: "USER" | "APP";
+                ownerId: string;
+                appKey: string | null;
+                folderId: string | null;
+                etag: string | null;
+                checksumSha256: string | null;
+                versionCount: number;
+                refCount: number;
+                metadata: Record<string, unknown>;
+                createdById: string | null;
+                createdAt: string;
+                updatedAt: string;
+                trashedAt: string | null;
+                contentPath: string;
+                previewPath: string | null;
+                publicUrl: string | null;
+                storage: {
+                    bucketKey: string;
+                    bucketLabel: string | null;
+                    kind: string;
+                    providerName: string;
+                    sourceUrl?: string | null | undefined;
+                    linked?: boolean | undefined;
+                } | null;
+            }>;
+            batch: (input: _pi_files_contracts.BatchFilesInput) => Promise<{
+                ok: string[];
+                failed: {
+                    id: string;
+                    code: string;
+                    detail: string;
+                }[];
+            }>;
+            contentUrl: (id: string, opts?: {
+                download?: boolean;
+                ttl?: number;
+            }) => Promise<{
+                url: string;
+                expiresAt: string;
+            }>;
+            stream: (id: string, opts?: {
+                range?: string | null;
+                download?: boolean;
+                signal?: AbortSignal;
+            }) => Promise<Response>;
+            contentPath: (id: string, opts?: {
+                download?: boolean;
+            }) => string;
+            preview: (id: string, opts?: {
+                size?: "sm" | "lg";
+                signal?: AbortSignal;
+            }) => Promise<Response>;
+            replace: (id: string, input: ReplaceFileInput) => Promise<{
+                kind: "put";
+                uploadId: string;
+                fileId: string;
+                url: string;
+                method: "PUT";
+                headers: Record<string, string>;
+                expiresAt: string;
+            } | {
+                kind: "multipart";
+                uploadId: string;
+                fileId: string;
+                partSizeBytes: number;
+                partCount: number;
+                expiresAt: string;
+            }>;
+            versions: (id: string) => Promise<{
+                versionNo: number;
+                current: boolean;
+                filename: string;
+                mimeType: string;
+                sizeBytes: string;
+                createdById: string | null;
+                createdAt: string;
+                expiresAt: string | null;
+            }[]>;
+            restoreVersion: (id: string, versionNo: number) => Promise<{
+                id: string;
+                filename: string;
+                mimeType: string;
+                sizeBytes: string;
+                status: "UPLOADING" | "ACTIVE" | "ORPHAN_CANDIDATE" | "TRASHED" | "PENDING_DELETE" | "MISSING" | "DELETED" | "ERROR";
+                visibility: "PRIVATE" | "TENANT" | "PUBLIC";
+                ownerType: "USER" | "APP";
+                ownerId: string;
+                appKey: string | null;
+                folderId: string | null;
+                etag: string | null;
+                checksumSha256: string | null;
+                versionCount: number;
+                refCount: number;
+                metadata: Record<string, unknown>;
+                createdById: string | null;
+                createdAt: string;
+                updatedAt: string;
+                trashedAt: string | null;
+                contentPath: string;
+                previewPath: string | null;
+                publicUrl: string | null;
+                storage: {
+                    bucketKey: string;
+                    bucketLabel: string | null;
+                    kind: string;
+                    providerName: string;
+                    sourceUrl?: string | null | undefined;
+                    linked?: boolean | undefined;
+                } | null;
+            }>;
+            deleteVersion: (id: string, versionNo: number) => Promise<{
+                ok: true;
+            }>;
+            versionContentUrl: (id: string, versionNo: number, opts?: {
+                download?: boolean;
+                ttl?: number;
+            }) => Promise<{
+                url: string;
+                expiresAt: string;
+            }>;
+        };
+        references: {
+            attach: (fileId: string, ref: _pi_files_contracts.FileReferenceInput) => Promise<{
+                featureKey: string;
+                entityType: string;
+                entityId: string;
+                role: string;
+                id: string;
+                appKey: string;
+                createdAt: string;
+            }>;
+            detach: (fileId: string, ref: _pi_files_contracts.FileReferenceInput) => Promise<{
+                ok: true;
+                refCount: number;
+            }>;
+            listOf: (fileId: string) => Promise<{
+                featureKey: string;
+                entityType: string;
+                entityId: string;
+                role: string;
+                id: string;
+                appKey: string;
+                createdAt: string;
+            }[]>;
+            move: (fileId: string, from: _pi_files_contracts.FileReferenceInput, to: _pi_files_contracts.FileReferenceInput) => Promise<{
+                featureKey: string;
+                entityType: string;
+                entityId: string;
+                role: string;
+                id: string;
+                appKey: string;
+                createdAt: string;
+            }>;
+            byEntity: (entityType: string, entityId: string, featureKey?: string) => Promise<{
+                reference: _pi_files_contracts.FileReferenceDto;
+                file: _pi_files_contracts.FileAssetDto;
+            }[]>;
+        };
+        folders: {
+            get: (id?: string) => Promise<{
+                folder: {
+                    id: string;
+                    name: string;
+                    kind: "USER_ROOT" | "APP_ROOT" | "NORMAL";
+                    ownerType: "USER" | "APP";
+                    ownerId: string;
+                    parentId: string | null;
+                    path: string;
+                    depth: number;
+                    status: "ACTIVE" | "TRASHED";
+                    createdAt: string;
+                    updatedAt: string;
+                    sourceId?: string | null | undefined;
+                    externalId?: string | null | undefined;
+                };
+                access: "view" | "owner" | "edit";
+                breadcrumb: {
+                    id: string;
+                    name: string;
+                    kind: "USER_ROOT" | "APP_ROOT" | "NORMAL";
+                }[];
+                children: {
+                    id: string;
+                    name: string;
+                    kind: "USER_ROOT" | "APP_ROOT" | "NORMAL";
+                    ownerType: "USER" | "APP";
+                    ownerId: string;
+                    parentId: string | null;
+                    path: string;
+                    depth: number;
+                    status: "ACTIVE" | "TRASHED";
+                    createdAt: string;
+                    updatedAt: string;
+                    sourceId?: string | null | undefined;
+                    externalId?: string | null | undefined;
+                }[];
+            }>;
+            tree: (root?: string, depth?: number) => Promise<unknown>;
+            create: (input: _pi_files_contracts.CreateFolderInput) => Promise<{
+                id: string;
+                name: string;
+                kind: "USER_ROOT" | "APP_ROOT" | "NORMAL";
+                ownerType: "USER" | "APP";
+                ownerId: string;
+                parentId: string | null;
+                path: string;
+                depth: number;
+                status: "ACTIVE" | "TRASHED";
+                createdAt: string;
+                updatedAt: string;
+                sourceId?: string | null | undefined;
+                externalId?: string | null | undefined;
+            }>;
+            update: (id: string, patch: _pi_files_contracts.UpdateFolderInput) => Promise<{
+                id: string;
+                name: string;
+                kind: "USER_ROOT" | "APP_ROOT" | "NORMAL";
+                ownerType: "USER" | "APP";
+                ownerId: string;
+                parentId: string | null;
+                path: string;
+                depth: number;
+                status: "ACTIVE" | "TRASHED";
+                createdAt: string;
+                updatedAt: string;
+                sourceId?: string | null | undefined;
+                externalId?: string | null | undefined;
+            }>;
+            trash: (id: string) => Promise<{
+                ok: true;
+            }>;
+            restore: (id: string) => Promise<{
+                id: string;
+                name: string;
+                kind: "USER_ROOT" | "APP_ROOT" | "NORMAL";
+                ownerType: "USER" | "APP";
+                ownerId: string;
+                parentId: string | null;
+                path: string;
+                depth: number;
+                status: "ACTIVE" | "TRASHED";
+                createdAt: string;
+                updatedAt: string;
+                sourceId?: string | null | undefined;
+                externalId?: string | null | undefined;
+            }>;
+            contents: (id: string, opts?: {
+                recursive?: boolean;
+            }) => Promise<{
+                folderId: string;
+                sourceId: string | null;
+                items: {
+                    id: string;
+                    isFolder: boolean;
+                    name: string;
+                    relativePath: string;
+                    parentId: string | null;
+                    mimeType: string | null;
+                    sizeBytes: string | null;
+                    md5: string | null;
+                    modifiedTime: string | null;
+                    providerFileId: string | null;
+                    webViewLink: string | null;
+                    status: string;
+                }[];
+            }>;
+            ensurePath: (id: string, names: string[]) => Promise<{
+                id: string;
+                name: string;
+                kind: "USER_ROOT" | "APP_ROOT" | "NORMAL";
+                ownerType: "USER" | "APP";
+                ownerId: string;
+                parentId: string | null;
+                path: string;
+                depth: number;
+                status: "ACTIVE" | "TRASHED";
+                createdAt: string;
+                updatedAt: string;
+                sourceId?: string | null | undefined;
+                externalId?: string | null | undefined;
+            }>;
+        };
+        sources: {
+            link: (input: _pi_files_contracts.LinkSourceInput) => Promise<{
+                id: string;
+                appKey: string;
+                bucketKey: string;
+                folderId: string;
+                externalFolderId: string;
+                sourceUrl: string;
+                label: string | null;
+                status: "ACTIVE" | "ERROR" | "PAUSED";
+                lastSyncedAt: string | null;
+                lastError: string | null;
+                createdAt: string;
+                stats?: {
+                    folders: number;
+                    files: number;
+                    created: number;
+                    updated: number;
+                    removed: number;
+                } | undefined;
+            }>;
+            list: () => Promise<{
+                id: string;
+                appKey: string;
+                bucketKey: string;
+                folderId: string;
+                externalFolderId: string;
+                sourceUrl: string;
+                label: string | null;
+                status: "ACTIVE" | "ERROR" | "PAUSED";
+                lastSyncedAt: string | null;
+                lastError: string | null;
+                createdAt: string;
+                stats?: {
+                    folders: number;
+                    files: number;
+                    created: number;
+                    updated: number;
+                    removed: number;
+                } | undefined;
+            }[]>;
+            get: (id: string) => Promise<{
+                id: string;
+                appKey: string;
+                bucketKey: string;
+                folderId: string;
+                externalFolderId: string;
+                sourceUrl: string;
+                label: string | null;
+                status: "ACTIVE" | "ERROR" | "PAUSED";
+                lastSyncedAt: string | null;
+                lastError: string | null;
+                createdAt: string;
+                stats?: {
+                    folders: number;
+                    files: number;
+                    created: number;
+                    updated: number;
+                    removed: number;
+                } | undefined;
+            }>;
+            sync: (id: string) => Promise<{
+                id: string;
+                appKey: string;
+                bucketKey: string;
+                folderId: string;
+                externalFolderId: string;
+                sourceUrl: string;
+                label: string | null;
+                status: "ACTIVE" | "ERROR" | "PAUSED";
+                lastSyncedAt: string | null;
+                lastError: string | null;
+                createdAt: string;
+                stats?: {
+                    folders: number;
+                    files: number;
+                    created: number;
+                    updated: number;
+                    removed: number;
+                } | undefined;
+            }>;
+            unlink: (id: string) => Promise<{
+                ok: true;
+                files: number;
+                folders: number;
+            }>;
+        };
+        quota: {
+            get: (scope?: "user" | "app" | "tenant") => Promise<{
+                scope: "app" | "tenant" | "user";
+                scopeId: string;
+                bytesUsed: string;
+                fileCount: number;
+                quotaBytes: string | null;
+            }>;
+        };
+        manifest: {
+            sync: (input: _pi_files_contracts.FilesManifest) => Promise<{
+                created: string[];
+                updated: string[];
+                deprecated: string[];
+            }>;
+        };
+        migration: {
+            adopt: (input: _pi_files_contracts.AdoptFileInput) => Promise<{
+                status: "created" | "existing";
+                fileId: string;
+            }>;
+        };
+        withUser: (token: string) => /*elided*/ any;
+    };
+    handlers: {
+        content: (opts: {
+            /** map request → fileId + ตรวจสิทธิ์ของ consumer; คืน null = 404, คืน Response = ส่งออกเลย (เช่น 401) */
+            resolve: (request: Request, params: Record<string, string | string[]>) => Promise<{
+                fileId: string;
+                download?: boolean;
+                filename?: string;
+            } | Response | null>;
+            /**
+             * redirect (default): 302 ไป presigned URL ของ storage — ถูกสุด, browser คง Range header ข้าม redirect
+             * stream: proxy bytes ผ่าน consumer → Pi Files → storage (URL ไม่หมดอายุ, กิน function time 2 ชั้น)
+             */
+            strategy?: "redirect" | "stream";
+        }) => (request: Request, ctx: RouteCtx) => Promise<Response>;
+        preview: (opts: {
+            /** map request → fileId + ตรวจสิทธิ์ของ consumer; คืน null = 404, คืน Response = ส่งออกเลย */
+            resolve: (request: Request, params: Record<string, string | string[]>) => Promise<{
+                fileId: string;
+            } | Response | null>;
+        }) => (request: Request, ctx: RouteCtx) => Promise<Response>;
+        uploads: (opts: {
+            /**
+             * ตรวจ session ของ consumer ทุก action; สำหรับ create ต้องคืน input ที่ server กำหนดเอง
+             * (featureKey / reference / onBehalfOfUserId / folderId) ทับค่าที่ browser ส่งมา
+             * คืน Response = ปฏิเสธ (เช่น 401/403)
+             */
+            authorize: (request: Request, action: {
+                kind: "create";
+                body: Partial<CreateUploadInput>;
+            }
+            /** อัปโหลดเวอร์ชันใหม่ทับ fileId — consumer ต้องตรวจว่าผู้ใช้แก้ไฟล์นี้ได้ */
+             | {
+                kind: "replace";
+                fileId: string;
+                body: Partial<ReplaceFileInput>;
+            } | {
+                kind: "parts" | "complete" | "abort";
+                uploadId: string;
+            }) => Promise<{
+                input?: Partial<CreateUploadInput>;
+            } | Response | null>;
+        }) => {
+            POST: (request: Request, ctx: RouteCtx) => Promise<Response>;
+            DELETE: (request: Request, ctx: RouteCtx) => Promise<Response>;
+        };
+    };
+    /** header สำหรับเรียก Pi Files เองจาก server code ของ consumer */
+    authHeader: () => Promise<Record<string, string>>;
+    url: (path: string) => string;
+};
+type PiFilesNext = ReturnType<typeof createPiFilesNext>;
+
+export { PiFilesClient, PiFilesOptions, createPiFilesNext, verifyWebhookSignature };
+export type { PiFilesNext, PiFilesWebhookEvent };