@unisource/sdk 0.6.0 → 0.8.0

package/README.md

@@ -1,55 +1,88 @@
 # @unisource/sdk
 
-Shared UniSource contracts and HTTP client used by both `apps/backend` and `apps/frontend`.
+Główne, współdzielone biblioteki oraz klient HTTP (SDK) wykorzystywane zarówno przez aplikację `frontend`, jak i `backend` (w ramach repozytorium UniSource).
 
-## What is included
+## Zawartość pakietu
 
-- Zod schemas and TypeScript types for uploads, files, folders, services, audit log, and share links
-- `UnisourceClient` for authenticated app and admin API calls
-- Standalone public share helpers: `getPublicFileInfo()` and `unlockPublicFile()`
-- Typed error classes: `UnisourceError` and `UnisourceNetworkError`
+SDK zapewnia pojedyncze źródło prawdy dla kontraktów API i upraszcza komunikację z backendem. Zawiera m.in.:
 
-## Development
+- **Zod Schemas & TypeScript Types**: Pełne definicje typów dla wszystkich encji w systemie: Pliki, Foldery, Udostępnienia (Share Links), Upload (w tym Multipart), Magazyn (Main Storage), Usługi (Services), Role Użytkowników oraz Audyty (Audit Logs).
+- **UnisourceClient**: Silnie typowany klient HTTP służący do bezpiecznej komunikacji z API z uwzględnieniem identyfikacji usługi (`X-Service-ID`) oraz autoryzacji (JWT/API Key).
+- **Publiczne Helpery**: Samodzielne metody do obsługi udostępnionych, publicznych linków (bez wymagania logowania) takie jak `getPublicFileInfo()` czy `unlockPublicFile()`.
+- **Obsługa Błędów**: Precyzyjne klasy błędów `UnisourceError` oraz `UnisourceNetworkError`.
 
-From the monorepo root:
+## Użycie (Usage)
 
-```bash
-pnpm install
-pnpm --filter @unisource/sdk build
-pnpm --filter @unisource/sdk test
-pnpm --filter @unisource/sdk typecheck
-```
-
-## Usage
+Przykład konfiguracji i pobrania listy plików przypisanych do użytkownika przy wykorzystaniu instancji klienta:
 
 ```ts
 import { UnisourceClient } from '@unisource/sdk';
 
+// 1. Konfiguracja klienta
 const client = new UnisourceClient({
-  baseUrl: 'https://api.example.com',
+  baseUrl: 'https://api.usrc.dev',
   serviceId: 'usrc',
-  getToken: async () => 'jwt-or-api-key',
+  getToken: async () => 'twoj-token-jwt-lub-api-key', // Zwróć null dla zapytań publicznych
 });
 
+// 2. Zapytanie API (np. lista plików z paginacją)
 const files = await client.myFiles.list({ folder_id: null, limit: 25 });
 ```
 
-Public share flows do not require service headers:
+### Obsługa udostępnień publicznych
+Zapytania o zasoby publiczne nie wymagają pełnej inicjalizacji klienta i posiadają dedykowane, lekkie metody:
 
 ```ts
 import { getPublicFileInfo, unlockPublicFile } from '@unisource/sdk';
 
-const info = await getPublicFileInfo('https://api.example.com', 'share-slug');
-const unlocked = await unlockPublicFile('https://api.example.com', 'share-slug', 'secret');
+// Pobranie metadanych udostępnionego pliku na podstawie slug'a
+const info = await getPublicFileInfo('https://api.usrc.dev', 'moj-unikalny-slug');
+
+// Odblokowanie dostępu do pliku chronionego hasłem
+const unlocked = await unlockPublicFile('https://api.usrc.dev', 'moj-unikalny-slug', 'tajne-haslo123');
+```
+
+## Rozwój lokalny (Development)
+
+W ramach monorepo (narzędzie pnpm):
+
+```bash
+# Instalacja wszystkich zależności (w roocie)
+pnpm install
+
+# Kompilacja SDK
+pnpm --filter @unisource/sdk build
+
+# Sprawdzanie typów
+pnpm --filter @unisource/sdk typecheck
+
+# Uruchomienie testów
+pnpm --filter @unisource/sdk test
 ```
 
-## Release workflow
+Pakiet może być linkowany lokalnie w ramach workspace, wystarczy w innym projekcie monorepo dodać zależność:
+`"@unisource/sdk": "workspace:*"`
 
