@igorchugurov/public-api-sdk 1.0.0 → 1.1.0

package/README.md

@@ -12,6 +12,56 @@ pnpm add @igorchugurov/public-api-sdk@workspace:*
 pnpm add @igorchugurov/public-api-sdk
 ```
 
+## ✨ Возможности
+
+SDK предоставляет полный набор инструментов для работы с универсальными сущностями:
+
+### 🔄 CRUD операции
+- **Получение списка** с расширенной фильтрацией, поиском и пагинацией
+- **Получение одного экземпляра** с автоматической загрузкой связей и файлов
+- **Создание** экземпляров с поддержкой relations и автоматической установкой `created_by`
+- **Обновление** экземпляров с поддержкой частичных обновлений и relations
+- **Удаление** экземпляров с автоматической очисткой связей
+
+### 🔗 Работа со связями (Relations)
+- Автоматическое определение relation-полей из конфигурации
+- Поддержка всех типов связей: `manyToMany`, `manyToOne`, `oneToMany`, `oneToOne`
+- Batch-загрузка связанных объектов для оптимизации производительности
+- Фильтрация по relations с режимами `any` (OR) и `all` (AND)
+- Опция получения 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 настроек
+- Генерация конфигурации колонок таблицы из полей
+
 ## 🚀 Быстрый старт
 
 ### 1. Server Component (SSR)
@@ -112,15 +162,21 @@ const instance = await sdk.getInstance(entityDefinitionId, id, {
 
 #### `createInstance(entityDefinitionId, data)`
 
-Создать новый экземпляр.
+Создать новый экземпляр. Автоматически генерирует уникальный `slug` из поля `name`.
 
 ```typescript
 const instance = await sdk.createInstance(entityDefinitionId, {
-  data: Record<string, unknown>;
+  data: Record<string, unknown>; // Обязательно должно содержать поле 'name' (string)
   relations?: Record<string, string[]>;
 });
 ```
 
+**Особенности:**
+- Автоматически генерирует уникальный `slug` из поля `name`
+- Если slug уже существует, добавляет случайный суффикс
+- Автоматически устанавливает `created_by` из текущего пользователя
+- Поддерживает создание relations в одном запросе
+
 #### `updateInstance(entityDefinitionId, id, data)`
 
 Обновить экземпляр.
@@ -159,6 +215,16 @@ const config = await sdk.getEntityDefinitionWithUIConfig(entityDefinitionId);
 // config: { entityDefinition, fields, uiConfig }
 ```
 
+#### `getAllEntityDefinitions()`
+
+Получить все EntityDefinitions проекта с полями одним запросом (JOIN). Используется для загрузки всех сущностей в layout.
+
+```typescript
+const entityDefinitions = await sdk.getAllEntityDefinitions();
+// Возвращает массив EntityDefinitionConfig с полями
+// Каждый элемент содержит: { id, name, slug, fields, ... }
+```
+
 ## 🔧 Типы
 
 ```typescript
@@ -173,6 +239,30 @@ import type {
 } from '@igorchugurov/public-api-sdk';
 ```
 
+### Slug поддержка
+
+Все экземпляры и определения сущностей теперь содержат поле `slug`:
+
+```typescript
+// EntityInstance содержит slug
+const instance: EntityInstanceWithFields = {
+  id: string;
+  slug: string; // URL-friendly идентификатор
+  entityDefinitionId: string;
+  // ...
+};
+
+// EntityDefinition также содержит slug
+const entityDef: EntityDefinition = {
+  id: string;
+  name: string;
+  slug: string; // URL-friendly идентификатор
+  // ...
+};
+```
+
+Slug автоматически генерируется при создании экземпляра из поля `name` и гарантирует уникальность в рамках одной EntityDefinition.
+
 ## 🛠️ Обработка ошибок
 
 SDK использует типизированные ошибки:

package/dist/{client-DqqjGYgA.d.mts → client-BV5AAKYo.d.mts}

