@idevconn/create-icore 0.1.0

package/templates/libs/shared/src/strategies/contract/storage-contract.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it, beforeEach } from 'vitest';
+import type { FileInput, StorageStrategy } from '../storage';
+
+const fixture = (): FileInput => ({
+  buffer: Buffer.from('hello world'),
+  filename: 'hello.txt',
+  mimeType: 'text/plain',
+});
+
+export function runStorageContract(name: string, factory: () => StorageStrategy): void {
+  describe(`StorageStrategy contract: ${name}`, () => {
+    let strategy: StorageStrategy;
+
+    beforeEach(() => {
+      strategy = factory();
+    });
+
+    it('upload returns a StorageRef under the user prefix', async () => {
+      const ref = await strategy.upload('user-1', fixture());
+      expect(ref.path.startsWith('user-1/')).toBe(true);
+      expect(ref.bucket).toBeTruthy();
+    });
+
+    it('list returns previously uploaded files for the same user', async () => {
+      await strategy.upload('user-2', fixture());
+      const refs = await strategy.list('user-2');
+      expect(refs.length).toBe(1);
+    });
+
+    it('list isolates users', async () => {
+      await strategy.upload('user-a', fixture());
+      expect(await strategy.list('user-b')).toEqual([]);
+    });
+
+    it('getSignedUrl returns a non-empty string', async () => {
+      const ref = await strategy.upload('user-3', fixture());
+      const url = await strategy.getSignedUrl('user-3', ref, 60);
+      expect(typeof url).toBe('string');
+      expect(url.length).toBeGreaterThan(0);
+    });
+
+    it('remove deletes the file', async () => {
+      const ref = await strategy.upload('user-4', fixture());
+      await strategy.remove('user-4', ref);
+      expect(await strategy.list('user-4')).toEqual([]);
+    });
+
+    it('signed URL for a foreign user throws', async () => {
+      const ref = await strategy.upload('owner', fixture());
+      await expect(strategy.getSignedUrl('attacker', ref)).rejects.toThrow();
+    });
+
+    it('remove by a foreign user throws', async () => {
+      const ref = await strategy.upload('owner', fixture());
+      await expect(strategy.remove('attacker', ref)).rejects.toThrow();
+    });
+  });
+}

package/templates/libs/shared/src/strategies/fakes/fake-auth.ts

@@ -0,0 +1,73 @@
+import { randomUUID } from 'node:crypto';
+import type { AuthSession, AuthStrategy, VerifiedToken } from '../auth';
+
+interface StoredUser {
+  id: string;
+  email: string;
+  password: string;
+  role?: string;
+}
+
+export class FakeAuthStrategy implements AuthStrategy {
+  private readonly users = new Map<string, StoredUser>();
+  private readonly tokensToUid = new Map<string, string>();
+  private readonly refreshToUid = new Map<string, string>();
+
+  async signUp(email: string, password: string): Promise<AuthSession> {
+    if (this.users.has(email)) throw new Error('user_exists');
+    const user: StoredUser = { id: randomUUID(), email, password };
+    this.users.set(email, user);
+    return this.issueSession(user);
+  }
+
+  async signIn(email: string, password: string): Promise<AuthSession> {
+    const user = this.users.get(email);
+    if (!user || user.password !== password) throw new Error('invalid_credentials');
+    return this.issueSession(user);
+  }
+
+  async refresh(refreshToken: string): Promise<AuthSession> {
+    const uid = this.refreshToUid.get(refreshToken);
+    if (!uid) throw new Error('invalid_refresh_token');
+    this.refreshToUid.delete(refreshToken);
+    const user = this.findById(uid);
+    return this.issueSession(user);
+  }
+
+  async verifyToken(token: string): Promise<VerifiedToken> {
+    const uid = this.tokensToUid.get(token);
+    if (!uid) throw new Error('invalid_token');
+    const user = this.findById(uid);
+    return { uid: user.id, email: user.email, role: user.role };
+  }
+
+  async setRole(uid: string, role: string): Promise<void> {
+    const user = this.findById(uid);
+    user.role = role;
+  }
+
+  async getRole(uid: string): Promise<string | null> {
+    const user = this.findById(uid);
+    return user.role ?? null;
+  }
+
+  private findById(uid: string): StoredUser {
+    for (const user of this.users.values()) {
+      if (user.id === uid) return user;
+    }
+    throw new Error('user_missing');
+  }
+
+  private issueSession(user: StoredUser): AuthSession {
+    const accessToken = randomUUID();
+    const refreshToken = randomUUID();
+    this.tokensToUid.set(accessToken, user.id);
+    this.refreshToUid.set(refreshToken, user.id);
+    return {
+      accessToken,
+      refreshToken,
+      expiresIn: 3600,
+      user: { id: user.id, email: user.email },
+    };
+  }
+}

