@eventmodelers/node-kit 0.0.2

package/templates/realtime-agent/node_modules/@supabase/storage-js/src/index.ts

@@ -0,0 +1,19 @@
+export { StorageClient } from './StorageClient'
+export type { StorageClientOptions } from './StorageClient'
+export { default as StorageAnalyticsClient } from './packages/StorageAnalyticsClient'
+
+// Vector Storage
+export {
+  StorageVectorsClient,
+  VectorBucketScope,
+  VectorIndexScope,
+} from './packages/StorageVectorsClient'
+export type { StorageVectorsClientOptions } from './packages/StorageVectorsClient'
+export { default as VectorBucketApi } from './packages/VectorBucketApi'
+export { default as VectorDataApi } from './packages/VectorDataApi'
+export { default as VectorIndexApi } from './packages/VectorIndexApi'
+export type { CreateIndexOptions } from './packages/VectorIndexApi'
+
+// Types and Errors
+export * from './lib/types'
+export * from './lib/common/errors'

package/templates/realtime-agent/node_modules/@supabase/storage-js/src/lib/common/BaseApiClient.ts

@@ -0,0 +1,104 @@
+import { ErrorNamespace, isStorageError, StorageError } from './errors'
+import { Fetch } from './fetch'
+import { normalizeHeaders, setHeader as setHeaderUtil } from './headers'
+import { resolveFetch } from './helpers'
+
+/**
+ * @ignore
+ * Base API client class for all Storage API classes
+ * Provides common infrastructure for error handling and configuration
+ *
+ * @typeParam TError - The error type (StorageError or subclass)
+ */
+export default abstract class BaseApiClient<TError extends StorageError = StorageError> {
+  protected url: string
+  protected headers: { [key: string]: string }
+  protected fetch: Fetch
+  protected shouldThrowOnError = false
+  protected namespace: ErrorNamespace
+
+  /**
+   * Creates a new BaseApiClient instance
+   * @param url - Base URL for API requests
+   * @param headers - Default headers for API requests
+   * @param fetch - Optional custom fetch implementation
+   * @param namespace - Error namespace ('storage' or 'vectors')
+   */
+  constructor(
+    url: string,
+    headers: { [key: string]: string } = {},
+    fetch?: Fetch,
+    namespace: ErrorNamespace = 'storage'
+  ) {
+    this.url = url
+    this.headers = normalizeHeaders(headers)
+    this.fetch = resolveFetch(fetch)
+    this.namespace = namespace
+  }
+
+  /**
+   * Enable throwing errors instead of returning them.
+   * When enabled, errors are thrown instead of returned in { data, error } format.
+   *
+   * @returns this - For method chaining
+   */
+  public throwOnError(): this {
+    this.shouldThrowOnError = true
+    return this
+  }
+
+  /**
+   * Set an HTTP header for the request.
+   * Creates a shallow copy of headers to avoid mutating shared state.
+   *
+   * @param name - Header name
+   * @param value - Header value
+   * @returns this - For method chaining
+   */
+  public setHeader(name: string, value: string): this {
+    this.headers = setHeaderUtil(this.headers, name, value)
+    return this
+  }
+
+  /**
+   * Handles API operation with standardized error handling
+   * Eliminates repetitive try-catch blocks across all API methods
+   *
+   * This wrapper:
+   * 1. Executes the operation
+   * 2. Returns { data, error: null } on success
+   * 3. Returns { data: null, error } on failure (if shouldThrowOnError is false)
+   * 4. Throws error on failure (if shouldThrowOnError is true)
+   *
+   * @typeParam T - The expected data type from the operation
+   * @param operation - Async function that performs the API call
+   * @returns Promise with { data, error } tuple
+   *
+   * @example Handling an operation
+   * ```typescript
+   * async listBuckets() {
+   *   return this.handleOperation(async () => {
+   *     return await get(this.fetch, `${this.url}/bucket`, {
+   *       headers: this.headers,
+   *     })
+   *   })
+   * }
+   * ```
+   */
+  protected async handleOperation<T>(
+    operation: () => Promise<T>
+  ): Promise<{ data: T; error: null } | { data: null; error: TError }> {
+    try {
+      const data = await operation()
+      return { data, error: null }
+    } catch (error) {
+      if (this.shouldThrowOnError) {
+        throw error
+      }
+      if (isStorageError(error)) {
+        return { data: null, error: error as TError }
+      }
+      throw error
+    }
+  }
+}

