@igorchugurov/public-api-sdk 1.1.0 → 1.3.0

package/LICENSE

@@ -20,3 +20,4 @@ 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

@@ -152,14 +152,68 @@ const { data, pagination } = await sdk.getInstances(entityDefinitionId, {
 
 #### `getInstance(entityDefinitionId, id, params?)`
 
-Получить один экземпляр.
+Получить один экземпляр по ID.
 
 ```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,
+});
+
+// Для отображения с файлами - полные объекты
+const instance = await sdk.getInstance("entity-def-id", "instance-id", {
+  relationsAsIds: false,
+  loadFiles: true, // файлы и изображения будут загружены как полные объекты EntityFile
+});
+```
+
+#### `getInstanceBySlug(entityDefinitionId, slug, params?)`
+
+Получить один экземпляр по slug.
+
+```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");
+
+// Для отображения с файлами - полные объекты
+const instance = await sdk.getInstanceBySlug("entity-def-id", "my-article-slug", {
+  relationsAsIds: false,
+  loadFiles: true, // файлы и изображения будут загружены как полные объекты EntityFile
+});
+```
+
+**Особенности:**
+- Валидирует формат slug перед запросом (только строчные латинские буквы, цифры и дефисы)
+- Работает аналогично `getInstance`, но ищет по slug вместо id
+- Поддерживает те же параметры, что и `getInstance`
+- Параметр `relationsAsIds`:
+  - `false` (по умолчанию) - возвращает полные объекты связанных сущностей
+  - `true` - возвращает только массивы ID связанных сущностей
+- Параметр `loadFiles`:
+  - `false` (по умолчанию) - файлы и изображения не загружаются
+  - `true` - файлы и изображения загружаются как полные объекты `EntityFile` (с `fileUrl`, `fileName`, `fileSize` и т.д.)
+
 #### `createInstance(entityDefinitionId, data)`
 
 Создать новый экземпляр. Автоматически генерирует уникальный `slug` из поля `name`.
@@ -322,3 +376,4 @@ pnpm dev
 
 MIT
 
+

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

@@ -1108,6 +1108,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>;
@@ -1146,11 +1151,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-BV5AAKYo.d.ts → client-D3jtlTId.d.ts}

@@ -1108,6 +1108,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>;
@@ -1146,11 +1151,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-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 { 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-D3jtlTId.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-D3jtlTId.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-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 { 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-D3jtlTId.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-D3jtlTId.js';
 import '@supabase/supabase-js';
 
 /**

package/dist/index.js

@@ -34,7 +34,8 @@ var __export = (target, all) => {
 var slug_exports = {};
 __export(slug_exports, {
   generateSlug: () => generateSlug,
-  generateUniqueSlugForInstance: () => generateUniqueSlugForInstance
+  generateUniqueSlugForInstance: () => generateUniqueSlugForInstance,
+  validateSlug: () => validateSlug
 });
 function generateSlug(name) {
   if (!name || typeof name !== "string") {
@@ -42,6 +43,16 @@ function generateSlug(name) {
   }
   return name.toLowerCase().trim().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").substring(0, 100);
 }
+function validateSlug(slug) {
+  if (!slug || typeof slug !== "string") {
+    return false;
+  }
+  if (slug.length === 0 || slug.length > 100) {
+    return false;
+  }
+  const slugRegex = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+  return slugRegex.test(slug);
+}
 function generateRandomSuffix() {
   return Math.random().toString(36).substring(2, 6);
 }
@@ -754,8 +765,25 @@ 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();
 var _PublicAPIClient = class _PublicAPIClient extends BasePublicAPIClient {
   constructor(supabase, projectId, mode, options = {}) {
     super(supabase, projectId, options);
@@ -785,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;
+  }
   /**
    * Получить один экземпляр
    */
@@ -861,34 +925,127 @@ 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 ((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 files = filesMap.get(field.name) || [];
+            transformedInstance.data[field.name] = files;
+          });
         }
-        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, []);
+      }
+      const instanceWithRelations = __spreadProps(__spreadValues({}, transformedInstance), {
+        relations: Object.keys(relations).length > 0 ? relations : void 0
+      });
+      return flattenInstance(
+        instanceWithRelations,
+        fields.map((f) => ({ name: f.name, dbType: f.dbType })),
+        (_a = params == null ? void 0 : params.relationsAsIds) != null ? _a : false
+      );
+    } catch (error) {
+      if (error instanceof NotFoundError || error instanceof PermissionDeniedError || error instanceof SDKError) {
+        throw error;
+      }
+      handleSupabaseError(error);
+    }
+  }
+  /**
+   * Получить один экземпляр по slug
+   */
+  async getInstanceBySlug(entityDefinitionId, slug, params) {
+    var _a;
+    try {
+      if (!validateSlug(slug)) {
+        throw new ValidationError(
+          "slug",
+          "Slug must contain only lowercase letters, numbers, and hyphens, and cannot start or end with a hyphen"
+        );
+      }
+      const fields = await this.getFields(entityDefinitionId);
+      const { data: instance, error: instanceError } = await this.supabase.from("entity_instance").select("*").eq("slug", slug).eq("entity_definition_id", entityDefinitionId).eq("project_id", this.projectId).single();
+      if (instanceError || !instance) {
+        handleInstanceError(
+          instanceError || new Error("Instance not found"),
+          slug
+        );
+      }
+      const transformedInstance = transformEntityInstance(instance);
+      if (transformedInstance.entityDefinitionId !== entityDefinitionId) {
+        throw new NotFoundError("Entity instance", slug);
+      }
+      const relationFields = fields.filter(
+        (f) => f.dbType === "manyToMany" || f.dbType === "manyToOne" || f.dbType === "oneToMany" || f.dbType === "oneToOne"
+      );
+      const relations = {};
+      if (relationFields.length > 0) {
+        const relationFieldIds = relationFields.map((f) => f.id).filter((id) => Boolean(id));
+        if (relationFieldIds.length > 0) {
+          const { data: allRelations, error: relationsError } = await this.supabase.from("entity_relation").select("target_instance_id, relation_field_id").eq("source_instance_id", transformedInstance.id).in("relation_field_id", relationFieldIds);
+          if (relationsError) {
+            throw new SDKError(
+              "RELATIONS_LOAD_ERROR",
+              `Failed to load relations for instance with slug ${slug}: ${relationsError.message}`,
+              500,
+              relationsError
+            );
+          }
+          if (allRelations && allRelations.length > 0) {
+            const targetInstanceIds = [
+              ...new Set(allRelations.map((r) => r.target_instance_id))
+            ];
+            const { data: relatedInstances, error: instancesError } = await this.supabase.from("entity_instance").select("*").in("id", targetInstanceIds);
+            if (instancesError) {
+              throw new SDKError(
+                "RELATED_INSTANCES_LOAD_ERROR",
+                `Failed to load related instances for instance with slug ${slug}: ${instancesError.message}`,
+                500,
+                instancesError
+              );
+            }
+            if (relatedInstances) {
+              const relatedInstancesMap = new Map(
+                relatedInstances.map((inst) => [
+                  inst.id,
+                  transformEntityInstance(inst)
+                ])
+              );
+              for (const relation of allRelations) {
+                const relationField = relationFields.find(
+                  (f) => f.id === relation.relation_field_id
+                );
+                if (relationField) {
+                  const relatedInstance = relatedInstancesMap.get(
+                    relation.target_instance_id
+                  );
+                  if (relatedInstance) {
+                    if (!relations[relationField.name]) {
+                      relations[relationField.name] = [];
+                    }
+                    relations[relationField.name].push(
+                      relatedInstance
+                    );
+                  }
+                }
               }
-              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(
+            transformedInstance.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;
           });
         }
       }
@@ -901,7 +1058,7 @@ var _PublicAPIClient = class _PublicAPIClient extends BasePublicAPIClient {
         (_a = params == null ? void 0 : params.relationsAsIds) != null ? _a : false
       );
     } catch (error) {
-      if (error instanceof NotFoundError || error instanceof PermissionDeniedError || error instanceof SDKError) {
+      if (error instanceof NotFoundError || error instanceof PermissionDeniedError || error instanceof ValidationError || error instanceof SDKError) {
         throw error;
       }
       handleSupabaseError(error);