package/templates/libs/shared/src/strategies/fakes/fake-storage.ts

@@ -0,0 +1,51 @@
+import { randomUUID } from 'node:crypto';
+import type { FileInput, StorageRef, StorageStrategy } from '../storage';
+
+interface StoredFile {
+  ownerId: string;
+  ref: StorageRef;
+  bytes: Buffer;
+  mimeType: string;
+}
+
+export class FakeStorageStrategy implements StorageStrategy {
+  private readonly bucket = 'fake-bucket';
+  private readonly files = new Map<string, StoredFile>();
+
+  async upload(userId: string, file: FileInput): Promise<StorageRef> {
+    const path = `${userId}/${randomUUID()}-${file.filename}`;
+    const ref: StorageRef = { bucket: this.bucket, path };
+    this.files.set(this.key(ref), {
+      ownerId: userId,
+      ref,
+      bytes: file.buffer,
+      mimeType: file.mimeType,
+    });
+    return ref;
+  }
+
+  async remove(userId: string, ref: StorageRef): Promise<void> {
+    const file = this.files.get(this.key(ref));
+    if (!file) throw new Error('not_found');
+    if (file.ownerId !== userId) throw new Error('forbidden');
+    this.files.delete(this.key(ref));
+  }
+
+  async getSignedUrl(userId: string, ref: StorageRef, ttlSec = 900): Promise<string> {
+    const file = this.files.get(this.key(ref));
+    if (!file) throw new Error('not_found');
+    if (file.ownerId !== userId) throw new Error('forbidden');
+    return `fake://${ref.bucket}/${ref.path}?ttl=${ttlSec}`;
+  }
+
+  async list(userId: string, prefix?: string): Promise<StorageRef[]> {
+    return [...this.files.values()]
+      .filter((f) => f.ownerId === userId)
+      .filter((f) => (prefix ? f.ref.path.startsWith(prefix) : true))
+      .map((f) => f.ref);
+  }
+
+  private key(ref: StorageRef): string {
+    return `${ref.bucket}::${ref.path}`;
+  }
+}

package/templates/libs/shared/src/strategies/fakes/index.ts

@@ -0,0 +1,2 @@
+export * from './fake-auth';
+export * from './fake-storage';

package/templates/libs/shared/src/strategies/index.ts

@@ -0,0 +1,5 @@
+export * from './auth';
+export * from './storage';
+export * from './contract/auth-contract';
+export * from './contract/storage-contract';
+export * from './fakes';

package/templates/libs/shared/src/strategies/storage.ts

@@ -0,0 +1,17 @@
+export interface StorageRef {
+  bucket: string;
+  path: string;
+}
+
+export interface FileInput {
+  buffer: Buffer;
+  filename: string;
+  mimeType: string;
+}
+
+export interface StorageStrategy {
+  upload(userId: string, file: FileInput): Promise<StorageRef>;
+  remove(userId: string, ref: StorageRef): Promise<void>;
+  getSignedUrl(userId: string, ref: StorageRef, ttlSec?: number): Promise<string>;
+  list(userId: string, prefix?: string): Promise<StorageRef[]>;
+}

