@venizia/ignis 0.4.3 → 0.4.4

package/dist/esm/components/static-asset/common/keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../../../../../src/components/static-asset/common/keys.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,+BAA+B;IAC1C,oPAAoP;aACpO,mCAA8B,GAAG,qCAAqC,CAAC","sourcesContent":["export class StaticAssetComponentBindingKeys {\n  /** The options an application registers through `configs.artifacts` land here, because an artifact index carries classes and no options. `application.component(StaticAssetComponent, { options })` passes them directly and wins over this key. */\n  static readonly STATIC_ASSET_COMPONENT_OPTIONS = '@app/static-asset-component/options';\n}\n"]}

package/dist/esm/components/static-asset/common/types.d.ts

@@ -0,0 +1,165 @@
+import type { BaseRestController, IAuthRouteConfig, TRouteContext } from '../../../base/index.js';
+import type { IDuration } from '@venizia/ignis-helpers/common';
+import type { BaseRelationalEntity, DefaultCRUDRepository, TTableObject } from '@venizia/ignis-connectors/postgres';
+import type { DiskHelper, IBucketRef, IFileStat, IObjectLocation, IObjectRef, IStorageHelper, IUploadResult, TUploadNaming } from '@venizia/ignis-helpers';
+import type { BunS3Helper } from '@venizia/ignis-helpers/bun-s3';
+import type { AnyType, TValueOrAsyncResolver, ValueOrPromise } from '@venizia/ignis-helpers/common';
+import type { TMultipartStorage } from '@venizia/ignis-helpers';
+import type { MinioHelper } from '@venizia/ignis-helpers/minio';
+import type { TMetaLinkCompatibleSchema, TMetaLinkSchema } from '../models/index.js';
+import type { StaticAssetStorageTypes } from './constants.js';
+export type TStaticAssetExtraOptions = {
+    parseMultipartBody?: {
+        storage?: TMultipartStorage;
+        uploadDir?: string;
+    };
+    /** `folderPath` carries the upload query's target folder - dropping it flattens nested uploads. */
+    normalizeNameFn?: (opts: {
+        file: TUploadNaming;
+    }) => string;
+    normalizeLinkFn?: (opts: IObjectLocation) => string;
+    /** Maximum folder nesting depth allowed in object paths. Default: 2 */
+    maxFolderDepth?: number;
+    /** Largest file the UPLOAD route accepts. Absent means no ceiling. Checked against `content-length` before spooling, then per file after parsing. */
+    maxBytes?: number;
+    [key: string]: AnyType;
+};
+/** Decides the key one uploaded file is stored under. `defaultKey` is what IGNIS would have written. */
+export type TObjectNameResolver = (opts: {
+    bucket: IBucketRef;
+    file: TUploadNaming;
+    defaultKey: string;
+}) => string;
+/** Adds routes of the application's own to a generated asset controller. Runs after every built-in route, so a built-in route always wins a path collision. `basePath` is the mount path with exactly one leading slash. */
+/** Adds routes of the application's own. Registration order decides a path collision, so the same shape serves both the before and the after hook. */
+export type TDefineExtraRoutes = (opts: {
+    controller: BaseRestController;
+    helper: IStorageHelper;
+    basePath: string;
+}) => void;
+export type TBucketParams = {
+    bucketName: string;
+};
+export type TObjectParams = {
+    bucketName: string;
+    objectName: string;
+};
+export type TUploadQuery = {
+    principalType?: string;
+    principalId?: string;
+    variant?: string;
+    /** Display order within the principal. Caller-supplied: deriving it would be a non-atomic read of `max(sequence)` then a write of `max + 1`. */
+    sequence?: number;
+    folderPath?: string;
+};
+export type TListQuery = {
+    prefix?: string;
+    recursive?: string;
+    maxKeys?: string;
+};
+export type TDirectUploadOptions = {
+    /** Who may ask for a policy. REQUIRED, not defaulted: this route hands out a write credential, and there is no safe default for that. */
+    authorize: (opts: {
+        context: TRouteContext;
+    }) => ValueOrPromise<boolean>;
+    /** Signs the commit token. Keep it out of the repository and out of the client. */
+    secretKey: string;
+    /** The ceiling the policy carries as `content-length-range`. A signed PUT cannot express this at all, which is why this is a POST policy. */
+    maxBytes: number;
+    /** Where a policy may write. The final key is NEVER in a policy, so content cannot be replaced after the commit. Default: `pending/`. */
+    pendingPrefix?: string;
+    /** How long a policy and its commit token stay good. Default: the helper's POST default. */
+    expiresIn?: IDuration;
+    /** Runs BEFORE the copy to the final key, so a hook that throws leaves the object under the pending prefix for a lifecycle rule to collect, rather than stranding it at the final key. */
+    onCommit?: (opts: {
+        bucket: IBucketRef;
+        pendingObject: IObjectRef;
+        object: IObjectRef;
+    }) => ValueOrPromise<void>;
+};
+export type TUploadPolicyRequest = {
+    files: Array<{
+        fileName: string;
+        contentType?: string;
+        size?: number;
+    }>;
+};
+/** The MetaLink table belongs to the application. `Schema` defaults to the table IGNIS ships, and widens to any table whose row carries the same fields. */
+export type TMetaLinkConfig<Schema extends TMetaLinkCompatibleSchema = TMetaLinkSchema> = {
+    model: TValueOrAsyncResolver<typeof BaseRelationalEntity<Schema>>;
+    repository: TValueOrAsyncResolver<DefaultCRUDRepository<Schema>>;
+    createMetaLink?: (opts: {
+        uploadResult: IUploadResult;
+        fileStat: IFileStat;
+        /** The caller's labels. Named for where they used to travel - they arrive in the request BODY now, as form fields on an upload and beside the commit token on a direct one. */
+        query: TUploadQuery;
+    }) => ValueOrPromise<{
+        count: number;
+        data: TTableObject<Schema>;
+    }>;
+};
+/** The part of a built-in route an application may change. */
+export type TStaticAssetRouteConfig = Partial<Omit<IAuthRouteConfig, 'method' | 'request' | 'responses'>> & {
+    /** Whether this route is registered. Defaults to true. */
+    enabled?: boolean;
+};
+export type TStaticAssetRoutes = {
+    getBuckets?: TStaticAssetRouteConfig;
+    getBucketByName?: TStaticAssetRouteConfig;
+    createBucket?: TStaticAssetRouteConfig;
+    deleteBucket?: TStaticAssetRouteConfig;
+    upload?: TStaticAssetRouteConfig;
+    listObjects?: TStaticAssetRouteConfig;
+    deleteObject?: TStaticAssetRouteConfig;
+    getObjectByName?: TStaticAssetRouteConfig;
+    downloadObjectByName?: TStaticAssetRouteConfig;
+    uploadPolicy?: TStaticAssetRouteConfig;
+    uploadCommit?: TStaticAssetRouteConfig;
+    recreateMetaLink?: TStaticAssetRouteConfig;
+};
+export type TStaticAssetsComponentOptions<Schema extends TMetaLinkCompatibleSchema = TMetaLinkSchema> = {
+    [key: string]: {
+        controller: {
+            name: string;
+            basePath: string;
+            isStrict?: boolean;
+            /** `true` serves a raw nested object path (`/objects/photos/2024/f.jpg`) - a URL shape change; a percent-encoded path keeps working either way. Default: `false`. */
+            rawObjectPath?: boolean;
+            /** The single bucket every object route uses. It leaves the URL (`/objects/{objectName}`) and the four bucket-management routes are not registered. The function form is read per request, so an environment variable can be read lazily. */
+            bucket?: TValueOrAsyncResolver<string>;
+            /**
+             * The key scope this controller owns, e.g. `inventory/`. Every route refuses a key outside it
+             * as a 404 without calling the storage, `listObjects` lists only inside it, and an upload key
+             * must land inside it: the default name is placed there, a `resolveObjectName` or
+             * `extra.normalizeNameFn` key outside it is refused. `maxFolderDepth` counts the folders below
+             * it. Absent: every key in the bucket.
+             */
+            keyPrefix?: string;
+            routes?: TStaticAssetRoutes;
+            /** Direct upload: the browser posts the bytes to the storage and IGNIS only signs the permission. Absent leaves both routes unregistered. Requires `bucket` - a policy names one bucket, and a bucket in the URL is a bucket the caller chooses. */
+            directUpload?: TDirectUploadOptions;
+        };
+        extra?: TStaticAssetExtraOptions;
+        /** Decides the stored object name of each uploaded file; absent keeps the storage helper's own naming. */
+        resolveObjectName?: TObjectNameResolver;
+        /** Registers the application's own routes BEFORE every built-in one, so a literal path wins over the catch-all `rawObjectPath` produces. Hono matches in registration order. */
+        defineRoutesBefore?: TDefineExtraRoutes;
+        /** Registers the application's own routes on the generated controller, after every built-in one. */
+        defineExtraRoutes?: TDefineExtraRoutes;
+    } & ({
+        storage: typeof StaticAssetStorageTypes.BUN_S3;
+        helper: BunS3Helper;
+    } | {
+        storage: typeof StaticAssetStorageTypes.DISK;
+        helper: DiskHelper;
+    } | {
+        storage: typeof StaticAssetStorageTypes.MINIO;
+        helper: MinioHelper;
+    }) & ({
+        useMetaLink?: false | undefined;
+    } | {
+        useMetaLink: true;
+        metaLink: TMetaLinkConfig<Schema>;
+    });
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/esm/components/static-asset/common/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../src/components/static-asset/common/types.ts"],"names":[],"mappings":"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"}

package/dist/esm/components/static-asset/common/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/components/static-asset/common/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../src/components/static-asset/common/types.ts"],"names":[],"mappings":"","sourcesContent":["import type { BaseRestController, IAuthRouteConfig, TRouteContext } from '@/base';\nimport type { IDuration } from '@venizia/ignis-helpers/common';\nimport type {\n  BaseRelationalEntity,\n  DefaultCRUDRepository,\n  TTableObject,\n} from '@venizia/ignis-connectors/postgres';\nimport type {\n  DiskHelper,\n  IBucketRef,\n  IFileStat,\n  IObjectLocation,\n  IObjectRef,\n  IStorageHelper,\n  IUploadResult,\n  TUploadNaming,\n} from '@venizia/ignis-helpers';\nimport type { BunS3Helper } from '@venizia/ignis-helpers/bun-s3';\nimport type { AnyType, TValueOrAsyncResolver, ValueOrPromise } from '@venizia/ignis-helpers/common';\nimport type { TMultipartStorage } from '@venizia/ignis-helpers';\nimport type { MinioHelper } from '@venizia/ignis-helpers/minio';\nimport type { TMetaLinkCompatibleSchema, TMetaLinkSchema } from '../models';\nimport type { StaticAssetStorageTypes } from './constants';\n\nexport type TStaticAssetExtraOptions = {\n  parseMultipartBody?: {\n    storage?: TMultipartStorage;\n    uploadDir?: string;\n  };\n\n  /** `folderPath` carries the upload query's target folder - dropping it flattens nested uploads. */\n  normalizeNameFn?: (opts: { file: TUploadNaming }) => string;\n  normalizeLinkFn?: (opts: IObjectLocation) => string;\n\n  /** Maximum folder nesting depth allowed in object paths. Default: 2 */\n  maxFolderDepth?: number;\n\n  /** Largest file the UPLOAD route accepts. Absent means no ceiling. Checked against `content-length` before spooling, then per file after parsing. */\n  maxBytes?: number;\n  [key: string]: AnyType;\n};\n\n/** Decides the key one uploaded file is stored under. `defaultKey` is what IGNIS would have written. */\nexport type TObjectNameResolver = (opts: {\n  bucket: IBucketRef;\n  file: TUploadNaming;\n  defaultKey: string;\n}) => string;\n\n/** Adds routes of the application's own to a generated asset controller. Runs after every built-in route, so a built-in route always wins a path collision. `basePath` is the mount path with exactly one leading slash. */\n/** Adds routes of the application's own. Registration order decides a path collision, so the same shape serves both the before and the after hook. */\nexport type TDefineExtraRoutes = (opts: {\n  controller: BaseRestController;\n  helper: IStorageHelper;\n  basePath: string;\n}) => void;\n\n// Declared by hand rather than inferred: RouteHandler inference here is heavy.\nexport type TBucketParams = { bucketName: string };\nexport type TObjectParams = { bucketName: string; objectName: string };\nexport type TUploadQuery = {\n  principalType?: string;\n  principalId?: string;\n  variant?: string;\n  /** Display order within the principal. Caller-supplied: deriving it would be a non-atomic read of `max(sequence)` then a write of `max + 1`. */\n  sequence?: number;\n  folderPath?: string;\n};\nexport type TListQuery = { prefix?: string; recursive?: string; maxKeys?: string };\n\nexport type TDirectUploadOptions = {\n  /** Who may ask for a policy. REQUIRED, not defaulted: this route hands out a write credential, and there is no safe default for that. */\n  authorize: (opts: { context: TRouteContext }) => ValueOrPromise<boolean>;\n\n  /** Signs the commit token. Keep it out of the repository and out of the client. */\n  secretKey: string;\n\n  /** The ceiling the policy carries as `content-length-range`. A signed PUT cannot express this at all, which is why this is a POST policy. */\n  maxBytes: number;\n\n  /** Where a policy may write. The final key is NEVER in a policy, so content cannot be replaced after the commit. Default: `pending/`. */\n  pendingPrefix?: string;\n\n  /** How long a policy and its commit token stay good. Default: the helper's POST default. */\n  expiresIn?: IDuration;\n\n  /** Runs BEFORE the copy to the final key, so a hook that throws leaves the object under the pending prefix for a lifecycle rule to collect, rather than stranding it at the final key. */\n  onCommit?: (opts: {\n    bucket: IBucketRef;\n    pendingObject: IObjectRef;\n    object: IObjectRef;\n  }) => ValueOrPromise<void>;\n};\n\nexport type TUploadPolicyRequest = {\n  files: Array<{ fileName: string; contentType?: string; size?: number }>;\n};\n\n/** The MetaLink table belongs to the application. `Schema` defaults to the table IGNIS ships, and widens to any table whose row carries the same fields. */\nexport type TMetaLinkConfig<Schema extends TMetaLinkCompatibleSchema = TMetaLinkSchema> = {\n  model: TValueOrAsyncResolver<typeof BaseRelationalEntity<Schema>>;\n  repository: TValueOrAsyncResolver<DefaultCRUDRepository<Schema>>;\n  createMetaLink?: (opts: {\n    uploadResult: IUploadResult;\n    fileStat: IFileStat;\n    /** The caller's labels. Named for where they used to travel - they arrive in the request BODY now, as form fields on an upload and beside the commit token on a direct one. */\n    query: TUploadQuery;\n  }) => ValueOrPromise<{ count: number; data: TTableObject<Schema> }>;\n};\n\n/** The part of a built-in route an application may change. */\nexport type TStaticAssetRouteConfig = Partial<\n  Omit<IAuthRouteConfig, 'method' | 'request' | 'responses'>\n> & {\n  /** Whether this route is registered. Defaults to true. */\n  enabled?: boolean;\n};\n\nexport type TStaticAssetRoutes = {\n  getBuckets?: TStaticAssetRouteConfig;\n  getBucketByName?: TStaticAssetRouteConfig;\n  createBucket?: TStaticAssetRouteConfig;\n  deleteBucket?: TStaticAssetRouteConfig;\n\n  upload?: TStaticAssetRouteConfig;\n  listObjects?: TStaticAssetRouteConfig;\n  deleteObject?: TStaticAssetRouteConfig;\n  getObjectByName?: TStaticAssetRouteConfig;\n  downloadObjectByName?: TStaticAssetRouteConfig;\n\n  uploadPolicy?: TStaticAssetRouteConfig;\n  uploadCommit?: TStaticAssetRouteConfig;\n\n  recreateMetaLink?: TStaticAssetRouteConfig;\n};\n\nexport type TStaticAssetsComponentOptions<\n  Schema extends TMetaLinkCompatibleSchema = TMetaLinkSchema,\n> = {\n  [key: string]: {\n    controller: {\n      name: string;\n      basePath: string;\n      isStrict?: boolean;\n\n      /** `true` serves a raw nested object path (`/objects/photos/2024/f.jpg`) - a URL shape change; a percent-encoded path keeps working either way. Default: `false`. */\n      rawObjectPath?: boolean;\n\n      /** The single bucket every object route uses. It leaves the URL (`/objects/{objectName}`) and the four bucket-management routes are not registered. The function form is read per request, so an environment variable can be read lazily. */\n      bucket?: TValueOrAsyncResolver<string>;\n\n      /**\n       * The key scope this controller owns, e.g. `inventory/`. Every route refuses a key outside it\n       * as a 404 without calling the storage, `listObjects` lists only inside it, and an upload key\n       * must land inside it: the default name is placed there, a `resolveObjectName` or\n       * `extra.normalizeNameFn` key outside it is refused. `maxFolderDepth` counts the folders below\n       * it. Absent: every key in the bucket.\n       */\n      keyPrefix?: string;\n\n      routes?: TStaticAssetRoutes;\n\n      /** Direct upload: the browser posts the bytes to the storage and IGNIS only signs the permission. Absent leaves both routes unregistered. Requires `bucket` - a policy names one bucket, and a bucket in the URL is a bucket the caller chooses. */\n      directUpload?: TDirectUploadOptions;\n    };\n    extra?: TStaticAssetExtraOptions;\n\n    /** Decides the stored object name of each uploaded file; absent keeps the storage helper's own naming. */\n    resolveObjectName?: TObjectNameResolver;\n\n    /** Registers the application's own routes BEFORE every built-in one, so a literal path wins over the catch-all `rawObjectPath` produces. Hono matches in registration order. */\n    defineRoutesBefore?: TDefineExtraRoutes;\n\n    /** Registers the application's own routes on the generated controller, after every built-in one. */\n    defineExtraRoutes?: TDefineExtraRoutes;\n  } & (\n    | { storage: typeof StaticAssetStorageTypes.BUN_S3; helper: BunS3Helper }\n    | { storage: typeof StaticAssetStorageTypes.DISK; helper: DiskHelper }\n    | { storage: typeof StaticAssetStorageTypes.MINIO; helper: MinioHelper }\n  ) &\n    (\n      | { useMetaLink?: false | undefined }\n      | { useMetaLink: true; metaLink: TMetaLinkConfig<Schema> }\n    );\n};\n"]}

package/dist/esm/components/static-asset/component.d.ts

@@ -0,0 +1,12 @@
+import { type BaseApplication } from '../../base/applications/index.js';
+import { BaseComponent } from '@venizia/ignis-kernel';
+import { type ValueOrPromise } from '@venizia/ignis-helpers/common';
+import { type TStaticAssetsComponentOptions } from './common/index.js';
+import type { TMetaLinkCompatibleSchema, TMetaLinkSchema } from './models/index.js';
+/** `Schema` is the MetaLink table the application binds. It has to live on the CLASS, not only on the options: `component(Ctor, { options })` infers the options from the class, so a class pinned to the shipped table can only carry options for that table. */
+export declare class StaticAssetComponent<Schema extends TMetaLinkCompatibleSchema = TMetaLinkSchema> extends BaseComponent<TStaticAssetsComponentOptions<Schema>> {
+    private application;
+    constructor(application: BaseApplication);
+    binding(): ValueOrPromise<void>;
+}
+//# sourceMappingURL=component.d.ts.map

package/dist/esm/components/static-asset/component.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../../../../src/components/static-asset/component.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAItD,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,EAAmC,KAAK,6BAA6B,EAAE,MAAM,UAAU,CAAC;AAC/F,OAAO,KAAK,EAAE,yBAAyB,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAG3E,kQAAkQ;AAClQ,qBAAa,oBAAoB,CAC/B,MAAM,SAAS,yBAAyB,GAAG,eAAe,CAC1D,SAAQ,aAAa,CAAC,6BAA6B,CAAC,MAAM,CAAC,CAAC;IAEN,OAAO,CAAC,WAAW;gBAAX,WAAW,EAAE,eAAe;IAcjF,OAAO,IAAI,cAAc,CAAC,IAAI,CAAC;CAwDzC"}

package/dist/esm/components/static-asset/component.js

@@ -0,0 +1,75 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var StaticAssetComponent_1;
+import { BaseComponent } from '@venizia/ignis-kernel';
+import { inject } from '../../base/metadata/index.js';
+import { CoreBindings } from '@venizia/ignis-kernel';
+import { Binding } from '@venizia/ignis-kernel';
+import { StaticAssetComponentBindingKeys } from './common/index.js';
+import { AssetControllerFactory, buildObjectLink } from './controller/index.js';
+/** `Schema` is the MetaLink table the application binds. It has to live on the CLASS, not only on the options: `component(Ctor, { options })` infers the options from the class, so a class pinned to the shipped table can only carry options for that table. */
+let StaticAssetComponent = StaticAssetComponent_1 = class StaticAssetComponent extends BaseComponent {
+    constructor(application) {
+        super({
+            scope: StaticAssetComponent_1.name,
+            initDefault: { enable: true, container: application },
+            bindings: {
+                [StaticAssetComponentBindingKeys.STATIC_ASSET_COMPONENT_OPTIONS]: Binding.bind({
+                    key: StaticAssetComponentBindingKeys.STATIC_ASSET_COMPONENT_OPTIONS,
+                }).toValue({}),
+            },
+        });
+        this.application = application;
+    }
+    binding() {
+        // Direct options win. The key is the path for an application that registers this component
+        // through `configs.artifacts`, where an index carries classes and no options.
+        const componentOptions = this.options ??
+            this.application.get({
+                key: StaticAssetComponentBindingKeys.STATIC_ASSET_COMPONENT_OPTIONS,
+            });
+        const componentOptionsEntries = Object.entries(componentOptions);
+        for (const [key, opt] of componentOptionsEntries) {
+            const { storage, controller, helper, extra, resolveObjectName, defineRoutesBefore, defineExtraRoutes, } = opt;
+            this.application.controller(AssetControllerFactory.defineAssetController({
+                controller,
+                storage,
+                helper,
+                useMetaLink: opt.useMetaLink,
+                metaLink: opt.useMetaLink ? opt.metaLink : undefined,
+                resolveObjectName,
+                defineRoutesBefore,
+                defineExtraRoutes,
+                options: {
+                    ...extra,
+                    normalizeLinkFn: extra?.normalizeLinkFn ??
+                        // The link follows the URL shape the controller serves: `{objectName}` is one Hono path segment unless `rawObjectPath` widens it, and a configured bucket leaves the path.
+                        ((linkOptions) => buildObjectLink({
+                            basePath: controller.basePath,
+                            bucket: linkOptions.bucket,
+                            object: linkOptions.object,
+                            hasConfiguredBucket: controller.bucket !== undefined,
+                            rawObjectPath: controller.rawObjectPath,
+                        })),
+                },
+            }));
+            this.application.logger.info(`[binding] Asset storage is bound | Key: %s | Storage type: %s | UseMetaLink: %s`, key, storage, Boolean(opt.useMetaLink));
+        }
+    }
+};
+StaticAssetComponent = StaticAssetComponent_1 = __decorate([
+    __param(0, inject({ key: CoreBindings.APPLICATION_INSTANCE })),
+    __metadata("design:paramtypes", [Function])
+], StaticAssetComponent);
+export { StaticAssetComponent };
+//# sourceMappingURL=component.js.map

package/dist/esm/components/static-asset/component.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"component.js","sourceRoot":"","sources":["../../../../src/components/static-asset/component.ts"],"names":[],"mappings":";;;;;;;;;;;;;AACA,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAEhD,OAAO,EAAE,+BAA+B,EAAsC,MAAM,UAAU,CAAC;AAE/F,OAAO,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEvE,kQAAkQ;AAClQ,IAAa,oBAAoB,4BAAjC,MAAa,oBAEX,SAAQ,aAAoD;IAC5D,YAC8D,WAA4B;QAExF,KAAK,CAAC;YACJ,KAAK,EAAE,sBAAoB,CAAC,IAAI;YAChC,WAAW,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE;YACrD,QAAQ,EAAE;gBACR,CAAC,+BAA+B,CAAC,8BAA8B,CAAC,EAC9D,OAAO,CAAC,IAAI,CAAgC;oBAC1C,GAAG,EAAE,+BAA+B,CAAC,8BAA8B;iBACpE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;aACjB;SACF,CAAC,CAAC;QAXyD,gBAAW,GAAX,WAAW,CAAiB;IAY1F,CAAC;IAEQ,OAAO;QACd,2FAA2F;QAC3F,8EAA8E;QAC9E,MAAM,gBAAgB,GACpB,IAAI,CAAC,OAAO;YACZ,IAAI,CAAC,WAAW,CAAC,GAAG,CAAwC;gBAC1D,GAAG,EAAE,+BAA+B,CAAC,8BAA8B;aACpE,CAAC,CAAC;QAEL,MAAM,uBAAuB,GAAG,MAAM,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC;QACjE,KAAK,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,uBAAuB,EAAE,CAAC;YACjD,MAAM,EACJ,OAAO,EACP,UAAU,EACV,MAAM,EACN,KAAK,EACL,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,GAClB,GAAG,GAAG,CAAC;YAER,IAAI,CAAC,WAAW,CAAC,UAAU,CACzB,sBAAsB,CAAC,qBAAqB,CAAC;gBAC3C,UAAU;gBACV,OAAO;gBACP,MAAM;gBACN,WAAW,EAAE,GAAG,CAAC,WAAW;gBAC5B,QAAQ,EAAE,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS;gBACpD,iBAAiB;gBACjB,kBAAkB;gBAClB,iBAAiB;gBACjB,OAAO,EAAE;oBACP,GAAG,KAAK;oBACR,eAAe,EACb,KAAK,EAAE,eAAe;wBACtB,2KAA2K;wBAC3K,CAAC,CAAC,WAAW,EAAE,EAAE,CACf,eAAe,CAAC;4BACd,QAAQ,EAAE,UAAU,CAAC,QAAQ;4BAC7B,MAAM,EAAE,WAAW,CAAC,MAAM;4BAC1B,MAAM,EAAE,WAAW,CAAC,MAAM;4BAC1B,mBAAmB,EAAE,UAAU,CAAC,MAAM,KAAK,SAAS;4BACpD,aAAa,EAAE,UAAU,CAAC,aAAa;yBACxC,CAAC,CAAC;iBACR;aACF,CAAC,CACH,CAAC;YAEF,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,IAAI,CAC1B,iFAAiF,EACjF,GAAG,EACH,OAAO,EACP,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,CACzB,CAAC;QACJ,CAAC;IACH,CAAC;CACF,CAAA;AA1EY,oBAAoB;IAI5B,WAAA,MAAM,CAAC,EAAE,GAAG,EAAE,YAAY,CAAC,oBAAoB,EAAE,CAAC,CAAA;;GAJ1C,oBAAoB,CA0EhC","sourcesContent":["import { type BaseApplication } from '@/base/applications';\nimport { BaseComponent } from '@venizia/ignis-kernel';\nimport { inject } from '@/base/metadata';\nimport { CoreBindings } from '@venizia/ignis-kernel';\nimport { Binding } from '@venizia/ignis-kernel';\nimport { type ValueOrPromise } from '@venizia/ignis-helpers/common';\nimport { StaticAssetComponentBindingKeys, type TStaticAssetsComponentOptions } from './common';\nimport type { TMetaLinkCompatibleSchema, TMetaLinkSchema } from './models';\nimport { AssetControllerFactory, buildObjectLink } from './controller';\n\n/** `Schema` is the MetaLink table the application binds. It has to live on the CLASS, not only on the options: `component(Ctor, { options })` infers the options from the class, so a class pinned to the shipped table can only carry options for that table. */\nexport class StaticAssetComponent<\n  Schema extends TMetaLinkCompatibleSchema = TMetaLinkSchema,\n> extends BaseComponent<TStaticAssetsComponentOptions<Schema>> {\n  constructor(\n    @inject({ key: CoreBindings.APPLICATION_INSTANCE }) private application: BaseApplication,\n  ) {\n    super({\n      scope: StaticAssetComponent.name,\n      initDefault: { enable: true, container: application },\n      bindings: {\n        [StaticAssetComponentBindingKeys.STATIC_ASSET_COMPONENT_OPTIONS]:\n          Binding.bind<TStaticAssetsComponentOptions>({\n            key: StaticAssetComponentBindingKeys.STATIC_ASSET_COMPONENT_OPTIONS,\n          }).toValue({}),\n      },\n    });\n  }\n\n  override binding(): ValueOrPromise<void> {\n    // Direct options win. The key is the path for an application that registers this component\n    // through `configs.artifacts`, where an index carries classes and no options.\n    const componentOptions =\n      this.options ??\n      this.application.get<TStaticAssetsComponentOptions<Schema>>({\n        key: StaticAssetComponentBindingKeys.STATIC_ASSET_COMPONENT_OPTIONS,\n      });\n\n    const componentOptionsEntries = Object.entries(componentOptions);\n    for (const [key, opt] of componentOptionsEntries) {\n      const {\n        storage,\n        controller,\n        helper,\n        extra,\n        resolveObjectName,\n        defineRoutesBefore,\n        defineExtraRoutes,\n      } = opt;\n\n      this.application.controller(\n        AssetControllerFactory.defineAssetController({\n          controller,\n          storage,\n          helper,\n          useMetaLink: opt.useMetaLink,\n          metaLink: opt.useMetaLink ? opt.metaLink : undefined,\n          resolveObjectName,\n          defineRoutesBefore,\n          defineExtraRoutes,\n          options: {\n            ...extra,\n            normalizeLinkFn:\n              extra?.normalizeLinkFn ??\n              // The link follows the URL shape the controller serves: `{objectName}` is one Hono path segment unless `rawObjectPath` widens it, and a configured bucket leaves the path.\n              ((linkOptions) =>\n                buildObjectLink({\n                  basePath: controller.basePath,\n                  bucket: linkOptions.bucket,\n                  object: linkOptions.object,\n                  hasConfiguredBucket: controller.bucket !== undefined,\n                  rawObjectPath: controller.rawObjectPath,\n                })),\n          },\n        }),\n      );\n\n      this.application.logger.info(\n        `[binding] Asset storage is bound | Key: %s | Storage type: %s | UseMetaLink: %s`,\n        key,\n        storage,\n        Boolean(opt.useMetaLink),\n      );\n    }\n  }\n}\n"]}

