@appweaver/cli 1.3.0 → 1.4.0

package/skill/references/security.md

@@ -321,11 +321,35 @@ export default createAuthService({
 });
 ```
 
-**User avatar** — the provider's avatar/picture URL is passed to `registrationData` as `additionalData.avatarUrl`. When
-`SECURITY_OAUTH2_FETCH_AVATAR_ENABLED=true` (JSON: `security.oauth2.fetchAvatarEnabled`), the avatar image is also
-downloaded during registration and passed as `additionalData.avatarFile`
-(`{ name, mimeType, size, data: Buffer }`), so it can be mapped to a model field or stored via the file service. The
-download is best-effort: failures are logged and registration proceeds without the file.
+**User avatar** — `registrationData` and `registrationFiles` receive the provider's picture URL as
+`additionalData.avatarUrl` and the downloaded image as `additionalData.avatarFile`
+(`{ name, mimeType, size, data: Buffer }`). `SECURITY_OAUTH2_FETCH_AVATAR_ENABLED=false` (JSON:
+`security.oauth2.fetchAvatarEnabled`) skips the download, leaving `avatarFile` `undefined`. The download is best-effort:
+failures are logged and registration proceeds without the file.
+
+**`registrationFiles` callback** — an optional callback on `createAuthService` that attaches the avatar (or any other
+file) to a newly registered user. A file must be linked to an existing resource, so it cannot be part of the
+registration payload and is stored right after the user record is created. Return a map of the model's **file fields**
+to the files to store; nullish values are skipped, so nothing is stored unless the callback asks for it:
+
+```ts
+// src/resources/user/service.ts
+export default createAuthService({
+  modelName: 'User',
+  registrationData: (source, email, password, additionalData) => ({
+    email,
+    password,
+    firstName: additionalData?.firstName ?? ''
+  }),
+  registrationFiles: (source, additionalData) => ({
+    avatar: additionalData?.avatarFile
+  })
+});
+```
+
+The file is validated against the `files.avatar` config of the model (media type, size limit, name pattern, image
+processing). Storing it is the best effort: a rejected file is logged and never fails the registration. Outside
+registration, use [`FileService.saveBuffer()`](./storage.md#saving-an-in-memory-file).
 
 ### Client-side OAuth2 integration example
 

package/skill/references/storage.md

@@ -220,26 +220,54 @@ When saving a file via `FileService`, you must provide the multipart data, the r
 `ResourceClient`.
 
 ```ts
-import { inject, injectService, injectModel } from '@appweaver/core';
+import { inject, injectService } from '@appweaver/core';
 import { FileService } from '@appweaver/core/storage';
 
 export class PostService {
   private readonly _fileService = inject(FileService);
   private readonly _postService = injectService('Post');
-  private readonly _postClient = injectModel('Post');
 
   async uploadImage(postId: number, data: MultipartFile) {
     const post = await this._postService.find(postId);
 
     // saveFile stores the file in Storage AND creates a File record in the DB
-    // linked to the 'image' field of the 'post' resource.
-    const file = await this._fileService.saveFile(data, post, this._postClient);
+    // linked to the file field named by the multipart field of the 'post' resource.
+    const file = await this._fileService.saveFile(
+      data,
+      post,
+      this._postService.client
+    );
 
     return file;
   }
 }
 ```
 
+### Saving an in-memory file
+
+`saveBuffer()` stores a file that did not arrive as a multipart upload — a downloaded avatar, a generated report, a
+thumbnail. It behaves exactly like `saveFile()` (media type check, size limit, name pattern, image processing,
+checksum, `File` record), except the content comes from a buffer and the target file field is named explicitly:
+
+```ts
+import { inject, injectService } from '@appweaver/core';
+import { FileService } from '@appweaver/core/storage';
+
+const users = injectService('User');
+const user = await users.find(userId);
+
+const file = await inject(FileService).saveBuffer(
+  'avatar', // the file field of the User model
+  { name: 'avatar.png', mimeType: 'image/png', data: buffer },
+  user,
+  users.client
+);
+```
+
+The optional `size` (defaults to the buffer length) is what the size limit is checked against, and `encoding` defaults
+to `7bit`. The owning resource must already exist — to attach files while a user is registering, use the
+[`registrationFiles`](./security.md) callback of `createAuthService`.
+
 ### File integrity (checksum)
 
 When a file is uploaded through `FileService.saveFile()` (or the resource file upload routes), a **SHA-256 checksum**
@@ -326,3 +354,9 @@ You can also call `deleteResourceFiles` manually if needed:
 ```ts
 await fileService.deleteResourceFiles('Post', postId);
 ```
+
+### Owning resource reference
+
+The `File` model records its owner through the `resourceName`, `resourceField` and `resourceId` columns. `resourceId`
+is a text column holding the owning record ID, so files attach to models with either an integer or a string primary
+key, and `deleteResourceFiles` accepts an ID of either type.

package/utils/loader-util.js

@@ -128,5 +128,8 @@ async function loadModels(modelPattern) {
     if (Object.keys(models).length === 0) {
         console.log('No resource models exports found matching pattern:', modelPattern);
     }
+    // Resolve the schemas referencing the primary key of another model, now that
+    // every model is registered
+    (0, common_1.relinkResourceModels)(models);
     return models;
 }