@gzl10/nexus-sdk 0.12.7 → 0.13.0

package/dist/collection/index.d.ts

@@ -0,0 +1,506 @@
+import { L as LocalizedString, i as FieldDefinition } from '../field-CngHXora.js';
+import { u as RolePermission, b as CollectionEntityDefinition, f as DagEntityDefinition, c as EventEntityDefinition, d as ConfigEntityDefinition } from '../entity-kPgsCMdR.js';
+import 'knex';
+import 'express';
+import 'pino';
+
+/**
+ * Collection Entity Configuration Types
+ *
+ * Types for configuring pre-defined entities from the collection.
+ */
+
+/**
+ * Configuration options for collection entity factories.
+ *
+ * Allows basic customization without modifying entity structure:
+ * - Table naming (prefix or full override)
+ * - Labels for UI
+ * - CASL subject for authorization
+ *
+ * @example
+ * ```typescript
+ * // With prefix
+ * createCommentsEntity({ tablePrefix: 'blog_' })
+ * // Result: table = 'blog_comments'
+ *
+ * // Full override
+ * createCommentsEntity({
+ *   table: 'feedback',
+ *   label: { en: 'Feedback', es: 'Retroalimentación' }
+ * })
+ * ```
+ */
+interface CollectionEntityConfig {
+    /**
+     * Prefix to prepend to the default table name.
+     * Example: 'blog_' + 'comments' = 'blog_comments'
+     */
+    tablePrefix?: string;
+    /**
+     * Full table name override (ignores tablePrefix if set).
+     */
+    table?: string;
+    /**
+     * Override singular label for UI.
+     */
+    label?: LocalizedString;
+    /**
+     * Override plural label for UI.
+     */
+    labelPlural?: LocalizedString;
+    /**
+     * Override CASL subject for authorization.
+     * Default is auto-generated from entity name (e.g., 'NxComment').
+     */
+    caslSubject?: string;
+    /**
+     * Override route prefix for API endpoints.
+     * Default is auto-generated from table name.
+     */
+    routePrefix?: string;
+}
+/**
+ * Factory function type for creating configurable entities.
+ */
+type EntityFactory<T> = (config?: CollectionEntityConfig) => T;
+
+/**
+ * Default CASL permissions for polymorphic entities.
+ * - All users can read
+ * - Authenticated users can create (own)
+ * - Users can update/delete their own records
+ * - Admins can manage all
+ */
+declare const polymorphicCaslPermissions: Record<string, RolePermission>;
+/**
+ * Default CASL permissions for system entities.
+ * - Users can read their own
+ * - Admins can manage all
+ */
+declare const systemCaslPermissions: Record<string, RolePermission>;
+/**
+ * Default CASL permissions for workflow entities.
+ * - Users can read their own assignments/approvals
+ * - Users can update assigned to them
+ * - Admins can manage all
+ */
+declare const workflowCaslPermissions: Record<string, RolePermission>;
+/**
+ * Standard polymorphic fields for relating to any entity.
+ * Include these in entities that can be attached to multiple entity types.
+ *
+ * @example
+ * ```typescript
+ * fields: {
+ *   id: idField,
+ *   ...polymorphicFields,
+ *   // entity-specific fields...
+ * }
+ * ```
+ */
+declare const polymorphicFields: {
+    entity_type: FieldDefinition;
+    entity_id: FieldDefinition;
+};
+/** Supported entity definition types */
+type ConfigurableEntity = CollectionEntityDefinition | DagEntityDefinition | EventEntityDefinition | ConfigEntityDefinition;
+/**
+ * Applies configuration overrides to an entity definition.
+ *
+ * @param base - The base entity definition
+ * @param defaultTable - Default table name (used with tablePrefix)
+ * @param defaultSubject - Default CASL subject
+ * @param config - Optional configuration overrides
+ * @returns Modified entity definition
+ *
+ * @example
+ * ```typescript
+ * const base = { type: 'collection', table: 'nx_comments', ... }
+ * const configured = applyEntityConfig(base, 'comments', 'NxComment', {
+ *   tablePrefix: 'blog_'
+ * })
+ * // Result: { table: 'blog_comments', casl: { subject: 'BlogComment' }, ... }
+ * ```
+ */
+declare function applyEntityConfig<T extends ConfigurableEntity>(base: T, defaultTable: string, defaultSubject: string, config?: CollectionEntityConfig): T;
+/**
+ * Creates a factory function for an entity definition.
+ *
+ * @param baseEntity - The base entity definition
+ * @param defaultTable - Default table name
+ * @param defaultSubject - Default CASL subject
+ * @returns Factory function that accepts optional config
+ *
+ * @example
+ * ```typescript
+ * const baseComments = { type: 'collection', table: 'nx_comments', ... }
+ * export const createCommentsEntity = createEntityFactory(
+ *   baseComments,
+ *   'comments',
+ *   'NxComment'
+ * )
+ *
+ * // Usage
+ * const entity = createCommentsEntity({ tablePrefix: 'blog_' })
+ * ```
+ */
+declare function createEntityFactory<T extends ConfigurableEntity>(baseEntity: T, defaultTable: string, defaultSubject: string): (config?: CollectionEntityConfig) => T;
+
+/**
+ * Comments Entity
+ *
+ * Polymorphic comments that can be attached to any entity.
+ * Supports threading via parent_id for nested replies.
+ *
+ * @example
+ * ```typescript
+ * // Use as-is
+ * import { commentsEntity } from '@gzl10/nexus-sdk/collection'
+ *
+ * // Or with custom table prefix
+ * import { createCommentsEntity } from '@gzl10/nexus-sdk/collection'
+ * const blogComments = createCommentsEntity({ tablePrefix: 'blog_' })
+ * ```
+ */
+
+/**
+ * Pre-configured comments entity ready to use.
+ * Table: nx_comments
+ */
+declare const commentsEntity: CollectionEntityDefinition;
+/**
+ * Factory to create a comments entity with custom configuration.
+ *
+ * @param config - Optional configuration overrides
+ * @returns Configured comments entity definition
+ *
+ * @example
+ * ```typescript
+ * const blogComments = createCommentsEntity({ tablePrefix: 'blog_' })
+ * // Table: blog_comments, Subject: BlogComment
+ * ```
+ */
+declare const createCommentsEntity: (config?: CollectionEntityConfig) => CollectionEntityDefinition;
+
+/**
+ * Pre-configured attachments entity ready to use.
+ * Table: nx_attachments
+ */
+declare const attachmentsEntity: CollectionEntityDefinition;
+/**
+ * Factory to create an attachments entity with custom configuration.
+ */
+declare const createAttachmentsEntity: (config?: CollectionEntityConfig) => CollectionEntityDefinition;
+
+/**
+ * Tag-Entity pivot table for polymorphic associations.
+ * This entity links tags to any other entity.
+ */
+declare const tagEntitiesEntity: CollectionEntityDefinition;
+/**
+ * Pre-configured tags entity ready to use.
+ * Table: nx_tags (DAG with nx_tags_parents)
+ */
+declare const tagsEntity: DagEntityDefinition;
+/**
+ * Factory to create a tags entity with custom configuration.
+ */
+declare const createTagsEntity: (config?: CollectionEntityConfig) => DagEntityDefinition;
+
+/**
+ * Pre-configured notes entity ready to use.
+ * Table: nx_notes
+ */
+declare const notesEntity: CollectionEntityDefinition;
+/**
+ * Factory to create a notes entity with custom configuration.
+ */
+declare const createNotesEntity: (config?: CollectionEntityConfig) => CollectionEntityDefinition;
+
+/**
+ * Pre-configured favorites entity ready to use.
+ * Table: nx_favorites
+ */
+declare const favoritesEntity: CollectionEntityDefinition;
+/**
+ * Factory to create a favorites entity with custom configuration.
+ */
+declare const createFavoritesEntity: (config?: CollectionEntityConfig) => CollectionEntityDefinition;
+
+/**
+ * Pre-configured ratings entity ready to use.
+ * Table: nx_ratings
+ */
+declare const ratingsEntity: CollectionEntityDefinition;
+/**
+ * Factory to create a ratings entity with custom configuration.
+ */
+declare const createRatingsEntity: (config?: CollectionEntityConfig) => CollectionEntityDefinition;
+
+/**
+ * Standard reaction types.
+ */
+declare const REACTION_TYPES: {
+    readonly LIKE: "like";
+    readonly LOVE: "love";
+    readonly HAHA: "haha";
+    readonly WOW: "wow";
+    readonly SAD: "sad";
+    readonly ANGRY: "angry";
+    readonly THUMBS_UP: "thumbs_up";
+    readonly THUMBS_DOWN: "thumbs_down";
+    readonly CELEBRATE: "celebrate";
+    readonly SUPPORT: "support";
+};
+/**
+ * Pre-configured reactions entity ready to use.
+ * Table: nx_reactions
+ */
+declare const reactionsEntity: CollectionEntityDefinition;
+/**
+ * Factory to create a reactions entity with custom configuration.
+ */
+declare const createReactionsEntity: (config?: CollectionEntityConfig) => CollectionEntityDefinition;
+
+/**
+ * Pre-configured mentions entity ready to use.
+ * Table: nx_mentions
+ */
+declare const mentionsEntity: CollectionEntityDefinition;
+/**
+ * Factory to create a mentions entity with custom configuration.
+ */
+declare const createMentionsEntity: (config?: CollectionEntityConfig) => CollectionEntityDefinition;
+
+/**
+ * Common option groups for quick reference.
+ */
+declare const OPTION_GROUPS: {
+    readonly STATUS: "status";
+    readonly PRIORITY: "priority";
+    readonly CATEGORY: "category";
+    readonly TYPE: "type";
+    readonly LEVEL: "level";
+    readonly SIZE: "size";
+    readonly COLOR: "color";
+};
+/**
+ * Default seed data for common options.
+ * Use this to seed the options table manually if needed.
+ *
+ * @example
+ * ```typescript
+ * // In module seed function
+ * await ctx.db('nx_options').insert(DEFAULT_OPTIONS_SEED)
+ * ```
+ */
+declare const DEFAULT_OPTIONS_SEED: {
+    id: string;
+    option_group: string;
+    value: string;
+    label: string;
+    color: string;
+    icon: string;
+    order: number;
+    is_default: boolean;
+    is_active: boolean;
+}[];
+/**
+ * Pre-configured options entity ready to use.
+ * Table: nx_options
+ *
+ * Includes seed data for common statuses and priorities.
+ */
+declare const optionsEntity: CollectionEntityDefinition;
+/**
+ * Factory to create an options entity with custom configuration.
+ *
+ * @example
+ * ```typescript
+ * // For a CRM module
+ * const crmOptions = createOptionsEntity({ tablePrefix: 'crm_' })
+ * // Table: crm_options
+ * ```
+ */
+declare const createOptionsEntity: (config?: CollectionEntityConfig) => CollectionEntityDefinition;
+/**
+ * Helper to create field options that reference this entity.
+ *
+ * @param group - The option_group to filter by
+ * @param module - Module name (default: 'collection')
+ * @param entity - Entity route (default: 'nx-options')
+ *
+ * @example
+ * ```typescript
+ * status: {
+ *   input: 'select',
+ *   options: dynamicOptions('status')
+ * }
+ * ```
+ */
+declare function dynamicOptions(group: string, module?: string, entity?: string): {
+    endpoint: string;
+    filter: {
+        option_group: string;
+        is_active: boolean;
+    };
+    valueField: string;
+    labelField: string;
+    sortField: string;
+};
+
+/**
+ * Common activity types.
+ */
+declare const ACTIVITY_TYPES: {
+    readonly LOGIN: "auth.login";
+    readonly LOGOUT: "auth.logout";
+    readonly PASSWORD_CHANGE: "auth.password_change";
+    readonly CREATE: "data.create";
+    readonly UPDATE: "data.update";
+    readonly DELETE: "data.delete";
+    readonly EXPORT: "system.export";
+    readonly IMPORT: "system.import";
+    readonly CONFIG_CHANGE: "system.config_change";
+    readonly CUSTOM: "custom";
+};
+/**
+ * Pre-configured activity log entity ready to use.
+ * Table: nx_activity_log
+ */
+declare const activityLogEntity: EventEntityDefinition;
+/**
+ * Factory to create an activity log entity with custom configuration.
+ */
+declare const createActivityLogEntity: (config?: CollectionEntityConfig) => EventEntityDefinition;
+
+/**
+ * Common notification types.
+ */
+declare const NOTIFICATION_TYPES: {
+    readonly INFO: "info";
+    readonly SUCCESS: "success";
+    readonly WARNING: "warning";
+    readonly ERROR: "error";
+    readonly MENTION: "mention";
+    readonly ASSIGNMENT: "assignment";
+    readonly REMINDER: "reminder";
+    readonly SYSTEM: "system";
+};
+/**
+ * Pre-configured notifications entity ready to use.
+ * Table: nx_notifications
+ */
+declare const notificationsEntity: CollectionEntityDefinition;
+/**
+ * Factory to create a notifications entity with custom configuration.
+ */
+declare const createNotificationsEntity: (config?: CollectionEntityConfig) => CollectionEntityDefinition;
+
+/**
+ * Common preference keys.
+ */
+declare const PREFERENCE_KEYS: {
+    readonly THEME: "theme";
+    readonly LANGUAGE: "language";
+    readonly TIMEZONE: "timezone";
+    readonly SIDEBAR_COLLAPSED: "sidebar_collapsed";
+    readonly NOTIFICATIONS_ENABLED: "notifications_enabled";
+    readonly EMAIL_DIGEST: "email_digest";
+};
+/**
+ * Pre-configured preferences entity ready to use.
+ * Table: nx_preferences
+ */
+declare const preferencesEntity: CollectionEntityDefinition;
+/**
+ * Factory to create a preferences entity with custom configuration.
+ */
+declare const createPreferencesEntity: (config?: CollectionEntityConfig) => CollectionEntityDefinition;
+
+/**
+ * Common schedule frequencies.
+ */
+declare const SCHEDULE_FREQUENCIES: {
+    readonly EVERY_MINUTE: "* * * * *";
+    readonly EVERY_5_MINUTES: "*/5 * * * *";
+    readonly EVERY_15_MINUTES: "*/15 * * * *";
+    readonly EVERY_HOUR: "0 * * * *";
+    readonly EVERY_DAY_MIDNIGHT: "0 0 * * *";
+    readonly EVERY_DAY_6AM: "0 6 * * *";
+    readonly EVERY_MONDAY: "0 0 * * 1";
+    readonly EVERY_MONTH_1ST: "0 0 1 * *";
+};
+/**
+ * Pre-configured schedules entity ready to use.
+ * Table: nx_schedules
+ */
+declare const schedulesEntity: CollectionEntityDefinition;
+/**
+ * Factory to create a schedules entity with custom configuration.
+ */
+declare const createSchedulesEntity: (config?: CollectionEntityConfig) => CollectionEntityDefinition;
+
+/**
+ * Common webhook events.
+ */
+declare const WEBHOOK_EVENTS: {
+    readonly CREATED: "created";
+    readonly UPDATED: "updated";
+    readonly DELETED: "deleted";
+    readonly PUBLISHED: "published";
+    readonly ARCHIVED: "archived";
+    readonly STATUS_CHANGED: "status_changed";
+};
+/**
+ * Pre-configured webhooks entity ready to use.
+ * Table: nx_webhooks
+ */
+declare const webhooksEntity: CollectionEntityDefinition;
+/**
+ * Factory to create a webhooks entity with custom configuration.
+ */
+declare const createWebhooksEntity: (config?: CollectionEntityConfig) => CollectionEntityDefinition;
+
+/**
+ * Approval status values.
+ */
+declare const APPROVAL_STATUS: {
+    readonly PENDING: "pending";
+    readonly APPROVED: "approved";
+    readonly REJECTED: "rejected";
+    readonly CANCELLED: "cancelled";
+    readonly EXPIRED: "expired";
+};
+/**
+ * Pre-configured approvals entity ready to use.
+ * Table: nx_approvals
+ */
+declare const approvalsEntity: CollectionEntityDefinition;
+/**
+ * Factory to create an approvals entity with custom configuration.
+ */
+declare const createApprovalsEntity: (config?: CollectionEntityConfig) => CollectionEntityDefinition;
+
+/**
+ * Assignment role types.
+ */
+declare const ASSIGNMENT_ROLES: {
+    readonly OWNER: "owner";
+    readonly ASSIGNEE: "assignee";
+    readonly REVIEWER: "reviewer";
+    readonly COLLABORATOR: "collaborator";
+    readonly WATCHER: "watcher";
+};
+/**
+ * Pre-configured assignments entity ready to use.
+ * Table: nx_assignments
+ */
+declare const assignmentsEntity: CollectionEntityDefinition;
+/**
+ * Factory to create an assignments entity with custom configuration.
+ */
+declare const createAssignmentsEntity: (config?: CollectionEntityConfig) => CollectionEntityDefinition;
+
+export { ACTIVITY_TYPES, APPROVAL_STATUS, ASSIGNMENT_ROLES, type CollectionEntityConfig, DEFAULT_OPTIONS_SEED, type EntityFactory, NOTIFICATION_TYPES, OPTION_GROUPS, PREFERENCE_KEYS, REACTION_TYPES, SCHEDULE_FREQUENCIES, WEBHOOK_EVENTS, activityLogEntity, applyEntityConfig, approvalsEntity, assignmentsEntity, attachmentsEntity, commentsEntity, createActivityLogEntity, createApprovalsEntity, createAssignmentsEntity, createAttachmentsEntity, createCommentsEntity, createEntityFactory, createFavoritesEntity, createMentionsEntity, createNotesEntity, createNotificationsEntity, createOptionsEntity, createPreferencesEntity, createRatingsEntity, createReactionsEntity, createSchedulesEntity, createTagsEntity, createWebhooksEntity, dynamicOptions, favoritesEntity, mentionsEntity, notesEntity, notificationsEntity, optionsEntity, polymorphicCaslPermissions, polymorphicFields, preferencesEntity, ratingsEntity, reactionsEntity, schedulesEntity, systemCaslPermissions, tagEntitiesEntity, tagsEntity, webhooksEntity, workflowCaslPermissions };