-Because `@unisource/sdk` is public, changes should ship with a changeset:
+## Wydawanie nowej wersji (Release Workflow)
+
+Pakiet `@unisource/sdk` jest pakietem publicznym na rejestrze NPM i korzysta z narzędzia [Changesets](https://github.com/changesets/changesets) do zarządzania wersjami.
+
+Aby opublikować nową wersję, wykonaj poniższe kroki z głównego katalogu (root) monorepo:
 
 ```bash
+# 1. Dodaj plik z opisem zmian (wybierz paczkę, typ bumpa i napisz komentarz)
 pnpm changeset
+
+# 2. Zatwierdź nową wersję na podstawie plików changeset (aktualizacja package.json oraz CHANGELOG.md)
 pnpm changeset version
+
+# 3. Zbuduj SDK by upewnić się, że kod wynikowy jest poprawny
 pnpm --filter @unisource/sdk build
+
+# 4. Sprawdź przed publikacją
+pnpm --filter @unisource/sdk publish --dry-run --access public --no-git-checks
+
+# 5. Opublikuj na rejestr NPM
 pnpm changeset publish
 ```
+Pamiętaj o dodaniu nowo powstałych tagów i commitów do głównego repozytorium po opublikowaniu paczki.

package/dist/index.d.mts

@@ -3,14 +3,30 @@ import { z } from "zod";
 //#region src/primitives.d.ts
 declare const nonEmptyString: z.ZodString;
 declare const positiveInt: z.ZodNumber;
+declare const nonNegativeInt: z.ZodNumber;
 declare const unixTimestamp: z.ZodNumber;
 declare const FILES_DEFAULT_LIMIT = 25;
 declare const FILES_MAX_LIMIT = 100;
+/**
+ * Storage backend a file lives on.
+ * - 'r2'      — Cloudflare R2 via presigned PUT / multipart
+ * - 'appwrite' — Appwrite Storage via direct browser SDK upload
+ *
+ * `recommendedUploadDestinationSchema` adds the meta-value 'hybrid' which is
+ * only valid as a service-wide setting (the upload manager picks r2/appwrite
+ * per-file based on size).
+ */
 declare const uploadDestinationSchema: z.ZodEnum<{
   appwrite: "appwrite";
   r2: "r2";
 }>;
 type UploadDestination = z.infer<typeof uploadDestinationSchema>;
+declare const recommendedUploadDestinationSchema: z.ZodEnum<{
+  appwrite: "appwrite";
+  hybrid: "hybrid";
+  r2: "r2";
+}>;
+type RecommendedUploadDestination = z.infer<typeof recommendedUploadDestinationSchema>;
 declare const uploadStatusSchema: z.ZodEnum<{
   completed: "completed";
   failed: "failed";
@@ -333,6 +349,7 @@ declare const fileRestoreResponseSchema: z.ZodObject<{
   id: z.ZodString;
 }, z.core.$strip>;
 type FileRestoreResponse = z.infer<typeof fileRestoreResponseSchema>;
+/** SDK4: filename hard-capped to 255 to match backend Zod validation. */
 declare const fileUpdateRequestSchema: z.ZodObject<{
   filename: z.ZodString;
 }, z.core.$strip>;
@@ -477,6 +494,7 @@ declare const serviceSchema: z.ZodObject<{
   max_file_size_bytes: z.ZodNumber;
   recommended_upload_destination: z.ZodOptional<z.ZodEnum<{
     appwrite: "appwrite";
+    hybrid: "hybrid";
     r2: "r2";
   }>>;
   created_at: z.ZodNumber;
@@ -491,6 +509,7 @@ declare const serviceDetailResponseSchema: z.ZodObject<{
     max_file_size_bytes: z.ZodNumber;
     recommended_upload_destination: z.ZodOptional<z.ZodEnum<{
       appwrite: "appwrite";
+      hybrid: "hybrid";
       r2: "r2";
     }>>;
     created_at: z.ZodNumber;
@@ -511,6 +530,7 @@ declare const adminServiceUpdateResponseSchema: z.ZodObject<{
     max_file_size_bytes: z.ZodNumber;
     recommended_upload_destination: z.ZodOptional<z.ZodEnum<{
       appwrite: "appwrite";
+      hybrid: "hybrid";
       r2: "r2";
     }>>;
     created_at: z.ZodNumber;
@@ -525,6 +545,7 @@ type AdminServiceUpdateResponse = z.infer<typeof adminServiceUpdateResponseSchem
 declare const adminServiceSettingsRequestSchema: z.ZodObject<{
   recommended_upload_destination: z.ZodOptional<z.ZodEnum<{
     appwrite: "appwrite";
+    hybrid: "hybrid";
     r2: "r2";
   }>>;
 }, z.core.$strip>;
@@ -538,6 +559,7 @@ declare const adminServiceSettingsResponseSchema: z.ZodObject<{
     max_file_size_bytes: z.ZodNumber;
     recommended_upload_destination: z.ZodOptional<z.ZodEnum<{
       appwrite: "appwrite";
+      hybrid: "hybrid";
       r2: "r2";
     }>>;
     created_at: z.ZodNumber;
@@ -1025,6 +1047,28 @@ declare const releaseSyncResponseSchema: z.ZodObject<{
   }, z.core.$strip>>;
 }, z.core.$strip>;
 type ReleaseSyncResponse = z.infer<typeof releaseSyncResponseSchema>;
+/**
+ * Response of `GET /app/releases/latest?channel=...` — used by client apps to
+ * discover the most recent completed release for a given distribution channel
+ * (e.g. `stable`, `beta`). Includes a short-lived presigned download URL.
+ */
+declare const appReleaseLatestQuerySchema: z.ZodObject<{
+  channel: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+}, z.core.$strip>;
+type AppReleaseLatestQuery = z.input<typeof appReleaseLatestQuerySchema>;
+declare const appReleaseLatestResponseSchema: z.ZodObject<{
+  id: z.ZodString;
+  name: z.ZodString;
+  size: z.ZodNumber;
+  r2_key: z.ZodString;
+  tags: z.ZodArray<z.ZodString>;
+  notes: z.ZodNullable<z.ZodString>;
+  force_update: z.ZodBoolean;
+  created_at: z.ZodString;
+  download_url: z.ZodString;
+  download_url_expires_at: z.ZodNumber;
+}, z.core.$strip>;
+type AppReleaseLatestResponse = z.infer<typeof appReleaseLatestResponseSchema>;
 //#endregion
 //#region src/shareLinks.d.ts
 declare const shareLinkSchema: z.ZodObject<{
@@ -1165,6 +1209,87 @@ declare const sharesCreateRequestSchema: z.ZodObject<{
 }, z.core.$strip>;
 type SharesCreateRequest = z.infer<typeof sharesCreateRequestSchema>;
 //#endregion
+//#region src/v2.d.ts
+declare const fileRecordsListV2QuerySchema: z.ZodObject<{
+  folder_id: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null | undefined, string | null | undefined>>;
+  is_trashed: z.ZodOptional<z.ZodPipe<z.ZodEnum<{
+    false: "false";
+    true: "true";
+  }>, z.ZodTransform<boolean, "false" | "true">>>;
+  search: z.ZodOptional<z.ZodString>;
+  mime_type: z.ZodOptional<z.ZodString>;
+  sort_by: z.ZodOptional<z.ZodEnum<{
+    created_at: "created_at";
+    name: "name";
+    size: "size";
+  }>>;
+  sort_dir: z.ZodOptional<z.ZodEnum<{
+    asc: "asc";
+    desc: "desc";
+  }>>;
+  cursor: z.ZodOptional<z.ZodString>;
+  limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+type FileRecordsListV2Query = z.infer<typeof fileRecordsListV2QuerySchema>;
+declare const bulkFileIdsSchema: z.ZodObject<{
+  ids: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+type BulkFileIds = z.infer<typeof bulkFileIdsSchema>;
+declare const bulkFileMoveRequestSchema: z.ZodObject<{
+  ids: z.ZodArray<z.ZodString>;
+  folder_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+type BulkFileMoveRequest = z.infer<typeof bulkFileMoveRequestSchema>;
+declare const bulkOperationResponseSchema: z.ZodObject<{
+  success: z.ZodBoolean;
+  processed_count: z.ZodNumber;
+  failed_ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+type BulkOperationResponse = z.infer<typeof bulkOperationResponseSchema>;
+declare const folderListV2QuerySchema: z.ZodObject<{
+  parent_id: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null | undefined, string | null | undefined>>;
+  is_trashed: z.ZodOptional<z.ZodPipe<z.ZodEnum<{
+    false: "false";
+    true: "true";
+  }>, z.ZodTransform<boolean, "false" | "true">>>;
+  search: z.ZodOptional<z.ZodString>;
+  sort_by: z.ZodOptional<z.ZodEnum<{
+    created_at: "created_at";
+    name: "name";
+  }>>;
+  sort_dir: z.ZodOptional<z.ZodEnum<{
+    asc: "asc";
+    desc: "desc";
+  }>>;
+  cursor: z.ZodOptional<z.ZodString>;
+  limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+type FolderListV2Query = z.infer<typeof folderListV2QuerySchema>;
+declare const bulkFolderIdsSchema: z.ZodObject<{
+  ids: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+type BulkFolderIds = z.infer<typeof bulkFolderIdsSchema>;
+declare const bulkFolderMoveRequestSchema: z.ZodObject<{
+  ids: z.ZodArray<z.ZodString>;
+  parent_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+type BulkFolderMoveRequest = z.infer<typeof bulkFolderMoveRequestSchema>;
+declare const folderBreadcrumbsResponseSchema: z.ZodObject<{
+  breadcrumbs: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    service_id: z.ZodString;
+    user_id: z.ZodString;
+    parent_id: z.ZodNullable<z.ZodString>;
+    name: z.ZodString;
+    color_tag: z.ZodNullable<z.ZodString>;
+    is_trashed: z.ZodBoolean;
+    trashed_at: z.ZodNullable<z.ZodNumber>;
+    created_at: z.ZodNumber;
+    updated_at: z.ZodNumber;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type FolderBreadcrumbsResponse = z.infer<typeof folderBreadcrumbsResponseSchema>;
+//#endregion
 //#region src/client.d.ts
 declare class UnisourceError extends Error {
   readonly status: number;
@@ -1300,6 +1425,7 @@ declare class UnisourceClient {
     updateServiceSettings: (body: AdminServiceSettingsRequest, signal?: AbortSignal) => Promise<AdminServiceSettingsResponse>; /** Get real-time storage usage for the service */
     usage: (signal?: AbortSignal) => Promise<ServiceUsageResponse>; /** List all uploads (pending/completed/failed) for this service */
     listUploads: (query?: {
+      destination?: UploadDestination;
       status?: UploadStatus;
       cursor?: string;
       limit?: number;
@@ -1349,6 +1475,49 @@ declare class UnisourceClient {
     get: (id: string, signal?: AbortSignal) => Promise<ShareLinkDetailResponse>; /** Delete a share link */
     delete: (id: string, signal?: AbortSignal) => Promise<ShareLinkDeleteResponse>;
   };
+  readonly v2: {
+    files: {
+      /** List files with advanced search, sorting, and filtering capabilities */list: (query?: FileRecordsListV2Query, signal?: AbortSignal, options?: {
+        asUser?: string;
+      }) => Promise<FileRecordsListResponse>; /** Move multiple files at once */
+      bulkMove: (body: BulkFileMoveRequest, signal?: AbortSignal, options?: {
+        asUser?: string;
+      }) => Promise<BulkOperationResponse>; /** Move multiple files to trash */
+      bulkTrash: (body: BulkFileIds, signal?: AbortSignal, options?: {
+        asUser?: string;
+      }) => Promise<BulkOperationResponse>; /** Restore multiple files from trash */
+      bulkRestore: (body: BulkFileIds, signal?: AbortSignal, options?: {
+        asUser?: string;
+      }) => Promise<BulkOperationResponse>;
+    };
+    folders: {
+      /** List folders with advanced search, sorting, and filtering capabilities */list: (query?: FolderListV2Query, signal?: AbortSignal, options?: {
+        asUser?: string;
+      }) => Promise<FolderListResponse>; /** Get the breadcrumb hierarchy for a specific folder */
+      breadcrumbs: (id: string, signal?: AbortSignal, options?: {
+        asUser?: string;
+      }) => Promise<FolderBreadcrumbsResponse>; /** Move multiple folders at once */
+      bulkMove: (body: BulkFolderMoveRequest, signal?: AbortSignal, options?: {
+        asUser?: string;
+      }) => Promise<BulkOperationResponse>; /** Move multiple folders to trash */
+      bulkTrash: (body: BulkFolderIds, signal?: AbortSignal, options?: {
+        asUser?: string;
+      }) => Promise<BulkOperationResponse>; /** Restore multiple folders from trash */
+      bulkRestore: (body: BulkFolderIds, signal?: AbortSignal, options?: {
+        asUser?: string;
+      }) => Promise<BulkOperationResponse>;
+    };
+  };
+  readonly app: {
+    releases: {
+      /**
+       * Get the latest completed release for a channel (e.g. `stable`, `beta`).
+       * Backed by `GET /app/releases/latest`. Returns the release metadata plus
+       * a short-lived presigned download URL.
+       */
+      latest: (channel?: string, signal?: AbortSignal) => Promise<AppReleaseLatestResponse>;
+    };
+  };
 }
 //#endregion
-export { type AdminServiceSettingsRequest, type AdminServiceSettingsResponse, type AdminServiceUpdateRequest, type AdminServiceUpdateResponse, type AdminUser, type AdminUserListResponse, type AdminUserPasswordResetRequest, type AdminUserPasswordResetResponse, type AdminUserRoleUpdateRequest, type AdminUserStorageLimitUpdateRequest, type AdminUserUpdateRequest, type AdminUserUpdateResponse, type ApiError, type AuditEvent, type AuditEventAction, type AuditLogListQuery, type AuditLogListResponse, FILES_DEFAULT_LIMIT, FILES_MAX_LIMIT, type FileDeleteResponse, type FileDownloadUrlResponse, type FileMoveRequest, type FileRecord, type FileRecordDetailResponse, type FileRecordsListQuery, type FileRecordsListResponse, type FileRestoreResponse, type FileUpdateRequest, type FileUpdateResponse, type Folder, type FolderCreateRequest, type FolderCreateResponse, type FolderDeleteResponse, type FolderDetailResponse, type FolderListQuery, type FolderListResponse, type FolderRestoreResponse, type FolderUpdateRequest, type FolderUpdateResponse, MainStorageDeleteResponse, MainStorageDetailResponse, MainStorageFile, MainStorageListQuery, MainStorageListResponse, MainStorageRenameRequest, MainStorageRenameResponse, MainStorageRestoreResponse, type MultipartAbortRequest, type MultipartAbortResponse, type MultipartCompleteRequest, type MultipartCompleteResponse, type MultipartCreateRequest, type MultipartCreateResponse, type MultipartListPartsQuery, type MultipartListPartsResponse, type MultipartPart, type MultipartSignPartQuery, type MultipartSignPartResponse, type PublicFileAccessResponse, type PublicFileLockedResponse, type ReleaseDTO, type ReleaseDeleteResponse, type ReleaseMultipartAbortRequest, type ReleaseMultipartAbortResponse, type ReleaseMultipartCompleteRequest, type ReleaseMultipartCompleteResponse, type ReleaseMultipartCreateRequest, type ReleaseMultipartCreateResponse, type ReleaseMultipartListPartsQuery, type ReleaseMultipartListPartsResponse, type ReleaseMultipartPart, type ReleaseMultipartSignPartQuery, type ReleaseMultipartSignPartResponse, type ReleaseSyncManifest, type ReleaseSyncRequest, type ReleaseSyncResponse, type ReleaseSyncResult, type ReleaseUpdateRequest, type ReleaseUploadCompleteRequest, type ReleaseUploadCompleteResponse, type ReleaseUploadFailResponse, type ReleaseUploadInitRequest, type ReleaseUploadInitResponse, type ReleasesListQuery, type ReleasesListResponse, type Service, type ServiceDetailResponse, type ServiceUsageResponse, type ShareLink, type ShareLinkCreateRequest, type ShareLinkCreateResponse, type ShareLinkDeleteResponse, type ShareLinkDetailResponse, type ShareLinkListResponse, type ShareLinkUpdateRequest, type ShareLinkUpdateResponse, type SharesCreateRequest, UnisourceClient, type UnisourceClientConfig, UnisourceError, UnisourceNetworkError, type UploadAppwriteInitRequest, type UploadAppwriteInitResponse, type UploadCompleteResponse, type UploadDestination, type UploadFailResponse, type UploadLifecycleRequest, type UploadR2InitRequest, type UploadR2InitResponse, type UploadRecord, type UploadRecordDetailResponse, type UploadStatus, type UploadType, type UploadsListResponse, adminServiceSettingsRequestSchema, adminServiceSettingsResponseSchema, adminServiceUpdateRequestSchema, adminServiceUpdateResponseSchema, adminUserListResponseSchema, adminUserPasswordResetRequestSchema, adminUserPasswordResetResponseSchema, adminUserRoleUpdateRequestSchema, adminUserSchema, adminUserStorageLimitUpdateRequestSchema, adminUserUpdateRequestSchema, adminUserUpdateResponseSchema, apiErrorSchema, auditEventActionSchema, auditEventSchema, auditLogListQuerySchema, auditLogListResponseSchema, fileDeleteResponseSchema, fileDownloadUrlResponseSchema, fileMoveRequestSchema, fileRecordDetailResponseSchema, fileRecordSchema, fileRecordsListQuerySchema, fileRecordsListResponseSchema, fileRestoreResponseSchema, fileUpdateRequestSchema, fileUpdateResponseSchema, folderCreateRequestSchema, folderCreateResponseSchema, folderDeleteResponseSchema, folderDetailResponseSchema, folderListQuerySchema, folderListResponseSchema, folderRestoreResponseSchema, folderSchema, folderUpdateRequestSchema, folderUpdateResponseSchema, getPublicFileInfo, mainStorageDeleteResponseSchema, mainStorageDetailResponseSchema, mainStorageFileSchema, mainStorageListQuerySchema, mainStorageListResponseSchema, mainStorageRenameRequestSchema, mainStorageRenameResponseSchema, mainStorageRestoreResponseSchema, multipartAbortRequestSchema, multipartAbortResponseSchema, multipartCompleteRequestSchema, multipartCompleteResponseSchema, multipartCreateRequestSchema, multipartCreateResponseSchema, multipartListPartsQuerySchema, multipartListPartsResponseSchema, multipartPartSchema, multipartSignPartQuerySchema, multipartSignPartResponseSchema, nonEmptyString, positiveInt, publicFileAccessResponseSchema, publicFileLockedResponseSchema, releaseDTOSchema, releaseDeleteResponseSchema, releaseMultipartAbortRequestSchema, releaseMultipartAbortResponseSchema, releaseMultipartCompleteRequestSchema, releaseMultipartCompleteResponseSchema, releaseMultipartCreateRequestSchema, releaseMultipartCreateResponseSchema, releaseMultipartListPartsQuerySchema, releaseMultipartListPartsResponseSchema, releaseMultipartPartSchema, releaseMultipartSignPartQuerySchema, releaseMultipartSignPartResponseSchema, releaseSyncManifestSchema, releaseSyncRequestSchema, releaseSyncResponseSchema, releaseSyncResultSchema, releaseUpdateRequestSchema, releaseUploadCompleteRequestSchema, releaseUploadCompleteResponseSchema, releaseUploadFailResponseSchema, releaseUploadInitRequestSchema, releaseUploadInitResponseSchema, releasesListQuerySchema, releasesListResponseSchema, serviceDetailResponseSchema, serviceSchema, serviceUsageResponseSchema, shareLinkCreateRequestSchema, shareLinkCreateResponseSchema, shareLinkDeleteResponseSchema, shareLinkDetailResponseSchema, shareLinkListResponseSchema, shareLinkSchema, shareLinkUpdateRequestSchema, shareLinkUpdateResponseSchema, sharesCreateRequestSchema, unixTimestamp, unlockPublicFile, uploadAppwriteInitRequestSchema, uploadAppwriteInitResponseSchema, uploadCompleteResponseSchema, uploadDestinationSchema, uploadFailResponseSchema, uploadLifecycleRequestSchema, uploadR2InitRequestSchema, uploadR2InitResponseSchema, uploadRecordDetailResponseSchema, uploadRecordSchema, uploadStatusSchema, uploadTypeSchema, uploadsListResponseSchema };
+export { type AdminServiceSettingsRequest, type AdminServiceSettingsResponse, type AdminServiceUpdateRequest, type AdminServiceUpdateResponse, type AdminUser, type AdminUserListResponse, type AdminUserPasswordResetRequest, type AdminUserPasswordResetResponse, type AdminUserRoleUpdateRequest, type AdminUserStorageLimitUpdateRequest, type AdminUserUpdateRequest, type AdminUserUpdateResponse, type ApiError, type AppReleaseLatestQuery, type AppReleaseLatestResponse, type AuditEvent, type AuditEventAction, type AuditLogListQuery, type AuditLogListResponse, type BulkFileIds, type BulkFileMoveRequest, type BulkFolderIds, type BulkFolderMoveRequest, type BulkOperationResponse, FILES_DEFAULT_LIMIT, FILES_MAX_LIMIT, type FileDeleteResponse, type FileDownloadUrlResponse, type FileMoveRequest, type FileRecord, type FileRecordDetailResponse, type FileRecordsListQuery, type FileRecordsListResponse, type FileRecordsListV2Query, type FileRestoreResponse, type FileUpdateRequest, type FileUpdateResponse, type Folder, type FolderBreadcrumbsResponse, type FolderCreateRequest, type FolderCreateResponse, type FolderDeleteResponse, type FolderDetailResponse, type FolderListQuery, type FolderListResponse, type FolderListV2Query, type FolderRestoreResponse, type FolderUpdateRequest, type FolderUpdateResponse, MainStorageDeleteResponse, MainStorageDetailResponse, MainStorageFile, MainStorageListQuery, MainStorageListResponse, MainStorageRenameRequest, MainStorageRenameResponse, MainStorageRestoreResponse, type MultipartAbortRequest, type MultipartAbortResponse, type MultipartCompleteRequest, type MultipartCompleteResponse, type MultipartCreateRequest, type MultipartCreateResponse, type MultipartListPartsQuery, type MultipartListPartsResponse, type MultipartPart, type MultipartSignPartQuery, type MultipartSignPartResponse, type PublicFileAccessResponse, type PublicFileLockedResponse, type RecommendedUploadDestination, type ReleaseDTO, type ReleaseDeleteResponse, type ReleaseMultipartAbortRequest, type ReleaseMultipartAbortResponse, type ReleaseMultipartCompleteRequest, type ReleaseMultipartCompleteResponse, type ReleaseMultipartCreateRequest, type ReleaseMultipartCreateResponse, type ReleaseMultipartListPartsQuery, type ReleaseMultipartListPartsResponse, type ReleaseMultipartPart, type ReleaseMultipartSignPartQuery, type ReleaseMultipartSignPartResponse, type ReleaseSyncManifest, type ReleaseSyncRequest, type ReleaseSyncResponse, type ReleaseSyncResult, type ReleaseUpdateRequest, type ReleaseUploadCompleteRequest, type ReleaseUploadCompleteResponse, type ReleaseUploadFailResponse, type ReleaseUploadInitRequest, type ReleaseUploadInitResponse, type ReleasesListQuery, type ReleasesListResponse, type Service, type ServiceDetailResponse, type ServiceUsageResponse, type ShareLink, type ShareLinkCreateRequest, type ShareLinkCreateResponse, type ShareLinkDeleteResponse, type ShareLinkDetailResponse, type ShareLinkListResponse, type ShareLinkUpdateRequest, type ShareLinkUpdateResponse, type SharesCreateRequest, UnisourceClient, type UnisourceClientConfig, UnisourceError, UnisourceNetworkError, type UploadAppwriteInitRequest, type UploadAppwriteInitResponse, type UploadCompleteResponse, type UploadDestination, type UploadFailResponse, type UploadLifecycleRequest, type UploadR2InitRequest, type UploadR2InitResponse, type UploadRecord, type UploadRecordDetailResponse, type UploadStatus, type UploadType, type UploadsListResponse, adminServiceSettingsRequestSchema, adminServiceSettingsResponseSchema, adminServiceUpdateRequestSchema, adminServiceUpdateResponseSchema, adminUserListResponseSchema, adminUserPasswordResetRequestSchema, adminUserPasswordResetResponseSchema, adminUserRoleUpdateRequestSchema, adminUserSchema, adminUserStorageLimitUpdateRequestSchema, adminUserUpdateRequestSchema, adminUserUpdateResponseSchema, apiErrorSchema, appReleaseLatestQuerySchema, appReleaseLatestResponseSchema, auditEventActionSchema, auditEventSchema, auditLogListQuerySchema, auditLogListResponseSchema, bulkFileIdsSchema, bulkFileMoveRequestSchema, bulkFolderIdsSchema, bulkFolderMoveRequestSchema, bulkOperationResponseSchema, fileDeleteResponseSchema, fileDownloadUrlResponseSchema, fileMoveRequestSchema, fileRecordDetailResponseSchema, fileRecordSchema, fileRecordsListQuerySchema, fileRecordsListResponseSchema, fileRecordsListV2QuerySchema, fileRestoreResponseSchema, fileUpdateRequestSchema, fileUpdateResponseSchema, folderBreadcrumbsResponseSchema, folderCreateRequestSchema, folderCreateResponseSchema, folderDeleteResponseSchema, folderDetailResponseSchema, folderListQuerySchema, folderListResponseSchema, folderListV2QuerySchema, folderRestoreResponseSchema, folderSchema, folderUpdateRequestSchema, folderUpdateResponseSchema, getPublicFileInfo, mainStorageDeleteResponseSchema, mainStorageDetailResponseSchema, mainStorageFileSchema, mainStorageListQuerySchema, mainStorageListResponseSchema, mainStorageRenameRequestSchema, mainStorageRenameResponseSchema, mainStorageRestoreResponseSchema, multipartAbortRequestSchema, multipartAbortResponseSchema, multipartCompleteRequestSchema, multipartCompleteResponseSchema, multipartCreateRequestSchema, multipartCreateResponseSchema, multipartListPartsQuerySchema, multipartListPartsResponseSchema, multipartPartSchema, multipartSignPartQuerySchema, multipartSignPartResponseSchema, nonEmptyString, nonNegativeInt, positiveInt, publicFileAccessResponseSchema, publicFileLockedResponseSchema, recommendedUploadDestinationSchema, releaseDTOSchema, releaseDeleteResponseSchema, releaseMultipartAbortRequestSchema, releaseMultipartAbortResponseSchema, releaseMultipartCompleteRequestSchema, releaseMultipartCompleteResponseSchema, releaseMultipartCreateRequestSchema, releaseMultipartCreateResponseSchema, releaseMultipartListPartsQuerySchema, releaseMultipartListPartsResponseSchema, releaseMultipartPartSchema, releaseMultipartSignPartQuerySchema, releaseMultipartSignPartResponseSchema, releaseSyncManifestSchema, releaseSyncRequestSchema, releaseSyncResponseSchema, releaseSyncResultSchema, releaseUpdateRequestSchema, releaseUploadCompleteRequestSchema, releaseUploadCompleteResponseSchema, releaseUploadFailResponseSchema, releaseUploadInitRequestSchema, releaseUploadInitResponseSchema, releasesListQuerySchema, releasesListResponseSchema, serviceDetailResponseSchema, serviceSchema, serviceUsageResponseSchema, shareLinkCreateRequestSchema, shareLinkCreateResponseSchema, shareLinkDeleteResponseSchema, shareLinkDetailResponseSchema, shareLinkListResponseSchema, shareLinkSchema, shareLinkUpdateRequestSchema, shareLinkUpdateResponseSchema, sharesCreateRequestSchema, unixTimestamp, unlockPublicFile, uploadAppwriteInitRequestSchema, uploadAppwriteInitResponseSchema, uploadCompleteResponseSchema, uploadDestinationSchema, uploadFailResponseSchema, uploadLifecycleRequestSchema, uploadR2InitRequestSchema, uploadR2InitResponseSchema, uploadRecordDetailResponseSchema, uploadRecordSchema, uploadStatusSchema, uploadTypeSchema, uploadsListResponseSchema };

package/dist/index.mjs

@@ -2,10 +2,25 @@ import { z } from "zod";
 //#region src/primitives.ts
 const nonEmptyString = z.string().trim().min(1);
 const positiveInt = z.number().int().positive();
+const nonNegativeInt = z.number().int().nonnegative();
 const unixTimestamp = z.number().int().nonnegative();
 const FILES_DEFAULT_LIMIT = 25;
 const FILES_MAX_LIMIT = 100;
+/**
+* Storage backend a file lives on.
+* - 'r2'      — Cloudflare R2 via presigned PUT / multipart
+* - 'appwrite' — Appwrite Storage via direct browser SDK upload
+*
+* `recommendedUploadDestinationSchema` adds the meta-value 'hybrid' which is
+* only valid as a service-wide setting (the upload manager picks r2/appwrite
+* per-file based on size).
+*/
 const uploadDestinationSchema = z.enum(["r2", "appwrite"]);
+const recommendedUploadDestinationSchema = z.enum([
+	"r2",
+	"appwrite",
+	"hybrid"
+]);
 const uploadStatusSchema = z.enum([
 	"pending",
 	"completed",
@@ -137,7 +152,7 @@ const fileRecordSchema = z.object({
 	folder_id: nonEmptyString.nullable(),
 	upload_id: nonEmptyString.nullable(),
 	filename: nonEmptyString,
-	size: positiveInt,
+	size: nonNegativeInt,
 	mime_type: nonEmptyString,
 	storage_destination: uploadDestinationSchema,
 	is_trashed: z.boolean(),
@@ -173,7 +188,8 @@ const fileRestoreResponseSchema = z.object({
 	success: z.literal(true),
 	id: nonEmptyString
 });
-const fileUpdateRequestSchema = z.object({ filename: nonEmptyString });
+/** SDK4: filename hard-capped to 255 to match backend Zod validation. */
+const fileUpdateRequestSchema = z.object({ filename: z.string().trim().min(1).max(255) });
 const fileUpdateResponseSchema = z.object({ file: fileRecordSchema });
 //#endregion
 //#region src/folders.ts
@@ -232,7 +248,7 @@ const serviceSchema = z.object({
 	max_storage_bytes: positiveInt,
 	current_used_bytes: z.number().int().nonnegative(),
 	max_file_size_bytes: positiveInt,
-	recommended_upload_destination: uploadDestinationSchema.optional(),
+	recommended_upload_destination: recommendedUploadDestinationSchema.optional(),
 	created_at: unixTimestamp
 });
 const serviceDetailResponseSchema = z.object({ service: serviceSchema });
@@ -246,7 +262,7 @@ const adminServiceUpdateResponseSchema = serviceDetailResponseSchema;
 * can flip the recommended default upload destination per service without
 * disturbing quota-related fields.
 */
-const adminServiceSettingsRequestSchema = z.object({ recommended_upload_destination: uploadDestinationSchema.optional() }).refine((v) => v.recommended_upload_destination !== void 0, { message: "At least one setting must be provided" });
+const adminServiceSettingsRequestSchema = z.object({ recommended_upload_destination: recommendedUploadDestinationSchema.optional() }).refine((v) => v.recommended_upload_destination !== void 0, { message: "At least one setting must be provided" });
 const adminServiceSettingsResponseSchema = serviceDetailResponseSchema;
 const serviceUsageResponseSchema = z.object({
 	service_id: nonEmptyString,
@@ -486,6 +502,24 @@ const releaseSyncResponseSchema = z.object({
 	synced: z.number().int().nonnegative(),
 	results: z.array(releaseSyncResultSchema)
 });
+/**
+* Response of `GET /app/releases/latest?channel=...` — used by client apps to
+* discover the most recent completed release for a given distribution channel
+* (e.g. `stable`, `beta`). Includes a short-lived presigned download URL.
+*/
+const appReleaseLatestQuerySchema = z.object({ channel: nonEmptyString.optional().default("stable") });
+const appReleaseLatestResponseSchema = z.object({
+	id: nonEmptyString,
+	name: nonEmptyString,
+	size: z.number().int().nonnegative(),
+	r2_key: nonEmptyString,
+	tags: z.array(nonEmptyString),
+	notes: z.string().nullable(),
+	force_update: z.boolean(),
+	created_at: nonEmptyString,
+	download_url: z.string().url(),
+	download_url_expires_at: positiveInt
+});
 //#endregion
 //#region src/shareLinks.ts
 const shareLinkSchema = z.object({
@@ -909,6 +943,101 @@ var UnisourceClient = class {
 		get: (id, signal) => apiRequest(this.config, "GET", `/shares/${id}`, { signal }),
 		delete: (id, signal) => apiRequest(this.config, "DELETE", `/shares/${id}`, { signal })
 	};
+	v2 = {
+		files: {
+			list: (query, signal, options) => apiRequest(this.config, "GET", "/v2/files", {
+				query,
+				signal,
+				extraHeaders: this.withAsUser(options)
+			}),
+			bulkMove: (body, signal, options) => apiRequest(this.config, "POST", "/v2/files/bulk-move", {
+				body,
+				signal,
+				extraHeaders: this.withAsUser(options)
+			}),
+			bulkTrash: (body, signal, options) => apiRequest(this.config, "POST", "/v2/files/bulk-trash", {
+				body,
+				signal,
+				extraHeaders: this.withAsUser(options)
+			}),
+			bulkRestore: (body, signal, options) => apiRequest(this.config, "POST", "/v2/files/bulk-restore", {
+				body,
+				signal,
+				extraHeaders: this.withAsUser(options)
+			})
+		},
+		folders: {
+			list: (query, signal, options) => apiRequest(this.config, "GET", "/v2/folders", {
+				query,
+				signal,
+				extraHeaders: this.withAsUser(options)
+			}),
+			breadcrumbs: (id, signal, options) => apiRequest(this.config, "GET", `/v2/folders/${id}/breadcrumbs`, {
+				signal,
+				extraHeaders: this.withAsUser(options)
+			}),
+			bulkMove: (body, signal, options) => apiRequest(this.config, "POST", "/v2/folders/bulk-move", {
+				body,
+				signal,
+				extraHeaders: this.withAsUser(options)
+			}),
+			bulkTrash: (body, signal, options) => apiRequest(this.config, "POST", "/v2/folders/bulk-trash", {
+				body,
+				signal,
+				extraHeaders: this.withAsUser(options)
+			}),
+			bulkRestore: (body, signal, options) => apiRequest(this.config, "POST", "/v2/folders/bulk-restore", {
+				body,
+				signal,
+				extraHeaders: this.withAsUser(options)
+			})
+		}
+	};
+	app = { releases: { latest: (channel = "stable", signal) => apiRequest(this.config, "GET", "/app/releases/latest", {
+		query: { channel },
+		signal
+	}) } };
 };
 //#endregion
-export { FILES_DEFAULT_LIMIT, FILES_MAX_LIMIT, UnisourceClient, UnisourceError, UnisourceNetworkError, adminServiceSettingsRequestSchema, adminServiceSettingsResponseSchema, adminServiceUpdateRequestSchema, adminServiceUpdateResponseSchema, adminUserListResponseSchema, adminUserPasswordResetRequestSchema, adminUserPasswordResetResponseSchema, adminUserRoleUpdateRequestSchema, adminUserSchema, adminUserStorageLimitUpdateRequestSchema, adminUserUpdateRequestSchema, adminUserUpdateResponseSchema, apiErrorSchema, auditEventActionSchema, auditEventSchema, auditLogListQuerySchema, auditLogListResponseSchema, fileDeleteResponseSchema, fileDownloadUrlResponseSchema, fileMoveRequestSchema, fileRecordDetailResponseSchema, fileRecordSchema, fileRecordsListQuerySchema, fileRecordsListResponseSchema, fileRestoreResponseSchema, fileUpdateRequestSchema, fileUpdateResponseSchema, folderCreateRequestSchema, folderCreateResponseSchema, folderDeleteResponseSchema, folderDetailResponseSchema, folderListQuerySchema, folderListResponseSchema, folderRestoreResponseSchema, folderSchema, folderUpdateRequestSchema, folderUpdateResponseSchema, getPublicFileInfo, mainStorageDeleteResponseSchema, mainStorageDetailResponseSchema, mainStorageFileSchema, mainStorageListQuerySchema, mainStorageListResponseSchema, mainStorageRenameRequestSchema, mainStorageRenameResponseSchema, mainStorageRestoreResponseSchema, multipartAbortRequestSchema, multipartAbortResponseSchema, multipartCompleteRequestSchema, multipartCompleteResponseSchema, multipartCreateRequestSchema, multipartCreateResponseSchema, multipartListPartsQuerySchema, multipartListPartsResponseSchema, multipartPartSchema, multipartSignPartQuerySchema, multipartSignPartResponseSchema, nonEmptyString, positiveInt, publicFileAccessResponseSchema, publicFileLockedResponseSchema, releaseDTOSchema, releaseDeleteResponseSchema, releaseMultipartAbortRequestSchema, releaseMultipartAbortResponseSchema, releaseMultipartCompleteRequestSchema, releaseMultipartCompleteResponseSchema, releaseMultipartCreateRequestSchema, releaseMultipartCreateResponseSchema, releaseMultipartListPartsQuerySchema, releaseMultipartListPartsResponseSchema, releaseMultipartPartSchema, releaseMultipartSignPartQuerySchema, releaseMultipartSignPartResponseSchema, releaseSyncManifestSchema, releaseSyncRequestSchema, releaseSyncResponseSchema, releaseSyncResultSchema, releaseUpdateRequestSchema, releaseUploadCompleteRequestSchema, releaseUploadCompleteResponseSchema, releaseUploadFailResponseSchema, releaseUploadInitRequestSchema, releaseUploadInitResponseSchema, releasesListQuerySchema, releasesListResponseSchema, serviceDetailResponseSchema, serviceSchema, serviceUsageResponseSchema, shareLinkCreateRequestSchema, shareLinkCreateResponseSchema, shareLinkDeleteResponseSchema, shareLinkDetailResponseSchema, shareLinkListResponseSchema, shareLinkSchema, shareLinkUpdateRequestSchema, shareLinkUpdateResponseSchema, sharesCreateRequestSchema, unixTimestamp, unlockPublicFile, uploadAppwriteInitRequestSchema, uploadAppwriteInitResponseSchema, uploadCompleteResponseSchema, uploadDestinationSchema, uploadFailResponseSchema, uploadLifecycleRequestSchema, uploadR2InitRequestSchema, uploadR2InitResponseSchema, uploadRecordDetailResponseSchema, uploadRecordSchema, uploadStatusSchema, uploadTypeSchema, uploadsListResponseSchema };
+//#region src/v2.ts
+const fileRecordsListV2QuerySchema = z.object({
+	folder_id: nonEmptyString.nullable().optional().transform((v) => v === "null" ? null : v),
+	is_trashed: z.enum(["true", "false"]).transform((v) => v === "true").optional(),
+	search: z.string().optional(),
+	mime_type: z.string().optional(),
+	sort_by: z.enum([
+		"created_at",
+		"name",
+		"size"
+	]).optional(),
+	sort_dir: z.enum(["asc", "desc"]).optional(),
+	cursor: nonEmptyString.optional(),
+	limit: z.coerce.number().int().min(1).max(100).optional()
+});
+const bulkFileIdsSchema = z.object({ ids: z.array(nonEmptyString).min(1).max(100) });
+const bulkFileMoveRequestSchema = z.object({
+	ids: z.array(nonEmptyString).min(1).max(100),
+	folder_id: nonEmptyString.nullable().optional()
+});
+const bulkOperationResponseSchema = z.object({
+	success: z.boolean(),
+	processed_count: z.number().int().nonnegative(),
+	failed_ids: z.array(nonEmptyString).optional()
+});
+const folderListV2QuerySchema = z.object({
+	parent_id: nonEmptyString.nullable().optional().transform((v) => v === "null" ? null : v),
+	is_trashed: z.enum(["true", "false"]).transform((v) => v === "true").optional(),
+	search: z.string().optional(),
+	sort_by: z.enum(["created_at", "name"]).optional(),
+	sort_dir: z.enum(["asc", "desc"]).optional(),
+	cursor: nonEmptyString.optional(),
+	limit: z.coerce.number().int().min(1).max(100).optional()
+});
+const bulkFolderIdsSchema = z.object({ ids: z.array(nonEmptyString).min(1).max(100) });
+const bulkFolderMoveRequestSchema = z.object({
+	ids: z.array(nonEmptyString).min(1).max(100),
+	parent_id: nonEmptyString.nullable().optional()
+});
+const folderBreadcrumbsResponseSchema = z.object({ breadcrumbs: z.array(folderSchema) });
+//#endregion
+export { FILES_DEFAULT_LIMIT, FILES_MAX_LIMIT, UnisourceClient, UnisourceError, UnisourceNetworkError, adminServiceSettingsRequestSchema, adminServiceSettingsResponseSchema, adminServiceUpdateRequestSchema, adminServiceUpdateResponseSchema, adminUserListResponseSchema, adminUserPasswordResetRequestSchema, adminUserPasswordResetResponseSchema, adminUserRoleUpdateRequestSchema, adminUserSchema, adminUserStorageLimitUpdateRequestSchema, adminUserUpdateRequestSchema, adminUserUpdateResponseSchema, apiErrorSchema, appReleaseLatestQuerySchema, appReleaseLatestResponseSchema, auditEventActionSchema, auditEventSchema, auditLogListQuerySchema, auditLogListResponseSchema, bulkFileIdsSchema, bulkFileMoveRequestSchema, bulkFolderIdsSchema, bulkFolderMoveRequestSchema, bulkOperationResponseSchema, fileDeleteResponseSchema, fileDownloadUrlResponseSchema, fileMoveRequestSchema, fileRecordDetailResponseSchema, fileRecordSchema, fileRecordsListQuerySchema, fileRecordsListResponseSchema, fileRecordsListV2QuerySchema, fileRestoreResponseSchema, fileUpdateRequestSchema, fileUpdateResponseSchema, folderBreadcrumbsResponseSchema, folderCreateRequestSchema, folderCreateResponseSchema, folderDeleteResponseSchema, folderDetailResponseSchema, folderListQuerySchema, folderListResponseSchema, folderListV2QuerySchema, folderRestoreResponseSchema, folderSchema, folderUpdateRequestSchema, folderUpdateResponseSchema, getPublicFileInfo, mainStorageDeleteResponseSchema, mainStorageDetailResponseSchema, mainStorageFileSchema, mainStorageListQuerySchema, mainStorageListResponseSchema, mainStorageRenameRequestSchema, mainStorageRenameResponseSchema, mainStorageRestoreResponseSchema, multipartAbortRequestSchema, multipartAbortResponseSchema, multipartCompleteRequestSchema, multipartCompleteResponseSchema, multipartCreateRequestSchema, multipartCreateResponseSchema, multipartListPartsQuerySchema, multipartListPartsResponseSchema, multipartPartSchema, multipartSignPartQuerySchema, multipartSignPartResponseSchema, nonEmptyString, nonNegativeInt, positiveInt, publicFileAccessResponseSchema, publicFileLockedResponseSchema, recommendedUploadDestinationSchema, releaseDTOSchema, releaseDeleteResponseSchema, releaseMultipartAbortRequestSchema, releaseMultipartAbortResponseSchema, releaseMultipartCompleteRequestSchema, releaseMultipartCompleteResponseSchema, releaseMultipartCreateRequestSchema, releaseMultipartCreateResponseSchema, releaseMultipartListPartsQuerySchema, releaseMultipartListPartsResponseSchema, releaseMultipartPartSchema, releaseMultipartSignPartQuerySchema, releaseMultipartSignPartResponseSchema, releaseSyncManifestSchema, releaseSyncRequestSchema, releaseSyncResponseSchema, releaseSyncResultSchema, releaseUpdateRequestSchema, releaseUploadCompleteRequestSchema, releaseUploadCompleteResponseSchema, releaseUploadFailResponseSchema, releaseUploadInitRequestSchema, releaseUploadInitResponseSchema, releasesListQuerySchema, releasesListResponseSchema, serviceDetailResponseSchema, serviceSchema, serviceUsageResponseSchema, shareLinkCreateRequestSchema, shareLinkCreateResponseSchema, shareLinkDeleteResponseSchema, shareLinkDetailResponseSchema, shareLinkListResponseSchema, shareLinkSchema, shareLinkUpdateRequestSchema, shareLinkUpdateResponseSchema, sharesCreateRequestSchema, unixTimestamp, unlockPublicFile, uploadAppwriteInitRequestSchema, uploadAppwriteInitResponseSchema, uploadCompleteResponseSchema, uploadDestinationSchema, uploadFailResponseSchema, uploadLifecycleRequestSchema, uploadR2InitRequestSchema, uploadR2InitResponseSchema, uploadRecordDetailResponseSchema, uploadRecordSchema, uploadStatusSchema, uploadTypeSchema, uploadsListResponseSchema };

package/package.json

@@ -2,7 +2,7 @@
   "name": "@unisource/sdk",
   "private": false,
   "type": "module",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Wspolne kontrakty danych dla backendu i frontendu UniSource.",
   "license": "MIT",
   "publishConfig": {

package/src/client.ts

@@ -1,4 +1,4 @@
-import type { ApiError, UploadStatus } from './primitives';
+import type { ApiError, UploadDestination, UploadStatus } from './primitives';
 import type {
   UploadR2InitRequest,
   UploadR2InitResponse,
@@ -40,6 +40,16 @@ import type {
   FolderDeleteResponse,
   FolderRestoreResponse,
 } from './folders';
+import type {
+  FileRecordsListV2Query,
+  FolderListV2Query,
+  BulkFileIds,
+  BulkFileMoveRequest,
+  BulkFolderIds,
+  BulkFolderMoveRequest,
+  BulkOperationResponse,
+  FolderBreadcrumbsResponse,
+} from './v2';
 import type {
   ServiceDetailResponse,
   ServiceUsageResponse,
@@ -97,6 +107,7 @@ import type {
   ReleaseMultipartCompleteRequest,
   ReleaseMultipartCompleteResponse,
   ReleaseMultipartAbortResponse,
+  AppReleaseLatestResponse,
 } from './releases';
 
 // ─── SDK Error classes ────────────────────────────────────────────────────────
@@ -501,7 +512,10 @@ export class UnisourceClient {
       apiRequest(this.config, 'GET', '/admin/service/usage', { signal }),
 
     /** List all uploads (pending/completed/failed) for this service */
-    listUploads: (query?: { status?: UploadStatus; cursor?: string; limit?: number }, signal?: AbortSignal): Promise<UploadsListResponse> =>
+    listUploads: (
+      query?: { destination?: UploadDestination; status?: UploadStatus; cursor?: string; limit?: number },
+      signal?: AbortSignal
+    ): Promise<UploadsListResponse> =>
       apiRequest(this.config, 'GET', '/admin/files', { query, signal }),
 
     /** Get a single upload for this service */
@@ -622,4 +636,65 @@ export class UnisourceClient {
     delete: (id: string, signal?: AbortSignal): Promise<ShareLinkDeleteResponse> =>
       apiRequest(this.config, 'DELETE', `/shares/${id}`, { signal }),
   };
+
+  // ─── V2 API Endpoints ───────────────────────────────────────────────────────
+
+  readonly v2 = {
+    files: {
+      /** List files with advanced search, sorting, and filtering capabilities */
+      list: (query?: FileRecordsListV2Query, signal?: AbortSignal, options?: { asUser?: string }): Promise<FileRecordsListResponse> =>
+        apiRequest(this.config, 'GET', '/v2/files', { query, signal, extraHeaders: this.withAsUser(options) }),
+
+      /** Move multiple files at once */
+      bulkMove: (body: BulkFileMoveRequest, signal?: AbortSignal, options?: { asUser?: string }): Promise<BulkOperationResponse> =>
+        apiRequest(this.config, 'POST', '/v2/files/bulk-move', { body, signal, extraHeaders: this.withAsUser(options) }),
+
+      /** Move multiple files to trash */
+      bulkTrash: (body: BulkFileIds, signal?: AbortSignal, options?: { asUser?: string }): Promise<BulkOperationResponse> =>
+        apiRequest(this.config, 'POST', '/v2/files/bulk-trash', { body, signal, extraHeaders: this.withAsUser(options) }),
+
+      /** Restore multiple files from trash */
+      bulkRestore: (body: BulkFileIds, signal?: AbortSignal, options?: { asUser?: string }): Promise<BulkOperationResponse> =>
+        apiRequest(this.config, 'POST', '/v2/files/bulk-restore', { body, signal, extraHeaders: this.withAsUser(options) }),
+    },
+
+    folders: {
+      /** List folders with advanced search, sorting, and filtering capabilities */
+      list: (query?: FolderListV2Query, signal?: AbortSignal, options?: { asUser?: string }): Promise<FolderListResponse> =>
+        apiRequest(this.config, 'GET', '/v2/folders', { query, signal, extraHeaders: this.withAsUser(options) }),
+
+      /** Get the breadcrumb hierarchy for a specific folder */
+      breadcrumbs: (id: string, signal?: AbortSignal, options?: { asUser?: string }): Promise<FolderBreadcrumbsResponse> =>
+        apiRequest(this.config, 'GET', `/v2/folders/${id}/breadcrumbs`, { signal, extraHeaders: this.withAsUser(options) }),
+
+      /** Move multiple folders at once */
+      bulkMove: (body: BulkFolderMoveRequest, signal?: AbortSignal, options?: { asUser?: string }): Promise<BulkOperationResponse> =>
+        apiRequest(this.config, 'POST', '/v2/folders/bulk-move', { body, signal, extraHeaders: this.withAsUser(options) }),
+
+      /** Move multiple folders to trash */
+      bulkTrash: (body: BulkFolderIds, signal?: AbortSignal, options?: { asUser?: string }): Promise<BulkOperationResponse> =>
+        apiRequest(this.config, 'POST', '/v2/folders/bulk-trash', { body, signal, extraHeaders: this.withAsUser(options) }),
+
+      /** Restore multiple folders from trash */
+      bulkRestore: (body: BulkFolderIds, signal?: AbortSignal, options?: { asUser?: string }): Promise<BulkOperationResponse> =>
+        apiRequest(this.config, 'POST', '/v2/folders/bulk-restore', { body, signal, extraHeaders: this.withAsUser(options) }),
+    }
+  };
+
+  // ─── App-facing endpoints (/app/*) — public release distribution ──────────────
+
+  readonly app = {
+    releases: {
+      /**
+       * Get the latest completed release for a channel (e.g. `stable`, `beta`).
+       * Backed by `GET /app/releases/latest`. Returns the release metadata plus
+       * a short-lived presigned download URL.
+       */
+      latest: (
+        channel: string = 'stable',
+        signal?: AbortSignal
+      ): Promise<AppReleaseLatestResponse> =>
+        apiRequest(this.config, 'GET', '/app/releases/latest', { query: { channel }, signal }),
+    },
+  };
 }

package/src/fileRecords.ts

@@ -1,5 +1,12 @@
 import { z } from 'zod';
-import { nonEmptyString, positiveInt, uploadDestinationSchema, FILES_DEFAULT_LIMIT, FILES_MAX_LIMIT } from './primitives';
+import {
+  nonEmptyString,
+  nonNegativeInt,
+  positiveInt,
+  uploadDestinationSchema,
+  FILES_DEFAULT_LIMIT,
+  FILES_MAX_LIMIT,
+} from './primitives';
 
 // ─── User-facing file record ──────────────────────────────────────────────────
 
@@ -14,7 +21,8 @@ export const fileRecordSchema = z.object({
   folder_id: nonEmptyString.nullable(),
   upload_id: nonEmptyString.nullable(),
   filename: nonEmptyString,
-  size: positiveInt,
+  /** SDK6: zero-byte uploads are valid (e.g. placeholders). */
+  size: nonNegativeInt,
   mime_type: nonEmptyString,
   storage_destination: uploadDestinationSchema,
   is_trashed: z.boolean(),
@@ -88,8 +96,9 @@ export type FileRestoreResponse = z.infer<typeof fileRestoreResponseSchema>;
 
 // ─── Update (rename) ──────────────────────────────────────────────────────────
 
+/** SDK4: filename hard-capped to 255 to match backend Zod validation. */
 export const fileUpdateRequestSchema = z.object({
-  filename: nonEmptyString,
+  filename: z.string().trim().min(1).max(255),
 });
 export type FileUpdateRequest = z.infer<typeof fileUpdateRequestSchema>;
 

package/src/index.ts

@@ -2,14 +2,21 @@
 export {
   nonEmptyString,
   positiveInt,
+  nonNegativeInt,
   unixTimestamp,
   uploadDestinationSchema,
+  recommendedUploadDestinationSchema,
   uploadStatusSchema,
   apiErrorSchema,
   FILES_DEFAULT_LIMIT,
   FILES_MAX_LIMIT,
 } from './primitives';
-export type { UploadDestination, UploadStatus, ApiError } from './primitives';
+export type {
+  UploadDestination,
+  RecommendedUploadDestination,
+  UploadStatus,
+  ApiError,
+} from './primitives';
 
 
 // ─── Upload ───────────────────────────────────────────────────────────────────
@@ -188,6 +195,8 @@ export {
   releaseMultipartCompleteResponseSchema,
   releaseMultipartAbortRequestSchema,
   releaseMultipartAbortResponseSchema,
+  appReleaseLatestQuerySchema,
+  appReleaseLatestResponseSchema,
 } from './releases';
 export type {
   ReleaseDTO,
@@ -215,6 +224,8 @@ export type {
   ReleaseMultipartCompleteResponse,
   ReleaseMultipartAbortRequest,
   ReleaseMultipartAbortResponse,
+  AppReleaseLatestQuery,
+  AppReleaseLatestResponse,
 } from './releases';
 
 // ─── Share Links ─────────────────────────────────────────────────────────────
@@ -254,3 +265,25 @@ export {
   unlockPublicFile,
 } from './client';
 export type { UnisourceClientConfig } from './client';
+
+// ─── V2 API ───────────────────────────────────────────────────────────────────
+export {
+  fileRecordsListV2QuerySchema,
+  bulkFileIdsSchema,
+  bulkFileMoveRequestSchema,
+  bulkOperationResponseSchema,
+  folderListV2QuerySchema,
+  bulkFolderIdsSchema,
+  bulkFolderMoveRequestSchema,
+  folderBreadcrumbsResponseSchema,
+} from './v2';
+export type {
+  FileRecordsListV2Query,
+  BulkFileIds,
+  BulkFileMoveRequest,
+  BulkOperationResponse,
+  FolderListV2Query,
+  BulkFolderIds,
+  BulkFolderMoveRequest,
+  FolderBreadcrumbsResponse,
+} from './v2';

package/src/primitives.ts

@@ -4,6 +4,7 @@ import { z } from 'zod';
 
 export const nonEmptyString = z.string().trim().min(1);
 export const positiveInt = z.number().int().positive();
+export const nonNegativeInt = z.number().int().nonnegative();
 export const unixTimestamp = z.number().int().nonnegative();
 
 // ─── Pagination constants ─────────────────────────────────────────────────────
@@ -13,9 +14,21 @@ export const FILES_MAX_LIMIT = 100;
 
 // ─── Upload Destination ──────────────────────────────────────────────────────
 
+/**
+ * Storage backend a file lives on.
+ * - 'r2'      — Cloudflare R2 via presigned PUT / multipart
+ * - 'appwrite' — Appwrite Storage via direct browser SDK upload
+ *
+ * `recommendedUploadDestinationSchema` adds the meta-value 'hybrid' which is
+ * only valid as a service-wide setting (the upload manager picks r2/appwrite
+ * per-file based on size).
+ */
 export const uploadDestinationSchema = z.enum(['r2', 'appwrite']);
 export type UploadDestination = z.infer<typeof uploadDestinationSchema>;
 
+export const recommendedUploadDestinationSchema = z.enum(['r2', 'appwrite', 'hybrid']);
+export type RecommendedUploadDestination = z.infer<typeof recommendedUploadDestinationSchema>;
+
 // ─── Upload Status ────────────────────────────────────────────────────────────
 
 export const uploadStatusSchema = z.enum(['pending', 'completed', 'failed']);

package/src/releases.ts

@@ -208,3 +208,29 @@ export const releaseSyncResponseSchema = z.object({
   results: z.array(releaseSyncResultSchema),
 });
 export type ReleaseSyncResponse = z.infer<typeof releaseSyncResponseSchema>;
+
+// ─── App-facing /app/releases/latest ─────────────────────────────────────────
+
+/**
+ * Response of `GET /app/releases/latest?channel=...` — used by client apps to
+ * discover the most recent completed release for a given distribution channel
+ * (e.g. `stable`, `beta`). Includes a short-lived presigned download URL.
+ */
+export const appReleaseLatestQuerySchema = z.object({
+  channel: nonEmptyString.optional().default('stable'),
+});
+export type AppReleaseLatestQuery = z.input<typeof appReleaseLatestQuerySchema>;
+
+export const appReleaseLatestResponseSchema = z.object({
+  id: nonEmptyString,
+  name: nonEmptyString,
+  size: z.number().int().nonnegative(),
+  r2_key: nonEmptyString,
+  tags: z.array(nonEmptyString),
+  notes: z.string().nullable(),
+  force_update: z.boolean(),
+  created_at: nonEmptyString,
+  download_url: z.string().url(),
+  download_url_expires_at: positiveInt,
+});
+export type AppReleaseLatestResponse = z.infer<typeof appReleaseLatestResponseSchema>;

package/src/services.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { nonEmptyString, positiveInt, unixTimestamp, uploadDestinationSchema } from './primitives';
+import { nonEmptyString, positiveInt, recommendedUploadDestinationSchema, unixTimestamp } from './primitives';
 
 // ─── Service record ───────────────────────────────────────────────────────────
 
@@ -10,7 +10,7 @@ export const serviceSchema = z.object({
   max_storage_bytes: positiveInt,
   current_used_bytes: z.number().int().nonnegative(),
   max_file_size_bytes: positiveInt,
-  recommended_upload_destination: uploadDestinationSchema.optional(),
+  recommended_upload_destination: recommendedUploadDestinationSchema.optional(),
   created_at: unixTimestamp,
 });
 export type Service = z.infer<typeof serviceSchema>;
@@ -43,7 +43,7 @@ export type AdminServiceUpdateResponse = z.infer<typeof adminServiceUpdateRespon
  */
 export const adminServiceSettingsRequestSchema = z
   .object({
-    recommended_upload_destination: uploadDestinationSchema.optional(),
+    recommended_upload_destination: recommendedUploadDestinationSchema.optional(),
   })
   .refine((v) => v.recommended_upload_destination !== undefined, {
     message: 'At least one setting must be provided',

package/src/v2.ts

@@ -0,0 +1,69 @@
+import { z } from 'zod';
+import { nonEmptyString, FILES_MAX_LIMIT } from './primitives';
+import { folderSchema } from './folders';
+
+// ─── File Records V2 ─────────────────────────────────────────────────────────
+
+export const fileRecordsListV2QuerySchema = z.object({
+  folder_id: nonEmptyString.nullable().optional().transform(v => v === 'null' ? null : v),
+  is_trashed: z.enum(['true', 'false']).transform(v => v === 'true').optional(),
+  search: z.string().optional(),
+  mime_type: z.string().optional(),
+  sort_by: z.enum(['created_at', 'name', 'size']).optional(),
+  sort_dir: z.enum(['asc', 'desc']).optional(),
+  cursor: nonEmptyString.optional(),
+  limit: z.coerce.number().int().min(1).max(FILES_MAX_LIMIT).optional(),
+});
+export type FileRecordsListV2Query = z.infer<typeof fileRecordsListV2QuerySchema>;
+
+// Bulk Operations for Files
+export const bulkFileIdsSchema = z.object({
+  ids: z.array(nonEmptyString).min(1).max(100),
+});
+export type BulkFileIds = z.infer<typeof bulkFileIdsSchema>;
+
+export const bulkFileMoveRequestSchema = z.object({
+  ids: z.array(nonEmptyString).min(1).max(100),
+  folder_id: nonEmptyString.nullable().optional(),
+});
+export type BulkFileMoveRequest = z.infer<typeof bulkFileMoveRequestSchema>;
+
+export const bulkOperationResponseSchema = z.object({
+  success: z.boolean(),
+  processed_count: z.number().int().nonnegative(),
+  failed_ids: z.array(nonEmptyString).optional(),
+});
+export type BulkOperationResponse = z.infer<typeof bulkOperationResponseSchema>;
+
+
+// ─── Folders V2 ──────────────────────────────────────────────────────────────
+
+export const folderListV2QuerySchema = z.object({
+  parent_id: nonEmptyString.nullable().optional().transform(v => v === 'null' ? null : v),
+  is_trashed: z.enum(['true', 'false']).transform(v => v === 'true').optional(),
+  search: z.string().optional(),
+  sort_by: z.enum(['created_at', 'name']).optional(),
+  sort_dir: z.enum(['asc', 'desc']).optional(),
+  cursor: nonEmptyString.optional(),
+  limit: z.coerce.number().int().min(1).max(FILES_MAX_LIMIT).optional(),
+});
+export type FolderListV2Query = z.infer<typeof folderListV2QuerySchema>;
+
+// Bulk Operations for Folders
+export const bulkFolderIdsSchema = z.object({
+  ids: z.array(nonEmptyString).min(1).max(100),
+});
+export type BulkFolderIds = z.infer<typeof bulkFolderIdsSchema>;
+
+export const bulkFolderMoveRequestSchema = z.object({
+  ids: z.array(nonEmptyString).min(1).max(100),
+  parent_id: nonEmptyString.nullable().optional(),
+});
+export type BulkFolderMoveRequest = z.infer<typeof bulkFolderMoveRequestSchema>;
+
+
+// Breadcrumbs
+export const folderBreadcrumbsResponseSchema = z.object({
+  breadcrumbs: z.array(folderSchema),
+});
+export type FolderBreadcrumbsResponse = z.infer<typeof folderBreadcrumbsResponseSchema>;