package/templates/libs/shared/src/transport.ts

@@ -0,0 +1,55 @@
+import { Transport, type ClientOptions, type MicroserviceOptions } from '@nestjs/microservices';
+
+function required(name: string): string {
+  const value = process.env[name];
+  if (!value) throw new Error(`Missing required env var: ${name}`);
+  return value;
+}
+
+function requiredPort(name: string): number {
+  const raw = required(name);
+  const port = Number(raw);
+  if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+    throw new Error(`Invalid ${name}: expected integer 1-65535, got ${raw}`);
+  }
+  return port;
+}
+
+export function buildTransport(prefix: string): ClientOptions {
+  const kind = (process.env[`${prefix}_TRANSPORT`] ?? 'tcp').toLowerCase();
+  switch (kind) {
+    case 'tcp':
+      return {
+        transport: Transport.TCP,
+        options: {
+          host: required(`${prefix}_HOST`),
+          port: requiredPort(`${prefix}_PORT`),
+        },
+      };
+    case 'redis':
+      // ioredis accepts a connection URL string; the NestJS RedisOptions type
+      // exposes host/port fields but passes options directly to ioredis which
+      // also accepts a url field at runtime.
+      return {
+        transport: Transport.REDIS,
+        options: { url: required(`${prefix}_REDIS_URL`) },
+      } as unknown as ClientOptions;
+    case 'nats':
+      return {
+        transport: Transport.NATS,
+        options: { servers: required(`${prefix}_NATS_URL`).split(',') },
+      };
+    default:
+      throw new Error(`Unknown transport: ${kind}`);
+  }
+}
+
+/**
+ * Same env contract as {@link buildTransport}, but typed for the server
+ * side: pass the result directly to `NestFactory.createMicroservice(...)`.
+ * Eliminates the `as unknown as MicroserviceOptions` cast at every MS
+ * bootstrap site.
+ */
+export function buildTransportMS(prefix: string): MicroserviceOptions {
+  return buildTransport(prefix) as unknown as MicroserviceOptions;
+}

package/templates/libs/shared/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "module": "node16",
+    "moduleResolution": "node16",
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "importHelpers": true,
+    "noImplicitOverride": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "noPropertyAccessFromIndexSignature": true
+  },
+  "files": [],
+  "include": [],
+  "references": [
+    {
+      "path": "./tsconfig.lib.json"
+    },
+    {
+      "path": "./tsconfig.spec.json"
+    }
+  ]
+}

package/templates/libs/shared/tsconfig.lib.json

@@ -0,0 +1,23 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../dist/out-tsc",
+    "declaration": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": [
+    "vite.config.ts",
+    "vite.config.mts",
+    "vitest.config.ts",
+    "vitest.config.mts",
+    "src/**/*.test.ts",
+    "src/**/*.spec.ts",
+    "src/**/*.test.tsx",
+    "src/**/*.spec.tsx",
+    "src/**/*.test.js",
+    "src/**/*.spec.js",
+    "src/**/*.test.jsx",
+    "src/**/*.spec.jsx"
+  ]
+}

package/templates/libs/shared/tsconfig.spec.json

@@ -0,0 +1,22 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../dist/out-tsc",
+    "types": ["vitest/globals", "vitest/importMeta", "vite/client", "node", "vitest"]
+  },
+  "include": [
+    "vite.config.ts",
+    "vite.config.mts",
+    "vitest.config.ts",
+    "vitest.config.mts",
+    "src/**/*.test.ts",
+    "src/**/*.spec.ts",
+    "src/**/*.test.tsx",
+    "src/**/*.spec.tsx",
+    "src/**/*.test.js",
+    "src/**/*.spec.js",
+    "src/**/*.test.jsx",
+    "src/**/*.spec.jsx",
+    "src/**/*.d.ts"
+  ]
+}

package/templates/libs/shared/vitest.config.mts

