@quatrain/cloudwrapper 1.1.13 → 1.1.15

package/LICENSE.md

@@ -0,0 +1,15 @@
+# LICENSE UPDATE NOTICE
+
+As of 01/01/2026, Quatrain Core is licensed under the **GNU Affero General Public License v3.0 (AGPL v3)**.
+Previous versions remain under the MIT License.
+
+## Why AGPL?
+
+We believe in open collaboration for the development ecosystem. The AGPL ensures that any modification or deployment of this BaaS stack, including over a network, benefits the entire community.
+
+## Commercial Services & Enterprise Usage
+
+We provide official deployment services, technical training, and certification for Quatrain Core.
+For organizations requiring a non-copyleft license (commercial license) or custom proprietary integrations, please contact the copyright holder: **Quatrain Technologies**.
+
+Copyright © 2024-2026 Quatrain Technologies. All Rights Reserved.

package/README.md

@@ -0,0 +1,172 @@
+# @quatrain/cloudwrapper
+
+Foundation package for cloud function wrappers. This package provides abstract base classes and type definitions for building cloud function triggers across different platforms (Firebase, Supabase, etc.).
+
+## Features
+
+-  Abstract base class for cloud wrapper implementations
+-  Type definitions for database and storage triggers
+-  Event payload types for cloud functions
+-  Static logger with "Cloud" namespace
+-  Platform-agnostic trigger definitions
+
+## Installation
+
+```bash
+npm install @quatrain/cloudwrapper
+```
+
+## Usage
+
+### Extending AbstractCloudWrapper
+
+```typescript
+import { AbstractCloudWrapper } from '@quatrain/cloudwrapper'
+
+class MyCloudWrapper extends AbstractCloudWrapper {
+   constructor(params: any) {
+      super(params)
+      // Your initialization logic
+   }
+
+   // Implement your cloud-specific methods
+}
+
+const wrapper = new MyCloudWrapper({
+   projectId: 'my-project',
+   region: 'us-central1',
+})
+```
+
+### Using CloudWrapper Logger
+
+```typescript
+import { CloudWrapper } from '@quatrain/cloudwrapper'
+
+CloudWrapper.logger.info('Cloud function initialized')
+CloudWrapper.logger.debug('Processing event...')
+CloudWrapper.logger.error('Error occurred:', error)
+```
+
+### Database Trigger Definition
+
+```typescript
+import { DatabaseTriggerType } from '@quatrain/cloudwrapper'
+import { BackendAction } from '@quatrain/backend'
+
+const userTrigger: DatabaseTriggerType = {
+   name: 'onUserCreate',
+   event: BackendAction.CREATE,
+   script: async (payload) => {
+      // Handle user creation
+      console.log('New user:', payload.after)
+   },
+   model: 'User',
+   path: '/users/{userId}',
+   schema: 'public', // Optional
+}
+```
+
+### Storage Trigger Definition
+
+```typescript
+import {
+   StorageTriggerType,
+   StorageEventPayloadType,
+} from '@quatrain/cloudwrapper'
+import { BackendAction } from '@quatrain/backend'
+
+const fileTrigger: StorageTriggerType = {
+   name: 'onFileUpload',
+   event: BackendAction.CREATE,
+   script: async (payload: StorageEventPayloadType) => {
+      const file = payload.after
+      console.log('File uploaded:', file?.fullPath)
+      console.log('Size:', file?.size, 'bytes')
+   },
+}
+```
+
+### Multiple Events
+
+```typescript
+import { DatabaseTriggerType } from '@quatrain/cloudwrapper'
+import { BackendAction } from '@quatrain/backend'
+
+const multiEventTrigger: DatabaseTriggerType = {
+   name: 'onPostChange',
+   event: [BackendAction.CREATE, BackendAction.UPDATE],
+   script: async (payload) => {
+      const before = payload.before
+      const after = payload.after
+
+      if (!before) {
+         console.log('Post created')
+      } else {
+         console.log('Post updated')
+      }
+   },
+   model: 'Post',
+   path: '/posts/{postId}',
+}
+```
+
+## Type Definitions
+
+### DatabaseTriggerType
+
+Defines triggers for database operations (create, update, delete).
+
+```typescript
+interface DatabaseTriggerType {
+   name: string
+   event: BackendAction | BackendAction[]
+   script: Function
+   model: string // Database model/table name
+   path: string // Path pattern for the trigger
+   schema?: string // Optional database schema
+}
+```
+
+### StorageTriggerType
+
+Defines triggers for storage operations (file upload, update, delete).
+
+```typescript
+interface StorageTriggerType {
+   name: string
+   event: BackendAction | BackendAction[]
+   script: Function
+}
+```
+
+### StorageEventPayloadType
+
+Payload structure for storage events.
+
+```typescript
+interface StorageEventPayloadType {
+   before: FileType | undefined // File state before event
+   after: FileType | undefined // File state after event
+   context: any // Additional context
+}
+```
+
+## Platform Adapters
+
+This package serves as the foundation. Specific implementations are available:
+
+-  **[@quatrain/cloudwrapper-firebase](../cloudwrapper-firebase)** - Firebase Functions adapter
+-  **[@quatrain/cloudwrapper-supabase](../cloudwrapper-supabase)** - Supabase Edge Functions adapter
+
+## BackendAction Enum
+
+Triggers use the `BackendAction` enum from `@quatrain/backend`:
+
+-  `BackendAction.CREATE` - Resource creation
+-  `BackendAction.UPDATE` - Resource modification
+-  `BackendAction.DELETE` - Resource deletion
+
+## License
+
+AGPL-3.0-only