package/templates/realtime-agent/node_modules/@supabase/storage-js/src/lib/common/errors.ts

@@ -0,0 +1,160 @@
+/**
+ * Namespace type for error classes
+ * Determines the error class names and type guards
+ */
+export type ErrorNamespace = 'storage' | 'vectors'
+
+/**
+ * Base error class for all Storage errors
+ * Supports both 'storage' and 'vectors' namespaces
+ */
+export class StorageError extends Error {
+  protected __isStorageError = true
+  protected namespace: ErrorNamespace
+  status: number | undefined
+  statusCode: string | undefined
+
+  constructor(
+    message: string,
+    namespace: ErrorNamespace = 'storage',
+    status?: number,
+    statusCode?: string
+  ) {
+    super(message)
+    this.namespace = namespace
+    this.name = namespace === 'vectors' ? 'StorageVectorsError' : 'StorageError'
+    this.status = status
+    this.statusCode = statusCode
+  }
+
+  toJSON(): {
+    name: string
+    message: string
+    status: number | undefined
+    statusCode: string | undefined
+  } {
+    return {
+      name: this.name,
+      message: this.message,
+      status: this.status,
+      statusCode: this.statusCode,
+    }
+  }
+}
+
+/**
+ * Type guard to check if an error is a StorageError
+ * @param error - The error to check
+ * @returns True if the error is a StorageError
+ */
+export function isStorageError(error: unknown): error is StorageError {
+  return typeof error === 'object' && error !== null && '__isStorageError' in error
+}
+
+/**
+ * API error returned from Storage service
+ * Includes HTTP status code and service-specific error code
+ */
+export class StorageApiError extends StorageError {
+  override status: number
+  override statusCode: string
+
+  constructor(
+    message: string,
+    status: number,
+    statusCode: string,
+    namespace: ErrorNamespace = 'storage'
+  ) {
+    super(message, namespace, status, statusCode)
+    this.name = namespace === 'vectors' ? 'StorageVectorsApiError' : 'StorageApiError'
+    this.status = status
+    this.statusCode = statusCode
+  }
+
+  toJSON(): {
+    name: string
+    message: string
+    status: number | undefined
+    statusCode: string | undefined
+  } {
+    return {
+      ...super.toJSON(),
+    }
+  }
+}
+
+/**
+ * Unknown error that doesn't match expected error patterns
+ * Wraps the original error for debugging
+ */
+export class StorageUnknownError extends StorageError {
+  originalError: unknown
+
+  constructor(message: string, originalError: unknown, namespace: ErrorNamespace = 'storage') {
+    super(message, namespace)
+    this.name = namespace === 'vectors' ? 'StorageVectorsUnknownError' : 'StorageUnknownError'
+    this.originalError = originalError
+  }
+}
+
+// ============================================================================
+// Backward Compatibility Exports for Vectors
+// ============================================================================
+
+/**
+ * @deprecated Use StorageError with namespace='vectors' instead
+ * Alias for backward compatibility with existing vector storage code
+ */
+export class StorageVectorsError extends StorageError {
+  constructor(message: string) {
+    super(message, 'vectors')
+  }
+}
+
+/**
+ * Type guard to check if an error is a StorageVectorsError
+ * @param error - The error to check
+ * @returns True if the error is a StorageVectorsError
+ */
+export function isStorageVectorsError(error: unknown): error is StorageVectorsError {
+  return isStorageError(error) && (error as StorageError)['namespace'] === 'vectors'
+}
+
+/**
+ * @deprecated Use StorageApiError with namespace='vectors' instead
+ * Alias for backward compatibility with existing vector storage code
+ */
+export class StorageVectorsApiError extends StorageApiError {
+  constructor(message: string, status: number, statusCode: string) {
+    super(message, status, statusCode, 'vectors')
+  }
+}
+
+/**
+ * @deprecated Use StorageUnknownError with namespace='vectors' instead
+ * Alias for backward compatibility with existing vector storage code
+ */
+export class StorageVectorsUnknownError extends StorageUnknownError {
+  constructor(message: string, originalError: unknown) {
+    super(message, originalError, 'vectors')
+  }
+}
+
+/**
+ * Error codes specific to S3 Vectors API
+ * Maps AWS service errors to application-friendly error codes
+ */
+export enum StorageVectorsErrorCode {
+  /** Internal server fault (HTTP 500) */
+  InternalError = 'InternalError',
+  /** Resource already exists / conflict (HTTP 409) */
+  S3VectorConflictException = 'S3VectorConflictException',
+  /** Resource not found (HTTP 404) */
+  S3VectorNotFoundException = 'S3VectorNotFoundException',
+  /** Delete bucket while not empty (HTTP 400) */
+  S3VectorBucketNotEmpty = 'S3VectorBucketNotEmpty',
+  /** Exceeds bucket quota/limit (HTTP 400) */
+  S3VectorMaxBucketsExceeded = 'S3VectorMaxBucketsExceeded',
+  /** Exceeds index quota/limit (HTTP 400) */
+  S3VectorMaxIndexesExceeded = 'S3VectorMaxIndexesExceeded',
+}