@@ -109,6 +109,7 @@ type PartialUIConfig = {
 interface EntityDefinition {
     id: string;
     name: string;
+    slug: string;
     description?: string | null;
     tableName: string;
     type: "primary" | "secondary" | "tertiary";
@@ -207,6 +208,7 @@ type DbTypeToTSType = {
 type EntityData<T extends Record<string, FieldValue> = Record<string, FieldValue>> = T;
 interface EntityInstance<TData extends Record<string, FieldValue> = Record<string, FieldValue>> {
     id: string;
+    slug: string;
     entityDefinitionId: string;
     projectId: string;
     data: EntityData<TData>;
@@ -230,6 +232,7 @@ interface EntityRelation {
  */
 type EntityInstanceWithFields<TFields extends Record<string, FieldValue> = Record<string, FieldValue>> = {
     id: string;
+    slug: string;
     entityDefinitionId: string;
     projectId: string;
     createdAt: string;
@@ -318,6 +321,7 @@ interface ProjectConfig {
 interface EntityDefinitionConfig {
     id: string;
     name: string;
+    slug: string;
     description?: string | null;
     tableName: string;
     type: "primary" | "secondary" | "tertiary";
@@ -1067,6 +1071,13 @@ declare abstract class BasePublicAPIClient {
      * @returns EntityDefinitionConfig с полями, отсортированными по display_index
      */
     getEntityDefinitionConfig(entityDefinitionId: string): Promise<EntityDefinitionConfig>;
+    /**
+     * Получить все EntityDefinitions проекта с полями одним запросом (JOIN)
+     * Используется для загрузки всех сущностей в layout
+     *
+     * @returns Массив EntityDefinitionConfig с полями
+     */
+    getAllEntityDefinitions(): Promise<EntityDefinitionConfig[]>;
     /**
      * Преобразование EntityDefinitionConfig в EntityDefinition
      */

package/dist/{client-DqqjGYgA.d.ts → client-BV5AAKYo.d.ts}

@@ -109,6 +109,7 @@ type PartialUIConfig = {
 interface EntityDefinition {
     id: string;
     name: string;
+    slug: string;
     description?: string | null;
     tableName: string;
     type: "primary" | "secondary" | "tertiary";
@@ -207,6 +208,7 @@ type DbTypeToTSType = {
 type EntityData<T extends Record<string, FieldValue> = Record<string, FieldValue>> = T;
 interface EntityInstance<TData extends Record<string, FieldValue> = Record<string, FieldValue>> {
     id: string;
+    slug: string;
     entityDefinitionId: string;
     projectId: string;
     data: EntityData<TData>;
@@ -230,6 +232,7 @@ interface EntityRelation {
  */
 type EntityInstanceWithFields<TFields extends Record<string, FieldValue> = Record<string, FieldValue>> = {
     id: string;
+    slug: string;
     entityDefinitionId: string;
     projectId: string;
     createdAt: string;
@@ -318,6 +321,7 @@ interface ProjectConfig {
 interface EntityDefinitionConfig {
     id: string;
     name: string;
+    slug: string;
     description?: string | null;
     tableName: string;
     type: "primary" | "secondary" | "tertiary";
@@ -1067,6 +1071,13 @@ declare abstract class BasePublicAPIClient {
      * @returns EntityDefinitionConfig с полями, отсортированными по display_index
      */
     getEntityDefinitionConfig(entityDefinitionId: string): Promise<EntityDefinitionConfig>;
+    /**
+     * Получить все EntityDefinitions проекта с полями одним запросом (JOIN)
+     * Используется для загрузки всех сущностей в layout
+     *
+     * @returns Массив EntityDefinitionConfig с полями
+     */
+    getAllEntityDefinitions(): Promise<EntityDefinitionConfig[]>;
     /**
      * Преобразование EntityDefinitionConfig в EntityDefinition
      */

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-DqqjGYgA.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-DqqjGYgA.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-BV5AAKYo.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-BV5AAKYo.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-DqqjGYgA.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-DqqjGYgA.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-BV5AAKYo.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-BV5AAKYo.js';
 import '@supabase/supabase-js';
 
 /**

package/dist/index.js

@@ -5,6 +5,7 @@ var ssr = require('@supabase/ssr');
 var __defProp = Object.defineProperty;
 var __defProps = Object.defineProperties;
 var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
+var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getOwnPropSymbols = Object.getOwnPropertySymbols;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __propIsEnum = Object.prototype.propertyIsEnumerable;
@@ -21,6 +22,50 @@ var __spreadValues = (a, b) => {
   return a;
 };
 var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/utils/slug.ts
+var slug_exports = {};
+__export(slug_exports, {
+  generateSlug: () => generateSlug,
+  generateUniqueSlugForInstance: () => generateUniqueSlugForInstance
+});
+function generateSlug(name) {
+  if (!name || typeof name !== "string") {
+    throw new Error("Name must be a non-empty string");
+  }
+  return name.toLowerCase().trim().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").substring(0, 100);
+}
+function generateRandomSuffix() {
+  return Math.random().toString(36).substring(2, 6);
+}
+async function generateUniqueSlugForInstance(name, entityDefinitionId, checkExists, excludeId) {
+  const baseSlug = generateSlug(name);
+  let slug = baseSlug;
+  let attempts = 0;
+  const maxAttempts = 100;
+  while (attempts < maxAttempts) {
+    const exists = await checkExists(slug, entityDefinitionId, excludeId);
+    if (!exists) {
+      return slug;
+    }
+    const randomSuffix = generateRandomSuffix();
+    slug = `${baseSlug}-${randomSuffix}`;
+    attempts++;
+  }
+  const timestamp = Date.now().toString(36);
+  return `${baseSlug}-${timestamp}`;
+}
+var init_slug = __esm({
+  "src/utils/slug.ts"() {
+  }
+});
 
 // src/types/entity-types.ts
 function isFieldValue(value) {
@@ -397,6 +442,7 @@ var BasePublicAPIClient = class {
     return {
       id: row.id,
       name: row.name,
+      slug: row.slug,
       description: row.description,
       tableName: row.table_name,
       type: row.type,
@@ -519,6 +565,38 @@ var BasePublicAPIClient = class {
     }
     return config;
   }
+  /**
+   * Получить все EntityDefinitions проекта с полями одним запросом (JOIN)
+   * Используется для загрузки всех сущностей в layout
+   *
+   * @returns Массив EntityDefinitionConfig с полями
+   */
+  async getAllEntityDefinitions() {
+    const { data, error } = await this.supabase.from("entity_definition").select(
+      `
+        *,
+        field!field_entity_definition_id_fkey (*)
+      `
+    ).eq("project_id", this.projectId).order("name");
+    if (error) {
+      throw new Error(`Failed to load entity definitions: ${error.message}`);
+    }
+    if (!data || data.length === 0) {
+      return [];
+    }
+    return data.map((row) => {
+      const entityDefinition = this.transformEntityDefinitionFromDB(row);
+      const fields = (row.field || []).map(
+        (fieldRow) => this.transformFieldFromDB(fieldRow)
+      );
+      fields.sort(
+        (a, b) => a.displayIndex - b.displayIndex
+      );
+      return __spreadProps(__spreadValues({}, entityDefinition), {
+        fields
+      });
+    });
+  }
   /**
    * Преобразование EntityDefinitionConfig в EntityDefinition
    */
@@ -526,6 +604,7 @@ var BasePublicAPIClient = class {
     return {
       id: config.id,
       name: config.name,
+      slug: config.slug,
       description: config.description,
       tableName: config.tableName,
       type: config.type,
@@ -637,6 +716,7 @@ var BasePublicAPIClient = class {
 function transformEntityInstance(row) {
   return {
     id: row.id,
+    slug: row.slug,
     entityDefinitionId: row.entity_definition_id,
     projectId: row.project_id,
     data: row.data || {},
@@ -647,6 +727,7 @@ function transformEntityInstance(row) {
 function flattenInstance(instance, fields, relationsAsIds = false) {
   const result = {
     id: instance.id,
+    slug: instance.slug,
     entityDefinitionId: instance.entityDefinitionId,
     projectId: instance.projectId,
     createdAt: instance.createdAt,
@@ -1214,9 +1295,27 @@ var _PublicAPIClient = class _PublicAPIClient extends BasePublicAPIClient {
         );
       }
       const { data: instanceData, relations } = data;
+      const name = instanceData.name;
+      if (!name || typeof name !== "string") {
+        throw new Error(
+          "Field 'name' is required and must be a string for slug generation"
+        );
+      }
+      const {
+        generateUniqueSlugForInstance: generateUniqueSlugForInstance2
+      } = await Promise.resolve().then(() => (init_slug(), slug_exports));
+      const slug = await generateUniqueSlugForInstance2(
+        name,
+        entityDefinitionId,
+        async (slugToCheck, entityDefIdToCheck) => {
+          const { data: existing } = await this.supabase.from("entity_instance").select("id").eq("entity_definition_id", entityDefIdToCheck).eq("slug", slugToCheck).single();
+          return !!existing;
+        }
+      );
       const { data: instance, error: instanceError } = await this.supabase.from("entity_instance").insert({
         entity_definition_id: entityDefinitionId,
         project_id: this.projectId,
+        slug,
         data: instanceData,
         created_by: (user == null ? void 0 : user.id) || null
       }).select().single();