package/lib/CloudWrapper.d.ts

@@ -1,3 +1,4 @@
 import { Core } from '@quatrain/core';
 export declare class CloudWrapper extends Core {
+    static logger: any;
 }

package/lib/CloudWrapper.js

@@ -1,7 +1,10 @@
 "use strict";
+var _a;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CloudWrapper = void 0;
 const core_1 = require("@quatrain/core");
 class CloudWrapper extends core_1.Core {
 }
 exports.CloudWrapper = CloudWrapper;
+_a = CloudWrapper;
+CloudWrapper.logger = _a.addLogger('Cloud');

package/lib/index.d.ts

@@ -1,4 +1,6 @@
 import { AbstractCloudWrapper } from './AbstractCloudWrapper';
 import { CloudWrapper } from './CloudWrapper';
 import { DatabaseTriggerType } from './types/DatabaseTriggerType';
-export { AbstractCloudWrapper, CloudWrapper, DatabaseTriggerType };
+import { StorageTriggerType } from './types/StorageTriggerType';
+import { StorageEventPayloadType } from './types/StorageEventPayloadType';
+export { AbstractCloudWrapper, CloudWrapper, DatabaseTriggerType, StorageTriggerType, StorageEventPayloadType, };

package/lib/types/DatabaseTriggerType.d.ts

@@ -1,9 +1,6 @@
-import { BackendAction } from '@quatrain/backend';
-export type DatabaseTriggerType = {
-    name: string;
-    event: BackendAction | BackendAction[];
+import { GenericTriggerType } from './GenericTriggerType';
+export interface DatabaseTriggerType extends GenericTriggerType {
     schema?: string;
     model: string;
     path: string;
-    script: Function;
-};
+}

package/lib/types/GenericEventPayloadType.d.ts

@@ -0,0 +1,5 @@
+export interface GenericEventPayloadType {
+    before: any;
+    after: any;
+    context: any;
+}

package/lib/types/GenericEventPayloadType.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/types/GenericTriggerType.d.ts

@@ -0,0 +1,6 @@
+import { BackendAction } from '@quatrain/backend';
+export type GenericTriggerType = {
+    name: string;
+    event: BackendAction | BackendAction[];
+    script: Function;
+};

package/lib/types/GenericTriggerType.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/types/StorageEventPayloadType.d.ts

@@ -0,0 +1,6 @@
+import { GenericEventPayloadType } from './GenericEventPayloadType';
+import { FileType } from '@quatrain/storage';
+export interface StorageEventPayloadType extends GenericEventPayloadType {
+    before: FileType | undefined;
+    after: FileType | undefined;
+}

package/lib/types/StorageEventPayloadType.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/types/StorageTriggerType.d.ts

@@ -0,0 +1,3 @@
+import { GenericTriggerType } from './GenericTriggerType';
+export interface StorageTriggerType extends GenericTriggerType {
+}