@@ -0,0 +1,21 @@
+import { defineConfig } from 'vitest/config';
+import { nxViteTsPaths } from '@nx/vite/plugins/nx-tsconfig-paths.plugin';
+import { nxCopyAssetsPlugin } from '@nx/vite/plugins/nx-copy-assets.plugin';
+
+export default defineConfig(() => ({
+  root: __dirname,
+  cacheDir: '../../node_modules/.vite/libs/shared',
+  plugins: [nxViteTsPaths(), nxCopyAssetsPlugin(['*.md'])],
+  test: {
+    name: 'shared',
+    watch: false,
+    globals: true,
+    environment: 'node',
+    include: ['src/**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}'],
+    reporters: ['default'],
+    coverage: {
+      reportsDirectory: '../../coverage/libs/shared',
+      provider: 'v8' as const,
+    },
+  },
+}));

package/templates/libs/storage-strategies/cloudinary/README.md

@@ -0,0 +1,11 @@
+# storage-cloudinary
+
+This library was generated with [Nx](https://nx.dev).
+
+## Building
+
+Run `nx build storage-cloudinary` to build the library.
+
+## Running unit tests
+
+Run `nx test storage-cloudinary` to execute the unit tests via [Vitest](https://vitest.dev/).

package/templates/libs/storage-strategies/cloudinary/eslint.config.mjs

@@ -0,0 +1,23 @@
+import baseConfig from '../../../eslint.config.mjs';
+
+export default [
+  ...baseConfig,
+  {
+    files: ['**/*.json'],
+    rules: {
+      '@nx/dependency-checks': [
+        'error',
+        {
+          ignoredFiles: [
+            '{projectRoot}/eslint.config.{js,cjs,mjs,ts,cts,mts}',
+            '{projectRoot}/vitest.config.{js,ts,mjs,mts}',
+          ],
+          ignoredDependencies: ['@icore/shared'],
+        },
+      ],
+    },
+    languageOptions: {
+      parser: await import('jsonc-eslint-parser'),
+    },
+  },
+];

package/templates/libs/storage-strategies/cloudinary/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@icore/storage-cloudinary",
+  "version": "0.0.1",
+  "private": true,
+  "type": "commonjs",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "dependencies": {
+    "@icore/shared": "*",
+    "tslib": "^2.3.0"
+  },
+  "devDependencies": {
+    "vitest": "^4.0.0"
+  }
+}

package/templates/libs/storage-strategies/cloudinary/project.json

@@ -0,0 +1,19 @@
+{
+  "name": "storage-cloudinary",
+  "$schema": "../../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "libs/storage-strategies/cloudinary/src",
+  "projectType": "library",
+  "tags": [],
+  "targets": {
+    "build": {
+      "executor": "@nx/js:tsc",
+      "outputs": ["{options.outputPath}"],
+      "options": {
+        "outputPath": "dist/libs/storage-strategies/cloudinary",
+        "main": "libs/storage-strategies/cloudinary/src/index.ts",
+        "tsConfig": "libs/storage-strategies/cloudinary/tsconfig.lib.json",
+        "assets": ["libs/storage-strategies/cloudinary/*.md"]
+      }
+    }
+  }
+}

package/templates/libs/storage-strategies/cloudinary/src/index.ts

@@ -0,0 +1,2 @@
+export * from './lib/cloudinary-storage.strategy.js';
+export * from './lib/testing/mock-cloudinary.js';

package/templates/libs/storage-strategies/cloudinary/src/lib/__tests__/cloudinary-storage.contract.unit.test.ts

@@ -0,0 +1,8 @@
+import { runStorageContract } from '@icore/shared';
+import { CloudinaryStorageStrategy } from '../cloudinary-storage.strategy.js';
+import { createMockCloudinary } from '../testing/mock-cloudinary.js';
+
+runStorageContract('CloudinaryStorageStrategy', () => {
+  const api = createMockCloudinary();
+  return new CloudinaryStorageStrategy({ api, bucket: 'icore-uploads' });
+});

package/templates/libs/storage-strategies/cloudinary/src/lib/cloudinary-storage.strategy.ts

@@ -0,0 +1,75 @@
+import { randomUUID } from 'node:crypto';
+import type { FileInput, StorageRef, StorageStrategy } from '@icore/shared';
+
+export interface CloudinaryUploadResult {
+  public_id: string;
+  secure_url: string;
+}
+
+export interface CloudinaryApiLike {
+  upload(
+    buffer: Buffer,
+    opts: { public_id: string; resource_type?: 'image' | 'video' | 'raw' },
+  ): Promise<CloudinaryUploadResult>;
+  destroy(publicId: string): Promise<void>;
+  privateDownloadUrl(
+    publicId: string,
+    format: string | undefined,
+    opts?: { expires_at?: number },
+  ): string;
+  resources(opts: { prefix?: string; type?: string }): Promise<{
+    resources: Array<{ public_id: string }>;
+  }>;
+}
+
+export interface CloudinaryStorageStrategyOptions {
+  api: CloudinaryApiLike;
+  bucket: string; // Cloudinary doesn't have buckets; we synthesize the ref.bucket field
+}
+
+export class CloudinaryStorageStrategy implements StorageStrategy {
+  private readonly api: CloudinaryApiLike;
+  private readonly bucket: string;
+
+  constructor(opts: CloudinaryStorageStrategyOptions) {
+    this.api = opts.api;
+    this.bucket = opts.bucket;
+  }
+
+  async upload(userId: string, file: FileInput): Promise<StorageRef> {
+    const publicId = `${userId}/${randomUUID()}-${file.filename}`;
+    const result = await this.api.upload(file.buffer, {
+      public_id: publicId,
+      resource_type: this.detectResourceType(file.mimeType),
+    });
+    return { bucket: this.bucket, path: result.public_id };
+  }
+
+  async remove(userId: string, ref: StorageRef): Promise<void> {
+    this.assertOwner(userId, ref);
+    await this.api.destroy(ref.path);
+  }
+
+  async getSignedUrl(userId: string, ref: StorageRef, ttlSec = 900): Promise<string> {
+    this.assertOwner(userId, ref);
+    return this.api.privateDownloadUrl(ref.path, undefined, {
+      expires_at: Math.floor(Date.now() / 1000) + ttlSec,
+    });
+  }
+
+  async list(userId: string, prefix?: string): Promise<StorageRef[]> {
+    const folder = prefix ? `${userId}/${prefix}` : userId;
+    const { resources } = await this.api.resources({ prefix: `${folder}/` });
+    return resources.map((r) => ({ bucket: this.bucket, path: r.public_id }));
+  }
+
+  private assertOwner(userId: string, ref: StorageRef): void {
+    if (!ref.path.startsWith(`${userId}/`)) throw new Error('forbidden');
+  }
+
+  private detectResourceType(mimeType: string): 'image' | 'video' | 'raw' {
+    if (mimeType.startsWith('image/')) return 'image';
+    if (mimeType.startsWith('video/')) return 'video';
+    return 'raw';
+  }
+}

package/templates/libs/storage-strategies/cloudinary/src/lib/testing/mock-cloudinary.ts

@@ -0,0 +1,36 @@
+import type { CloudinaryApiLike, CloudinaryUploadResult } from '../cloudinary-storage.strategy.js';
+
+interface StoredObject {
+  bytes: Buffer;
+  resourceType: 'image' | 'video' | 'raw';
+}
+
+export function createMockCloudinary(): CloudinaryApiLike {
+  const objects = new Map<string, StoredObject>();
+
+  return {
+    async upload(buffer, opts) {
+      const publicId = opts.public_id;
+      if (objects.has(publicId)) throw new Error('exists');
+      objects.set(publicId, { bytes: buffer, resourceType: opts.resource_type ?? 'raw' });
+      return {
+        public_id: publicId,
+        secure_url: `https://mock.cloudinary/raw/${publicId}`,
+      } satisfies CloudinaryUploadResult;
+    },
+    async destroy(publicId) {
+      if (!objects.has(publicId)) throw new Error('not_found');
+      objects.delete(publicId);
+    },
+    privateDownloadUrl(publicId, _format, opts) {
+      if (!objects.has(publicId)) throw new Error('not_found');
+      return `https://mock.cloudinary/signed/${publicId}?ttl=${opts?.expires_at ?? 'na'}`;
+    },
+    async resources(opts) {
+      const matches = [...objects.keys()].filter((id) =>
+        opts.prefix ? id.startsWith(opts.prefix) : true,
+      );
+      return { resources: matches.map((public_id) => ({ public_id })) };
+    },
+  };
+}

package/templates/libs/storage-strategies/cloudinary/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "module": "node16",
+    "moduleResolution": "node16",
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "importHelpers": true,
+    "noImplicitOverride": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "noPropertyAccessFromIndexSignature": true
+  },
+  "files": [],
+  "include": [],
+  "references": [
+    {
+      "path": "./tsconfig.lib.json"
+    },
+    {
+      "path": "./tsconfig.spec.json"
+    }
+  ]
+}