package/dist/esm/components/static-asset/controller/base.definition.d.ts

@@ -0,0 +1,28 @@
+import type { IAuthRouteConfig } from '../../../base/index.js';
+/** The ten built-in asset routes. Only `path` and `request.params` differ between option combinations. */
+export interface IAssetDefinitions {
+    GET_BUCKETS: IAuthRouteConfig;
+    GET_BUCKET_BY_NAME: IAuthRouteConfig;
+    CREATE_BUCKET: IAuthRouteConfig;
+    DELETE_BUCKET: IAuthRouteConfig;
+    GET_OBJECT_BY_NAME: IAuthRouteConfig;
+    DOWNLOAD_OBJECT_BY_NAME: IAuthRouteConfig;
+    UPLOAD_POLICY: IAuthRouteConfig;
+    UPLOAD_COMMIT: IAuthRouteConfig;
+    UPLOAD: IAuthRouteConfig;
+    DELETE_OBJECT: IAuthRouteConfig;
+    LIST_OBJECTS: IAuthRouteConfig;
+    RECREATE_METALINK: IAuthRouteConfig;
+}
+/**
+ * Builds the route configs of one asset controller.
+ * `hasConfiguredBucket` drops `/buckets/{bucketName}` and its param from every object route.
+ * `rawObjectPath` appends the `{.+}` catch-all, the spelling `@hono/zod-openapi` translates.
+ */
+export declare const buildAssetDefinitions: (opts: {
+    hasConfiguredBucket?: boolean;
+    rawObjectPath?: boolean;
+}) => IAssetDefinitions;
+/** The bucket-in-path shape, unchanged - every existing importer keeps working. */
+export declare const StaticAssetDefinitions: IAssetDefinitions;
+//# sourceMappingURL=base.definition.d.ts.map