package/lib/types/StorageTriggerType.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,40 +1,43 @@
 {
-  "name": "@quatrain/cloudwrapper",
-  "version": "1.1.13",
-  "license": "MIT",
-  "description": "Cloud wrappers commons",
-  "main": "lib/index.js",
-  "types": "lib/index.d.ts",
-  "files": [
-    "lib/",
-    "README.md"
-  ],
-  "author": "Quatrain Développement SAS <developers@quatrain.com>",
-  "peerDependencies": {
-    "@quatrain/backend": "^1.1.12",
-    "@quatrain/core": "^1.1.14"
-  },
-  "devDependencies": {
-    "@tsconfig/recommended": "^1.0.1",
-    "@types/jest": "^27.0.3",
-    "@types/node": "^22.10.1",
-    "jest": "^27.4.7",
-    "jest-node-exports-resolver": "^1.1.6",
-    "jest-serial-runner": "^1.2.1",
-    "trace-unhandled": "^2.0.1",
-    "ts-jest": "^27.1.2",
-    "ts-node": "^10.9.1",
-    "typescript": "^5.1.5"
-  },
-  "scripts": {
-    "test-ci": "jest --runInBand",
-    "build": "tsc",
-    "wbuild": "tsc --watch",
-    "bump-to": "yarn version",
-    "hash": "node ../../bin/hashFolder.js",
-    "hash:persist": "yarn hash  > .hash_latest.txt",
-    "hash:compare": "yarn hash > .hash_newest.txt && cmp -s .hash_latest.txt .hash_newest.txt",
-    "publish": "yarn hash:compare || yarn publish:process",
-    "publish:process": "yarn version patch && yarn build && yarn npm publish --access public && yarn hash:persist"
-  }
-}
+   "name": "@quatrain/cloudwrapper",
+   "version": "1.1.15",
+   "license": "AGPL-3.0-only",
+   "description": "Cloud wrappers commons",
+   "main": "lib/index.js",
+   "types": "lib/index.d.ts",
+   "bun": "src/index.ts",
+   "files": [
+      "LICENSE.md",
+      "src/",
+      "lib/",
+      "README.md"
+   ],
+   "author": "Quatrain Développement SAS <developers@quatrain.com>",
+   "peerDependencies": {
+      "@quatrain/backend": "^1.1.26",
+      "@quatrain/core": "^1.1.42"
+   },
+   "devDependencies": {
+      "@tsconfig/recommended": "^1.0.1",
+      "@types/jest": "^30.0.0",
+      "@types/node": "^22.10.1",
+      "jest": "^30.2.0",
+      "jest-node-exports-resolver": "^1.1.6",
+      "jest-serial-runner": "^1.2.1",
+      "trace-unhandled": "^2.0.1",
+      "ts-jest": "^29.4.1",
+      "ts-node": "^10.9.1",
+      "typescript": "^5.2.2"
+   },
+   "scripts": {
+      "test-ci": "jest --runInBand",
+      "build": "tsc",
+      "wbuild": "tsc --watch",
+      "bump-to": "yarn version"
+   },
+   "dependencies": {
+      "@quatrain/backend": "^1.1.26",
+      "@quatrain/core": "^1.1.42",
+      "@quatrain/storage": "^1.1"
+   }
+}

package/src/AbstractCloudWrapper.ts

@@ -0,0 +1,7 @@
+export class AbstractCloudWrapper {
+   protected _params: any
+
+   constructor(params: any) {
+      this._params = params
+   }
+}

package/src/CloudWrapper.test.ts

