@igorchugurov/public-api-sdk 1.2.0 → 1.4.0

package/LICENSE

@@ -19,4 +19,3 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
-

package/README.md

@@ -17,6 +17,7 @@ pnpm add @igorchugurov/public-api-sdk
 SDK предоставляет полный набор инструментов для работы с универсальными сущностями:
 
 ### 🔄 CRUD операции
+
 - **Получение списка** с расширенной фильтрацией, поиском и пагинацией
 - **Получение одного экземпляра** с автоматической загрузкой связей и файлов
 - **Создание** экземпляров с поддержкой relations и автоматической установкой `created_by`
@@ -24,6 +25,7 @@ SDK предоставляет полный набор инструментов
 - **Удаление** экземпляров с автоматической очисткой связей
 
 ### 🔗 Работа со связями (Relations)
+
 - Автоматическое определение relation-полей из конфигурации
 - Поддержка всех типов связей: `manyToMany`, `manyToOne`, `oneToMany`, `oneToOne`
 - Batch-загрузка связанных объектов для оптимизации производительности
@@ -31,33 +33,39 @@ SDK предоставляет полный набор инструментов
 - Опция получения relations как ID или полных объектов
 
 ### 🔍 Поиск и фильтрация
+
 - **Умный поиск** по полям с флагом `searchable: true`
 - **JSONB фильтрация** для обычных полей
 - **Relation фильтрация** с автоматическим определением relation-полей
 - **Гибкая сортировка** по любому полю с поддержкой `asc`/`desc`
 
 ### 📁 Работа с файлами
+
 - Автоматическая загрузка файлов и изображений для полей типа `files` и `images`
 - Batch-загрузка файлов для оптимизации запросов
 - Поддержка множественных файлов на поле
 
 ### ⚡ Производительность
+
 - **Кэширование конфигурации** EntityDefinition и Fields (TTL: 5 минут по умолчанию)
 - **Batch-запросы** для relations и файлов
 - **Оптимизированные RPC функции** для поиска и загрузки связей
 - Поддержка ESM и CJS форматов
 
 ### 🎯 Типобезопасность
+
 - Полная типизация всех методов и параметров
 - Экспорт всех типов для использования в вашем коде
 - Типизированные ошибки для удобной обработки
 
 ### 🔐 Безопасность
+
 - Интеграция с Supabase RLS (Row Level Security)
 - Автоматическая проверка прав доступа
 - Типизированные ошибки для различных сценариев доступа
 
 ### 🎨 UI конфигурация
+
 - Автоматическая генерация UI конфигурации из EntityDefinition и Fields
 - Поддержка кастомных UI настроек
 - Генерация конфигурации колонок таблицы из полей
@@ -67,8 +75,8 @@ SDK предоставляет полный набор инструментов
 ### 1. Server Component (SSR)
 
 ```typescript
-import { createServerSDK } from '@igorchugurov/public-api-sdk/server';
-import { cookies } from 'next/headers';
+import { createServerSDK } from "@igorchugurov/public-api-sdk/server";
+import { cookies } from "next/headers";
 
 export default async function MyPage({ params }) {
   const { projectId } = await params;
@@ -97,7 +105,7 @@ export default async function MyPage({ params }) {
   const { data, pagination } = await sdk.getInstances(entityDefinitionId, {
     page: 1,
     limit: 20,
-    search: 'test',
+    search: "test",
   });
 
   return <div>{/* ... */}</div>;
@@ -107,9 +115,9 @@ export default async function MyPage({ params }) {
 ### 2. Client Component
 
 ```typescript
-'use client';
+"use client";
 