package/dist/esm/components/static-asset/controller/base.definition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.definition.d.ts","sourceRoot":"","sources":["../../../../../src/components/static-asset/controller/base.definition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAiE/C,0GAA0G;AAC1G,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,gBAAgB,CAAC;IAC9B,kBAAkB,EAAE,gBAAgB,CAAC;IACrC,aAAa,EAAE,gBAAgB,CAAC;IAChC,aAAa,EAAE,gBAAgB,CAAC;IAChC,kBAAkB,EAAE,gBAAgB,CAAC;IACrC,uBAAuB,EAAE,gBAAgB,CAAC;IAC1C,aAAa,EAAE,gBAAgB,CAAC;IAChC,aAAa,EAAE,gBAAgB,CAAC;IAChC,MAAM,EAAE,gBAAgB,CAAC;IACzB,aAAa,EAAE,gBAAgB,CAAC;IAChC,YAAY,EAAE,gBAAgB,CAAC;IAC/B,iBAAiB,EAAE,gBAAgB,CAAC;CACrC;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,GAAI,MAAM;IAC1C,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,KAAG,iBAkQH,CAAC;AAEF,mFAAmF;AACnF,eAAO,MAAM,sBAAsB,mBAA4B,CAAC"}

package/dist/esm/components/static-asset/controller/base.definition.js