@@ -0,0 +1,232 @@
+import { AbstractCloudWrapper } from './AbstractCloudWrapper'
+import { CloudWrapper } from './CloudWrapper'
+import {
+   DatabaseTriggerType,
+   StorageTriggerType,
+   StorageEventPayloadType,
+} from './index'
+import { BackendAction } from '@quatrain/backend'
+
+describe('CloudWrapper Package', () => {
+   describe('AbstractCloudWrapper', () => {
+      it('should create instance with params', () => {
+         const params = { config: 'test-config', apiKey: 'test-key' }
+         const wrapper = new AbstractCloudWrapper(params)
+
+         expect(wrapper).toBeInstanceOf(AbstractCloudWrapper)
+         // Access protected property through any for testing
+         expect((wrapper as any)._params).toEqual(params)
+      })
+
+      it('should store empty params', () => {
+         const wrapper = new AbstractCloudWrapper({})
+
+         expect((wrapper as any)._params).toEqual({})
+      })
+
+      it('should store undefined params as undefined', () => {
+         const wrapper = new AbstractCloudWrapper(undefined)
+
+         expect((wrapper as any)._params).toBeUndefined()
+      })
+   })
+
+   describe('CloudWrapper', () => {
+      it('should extend Core class', () => {
+         // CloudWrapper extends Core, so it should have Core properties
+         expect(CloudWrapper).toBeDefined()
+         expect(typeof CloudWrapper).toBe('function')
+      })
+
+      it('should have logger property', () => {
+         expect(CloudWrapper.logger).toBeDefined()
+         expect(CloudWrapper.logger).toHaveProperty('debug')
+         expect(CloudWrapper.logger).toHaveProperty('info')
+         expect(CloudWrapper.logger).toHaveProperty('warn')
+         expect(CloudWrapper.logger).toHaveProperty('error')
+      })
+
+      it('should create logger with "Cloud" namespace', () => {
+         // The logger is created with 'Cloud' namespace
+         expect(CloudWrapper.logger).toBeDefined()
+      })
+   })
+
+   describe('Type Exports', () => {
+      describe('DatabaseTriggerType', () => {
+         it('should be importable', () => {
+            // Type check - if this compiles, the type exists
+            const trigger: DatabaseTriggerType = {
+               name: 'test-trigger',
+               event: BackendAction.CREATE,
+               script: () => {},
+               model: 'User',
+               path: '/users/{userId}',
+               schema: 'public',
+            }
+
+            expect(trigger).toBeDefined()
+            expect(trigger.name).toBe('test-trigger')
+            expect(trigger.model).toBe('User')
+            expect(trigger.path).toBe('/users/{userId}')
+            expect(trigger.schema).toBe('public')
+         })
+
+         it('should work without optional schema', () => {
+            const trigger: DatabaseTriggerType = {
+               name: 'test-trigger',
+               event: BackendAction.UPDATE,
+               script: () => {},
+               model: 'Post',
+               path: '/posts/{postId}',
+            }
+
+            expect(trigger).toBeDefined()
+            expect(trigger.schema).toBeUndefined()
+         })
+
+         it('should support array of events', () => {
+            const trigger: DatabaseTriggerType = {
+               name: 'multi-event-trigger',
+               event: [BackendAction.CREATE, BackendAction.UPDATE],
+               script: () => {},
+               model: 'Comment',
+               path: '/comments/{commentId}',
+            }
+
+            expect(trigger).toBeDefined()
+            expect(Array.isArray(trigger.event)).toBe(true)
+         })
+      })
+
+      describe('StorageTriggerType', () => {
+         it('should be importable', () => {
+            const trigger: StorageTriggerType = {
+               name: 'storage-trigger',
+               event: BackendAction.CREATE,
+               script: () => {},
+            }
+
+            expect(trigger).toBeDefined()
+            expect(trigger.name).toBe('storage-trigger')
+         })
+
+         it('should extend GenericTriggerType', () => {
+            // StorageTriggerType should have all GenericTriggerType properties
+            const trigger: StorageTriggerType = {
+               name: 'file-upload',
+               event: [
+                  BackendAction.CREATE,
+                  BackendAction.UPDATE,
+                  BackendAction.DELETE,
+               ],
+               script: () => {},
+            }
+
+            expect(trigger.name).toBeDefined()
+            expect(trigger.event).toBeDefined()
+            expect(trigger.script).toBeDefined()
+         })
+      })
+
+      describe('StorageEventPayloadType', () => {
+         it('should be importable', () => {
+            const payload: StorageEventPayloadType = {
+               before: undefined,
+               after: {
+                  name: 'test.jpg',
+                  bucket: 'uploads',
+                  fullPath: '/uploads/test.jpg',
+                  contentType: 'image/jpeg',
+                  size: 1024,
+                  timeCreated: new Date(),
+                  updated: new Date(),
+               },
+               context: {},
+            }
+
+            expect(payload).toBeDefined()
+            expect(payload.before).toBeUndefined()
+            expect(payload.after).toBeDefined()
+         })
+
+         it('should support before and after file objects', () => {
+            const fileData = {
+               name: 'document.pdf',
+               bucket: 'documents',
+               fullPath: '/documents/document.pdf',
+               contentType: 'application/pdf',
+               size: 2048,
+               timeCreated: new Date(),
+               updated: new Date(),
+            }
+
+            const payload: StorageEventPayloadType = {
+               before: fileData,
+               after: { ...fileData, size: 3072 }, // Modified size
+               context: { userId: 'user-123' },
+            }
+
+            expect(payload.before?.size).toBe(2048)
+            expect(payload.after?.size).toBe(3072)
+            expect(payload.context.userId).toBe('user-123')
+         })
+
+         it('should allow undefined before for create events', () => {
+            const payload: StorageEventPayloadType = {
+               before: undefined,
+               after: {
+                  name: 'new-file.txt',
+                  bucket: 'files',
+                  fullPath: '/files/new-file.txt',
+                  contentType: 'text/plain',
+                  size: 512,
+                  timeCreated: new Date(),
+                  updated: new Date(),
+               },
+               context: {},
+            }
+
+            expect(payload.before).toBeUndefined()
+            expect(payload.after).toBeDefined()
+         })
+
+         it('should allow undefined after for delete events', () => {
+            const payload: StorageEventPayloadType = {
+               before: {
+                  name: 'deleted-file.txt',
+                  bucket: 'files',
+                  fullPath: '/files/deleted-file.txt',
+                  contentType: 'text/plain',
+                  size: 256,
+                  timeCreated: new Date(),
+                  updated: new Date(),
+               },
+               after: undefined,
+               context: {},
+            }
+
+            expect(payload.before).toBeDefined()
+            expect(payload.after).toBeUndefined()
+         })
+      })
+   })
+
+   describe('Module Exports', () => {
+      it('should export AbstractCloudWrapper', () => {
+         expect(AbstractCloudWrapper).toBeDefined()
+         expect(typeof AbstractCloudWrapper).toBe('function')
+      })
+
+      it('should export CloudWrapper', () => {
+         expect(CloudWrapper).toBeDefined()
+         expect(typeof CloudWrapper).toBe('function')
+      })
+
+      it('should export all type definitions', () => {
+         // If these imports work, the exports are correct
+         // TypeScript will catch any export issues at compile time
+         expect(true).toBe(true)
+      })
+   })
+})

