@api-client/core 0.18.34 → 0.18.35

package/src/sdk/SdkMock.ts

@@ -0,0 +1,792 @@
+import { nanoid } from '../nanoid.js'
+import type { IOrganization } from '../models/store/Organization.js'
+import type { GroupSchema } from '../models/store/Group.js'
+import type { IUser } from '../models/store/User.js'
+import { OrganizationKind } from '../models/kinds.js'
+import { GroupKind } from '../models/kinds.js'
+import { Kind as UserKind } from '../models/store/User.js'
+import { File, type IFile, type FileBreadcrumb } from '../models/store/File.js'
+import { CertificateFileKind, DomainFileKind, FolderKind, ProjectKind } from '../models/kinds.js'
+import type { ContextListResult, IBulkOperationResult } from '../events/BaseEvents.js'
+import type { MediaPatchRevision } from '../patch/types.js'
+import type { IFolder } from '../models/Folder.js'
+import type { TrashEntry } from '../models/TrashEntry.js'
+import type { StoreSdk } from './StoreSdkWeb.js'
+import * as sinon from 'sinon'
+import { Exception } from '../exceptions/exception.js'
+
+/**
+ * Options for customizing mock responses.
+ */
+export interface MockResponseOptions {
+  /**
+   * Custom response data to return instead of generated random data.
+   */
+  data?: unknown
+  /**
+   * HTTP status code to return. Defaults to 200.
+   */
+  status?: number
+  /**
+   * Custom headers to include in the response.
+   */
+  headers?: Record<string, string>
+}
+
+/**
+ * A stub reference that can be used to restore the original behavior.
+ */
+export interface StubReference {
+  /**
+   * Restores the original behavior.
+   */
+  restore: () => void
+}
+
+/**
+ * SDK mocking utility for testing. Provides simple API to mock SDK calls
+ * with random or custom responses.
+ *
+ * @example
+ * ```typescript
+ * import { SdkMock } from '@api-client/core/sdk/SdkMock.js';
+ * import { StoreSdk } from '@api-client/core/sdk/StoreSdkWeb.js';
+ *
+ * const sdk = new StoreSdk('http://localhost:8080');
+ * const mocker = new SdkMock(sdk);
+ *
+ * // Simple usage - returns random valid organization
+ * const stub1 = mocker.organizations.list();
+ *
+ * // Custom response
+ * const stub2 = mocker.organizations.create({
+ *   data: { key: 'org-1', name: 'Test Org', ... }
+ * });
+ *
+ * // Custom status and headers
+ * const stub3 = mocker.users.me({
+ *   status: 404,
+ *   headers: { 'X-Custom': 'value' }
+ * });
+ *
+ * // Restore all stubs
+ * mocker.restore();
+ * ```
+ */
+export class SdkMock {
+  private stubs: StubReference[] = []
+
+  constructor(private sdk: StoreSdk) {}
+
+  /**
+   * Organization API mocks.
+   */
+  organizations = {
+    /**
+     * Mocks the `organizations.list()` method.
+     * @param options Optional response customization.
+     * @returns A stub reference that can be used to restore the original behavior.
+     */
+    list: (options?: MockResponseOptions): StubReference => {
+      return this.createStub('organizations', 'list', () => {
+        const defaultData = {
+          items: [this.generateOrganization(), this.generateOrganization()],
+          nextPageToken: undefined,
+        }
+        if (options?.status !== undefined && options.status !== 200) {
+          throw new Exception('Mocked error', { status: options.status })
+        }
+        return (options?.data ?? defaultData) as unknown
+      })
+    },
+
+    /**
+     * Mocks the `organizations.create()` method.
+     * @param options Optional response customization.
+     * @returns A stub reference that can be used to restore the original behavior.
+     */
+    create: (options?: MockResponseOptions): StubReference => {
+      return this.createStub('organizations', 'create', () => {
+        const defaultData = this.generateOrganization()
+        if (options?.status !== undefined && options.status !== 200) {
+          throw new Exception('Mocked error', { status: options.status })
+        }
+        return (options?.data ?? defaultData) as unknown
+      })
+    },
+
+    /**
+     * Mocks the `organizations.read()` method.
+     * @param options Optional response customization.
+     * @returns A stub reference that can be used to restore the original behavior.
+     */
+    read: (options?: MockResponseOptions): StubReference => {
+      return this.createStub('organizations', 'read', () => {
+        const defaultData = this.generateOrganization()
+        if (options?.status !== undefined && options.status !== 200) {
+          throw new Exception('Mocked error', { status: options.status })
+        }
+        return (options?.data ?? defaultData) as unknown
+      })
+    },
+
+    /**
+     * Mocks the `organizations.delete()` method.
+     * @param options Optional response customization.
+     * @returns A stub reference that can be used to restore the original behavior.
+     */
+    delete: (options?: MockResponseOptions): StubReference => {
+      return this.createStub('organizations', 'delete', () => {
+        const status = options?.status ?? 204
+        if (status !== 204) {
+          throw new Exception('Mocked error', { status })
+        }
+        return undefined
+      })
+    },
+  }
+
+  /**
+   * Group API mocks.
+   */
+  groups = {
+    /**
+     * Mocks the `groups.list()` method.
+     * @param options Optional response customization.
+     * @returns A stub reference that can be used to restore the original behavior.
+     */
+    list: (options?: MockResponseOptions): StubReference => {
+      return this.createStub('groups', 'list', () => {
+        const defaultData = {
+          items: [this.generateGroup(), this.generateGroup()],
+          nextPageToken: undefined,
+        }
+        if (options?.status !== undefined && options.status !== 200) {
+          throw new Exception('Mocked error', { status: options.status })
+        }
+        return (options?.data ?? defaultData) as unknown
+      })
+    },
+
+    /**
+     * Mocks the `groups.create()` method.
+     * @param options Optional response customization.
+     * @returns A stub reference that can be used to restore the original behavior.
+     */
+    create: (options?: MockResponseOptions): StubReference => {
+      return this.createStub('groups', 'create', () => {
+        const defaultData = this.generateGroup()
+        const status = options?.status ?? 201
+        if (status !== 201) {
+          throw new Exception('Mocked error', { status })
+        }
+        return (options?.data ?? defaultData) as unknown
+      })
+    },
+
+    /**
+     * Mocks the `groups.read()` method.
+     * @param options Optional response customization.
+     * @returns A stub reference that can be used to restore the original behavior.
+     */
+    read: (options?: MockResponseOptions): StubReference => {
+      return this.createStub('groups', 'read', () => {
+        const defaultData = this.generateGroup()
+        if (options?.status !== undefined && options.status !== 200) {
+          throw new Exception('Mocked error', { status: options.status })
+        }
+        return (options?.data ?? defaultData) as unknown
+      })
+    },
+
+    /**
+     * Mocks the `groups.update()` method.
+     * @param options Optional response customization.
+     * @returns A stub reference that can be used to restore the original behavior.
+     */
+    update: (options?: MockResponseOptions): StubReference => {
+      return this.createStub('groups', 'update', () => {
+        const defaultData = this.generateGroup()
+        if (options?.status !== undefined && options.status !== 200) {
+          throw new Exception('Mocked error', { status: options.status })
+        }
+        return (options?.data ?? defaultData) as unknown
+      })
+    },
+
+    /**
+     * Mocks the `groups.delete()` method.
+     * @param options Optional response customization.
+     * @returns A stub reference that can be used to restore the original behavior.
+     */
+    delete: (options?: MockResponseOptions): StubReference => {
+      return this.createStub('groups', 'delete', () => {
+        const status = options?.status ?? 204
+        if (status !== 204) {
+          throw new Exception('Mocked error', { status })
+        }
+        return undefined
+      })
+    },
+  }
+
+  /**
+   * User API mocks.
+   */
+  users = {
+    /**
+     * Mocks the `user.me()` method.
+     * @param options Optional response customization.
+     * @returns A stub reference that can be used to restore the original behavior.
+     */
+    me: (options?: MockResponseOptions): StubReference => {
+      return this.createStub('user', 'me', () => {
+        const defaultData = this.generateUser()
+        if (options?.status !== undefined && options.status !== 200) {
+          throw new Exception('Mocked error', { status: options.status })
+        }
+        return (options?.data ?? defaultData) as unknown
+      })
+    },
+  }
+
+  /**
+   * Auth API mocks.
+   */
+  auth = {
+    /**
+     * Mocks the `auth.oauthRedirect()` method.
+     * This method returns `null` by default as it performs window navigation.
+     * @param options Optional response customization.
+     * @returns A stub reference that can be used to restore the original behavior.
+     */
+    oauthRedirect: (options?: MockResponseOptions): StubReference => {
+      return this.createStub(
+        'auth',
+        'oauthRedirect',
+        () => {
+          const defaultData = options?.data ?? null
+          return defaultData
+        },
+        true
+      )
+    },
+  }
+
+  /**
+   * Files API mocks.
+   */
+  file = {
+    /**
+     * Mocks the `file.list()` method.
+     */
+    list: (options?: MockResponseOptions): StubReference => {
+      return this.createStub('file', 'list', () => {
+        const defaultData: ContextListResult<IFile> = {
+          items: [this.generateFile(), this.generateFile()],
+        }
+        if (options?.status !== undefined && options.status !== 200) {
+          throw new Exception('Mocked error', { status: options.status })
+        }
+        return (options?.data ?? defaultData) as unknown
+      })
+    },
+
+    /**
+     * Mocks the `file.createMeta()` method.
+     */
+    createMeta: (options?: MockResponseOptions): StubReference => {
+      return this.createStub('file', 'createMeta', () => {
+        const defaultData: IFile = this.generateFile()
+        const status = options?.status ?? 201
+        if (status !== 201) {
+          throw new Exception('Mocked error', { status })
+        }
+        return (options?.data ?? defaultData) as unknown
+      })
+    },
+
+    /**
+     * Mocks the `file.createMedia()` method.
+     */
+    createMedia: (options?: MockResponseOptions): StubReference => {
+      return this.createStub('file', 'createMedia', () => {
+        const status = options?.status ?? 200
+        if (status !== 200) {
+          throw new Exception('Mocked error', { status })
+        }
+        return undefined
+      })
+    },
+
+    /**
+     * Mocks the `file.create()` method.
+     */
+    create: (options?: MockResponseOptions): StubReference => {
+      return this.createStub('file', 'create', () => {
+        const status = options?.status ?? 201
+        if (status !== 201) {
+          throw new Exception('Mocked error', { status })
+        }
+        const defaultData: IFile = this.generateFile()
+        return (options?.data ?? defaultData) as unknown
+      })
+    },
+
+    /**
+     * Mocks the `file.createFolder()` method.
+     */
+    createFolder: (options?: MockResponseOptions): StubReference => {
+      return this.createStub('file', 'createFolder', () => {
+        const status = options?.status ?? 201
+        if (status !== 201) {
+          throw new Exception('Mocked error', { status })
+        }
+        const defaultData: IFolder = this.generateFolder()
+        return (options?.data ?? defaultData) as unknown
+      })
+    },
+
+    /**
+     * Mocks the `file.read()` method.
+     */
+    read: (options?: MockResponseOptions): StubReference => {
+      return this.createStub('file', 'read', () => {
+        const defaultData: IFile = this.generateFile()
+        if (options?.status !== undefined && options.status !== 200) {
+          throw new Exception('Mocked error', { status: options.status })
+        }
+        return (options?.data ?? defaultData) as unknown
+      })
+    },
+
+    /**
+     * Mocks the `file.readMedia()` method.
+     */
+    readMedia: (options?: MockResponseOptions): StubReference => {
+      return this.createStub('file', 'readMedia', () => {
+        if (options?.status !== undefined && options.status !== 200) {
+          throw new Exception('Mocked error', { status: options.status })
+        }
+        const defaultData = { media: { ok: true }, version: 1 }
+        return (options?.data ?? defaultData) as unknown
+      })
+    },
+
+    /**
+     * Mocks the `file.readBulk()` method.
+     */
+    readBulk: (options?: MockResponseOptions): StubReference => {
+      return this.createStub('file', 'readBulk', () => {
+        const defaultData: IBulkOperationResult<IFile> = {
+          items: [this.generateFile(), undefined],
+        }
+        if (options?.status !== undefined && options.status !== 200) {
+          throw new Exception('Mocked error', { status: options.status })
+        }
+        return (options?.data ?? defaultData) as unknown
+      })
+    },
+
+    /**
+     * Mocks the `file.patch()` method.
+     */
+    patch: (options?: MockResponseOptions): StubReference => {
+      return this.createStub('file', 'patch', () => {
+        const defaultData: IFile = this.generateFile()
+        if (options?.status !== undefined && options.status !== 200) {
+          throw new Exception('Mocked error', { status: options.status })
+        }
+        return (options?.data ?? defaultData) as unknown
+      })
+    },
+
+    /**
+     * Mocks the `file.patchMedia()` method.
+     */
+    patchMedia: (options?: MockResponseOptions): StubReference => {
+      return this.createStub('file', 'patchMedia', () => {
+        const defaultData: MediaPatchRevision = this.generateMediaPatchRevision()
+        if (options?.status !== undefined && options.status !== 200) {
+          throw new Exception('Mocked error', { status: options.status })
+        }
+        return (options?.data ?? defaultData) as unknown
+      })
+    },
+
+    /**
+     * Mocks the `file.delete()` method.
+     */
+    delete: (options?: MockResponseOptions): StubReference => {
+      return this.createStub('file', 'delete', () => {
+        const status = options?.status ?? 204
+        if (status !== 204) {
+          throw new Exception('Mocked error', { status })
+        }
+        return undefined
+      })
+    },
+
+    /**
+     * Mocks the `file.deleteBulk()` method.
+     */
+    deleteBulk: (options?: MockResponseOptions): StubReference => {
+      return this.createStub('file', 'deleteBulk', () => {
+        const status = options?.status ?? 204
+        if (status !== 204) {
+          throw new Exception('Mocked error', { status })
+        }
+        return undefined
+      })
+    },
+
+    /**
+     * Mocks the `file.patchUsers()` method.
+     */
+    patchUsers: (options?: MockResponseOptions): StubReference => {
+      return this.createStub('file', 'patchUsers', () => {
+        const defaultData: IFile = this.generateFile()
+        if (options?.status !== undefined && options.status !== 200) {
+          throw new Exception('Mocked error', { status: options.status })
+        }
+        return (options?.data ?? defaultData) as unknown
+      })
+    },
+
+    /**
+     * Mocks the `file.addUser()` method.
+     */
+    addUser: (options?: MockResponseOptions): StubReference => {
+      return this.createStub('file', 'addUser', () => {
+        const defaultData: IFile = this.generateFile()
+        if (options?.status !== undefined && options.status !== 200) {
+          throw new Exception('Mocked error', { status: options.status })
+        }
+        return (options?.data ?? defaultData) as unknown
+      })
+    },
+
+    /**
+     * Mocks the `file.removeUser()` method.
+     */
+    removeUser: (options?: MockResponseOptions): StubReference => {
+      return this.createStub('file', 'removeUser', () => {
+        const defaultData: IFile = this.generateFile()
+        if (options?.status !== undefined && options.status !== 200) {
+          throw new Exception('Mocked error', { status: options.status })
+        }
+        return (options?.data ?? defaultData) as unknown
+      })
+    },
+
+    /**
+     * Mocks the `file.listUsers()` method.
+     */
+    listUsers: (options?: MockResponseOptions): StubReference => {
+      return this.createStub('file', 'listUsers', () => {
+        const defaultData: ContextListResult<IUser> = {
+          items: [this.generateUser(), this.generateUser()],
+        }
+        if (options?.status !== undefined && options.status !== 200) {
+          throw new Exception('Mocked error', { status: options.status })
+        }
+        return (options?.data ?? defaultData) as unknown
+      })
+    },
+
+    /**
+     * Mocks the `file.breadcrumbs()` method.
+     */
+    breadcrumbs: (options?: MockResponseOptions): StubReference => {
+      return this.createStub('file', 'breadcrumbs', () => {
+        const defaultData: ContextListResult<FileBreadcrumb> = {
+          items: this.generateBreadcrumbs(),
+        }
+        if (options?.status !== undefined && options.status !== 200) {
+          throw new Exception('Mocked error', { status: options.status })
+        }
+        return (options?.data ?? defaultData) as unknown
+      })
+    },
+  }
+
+  /**
+   * Shared API mocks.
+   */
+  shared = {
+    list: (options?: MockResponseOptions): StubReference => {
+      return this.createStub('shared', 'list', () => {
+        const defaultData: ContextListResult<IFile> = {
+          items: [this.generateFile(), this.generateFile()],
+        }
+        if (options?.status !== undefined && options.status !== 200) {
+          throw new Exception('Mocked error', { status: options.status })
+        }
+        return (options?.data ?? defaultData) as unknown
+      })
+    },
+  }
+
+  /**
+   * Trash API mocks.
+   */
+  trash = {
+    list: (options?: MockResponseOptions): StubReference => {
+      return this.createStub('trash', 'list', () => {
+        const defaultData: ContextListResult<TrashEntry> = {
+          items: [this.generateTrashEntry(), this.generateTrashEntry()],
+        }
+        if (options?.status !== undefined && options.status !== 200) {
+          throw new Exception('Mocked error', { status: options.status })
+        }
+        return (options?.data ?? defaultData) as unknown
+      })
+    },
+    delete: (options?: MockResponseOptions): StubReference => {
+      return this.createStub('trash', 'delete', () => {
+        const status = options?.status ?? 204
+        if (status !== 204) {
+          throw new Exception('Mocked error', { status })
+        }
+        return undefined
+      })
+    },
+    restore: (options?: MockResponseOptions): StubReference => {
+      return this.createStub('trash', 'restore', () => {
+        const status = options?.status ?? 204
+        if (status !== 204) {
+          throw new Exception('Mocked error', { status })
+        }
+        return undefined
+      })
+    },
+    empty: (options?: MockResponseOptions): StubReference => {
+      return this.createStub('trash', 'empty', () => {
+        const status = options?.status ?? 204
+        if (status !== 204) {
+          throw new Exception('Mocked error', { status })
+        }
+        return undefined
+      })
+    },
+  }
+
+  /**
+   * Restores all stubs created by this mocker.
+   */
+  restore(): void {
+    this.stubs.forEach((stub) => stub.restore())
+    this.stubs = []
+  }
+
+  /**
+   * Creates a stub for a specific SDK method.
+   * @param api The API name (e.g., 'organizations', 'groups', 'user', 'auth').
+   * @param method The method name to stub.
+   * @param implementation The stub implementation that returns the mocked data.
+   * @returns A stub reference.
+   */
+  private createStub(
+    api: 'organizations' | 'groups' | 'user' | 'auth' | 'file' | 'shared' | 'trash',
+    method: string,
+    implementation: () => unknown,
+    sync?: boolean
+  ): StubReference {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const target = (this.sdk as any)[api]
+    if (!target) {
+      throw new Error(`API '${api}' not found in SDK`)
+    }
+
+    const original = target[method]
+    if (typeof original !== 'function') {
+      throw new Error(`Method '${method}' not found in ${api} API`)
+    }
+
+    // Store original and create stub using sinon
+    const stub = sync
+      ? sinon.stub(target, method).callsFake(() => implementation())
+      : sinon.stub(target, method).callsFake(async () => implementation())
+
+    const stubRef: StubReference = {
+      restore: () => {
+        if (stub) {
+          stub.restore()
+        }
+        const index = this.stubs.indexOf(stubRef)
+        if (index > -1) {
+          this.stubs.splice(index, 1)
+        }
+      },
+    }
+
+    this.stubs.push(stubRef)
+    return stubRef
+  }
+
+  /**
+   * Creates a response object from data and options.
+   * @param defaultData Default data to return if not overridden.
+   * @param options Response options.
+   * @returns The final data to return (for non-HTTP responses) or IStoreResponse (for HTTP responses).
+   */
+  private createResponse(defaultData: unknown, options?: MockResponseOptions): unknown {
+    // For SDK-level stubs we return plain data. Status and headers are
+    // accepted but not propagated, since high-level SDK methods return data.
+    const data = options?.data !== undefined ? options.data : defaultData
+    return data
+  }
+
+  /**
+   * Generates a random organization object.
+   */
+  private generateOrganization(): IOrganization {
+    return {
+      kind: OrganizationKind,
+      key: nanoid(),
+      name: `Organization ${this.randomString()}`,
+      createdBy: nanoid(),
+      createdDate: Date.now() - Math.random() * 1000 * 60 * 60 * 24 * 30,
+      grantType: this.randomChoice(['owner', 'manager', 'editor', 'viewer'] as const),
+    }
+  }
+
+  /**
+   * Generates a random group object.
+   */
+  private generateGroup(): GroupSchema {
+    return {
+      kind: GroupKind,
+      key: nanoid(),
+      name: `Group ${this.randomString()}`,
+      description: `Description for ${this.randomString()}`,
+      owner: nanoid(),
+      oid: nanoid(),
+      users: [],
+      createdAt: Date.now() - Math.random() * 1000 * 60 * 60 * 24 * 30,
+      updatedAt: Date.now() - Math.random() * 1000 * 60 * 60 * 24 * 7,
+      icon: `https://example.com/icon-${nanoid()}.png`,
+      color: this.randomColor(),
+    }
+  }
+
+  /**
+   * Generates a random user object.
+   */
+  private generateUser(): IUser {
+    const firstName = this.randomString()
+    const lastName = this.randomString()
+    return {
+      kind: UserKind,
+      key: nanoid(),
+      name: `${firstName} ${lastName}`,
+      email: [
+        {
+          email: `${firstName.toLowerCase()}.${lastName.toLowerCase()}@example.com`,
+          verified: true,
+        },
+      ],
+      status: 'active',
+      created: Date.now() - Math.random() * 1000 * 60 * 60 * 24 * 365,
+      updated: Date.now() - Math.random() * 1000 * 60 * 60 * 24 * 7,
+    }
+  }
+
+  /**
+   * Generates a random file meta object.
+   */
+  private generateFile(): IFile {
+    const kind = this.randomChoice([ProjectKind, DomainFileKind, CertificateFileKind, FolderKind] as const)
+    const name = `File ${this.randomString()}`
+    return File.createSchema({ kind, info: { name } })
+  }
+
+  /**
+   * Generates a random folder meta object.
+   */
+  private generateFolder(): IFolder {
+    const file = File.createSchema({ kind: FolderKind, info: { name: `Folder ${this.randomString()}` } }) as IFolder
+    return file
+  }
+
+  /**
+   * Generates a random media patch revision object.
+   */
+  private generateMediaPatchRevision(): MediaPatchRevision {
+    const version = Math.floor(Math.random() * 10) + 1
+    return {
+      id: nanoid(),
+      timestamp: Date.now(),
+      patch: [],
+      version,
+      revert: [],
+      newVersion: version + 1,
+    }
+  }
+
+  /**
+   * Generates a random breadcrumbs list.
+   */
+  private generateBreadcrumbs(): FileBreadcrumb[] {
+    const depth = 2 + Math.floor(Math.random() * 2) // 2-3
+    const items: FileBreadcrumb[] = []
+    for (let i = 0; i < depth; i += 1) {
+      items.push({ key: nanoid(), kind: i === depth - 1 ? ProjectKind : FolderKind, name: this.randomString() })
+    }
+    return items
+  }
+
+  /**
+   * Generates a random trash entry.
+   */
+  private generateTrashEntry(): TrashEntry {
+    return {
+      key: nanoid(),
+      refKey: nanoid(),
+      kind: this.randomChoice([ProjectKind, DomainFileKind, CertificateFileKind, FolderKind] as const),
+      name: `Deleted ${this.randomString()}`,
+      info: { byMe: false, time: Date.now() - Math.floor(Math.random() * 1000000), user: nanoid(), name: 'User' },
+      capabilities: { canDelete: true, canRestore: true },
+    }
+  }
+
+  /**
+   * Generates a random string.
+   */
+  private randomString(): string {
+    const words = [
+      'Alpha',
+      'Beta',
+      'Gamma',
+      'Delta',
+      'Epsilon',
+      'Zeta',
+      'Theta',
+      'Lambda',
+      'Sigma',
+      'Omega',
+      'Phoenix',
+      'Dragon',
+      'Tiger',
+      'Eagle',
+      'Falcon',
+    ]
+    return words[Math.floor(Math.random() * words.length)]
+  }
+
+  /**
+   * Returns a random choice from an array.
+   */
+  private randomChoice<T>(choices: readonly T[]): T {
+    return choices[Math.floor(Math.random() * choices.length)]
+  }
+
+  /**
+   * Generates a random hex color.
+   */
+  private randomColor(): string {
+    return `#${Math.floor(Math.random() * 16777215)
+      .toString(16)
+      .padStart(6, '0')}`
+  }
+}