package/templates/libs/storage-strategies/cloudinary/tsconfig.lib.json

@@ -0,0 +1,23 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../../dist/out-tsc",
+    "declaration": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": [
+    "vite.config.ts",
+    "vite.config.mts",
+    "vitest.config.ts",
+    "vitest.config.mts",
+    "src/**/*.test.ts",
+    "src/**/*.spec.ts",
+    "src/**/*.test.tsx",
+    "src/**/*.spec.tsx",
+    "src/**/*.test.js",
+    "src/**/*.spec.js",
+    "src/**/*.test.jsx",
+    "src/**/*.spec.jsx"
+  ]
+}

package/templates/libs/storage-strategies/cloudinary/tsconfig.spec.json

@@ -0,0 +1,22 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../../dist/out-tsc",
+    "types": ["vitest/globals", "vitest/importMeta", "vite/client", "node", "vitest"]
+  },
+  "include": [
+    "vite.config.ts",
+    "vite.config.mts",
+    "vitest.config.ts",
+    "vitest.config.mts",
+    "src/**/*.test.ts",
+    "src/**/*.spec.ts",
+    "src/**/*.test.tsx",
+    "src/**/*.spec.tsx",
+    "src/**/*.test.js",
+    "src/**/*.spec.js",
+    "src/**/*.test.jsx",
+    "src/**/*.spec.jsx",
+    "src/**/*.d.ts"
+  ]
+}