package/src/CloudWrapper.ts

@@ -0,0 +1,5 @@
+import { Core } from '@quatrain/core'
+
+export class CloudWrapper extends Core {
+    static logger = this.addLogger('Cloud')
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+import { AbstractCloudWrapper } from './AbstractCloudWrapper'
+import { CloudWrapper } from './CloudWrapper'
+import { DatabaseTriggerType } from './types/DatabaseTriggerType'
+import { StorageTriggerType } from './types/StorageTriggerType'
+import { StorageEventPayloadType } from './types/StorageEventPayloadType'
+
+export {
+   AbstractCloudWrapper,
+   CloudWrapper,
+   DatabaseTriggerType,
+   StorageTriggerType,
+   StorageEventPayloadType,
+}

package/src/types/DatabaseTriggerType.ts

@@ -0,0 +1,7 @@
+import { GenericTriggerType } from './GenericTriggerType'
+
+export interface DatabaseTriggerType extends GenericTriggerType {
+   schema?: string
+   model: string
+   path: string
+}

package/src/types/GenericEventPayloadType.ts

@@ -0,0 +1,5 @@
+export interface GenericEventPayloadType {
+   before: any
+   after: any
+   context: any
+}

package/src/types/GenericTriggerType.ts

@@ -0,0 +1,7 @@
+import { BackendAction } from '@quatrain/backend'
+
+export type GenericTriggerType = {
+   name: string
+   event: BackendAction | BackendAction[]
+   script: Function
+}

package/src/types/StorageEventPayloadType.ts

@@ -0,0 +1,7 @@
+import { GenericEventPayloadType } from './GenericEventPayloadType'
+import { FileType } from '@quatrain/storage'
+
+export interface StorageEventPayloadType extends GenericEventPayloadType {
+   before: FileType | undefined
+   after: FileType | undefined
+}

package/src/types/StorageTriggerType.ts

@@ -0,0 +1,3 @@
+import { GenericTriggerType } from './GenericTriggerType'
+
+export interface StorageTriggerType extends GenericTriggerType {}