-import { createClientSDK } from '@igorchugurov/public-api-sdk';
+import { createClientSDK } from "@igorchugurov/public-api-sdk";
 
 const sdk = createClientSDK(
   projectId,
@@ -157,14 +165,25 @@ const { data, pagination } = await sdk.getInstances(entityDefinitionId, {
 ```typescript
 const instance = await sdk.getInstance(entityDefinitionId, id, {
   relationsAsIds?: boolean; // default: false
+  loadFiles?: boolean; // default: false
 });
 ```
 
 **Пример:**
 
 ```typescript
+// Базовое использование - без файлов
+const instance = await sdk.getInstance("entity-def-id", "instance-id");
+
+// Для редактирования - нужны только ID связей
 const instance = await sdk.getInstance("entity-def-id", "instance-id", {
-  relationsAsIds: true, // для редактирования - нужны только ID
+  relationsAsIds: true,
+});
+
+// Для отображения с файлами - полные объекты
+const instance = await sdk.getInstance("entity-def-id", "instance-id", {
+  relationsAsIds: false,
+  loadFiles: true, // файлы и изображения будут загружены как полные объекты EntityFile
 });
 ```
 
@@ -175,24 +194,41 @@ const instance = await sdk.getInstance("entity-def-id", "instance-id", {
 ```typescript
 const instance = await sdk.getInstanceBySlug(entityDefinitionId, slug, {
   relationsAsIds?: boolean; // default: false
+  loadFiles?: boolean; // default: false
 });
 ```
 
 **Пример:**
 
 ```typescript
-const instance = await sdk.getInstanceBySlug("entity-def-id", "my-article-slug", {
-  relationsAsIds: false, // для отображения - нужны полные объекты
-});
+// Базовое использование - без файлов
+const instance = await sdk.getInstanceBySlug(
+  "entity-def-id",
+  "my-article-slug"
+);
+
+// Для отображения с файлами - полные объекты
+const instance = await sdk.getInstanceBySlug(
+  "entity-def-id",
+  "my-article-slug",
+  {
+    relationsAsIds: false,
+    loadFiles: true, // файлы и изображения будут загружены как полные объекты EntityFile
+  }
+);
 ```
 
 **Особенности:**
+
 - Валидирует формат slug перед запросом (только строчные латинские буквы, цифры и дефисы)
 - Работает аналогично `getInstance`, но ищет по slug вместо id
-- Поддерживает те же параметры, что и `getInstance` (relationsAsIds)
+- Поддерживает те же параметры, что и `getInstance`
 - Параметр `relationsAsIds`:
   - `false` (по умолчанию) - возвращает полные объекты связанных сущностей
   - `true` - возвращает только массивы ID связанных сущностей
+- Параметр `loadFiles`:
+  - `false` (по умолчанию) - файлы и изображения не загружаются
+  - `true` - файлы и изображения загружаются как полные объекты `EntityFile` (с `fileUrl`, `fileName`, `fileSize` и т.д.)
 
 #### `createInstance(entityDefinitionId, data)`
 
@@ -206,6 +242,7 @@ const instance = await sdk.createInstance(entityDefinitionId, {
 ```
 
 **Особенности:**
+
 - Автоматически генерирует уникальный `slug` из поля `name`
 - Если slug уже существует, добавляет случайный суффикс
 - Автоматически устанавливает `created_by` из текущего пользователя
@@ -270,7 +307,7 @@ import type {
   CreateInstanceData,
   UpdateInstanceData,
   PaginationResult,
-} from '@igorchugurov/public-api-sdk';
+} from "@igorchugurov/public-api-sdk";
 ```
 
 ### Slug поддержка
@@ -308,7 +345,7 @@ import {
   ValidationError,
   AuthenticationError,
   SDKError,
-} from '@igorchugurov/public-api-sdk';
+} from "@igorchugurov/public-api-sdk";
 
 try {
   const instance = await sdk.getInstance(entityDefinitionId, id);
@@ -355,4 +392,3 @@ pnpm dev
 ## 📄 Лицензия
 
 MIT
-

package/dist/{client-DS5xnLAo.d.mts → client-BTvcDpY4.d.mts}

@@ -164,6 +164,8 @@ interface Field {
     selectorRelationId?: string | null;
     relationFieldName?: string | null;
     relationFieldLabel?: string | null;
+    relationFieldRequired?: boolean;
+    relationFieldRequiredText?: string | null;
     defaultStringValue?: string | null;
     defaultNumberValue?: number | null;
     defaultBooleanValue?: boolean | null;
@@ -177,6 +179,7 @@ interface Field {
     foreignKeyValue?: string | null;
     typeFieldName?: string | null;
     optionsFieldName?: string | null;
+    exclude?: string | null;
     acceptFileTypes?: string | null;
     maxFileSize?: number | null;
     maxFiles?: number | null;
@@ -1108,9 +1111,11 @@ declare abstract class BasePublicAPIClient {
     }>;
     abstract getInstance(entityDefinitionId: string, id: string, params?: {
         relationsAsIds?: boolean;
+        loadFiles?: boolean;
     }): Promise<EntityInstanceWithFields>;
     abstract getInstanceBySlug(entityDefinitionId: string, slug: string, params?: {
         relationsAsIds?: boolean;
+        loadFiles?: boolean;
     }): Promise<EntityInstanceWithFields>;
     abstract createInstance(entityDefinitionId: string, data: CreateInstanceData): Promise<EntityInstanceWithFields>;
     abstract updateInstance(entityDefinitionId: string, id: string, data: UpdateInstanceData): Promise<EntityInstanceWithFields>;
@@ -1149,17 +1154,24 @@ declare class PublicAPIClient extends BasePublicAPIClient {
      * Получить режим работы клиента (для отладки)
      */
     getMode(): "server" | "client";
+    /**
+     * Загружает файлы для экземпляра и возвращает их как полные объекты EntityFile,
+     * сгруппированные по именам полей
+     */
+    private loadFilesForInstance;
     /**
      * Получить один экземпляр
      */
     getInstance(entityDefinitionId: string, id: string, params?: {
         relationsAsIds?: boolean;
+        loadFiles?: boolean;
     }): Promise<EntityInstanceWithFields>;
     /**
      * Получить один экземпляр по slug
      */
     getInstanceBySlug(entityDefinitionId: string, slug: string, params?: {
         relationsAsIds?: boolean;
+        loadFiles?: boolean;
     }): Promise<EntityInstanceWithFields>;
     /**
      * Получить список экземпляров

package/dist/{client-DS5xnLAo.d.ts → client-BTvcDpY4.d.ts}

@@ -164,6 +164,8 @@ interface Field {
     selectorRelationId?: string | null;
     relationFieldName?: string | null;
     relationFieldLabel?: string | null;
+    relationFieldRequired?: boolean;
+    relationFieldRequiredText?: string | null;
     defaultStringValue?: string | null;
     defaultNumberValue?: number | null;
     defaultBooleanValue?: boolean | null;
@@ -177,6 +179,7 @@ interface Field {
     foreignKeyValue?: string | null;
     typeFieldName?: string | null;
     optionsFieldName?: string | null;
+    exclude?: string | null;
     acceptFileTypes?: string | null;
     maxFileSize?: number | null;
     maxFiles?: number | null;
@@ -1108,9 +1111,11 @@ declare abstract class BasePublicAPIClient {
     }>;
     abstract getInstance(entityDefinitionId: string, id: string, params?: {
         relationsAsIds?: boolean;
+        loadFiles?: boolean;
     }): Promise<EntityInstanceWithFields>;
     abstract getInstanceBySlug(entityDefinitionId: string, slug: string, params?: {
         relationsAsIds?: boolean;
+        loadFiles?: boolean;
     }): Promise<EntityInstanceWithFields>;
     abstract createInstance(entityDefinitionId: string, data: CreateInstanceData): Promise<EntityInstanceWithFields>;
     abstract updateInstance(entityDefinitionId: string, id: string, data: UpdateInstanceData): Promise<EntityInstanceWithFields>;
@@ -1149,17 +1154,24 @@ declare class PublicAPIClient extends BasePublicAPIClient {
      * Получить режим работы клиента (для отладки)
      */
     getMode(): "server" | "client";
+    /**
+     * Загружает файлы для экземпляра и возвращает их как полные объекты EntityFile,
+     * сгруппированные по именам полей
+     */
+    private loadFilesForInstance;
     /**
      * Получить один экземпляр
      */
     getInstance(entityDefinitionId: string, id: string, params?: {
         relationsAsIds?: boolean;
+        loadFiles?: boolean;
     }): Promise<EntityInstanceWithFields>;
     /**
      * Получить один экземпляр по slug
      */
     getInstanceBySlug(entityDefinitionId: string, slug: string, params?: {
         relationsAsIds?: boolean;
+        loadFiles?: boolean;
     }): Promise<EntityInstanceWithFields>;
     /**
      * Получить список экземпляров

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { F as FieldConfig, a as FieldValue, E as EntityDefinition, b as Field, c as EntityUIConfig, C as ColumnConfig, S as SDKOptions, P as PublicAPIClient } from './client-DS5xnLAo.mjs';
-export { y as ActionConfig, A as AuthResult, g as CreateInstanceData, D as DbType, l as DbTypeToTSType, m as EntityData, e as EntityDefinitionConfig, x as EntityFile, n as EntityInstance, q as EntityInstanceWithFields, p as EntityRelation, k as FieldOption, j as FieldType, r as FilterValue, z as FormPageConfig, G as GetInstancesOptions, I as InstanceData, L as ListPageConfig, M as MessagesConfig, h as PaginationResult, w as PartialInstanceData, B as PartialUIConfig, d as ProjectConfig, Q as QueryParams, R as RelationFilterInfo, f as RelationFilterMode, o as RelationType, s as RelationsData, i as SignUpData, U as UpdateInstanceData, v as getFieldValue, u as isEntityData, t as isFieldValue } from './client-DS5xnLAo.mjs';
+import { F as FieldConfig, a as FieldValue, E as EntityDefinition, b as Field, c as EntityUIConfig, C as ColumnConfig, S as SDKOptions, P as PublicAPIClient } from './client-BTvcDpY4.mjs';
+export { y as ActionConfig, A as AuthResult, g as CreateInstanceData, D as DbType, l as DbTypeToTSType, m as EntityData, e as EntityDefinitionConfig, x as EntityFile, n as EntityInstance, q as EntityInstanceWithFields, p as EntityRelation, k as FieldOption, j as FieldType, r as FilterValue, z as FormPageConfig, G as GetInstancesOptions, I as InstanceData, L as ListPageConfig, M as MessagesConfig, h as PaginationResult, w as PartialInstanceData, B as PartialUIConfig, d as ProjectConfig, Q as QueryParams, R as RelationFilterInfo, f as RelationFilterMode, o as RelationType, s as RelationsData, i as SignUpData, U as UpdateInstanceData, v as getFieldValue, u as isEntityData, t as isFieldValue } from './client-BTvcDpY4.mjs';
 import '@supabase/supabase-js';
 
 /**

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { F as FieldConfig, a as FieldValue, E as EntityDefinition, b as Field, c as EntityUIConfig, C as ColumnConfig, S as SDKOptions, P as PublicAPIClient } from './client-DS5xnLAo.js';
-export { y as ActionConfig, A as AuthResult, g as CreateInstanceData, D as DbType, l as DbTypeToTSType, m as EntityData, e as EntityDefinitionConfig, x as EntityFile, n as EntityInstance, q as EntityInstanceWithFields, p as EntityRelation, k as FieldOption, j as FieldType, r as FilterValue, z as FormPageConfig, G as GetInstancesOptions, I as InstanceData, L as ListPageConfig, M as MessagesConfig, h as PaginationResult, w as PartialInstanceData, B as PartialUIConfig, d as ProjectConfig, Q as QueryParams, R as RelationFilterInfo, f as RelationFilterMode, o as RelationType, s as RelationsData, i as SignUpData, U as UpdateInstanceData, v as getFieldValue, u as isEntityData, t as isFieldValue } from './client-DS5xnLAo.js';
+import { F as FieldConfig, a as FieldValue, E as EntityDefinition, b as Field, c as EntityUIConfig, C as ColumnConfig, S as SDKOptions, P as PublicAPIClient } from './client-BTvcDpY4.js';
+export { y as ActionConfig, A as AuthResult, g as CreateInstanceData, D as DbType, l as DbTypeToTSType, m as EntityData, e as EntityDefinitionConfig, x as EntityFile, n as EntityInstance, q as EntityInstanceWithFields, p as EntityRelation, k as FieldOption, j as FieldType, r as FilterValue, z as FormPageConfig, G as GetInstancesOptions, I as InstanceData, L as ListPageConfig, M as MessagesConfig, h as PaginationResult, w as PartialInstanceData, B as PartialUIConfig, d as ProjectConfig, Q as QueryParams, R as RelationFilterInfo, f as RelationFilterMode, o as RelationType, s as RelationsData, i as SignUpData, U as UpdateInstanceData, v as getFieldValue, u as isEntityData, t as isFieldValue } from './client-BTvcDpY4.js';
 import '@supabase/supabase-js';
 
 /**

package/dist/index.js

@@ -765,6 +765,22 @@ function flattenInstance(instance, fields, relationsAsIds = false) {
   }
   return result;
 }
+function transformEntityFile(row) {
+  return {
+    id: row.id,
+    entityInstanceId: row.entity_instance_id,
+    fieldId: row.field_id,
+    fileUrl: row.file_url,
+    filePath: row.file_path,
+    fileName: row.file_name,
+    fileSize: row.file_size,
+    fileType: row.file_type,
+    storageBucket: row.storage_bucket,
+    uploadedBy: row.uploaded_by,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at
+  };
+}
 
 // src/client.ts
 init_slug();
@@ -797,6 +813,42 @@ var _PublicAPIClient = class _PublicAPIClient extends BasePublicAPIClient {
   getMode() {
     return this.mode;
   }
+  /**
+   * Загружает файлы для экземпляра и возвращает их как полные объекты EntityFile,
+   * сгруппированные по именам полей
+   */
+  async loadFilesForInstance(instanceId, fileFields) {
+    if (fileFields.length === 0) {
+      return /* @__PURE__ */ new Map();
+    }
+    const { data: allFiles, error: filesError } = await this.supabase.from("entity_file").select("*").eq("entity_instance_id", instanceId);
+    if (filesError) {
+      throw new SDKError(
+        "FILES_LOAD_ERROR",
+        `Failed to load files for instance ${instanceId}: ${filesError.message}`,
+        500,
+        filesError
+      );
+    }
+    if (!allFiles || allFiles.length === 0) {
+      return /* @__PURE__ */ new Map();
+    }
+    const filesMap = /* @__PURE__ */ new Map();
+    const fieldIdToName = new Map(
+      fileFields.map((f) => [f.id, f.name])
+    );
+    allFiles.forEach((fileRow) => {
+      if (!fileRow.field_id) return;
+      const fieldName = fieldIdToName.get(fileRow.field_id);
+      if (!fieldName) return;
+      const entityFile = transformEntityFile(fileRow);
+      if (!filesMap.has(fieldName)) {
+        filesMap.set(fieldName, []);
+      }
+      filesMap.get(fieldName).push(entityFile);
+    });
+    return filesMap;
+  }
   /**
    * Получить один экземпляр
    */
@@ -873,34 +925,15 @@ var _PublicAPIClient = class _PublicAPIClient extends BasePublicAPIClient {
           }
         }
       }
-      const fileFields = fields.filter(
-        (f) => f.type === "files" || f.type === "images"
-      );
-      if (fileFields.length > 0) {
-        const { data: allFiles, error: filesError } = await this.supabase.from("entity_file").select("id, field_id").eq("entity_instance_id", id);
-        if (filesError) {
-          throw new SDKError(
-            "FILES_LOAD_ERROR",
-            `Failed to load files for instance ${id}: ${filesError.message}`,
-            500,
-            filesError
-          );
-        }
-        if (allFiles) {
-          const filesByFieldId = /* @__PURE__ */ new Map();
-          allFiles.forEach((file) => {
-            if (file.field_id) {
-              if (!filesByFieldId.has(file.field_id)) {
-                filesByFieldId.set(file.field_id, []);
-              }
-              filesByFieldId.get(file.field_id).push(file.id);
-            }
-          });
+      if ((params == null ? void 0 : params.loadFiles) === true) {
+        const fileFields = fields.filter(
+          (f) => f.type === "files" || f.type === "images"
+        );
+        if (fileFields.length > 0) {
+          const filesMap = await this.loadFilesForInstance(id, fileFields);
           fileFields.forEach((field) => {
-            const fileIds = filesByFieldId.get(field.id) || [];
-            if (fileIds.length > 0 || !transformedInstance.data[field.name]) {
-              transformedInstance.data[field.name] = fileIds;
-            }
+            const files = filesMap.get(field.name) || [];
+            transformedInstance.data[field.name] = files;
           });
         }
       }
@@ -1001,34 +1034,18 @@ var _PublicAPIClient = class _PublicAPIClient extends BasePublicAPIClient {
           }
         }
       }
-      const fileFields = fields.filter(
-        (f) => f.type === "files" || f.type === "images"
-      );
-      if (fileFields.length > 0) {
-        const { data: allFiles, error: filesError } = await this.supabase.from("entity_file").select("id, field_id").eq("entity_instance_id", transformedInstance.id);
-        if (filesError) {
-          throw new SDKError(
-            "FILES_LOAD_ERROR",
-            `Failed to load files for instance with slug ${slug}: ${filesError.message}`,
-            500,
-            filesError
+      if ((params == null ? void 0 : params.loadFiles) === true) {
+        const fileFields = fields.filter(
+          (f) => f.type === "files" || f.type === "images"
+        );
+        if (fileFields.length > 0) {
+          const filesMap = await this.loadFilesForInstance(
+            transformedInstance.id,
+            fileFields
           );
-        }
-        if (allFiles) {
-          const filesByFieldId = /* @__PURE__ */ new Map();
-          allFiles.forEach((file) => {
-            if (file.field_id) {
-              if (!filesByFieldId.has(file.field_id)) {
-                filesByFieldId.set(file.field_id, []);
-              }
-              filesByFieldId.get(file.field_id).push(file.id);
-            }
-          });
           fileFields.forEach((field) => {
-            const fileIds = filesByFieldId.get(field.id) || [];
-            if (fileIds.length > 0 || !transformedInstance.data[field.name]) {
-              transformedInstance.data[field.name] = fileIds;
-            }
+            const files = filesMap.get(field.name) || [];
+            transformedInstance.data[field.name] = files;
           });
         }
       }