npm package: @nocios/crudify-admin
Description: Cliente JavaScript/TypeScript para consumir la API de Crudify Admin
Author: Nocios
Latest version: 5.0.2

# @nocios/crudify-admin

> TypeScript/JavaScript client library for Crudify Admin API

A lightweight, fully-typed client for managing **Modules** and **Actions** in your Crudify application.

[![npm version](https://img.shields.io/npm/v/@nocios/crudify-admin.svg)](https://www.npmjs.com/package/@nocios/crudify-admin)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## Features

- ✅ **Full TypeScript Support** - Complete type definitions for all operations
- ✅ **Modules Management** - Create, read, update, delete modules with version control
- ✅ **Actions Management** - Manage UI actions with dynamic configurations
- ✅ **Version Control** - Full version history with rollback capability
- ✅ **Soft Deletes** - Safe deletion with key reusability
- ✅ **Filtering** - Query actions by module, type, and position
- ✅ **Lightweight** - Zero dependencies for core functionality
- ✅ **Tested** - 81 tests covering all functionality

---

## Installation

```bash
npm install @nocios/crudify-admin
```

---

## Quick Start

### Initialize

```typescript
import CrudifyAdmin from "@nocios/crudify-admin";

CrudifyAdmin.init({
  url: "https://your-api-url.com",
  apiKey: "your-api-key",
});
```

### Create a Module

```typescript
const response = await CrudifyAdmin.createModule({
  key: "users",
  dbSchema: {
    name: { type: "String", required: true },
    email: { type: "String", required: true, unique: true },
  },
});

console.log(response.data);
```

### Create an Action

```typescript
const response = await CrudifyAdmin.createAction({
  key: "listUsers",
  moduleKey: "users",
  viewType: "list",
  positions: ["menu"],
  data: {
    headerGrid: [
      { field: "name", minWidth: 200, sortable: true },
      { field: "email", minWidth: 250, sortable: true },
    ],
  },
});

console.log(response.data);
```

---

## Documentation

### 📚 Complete API Reference

- **[Modules API](./docs/modules.md)** - Complete documentation for managing Modules

  - CRUD operations
  - Version control & rollback
  - Complex schemas
  - Error handling
  - Examples

- **[Actions API](./docs/actions.md)** - Complete documentation for managing Actions
  - CRUD operations
  - Action types (list, form, custom, simple)
  - Filtering & querying
  - Version control & rollback
  - Dynamic configurations
  - Error handling
  - Examples

---

## API Overview

### Modules

Modules represent the data structures in your Crudify application.

```typescript
// List all modules
await CrudifyAdmin.listModules();

// Get specific module
await CrudifyAdmin.getModule("users");

// Create module
await CrudifyAdmin.createModule({ key: "products", dbSchema: {...} });

// Edit module
await CrudifyAdmin.editModule("products", { dbSchema: {...} });

// Delete module (soft delete)
await CrudifyAdmin.deleteModule("products");

// Activate/Deactivate
await CrudifyAdmin.activateModule("products");
await CrudifyAdmin.deactivateModule("products");

// Version history
await CrudifyAdmin.getModuleVersions("products");

// Rollback to version
await CrudifyAdmin.editModule("products", { version: "1.0.0" });
```

**[→ Full Modules Documentation](./docs/modules.md)**

---

### Actions

Actions are UI configuration objects that define how users interact with modules.

```typescript
// List all actions
await CrudifyAdmin.listActions();

// List with filters
await CrudifyAdmin.listActions({
  moduleKey: "users",
  viewType: "list",
  positions: "menu"
});

// Get specific action
await CrudifyAdmin.getAction("listUsers");

// Create action
await CrudifyAdmin.createAction({
  key: "createUser",
  moduleKey: "users",
  viewType: "form",
  data: { fields: [...] }
});

// Edit action
await CrudifyAdmin.editAction("createUser", { order: 20 });

// Delete action (soft delete)
await CrudifyAdmin.deleteAction("createUser");

// Activate/Deactivate
await CrudifyAdmin.activateAction("createUser");
await CrudifyAdmin.deactivateAction("createUser");

// Version history
await CrudifyAdmin.getActionVersions("createUser");

// Rollback to version
await CrudifyAdmin.editAction("createUser", { version: "1.0.0" });
```

**[→ Full Actions Documentation](./docs/actions.md)**

---

## TypeScript Support

Full TypeScript support with complete type definitions:

```typescript
import CrudifyAdmin, {
  // Configuration
  CrudifyAdminConfig,

  // Modules
  IModule,
  ModuleCreateInput,
  ModuleEditInput,

  // Actions
  IAction,
  ActionCreateInput,
  ActionEditInput,
  ActionListFilters,

  // Response
  ApiResponse,
} from "@nocios/crudify-admin";

// Typed responses
const response: ApiResponse<IModule> = await CrudifyAdmin.getModule("users");
const actions: ApiResponse<IAction[]> = await CrudifyAdmin.listActions();
```

---

## Error Handling

All methods return a standardized response format:

```typescript
interface ApiResponse<T = any> {
  success: boolean;
  data?: T;
  message?: string;
  count?: number;
  errors?: any;
}
```

**Example:**

```typescript
const response = await CrudifyAdmin.createModule(moduleData);

if (response.success) {
  console.log("Module created:", response.data);
} else {
  console.error("Error:", response.errors);
}
```

---

## Advanced Configuration

### Custom Headers

You can add custom headers to every request:

```typescript
CrudifyAdmin.init({
  url: "https://your-api-url.com",
  apiKey: "your-api-key",
  getAdditionalHeaders: () => ({
    "X-User-ID": "user-123",
    "X-Session-ID": "session-456",
  }),
});
```

---

## Testing

The library includes comprehensive tests with 81 test cases covering:

- ✅ All CRUD operations
- ✅ Version management
- ✅ Error handling
- ✅ Network errors
- ✅ Concurrent operations
- ✅ Edge cases
- ✅ E2E workflows

### Run Tests

```bash
# Run all tests
npm test

# Watch mode (development)
npm run test:watch

# UI mode
npm run test:ui

# Coverage report
npm run test:coverage
```

---

## Development

### Build

```bash
npm run build
```

### Local Development

```bash
# Install dependencies
npm install

# Run tests
npm test

# Build library
npm run build
```

---

## Examples

### Complete Workflow

```typescript
import CrudifyAdmin from "@nocios/crudify-admin";

// 1. Initialize
CrudifyAdmin.init({
  url: "https://api.example.com",
  apiKey: "your-api-key",
});

// 2. Create a module
const module = await CrudifyAdmin.createModule({
  key: "products",
  dbSchema: {
    name: { type: "String", required: true },
    price: { type: "Number", required: true },
  },
});

// 3. Create a list action for the module
const listAction = await CrudifyAdmin.createAction({
  key: "listProducts",
  moduleKey: "products",
  viewType: "list",
  positions: ["menu"],
  data: {
    headerGrid: [
      { field: "name", minWidth: 200, sortable: true },
      { field: "price", width: 150, kind: "number" },
    ],
  },
});

// 4. Create a form action for the module
const formAction = await CrudifyAdmin.createAction({
  key: "createProduct",
  moduleKey: "products",
  viewType: "form",
  positions: ["outside_table"],
  data: {
    fields: [
      { key: "name", kind: "text", required: true },
      { key: "price", kind: "number", required: true },
    ],
  },
});

// 5. List all actions for the module
const actions = await CrudifyAdmin.listActions({
  moduleKey: "products",
});

console.log(`Created module and ${actions.count} actions`);
```

---

## Version History

### 2.1.0 (Current)

- ✨ Added complete Actions API support
- ✨ Added action filtering by module, type, and position
- ✨ Added 48 new tests for Actions
- 📚 Added comprehensive documentation
- 🎯 81 tests passing

### 2.0.2

- ✅ Modules API with version control
- ✅ Soft delete support
- ✅ Complete TypeScript types

---

## License

MIT © [Nocios](https://github.com/nocios)

---

## Links

- [GitHub Repository](https://github.com/nocios/crudify-admin)
- [npm Package](https://www.npmjs.com/package/@nocios/crudify-admin)
- [Modules Documentation](./docs/modules.md)
- [Actions Documentation](./docs/actions.md)
- [Issues](https://github.com/nocios/crudify-admin/issues)

---

## Support

If you have questions or need help, please:

1. Check the [Modules Documentation](./docs/modules.md)
2. Check the [Actions Documentation](./docs/actions.md)
3. Review the [test files](./test/) for examples
4. [Open an issue](https://github.com/nocios/crudify-admin/issues)

---

Made with ❤️ by [Nocios](https://github.com/nocios)