@@ -0,0 +1,305 @@
+import { errorResponses, jsonResponse } from '@venizia/ignis-kernel';
+import { z } from '@hono/zod-openapi';
+import { HTTP } from '@venizia/ignis-helpers/common';
+import { MetaLinkRecreateActions } from '../common/constants.js';
+/** The labels both upload paths take. They ride the BODY, not the URL - an identifier in a query string lands in every access log between the client and here. */
+const uploadLabels = () => ({
+    principalType: z.string().optional(),
+    principalId: z.string().or(z.number()).optional(),
+    variant: z.string().optional(),
+    sequence: z.coerce.number().int().optional(),
+});
+const MultipartBodySchema = z.object({
+    files: z.union([z.instanceof(File), z.array(z.instanceof(File))]).openapi({
+        type: 'array',
+        items: {
+            type: 'string',
+            format: 'binary',
+        },
+    }),
+    ...uploadLabels(),
+    folderPath: z.string().optional().openapi({
+        description: 'Target folder path for uploaded files (e.g., "photos/2024")',
+        example: 'photos/2024',
+    }),
+});
+const bucketNameParam = () => z.string().openapi({
+    param: {
+        name: 'bucketName',
+        in: 'path',
+    },
+    example: 'images',
+});
+const objectNameParam = () => z.string().openapi({
+    param: {
+        name: 'objectName',
+        in: 'path',
+        description: 'Object name or path (e.g., "photo.jpg" or "photos/2024/photo.jpg")',
+    },
+    example: 'photos/2024/photo.jpg',
+});
+const fileStreamResponses = () => ({
+    [HTTP.ResultCodes.RS_2.Ok]: {
+        description: 'File stream response',
+        content: {
+            'application/octet-stream': {
+                schema: {
+                    type: 'string',
+                    format: 'binary',
+                },
+            },
+        },
+    },
+    ...errorResponses(),
+});
+/**
+ * Builds the route configs of one asset controller.
+ * `hasConfiguredBucket` drops `/buckets/{bucketName}` and its param from every object route.
+ * `rawObjectPath` appends the `{.+}` catch-all, the spelling `@hono/zod-openapi` translates.
+ */
+export const buildAssetDefinitions = (opts) => {
+    const { hasConfiguredBucket = false, rawObjectPath = false } = opts;
+    const bucketPrefix = hasConfiguredBucket ? '' : '/buckets/{bucketName}';
+    // `{objectName}` is ONE segment: a folder path travels percent-encoded (`photos%2F2024%2Ff.jpg`).
+    // The catch-all also matches a RAW nested path; the encoded form keeps working either way.
+    const objectSegment = rawObjectPath ? '{objectName}{.+}' : '{objectName}';
+    // A configured bucket is never in the URL, so a route whose only param was `bucketName` carries none.
+    const bucketRequest = () => hasConfiguredBucket ? {} : { params: z.object({ bucketName: bucketNameParam() }) };
+    const objectRequest = () => ({
+        params: hasConfiguredBucket
+            ? z.object({ objectName: objectNameParam() })
+            : z.object({ bucketName: bucketNameParam(), objectName: objectNameParam() }),
+    });
+    return {
+        GET_BUCKETS: {
+            method: 'get',
+            path: '/buckets',
+            responses: jsonResponse({
+                schema: z.array(z.object({
+                    name: z.string(),
+                    creationDate: z.iso.datetime(),
+                })),
+            }),
+        },
+        GET_BUCKET_BY_NAME: {
+            method: 'get',
+            path: bucketPrefix,
+            request: {
+                params: z.object({ bucketName: bucketNameParam() }),
+            },
+            responses: jsonResponse({
+                schema: z
+                    .object({
+                    name: z.string(),
+                    creationDate: z.iso.datetime(),
+                })
+                    .nullable(),
+            }),
+        },
+        CREATE_BUCKET: {
+            method: 'post',
+            path: bucketPrefix,
+            request: {
+                params: z.object({ bucketName: bucketNameParam() }),
+            },
+            responses: jsonResponse({
+                schema: z
+                    .object({
+                    name: z.string(),
+                    creationDate: z.iso.datetime(),
+                })
+                    .nullable(),
+            }),
+        },
+        DELETE_BUCKET: {
+            method: 'delete',
+            path: bucketPrefix,
+            request: {
+                params: z.object({ bucketName: bucketNameParam() }),
+            },
+            responses: jsonResponse({
+                schema: z.object({
+                    isDeleted: z.boolean(),
+                }),
+            }),
+        },
+        GET_OBJECT_BY_NAME: {
+            method: 'get',
+            path: `${bucketPrefix}/objects/${objectSegment}`,
+            request: objectRequest(),
+            responses: fileStreamResponses(),
+        },
+        DOWNLOAD_OBJECT_BY_NAME: {
+            method: 'get',
+            path: `${bucketPrefix}/download/${objectSegment}`,
+            request: objectRequest(),
+            responses: fileStreamResponses(),
+        },
+        UPLOAD_POLICY: {
+            method: 'post',
+            path: `${bucketPrefix}/upload-policy`,
+            request: {
+                body: {
+                    content: {
+                        'application/json': {
+                            schema: z.object({
+                                files: z.array(z.object({
+                                    fileName: z.string().min(1),
+                                    contentType: z.string().optional(),
+                                    size: z.number().int().nonnegative().optional(),
+                                })),
+                            }),
+                        },
+                    },
+                },
+            },
+            responses: jsonResponse({
+                schema: z.array(z.object({
+                    postURL: z.string(),
+                    formData: z.record(z.string(), z.string()),
+                    objectName: z.string(),
+                    commitToken: z.string(),
+                    expiresAt: z.string(),
+                })),
+                description: 'One signed POST policy per file, plus the token its commit is claimed with',
+            }),
+        },
+        UPLOAD_COMMIT: {
+            method: 'post',
+            path: `${bucketPrefix}/upload-commit`,
+            request: {
+                body: {
+                    content: {
+                        'application/json': {
+                            // The labels sit beside the token, not inside it: the token is an HMAC over
+                            // { bucket, key, expiresAt } and deliberately carries no business fields.
+                            schema: z.object({ commitToken: z.string().min(1), ...uploadLabels() }),
+                        },
+                    },
+                },
+            },
+            responses: jsonResponse({
+                schema: z.object({
+                    bucket: z.object({ name: z.string() }),
+                    object: z.object({ key: z.string() }),
+                    link: z.string(),
+                    metaLink: z
+                        .union([z.object({ data: z.any() }), z.object({ error: z.string() })])
+                        .optional(),
+                }),
+                description: 'The object at its final key, copied out of the pending prefix',
+            }),
+        },
+        UPLOAD: {
+            method: 'post',
+            path: `${bucketPrefix}/objects`,
+            request: {
+                ...bucketRequest(),
+                body: {
+                    content: {
+                        'multipart/form-data': {
+                            schema: MultipartBodySchema,
+                        },
+                    },
+                },
+            },
+            responses: jsonResponse({
+                schema: z.array(z.object({
+                    bucket: z.object({ name: z.string() }),
+                    object: z.object({
+                        key: z.string(),
+                        size: z.number(),
+                        contentType: z.string(),
+                    }),
+                    link: z.string(),
+                    metaLink: z
+                        .union([z.object({ data: z.any() }), z.object({ error: z.string() })])
+                        .optional(),
+                })),
+            }),
+        },
+        DELETE_OBJECT: {
+            method: 'delete',
+            path: `${bucketPrefix}/objects/${objectSegment}`,
+            request: objectRequest(),
+            responses: jsonResponse({
+                schema: z.object({
+                    success: z.boolean(),
+                }),
+            }),
+        },
+        LIST_OBJECTS: {
+            method: 'get',
+            path: `${bucketPrefix}/objects`,
+            request: {
+                ...bucketRequest(),
+                query: z.object({
+                    prefix: z
+                        .string()
+                        .optional()
+                        .openapi({
+                        param: {
+                            name: 'prefix',
+                            in: 'query',
+                            description: 'Filter objects by prefix',
+                        },
+                        example: 'folder/',
+                    }),
+                    recursive: z
+                        .string()
+                        .optional()
+                        .openapi({
+                        param: {
+                            name: 'recursive',
+                            in: 'query',
+                            description: 'Recursive listing',
+                        },
+                        example: 'true',
+                    }),
+                    maxKeys: z
+                        .string()
+                        .optional()
+                        .openapi({
+                        param: {
+                            name: 'maxKeys',
+                            in: 'query',
+                            description: 'Maximum number of objects to return',
+                        },
+                        example: '100',
+                    }),
+                }),
+            },
+            responses: jsonResponse({
+                schema: z.array(z.object({
+                    name: z.string().optional(),
+                    size: z.number().optional(),
+                    lastModified: z.iso.datetime().optional(),
+                    etag: z.string().optional(),
+                    prefix: z.string().optional(),
+                })),
+            }),
+        },
+        RECREATE_METALINK: {
+            method: 'put',
+            path: `${bucketPrefix}/meta-links/${objectSegment}`,
+            request: objectRequest(),
+            responses: jsonResponse({
+                schema: z.object({
+                    success: z.boolean(),
+                    action: z
+                        .enum([MetaLinkRecreateActions.REFRESHED, MetaLinkRecreateActions.CREATED])
+                        .openapi({
+                        description: '`refreshed` when rows for the object existed, `created` when none did',
+                        example: 'refreshed',
+                    }),
+                    count: z.number().openapi({ description: 'Rows refreshed or created' }),
+                    metaLink: z.any().optional().openapi({ description: 'The first of `metaLinks`' }),
+                    metaLinks: z.array(z.any()),
+                }),
+            }),
+        },
+    };
+};
+/** The bucket-in-path shape, unchanged - every existing importer keeps working. */
+export const StaticAssetDefinitions = buildAssetDefinitions({});
+//# sourceMappingURL=base.definition.js.map