package/templates/libs/storage-strategies/cloudinary/vitest.config.mts

@@ -0,0 +1,22 @@
+import { defineConfig } from 'vitest/config';
+import { nxViteTsPaths } from '@nx/vite/plugins/nx-tsconfig-paths.plugin';
+import { nxCopyAssetsPlugin } from '@nx/vite/plugins/nx-copy-assets.plugin';
+
+export default defineConfig(() => ({
+  root: __dirname,
+  cacheDir: '../../../node_modules/.vite/libs/storage-strategies/cloudinary',
+  plugins: [nxViteTsPaths(), nxCopyAssetsPlugin(['*.md'])],
+  test: {
+    name: 'storage-cloudinary',
+    watch: false,
+    globals: true,
+    environment: 'node',
+    include: ['{src,tests}/**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}'],
+    passWithNoTests: true,
+    reporters: ['default'],
+    coverage: {
+      reportsDirectory: '../../../coverage/libs/storage-strategies/cloudinary',
+      provider: 'v8' as const,
+    },
+  },
+}));

package/templates/libs/storage-strategies/firebase/README.md

@@ -0,0 +1,11 @@
+# storage-firebase
+
+This library was generated with [Nx](https://nx.dev).
+
+## Building
+
+Run `nx build storage-firebase` to build the library.
+
+## Running unit tests
+
+Run `nx test storage-firebase` to execute the unit tests via [Vitest](https://vitest.dev/).