package/templates/realtime-agent/node_modules/@supabase/storage-js/src/lib/common/fetch.ts

@@ -0,0 +1,303 @@
+import { StorageApiError, StorageError, StorageUnknownError, ErrorNamespace } from './errors'
+import { setHeader } from './headers'
+import { isPlainObject, resolveResponse } from './helpers'
+import { FetchParameters } from '../types'
+
+export type Fetch = typeof fetch
+
+/**
+ * Options for fetch requests
+ */
+export interface FetchOptions {
+  headers?: {
+    [key: string]: string
+  }
+  duplex?: string
+  noResolveJson?: boolean
+}
+
+/**
+ * HTTP methods supported by the API
+ */
+export type RequestMethodType = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'HEAD'
+
+/**
+ * Extracts error message from various error response formats
+ * @param err - Error object from API
+ * @returns Human-readable error message
+ */
+const _getErrorMessage = (err: unknown): string => {
+  if (typeof err === 'object' && err !== null) {
+    const e = err as Record<string, unknown>
+    if (typeof e.msg === 'string') return e.msg
+    if (typeof e.message === 'string') return e.message
+    if (typeof e.error_description === 'string') return e.error_description
+    if (typeof e.error === 'string') return e.error
+    if (typeof e.error === 'object' && e.error !== null) {
+      const nested = e.error as Record<string, unknown>
+      if (typeof nested.message === 'string') return nested.message
+    }
+  }
+  return JSON.stringify(err)
+}
+
+/**
+ * Handles fetch errors and converts them to Storage error types
+ * @param error - The error caught from fetch
+ * @param reject - Promise rejection function
+ * @param options - Fetch options that may affect error handling
+ * @param namespace - Error namespace ('storage' or 'vectors')
+ */
+const handleError = async (
+  error: unknown,
+  reject: (reason: StorageError) => void,
+  options: FetchOptions | undefined,
+  namespace: ErrorNamespace
+) => {
+  // Structural detection of json() method, present in all Response implementations
+  // (native, node-fetch, cross-fetch, undici) and absent from standard Error objects.
+  // Checking 'ok' or 'status' via `in` is unreliable across fetch polyfills/realms.
+  const isResponseLike =
+    error !== null &&
+    typeof error === 'object' &&
+    'json' in error &&
+    typeof (error as Record<string, unknown>).json === 'function'
+
+  if (isResponseLike) {
+    const responseError = error as Response
+    // Defensive coercion: some fetch polyfills have historically returned status as a string.
+    let status = parseInt(String(responseError.status), 10)
+    if (!Number.isFinite(status)) {
+      status = 500
+    }
+
+    responseError
+      .json()
+      .then(
+        (err: { statusCode?: string; code?: string; error?: string; message?: string } | null) => {
+          const statusCode = err?.statusCode || err?.code || status + ''
+          reject(new StorageApiError(_getErrorMessage(err), status, statusCode, namespace))
+        }
+      )
+      .catch(() => {
+        const statusCode = status + ''
+        const message = responseError.statusText || `HTTP ${status} error`
+        reject(new StorageApiError(message, status, statusCode, namespace))
+      })
+  } else {
+    reject(new StorageUnknownError(_getErrorMessage(error), error, namespace))
+  }
+}
+
+/**
+ * Builds request parameters for fetch calls
+ * @param method - HTTP method
+ * @param options - Custom fetch options
+ * @param parameters - Additional fetch parameters like AbortSignal
+ * @param body - Request body (will be JSON stringified if plain object)
+ * @returns Complete fetch request parameters
+ */
+const _getRequestParams = (
+  method: RequestMethodType,
+  options?: FetchOptions,
+  parameters?: FetchParameters,
+  body?: object
+) => {
+  const params: { [k: string]: any } = { method, headers: options?.headers || {} }
+
+  if (method === 'GET' || method === 'HEAD' || !body) {
+    return { ...params, ...parameters }
+  }
+
+  if (isPlainObject(body)) {
+    const headers = options?.headers || {}
+    let contentType: string | undefined
+
+    for (const [key, value] of Object.entries(headers)) {
+      if (key.toLowerCase() === 'content-type') {
+        contentType = value
+      }
+    }
+
+    params.headers = setHeader(headers, 'Content-Type', contentType ?? 'application/json')
+    params.body = JSON.stringify(body)
+  } else {
+    params.body = body
+  }
+
+  if (options?.duplex) {
+    params.duplex = options.duplex
+  }
+
+  return { ...params, ...parameters }
+}
+
+/**
+ * Internal request handler that wraps fetch with error handling
+ * @param fetcher - Fetch function to use
+ * @param method - HTTP method
+ * @param url - Request URL
+ * @param options - Custom fetch options
+ * @param parameters - Additional fetch parameters
+ * @param body - Request body
+ * @param namespace - Error namespace ('storage' or 'vectors')
+ * @returns Promise with parsed response or error
+ */
+async function _handleRequest(
+  fetcher: Fetch,
+  method: RequestMethodType,
+  url: string,
+  options: FetchOptions | undefined,
+  parameters: FetchParameters | undefined,
+  body: object | undefined,
+  namespace: ErrorNamespace
+): Promise<any> {
+  return new Promise((resolve, reject) => {
+    fetcher(url, _getRequestParams(method, options, parameters, body))
+      .then((result) => {
+        if (!result.ok) throw result
+        if (options?.noResolveJson) return result
+
+        // AWS S3 Vectors API returns 200 OK with content-length: 0 for successful mutations
+        // (putVectors, deleteVectors) instead of 204 or JSON response. This is AWS's design choice
+        // for performance optimization of bulk operations (up to 500 vectors per request).
+        // We handle this to prevent "Unexpected end of JSON input" errors when calling result.json()
+        if (namespace === 'vectors') {
+          const contentType = result.headers.get('content-type')
+          const contentLength = result.headers.get('content-length')
+
+          // Return empty object for explicitly empty responses
+          if (contentLength === '0' || result.status === 204) {
+            return {}
+          }
+
+          // Return empty object if no JSON content type
+          if (!contentType || !contentType.includes('application/json')) {
+            return {}
+          }
+        }
+
+        return result.json()
+      })
+      .then((data) => resolve(data))
+      .catch((error) => handleError(error, reject, options, namespace))
+  })
+}
+
+/**
+ * Creates a fetch API with the specified namespace
+ * @param namespace - Error namespace ('storage' or 'vectors')
+ * @returns Object with HTTP method functions
+ */
+export function createFetchApi(namespace: ErrorNamespace = 'storage') {
+  return {
+    /**
+     * Performs a GET request
+     * @param fetcher - Fetch function to use
+     * @param url - Request URL
+     * @param options - Custom fetch options
+     * @param parameters - Additional fetch parameters
+     * @returns Promise with parsed response
+     */
+    get: async (
+      fetcher: Fetch,
+      url: string,
+      options?: FetchOptions,
+      parameters?: FetchParameters
+    ): Promise<any> => {
+      return _handleRequest(fetcher, 'GET', url, options, parameters, undefined, namespace)
+    },
+
+    /**
+     * Performs a POST request
+     * @param fetcher - Fetch function to use
+     * @param url - Request URL
+     * @param body - Request body to be JSON stringified
+     * @param options - Custom fetch options
+     * @param parameters - Additional fetch parameters
+     * @returns Promise with parsed response
+     */
+    post: async (
+      fetcher: Fetch,
+      url: string,
+      body: object,
+      options?: FetchOptions,
+      parameters?: FetchParameters
+    ): Promise<any> => {
+      return _handleRequest(fetcher, 'POST', url, options, parameters, body, namespace)
+    },
+
+    /**
+     * Performs a PUT request
+     * @param fetcher - Fetch function to use
+     * @param url - Request URL
+     * @param body - Request body to be JSON stringified
+     * @param options - Custom fetch options
+     * @param parameters - Additional fetch parameters
+     * @returns Promise with parsed response
+     */
+    put: async (
+      fetcher: Fetch,
+      url: string,
+      body: object,
+      options?: FetchOptions,
+      parameters?: FetchParameters
+    ): Promise<any> => {
+      return _handleRequest(fetcher, 'PUT', url, options, parameters, body, namespace)
+    },
+
+    /**
+     * Performs a HEAD request
+     * @param fetcher - Fetch function to use
+     * @param url - Request URL
+     * @param options - Custom fetch options
+     * @param parameters - Additional fetch parameters
+     * @returns Promise with Response object (not JSON parsed)
+     */
+    head: async (
+      fetcher: Fetch,
+      url: string,
+      options?: FetchOptions,
+      parameters?: FetchParameters
+    ): Promise<any> => {
+      return _handleRequest(
+        fetcher,
+        'HEAD',
+        url,
+        {
+          ...options,
+          noResolveJson: true,
+        },
+        parameters,
+        undefined,
+        namespace
+      )
+    },
+
+    /**
+     * Performs a DELETE request
+     * @param fetcher - Fetch function to use
+     * @param url - Request URL
+     * @param body - Request body to be JSON stringified
+     * @param options - Custom fetch options
+     * @param parameters - Additional fetch parameters
+     * @returns Promise with parsed response
+     */
+    remove: async (
+      fetcher: Fetch,
+      url: string,
+      body: object,
+      options?: FetchOptions,
+      parameters?: FetchParameters
+    ): Promise<any> => {
+      return _handleRequest(fetcher, 'DELETE', url, options, parameters, body, namespace)
+    },
+  }
+}
+
+// Default exports for backward compatibility with 'storage' namespace
+const defaultApi = createFetchApi('storage')
+export const { get, post, put, head, remove } = defaultApi
+
+// Vectors API with 'vectors' namespace for proper error handling
+export const vectorsApi = createFetchApi('vectors')

package/templates/realtime-agent/node_modules/@supabase/storage-js/src/lib/common/headers.ts

@@ -0,0 +1,43 @@
+/**
+ * Sets a header with case-insensitive deduplication.
+ * Removes any existing headers whose name matches (case-insensitive),
+ * then sets the value under the lowercase key. Does not mutate the input object.
+ *
+ * @param headers - Existing headers object
+ * @param name - Header name to set (stored as lowercase)
+ * @param value - Header value
+ * @returns New headers object with the header set
+ */
+export function setHeader(
+  headers: Record<string, string>,
+  name: string,
+  value: string
+): Record<string, string> {
+  const result = { ...headers }
+  const nameLower = name.toLowerCase()
+
+  for (const key of Object.keys(result)) {
+    if (key.toLowerCase() === nameLower) {
+      delete result[key]
+    }
+  }
+
+  result[nameLower] = value
+  return result
+}
+
+/**
+ * Normalizes all header keys to lowercase with case-insensitive deduplication.
+ * When duplicate keys exist (differing only in case), the last value wins.
+ * Does not mutate the input object.
+ *
+ * @param headers - Headers object to normalize
+ * @returns New headers object with all keys lowercased
+ */
+export function normalizeHeaders(headers: Record<string, string>): Record<string, string> {
+  const result: Record<string, string> = {}
+  for (const [key, value] of Object.entries(headers)) {
+    result[key.toLowerCase()] = value
+  }
+  return result
+}