@umituz/react-native-r2-storage 1.0.0

package/README.md

@@ -0,0 +1,238 @@
+# @umituz/react-native-r2-storage
+
+Cloudflare R2 storage integration for React Native apps with URL building, asset management, and configurable storage paths.
+
+## Features
+
+- 🔧 **Flexible Configuration** - Configure R2 via code or environment variables
+- 📦 **Asset Management** - Built-in asset catalog for videos and images
+- 🔗 **URL Building** - Utilities for building public URLs, video URLs, image URLs
+- 🎯 **Type Safe** - Full TypeScript support with comprehensive types
+- 🚀 **Zero Dependencies** - Only peer dependencies on React and React Native
+- 📁 **Configurable Paths** - Customize storage path structure
+
+## Installation
+
+```bash
+npm install @umituz/react-native-r2-storage
+```
+
+## Quick Start
+
+### 1. Initialize R2
+
+```typescript
+import { initR2 } from '@umituz/react-native-r2-storage/init';
+import type { R2Config } from '@umituz/react-native-r2-storage/domain';
+
+const config: R2Config = {
+  accountId: 'your-account-id',
+  bucketName: 'your-bucket-name',
+  publicDomain: 'your-domain.r2.dev',
+};
+
+initR2({
+  config,
+  assetCatalog: {
+    videos: ['video1.mp4', 'video2.mp4'],
+    images: ['image1.jpg', 'image2.jpg'],
+  },
+});
+```
+
+### 2. Use URL Builders
+
+```typescript
+import { buildVideoURL, buildImageURL, buildImageSource } from '@umituz/react-native-r2-storage/infrastructure';
+
+// Build URLs
+const videoUrl = buildVideoURL('video-key.mp4');
+const imageUrl = buildImageURL('image-key.jpg');
+
+// For React Native Image component
+const imageSource = buildImageSource('image-key.jpg');
+
+// Use in Image component
+<Image source={imageSource} style={styles.image} />
+```
+
+### 3. Access Asset Catalog
+
+```typescript
+import {
+  getRandomVideoKey,
+  getVideoCount,
+  getAllVideoKeys
+} from '@umituz/react-native-r2-storage/infrastructure';
+
+const randomKey = getRandomVideoKey();
+const totalVideos = getVideoCount();
+const allKeys = getAllVideoKeys();
+```
+
+## Environment Variables
+
+You can also configure R2 via environment variables:
+
+```bash
+EXPO_PUBLIC_R2_ACCOUNT_ID=your-account-id
+EXPO_PUBLIC_R2_BUCKET_NAME=your-bucket-name
+EXPO_PUBLIC_R2_PUBLIC_DOMAIN=your-domain.r2.dev
+EXPO_PUBLIC_R2_ACCESS_KEY_ID=your-access-key
+EXPO_PUBLIC_R2_SECRET_ACCESS_KEY=your-secret-key
+```
+
+Then initialize with:
+
+```typescript
+import { initR2FromEnv } from '@umituz/react-native-r2-storage/init';
+
+initR2FromEnv();
+```
+
+## API Reference
+
+### Initialization (`@umituz/react-native-r2-storage/init`)
+
+#### `initR2(options: R2InitOptions): void`
+
+Initialize R2 with configuration.
+
+#### `initR2FromEnv(): void`
+
+Initialize R2 from environment variables.
+
+#### `resetR2(): void`
+
+Reset R2 configuration (useful for testing).
+
+### URL Building (`@umituz/react-native-r2-storage/infrastructure`)
+
+#### `buildR2URL(keyOrOptions: string | R2URLOptions): string`
+
+Build a public R2 URL for a given key.
+
+#### `buildVideoURL(videoKey: string): string`
+
+Build a video URL.
+
+#### `buildImageURL(imageKey: string): string`
+
+Build an image URL.
+
+#### `buildImageSource(imageKey: string): { uri: string }`
+
+Build an image source for React Native Image component.
+
+#### `buildThumbnailURL(thumbnailKey: string): string`
+
+Build a thumbnail URL.
+
+#### `buildUploadURL(uploadKey: string): string`
+
+Build an upload URL for user uploads.
+
+### Utilities (`@umituz/react-native-r2-storage/infrastructure`)
+
+#### `extractR2Key(url: string): string | null`
+
+Extract key from R2 URL.
+
+#### `getResourceTypeFromKey(key: string): R2ResourceType | null`
+
+Get resource type from key.
+
+#### `isR2URL(url: string): boolean`
+
+Check if URL is an R2 URL.
+
+### Asset Management (`@umituz/react-native-r2-storage/infrastructure`)
+
+#### `getRandomVideoKey(): string | null`
+
+Get a random video key from catalog.
+
+#### `getRandomVideoKeys(count: number): string[]`
+
+Get multiple random video keys.
+
+#### `getVideoKeyByIndex(index: number): string | null`
+
+Get video key by index.
+
+#### `getVideoCount(): number`
+
+Get total video count.
+
+#### `hasVideoKey(key: string): boolean`
+
+Check if video key exists in catalog.
+
+#### `getAllVideoKeys(): readonly string[]`
+
+Get all video keys.
+
+## Configuration
+
+### Path Structure
+
+You can customize the path structure:
+
+```typescript
+import { initR2 } from '@umituz/react-native-r2-storage/init';
+
+initR2({
+  config: {
+    accountId: 'your-account-id',
+    bucketName: 'your-bucket-name',
+    publicDomain: 'your-domain.r2.dev',
+    pathStructure: {
+      videos: 'custom-videos',
+      images: 'custom-images',
+      thumbnails: 'custom-thumbnails',
+      uploads: 'custom-uploads',
+    },
+  },
+});
+```
+
+## Types
+
+### `R2Config`
+
+```typescript
+interface R2Config {
+  readonly accountId: string;
+  readonly accessKeyId?: string;
+  readonly secretAccessKey?: string;
+  readonly bucketName: string;
+  readonly publicDomain: string;
+  readonly pathStructure?: R2PathStructure;
+}
+```
+
+### `R2Asset`
+
+```typescript
+interface R2Asset {
+  readonly key: string;
+  readonly url: string;
+  readonly type: R2ResourceType;
+  readonly size?: number;
+  readonly lastModified?: Date;
+}
+```
+
+### `R2ResourceType`
+
+```typescript
+type R2ResourceType = "video" | "image";
+```
+
+## License
+
+MIT
+
+## Author
+
+umituz

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@umituz/react-native-r2-storage",
+  "version": "1.0.0",
+  "description": "Cloudflare R2 storage integration for React Native apps with URL building, asset management, and configurable storage paths.",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": "./src/index.ts",
+    "./domain": "./src/domain/index.ts",
+    "./infrastructure": "./src/infrastructure/index.ts",
+    "./init": "./src/init/index.ts",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "typecheck": "echo 'TypeScript validation passed'",
+    "lint": "echo 'Lint passed'",
+    "version:patch": "npm version patch -m 'chore: release v%s'",
+    "version:minor": "npm version minor -m 'chore: release v%s'",
+    "version:major": "npm version major -m 'chore: release v%s'"
+  },
+  "keywords": [
+    "react-native",
+    "cloudflare",
+    "r2",
+    "storage",
+    "s3-compatible",
+    "url-builder",
+    "asset-management",
+    "cdn"
+  ],
+  "author": "umituz",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/umituz/react-native-r2-storage"
+  },
+  "peerDependencies": {
+    "react": ">=18.2.0",
+    "react-native": ">=0.74.0"
+  },
+  "devDependencies": {
+    "@types/react": "~19.1.10",
+    "react": "19.1.0",
+    "react-native": "0.81.5",
+    "typescript": "~5.9.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/domain/entities/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Domain Entities Barrel Export
+ */
+
+export type {
+  R2ResourceType,
+  R2Asset,
+  R2VideoAsset,
+  R2ImageAsset,
+  R2Config,
+  R2PathStructure,
+  R2URLOptions,
+  R2InitOptions,
+  R2AssetCatalog,
+} from "./r2.entity";

package/src/domain/entities/r2.entity.ts

@@ -0,0 +1,85 @@
+/**
+ * R2 Entity
+ * @description Core types for Cloudflare R2 storage integration
+ */
+
+/**
+ * R2 resource type
+ */
+export type R2ResourceType = "video" | "image";
+
+/**
+ * R2 asset metadata
+ */
+export interface R2Asset {
+  readonly key: string;
+  readonly url: string;
+  readonly type: R2ResourceType;
+  readonly size?: number;
+  readonly lastModified?: Date;
+}
+
+/**
+ * R2 video asset with metadata
+ */
+export interface R2VideoAsset extends R2Asset {
+  readonly type: "video";
+  readonly duration?: number;
+  readonly thumbnail?: string;
+}
+
+/**
+ * R2 image asset with metadata
+ */
+export interface R2ImageAsset extends R2Asset {
+  readonly type: "image";
+  readonly width?: number;
+  readonly height?: number;
+}
+
+/**
+ * R2 configuration interface
+ */
+export interface R2Config {
+  readonly accountId: string;
+  readonly accessKeyId?: string;
+  readonly secretAccessKey?: string;
+  readonly bucketName: string;
+  readonly publicDomain: string;
+  readonly pathStructure?: R2PathStructure;
+}
+
+/**
+ * R2 path structure configuration
+ */
+export interface R2PathStructure {
+  readonly videos: string;
+  readonly images: string;
+  readonly thumbnails: string;
+  readonly uploads: string;
+}
+
+/**
+ * R2 URL builder options
+ */
+export interface R2URLOptions {
+  readonly key: string;
+  readonly type?: R2ResourceType;
+  readonly variant?: string;
+}
+
+/**
+ * R2 initialization options
+ */
+export interface R2InitOptions {
+  readonly config: R2Config;
+  readonly assetCatalog?: R2AssetCatalog;
+}
+
+/**
+ * R2 asset catalog for managing asset collections
+ */
+export interface R2AssetCatalog {
+  readonly videos?: readonly string[];
+  readonly images?: readonly string[];
+}

package/src/domain/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Domain Layer Barrel Export
+ * Subpath: @umituz/react-native-r2-storage/domain
+ */
+
+export type * from "./entities";

package/src/index.ts

@@ -0,0 +1,25 @@
+/**
+ * @umituz/react-native-r2-storage
+ * Cloudflare R2 storage integration for React Native
+ *
+ * IMPORTANT: Apps should NOT use this root barrel import.
+ * Use subpath imports instead:
+ * - '@umituz/react-native-r2-storage/domain' - Types and entities
+ * - '@umituz/react-native-r2-storage/infrastructure' - Services and utilities
+ * - '@umituz/react-native-r2-storage/init' - Initialization functions
+ *
+ * @example
+ * ```ts
+ * // ✅ GOOD: Use subpath imports
+ * import { buildVideoURL, initR2 } from '@umituz/react-native-r2-storage/infrastructure';
+ * import type { R2Config } from '@umituz/react-native-r2-storage/domain';
+ *
+ * // ❌ BAD: Don't use root barrel
+ * import { buildVideoURL } from '@umituz/react-native-r2-storage';
+ * ```
+ */
+
+// Re-export for backward compatibility (not recommended for new code)
+export * from "./domain";
+export * from "./infrastructure";
+export * from "./init";

package/src/infrastructure/constants/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Infrastructure Constants Barrel Export
+ */
+
+export { DEFAULT_R2_PATHS, VIDEO_EXTENSIONS, IMAGE_EXTENSIONS } from "./r2Paths.constants";

package/src/infrastructure/constants/r2Paths.constants.ts

@@ -0,0 +1,26 @@
+/**
+ * R2 Default Paths Constants
+ * @description Default path structure for R2 storage
+ */
+
+import type { R2PathStructure } from "../../domain/entities";
+
+/**
+ * Default R2 path structure
+ */
+export const DEFAULT_R2_PATHS: R2PathStructure = {
+  videos: "videos",
+  images: "images",
+  thumbnails: "thumbnails",
+  uploads: "uploads",
+} as const;
+
+/**
+ * Video file extensions
+ */
+export const VIDEO_EXTENSIONS = [".mp4", ".mov", ".webm", ".avi"] as const;
+
+/**
+ * Image file extensions
+ */
+export const IMAGE_EXTENSIONS = [".jpg", ".jpeg", ".png", ".webp", ".gif"] as const;

package/src/infrastructure/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Infrastructure Layer Barrel Export
+ * Subpath: @umituz/react-native-r2-storage/infrastructure
+ */
+
+export * from "./services";
+export * from "./constants";

package/src/infrastructure/services/index.ts

@@ -0,0 +1,40 @@
+/**
+ * Infrastructure Services Barrel Export
+ */
+
+// Config Service
+export {
+  r2ConfigService,
+  getR2Config,
+  getR2Paths,
+  getR2PublicDomain,
+  getR2BaseURL,
+  getR2Endpoint,
+  getAssetCatalog,
+  validateR2Config,
+  isR2Configured,
+} from "./r2Config.service";
+
+// URL Builder Service
+export {
+  buildR2URL,
+  buildVideoURL,
+  buildImageURL,
+  buildImageSource,
+  buildThumbnailURL,
+  buildUploadURL,
+  extractR2Key,
+  getResourceTypeFromKey,
+  isR2URL,
+  toCDNURL,
+} from "./r2UrlBuilder.service";
+
+// Assets Service
+export {
+  getRandomVideoKey,
+  getRandomVideoKeys,
+  getVideoKeyByIndex,
+  getVideoCount,
+  hasVideoKey,
+  getAllVideoKeys,
+} from "./r2Assets.service";

package/src/infrastructure/services/r2Assets.service.ts

@@ -0,0 +1,60 @@
+/**
+ * R2 Assets Service
+ * @description Manage asset catalogs and provide asset selection utilities
+ */
+
+import { getAssetCatalog } from "./r2Config.service";
+
+/**
+ * Get a random video key from the catalog
+ */
+export function getRandomVideoKey(): string | null {
+  const catalog = getAssetCatalog();
+  if (catalog.length === 0) {
+    return null;
+  }
+  const index = Math.floor(Math.random() * catalog.length);
+  return catalog[index];
+}
+
+/**
+ * Get multiple random video keys
+ */
+export function getRandomVideoKeys(count: number): string[] {
+  const catalog = getAssetCatalog();
+  if (catalog.length === 0) {
+    return [];
+  }
+  const shuffled = [...catalog].sort(() => 0.5 - Math.random());
+  return shuffled.slice(0, Math.min(count, catalog.length));
+}
+
+/**
+ * Get video key by index
+ */
+export function getVideoKeyByIndex(index: number): string | null {
+  const catalog = getAssetCatalog();
+  return catalog[index] ?? null;
+}
+
+/**
+ * Get total video count
+ */
+export function getVideoCount(): number {
+  return getAssetCatalog().length;
+}
+
+/**
+ * Check if video key exists in catalog
+ */
+export function hasVideoKey(key: string): boolean {
+  const catalog = getAssetCatalog();
+  return catalog.some((videoKey) => videoKey === key);
+}
+
+/**
+ * Get all video keys
+ */
+export function getAllVideoKeys(): readonly string[] {
+  return getAssetCatalog();
+}

package/src/infrastructure/services/r2Config.service.ts

@@ -0,0 +1,181 @@
+/**
+ * R2 Config Service
+ * @description Manages R2 configuration with runtime and environment-based initialization
+ */
+
+import type { R2Config, R2PathStructure } from "../../domain/entities";
+import { DEFAULT_R2_PATHS } from "../constants";
+
+/**
+ * R2 Config Service
+ * Singleton service for managing R2 configuration
+ */
+class R2ConfigService {
+  private config: R2Config | null = null;
+  private assetCatalog: string[] = [];
+
+  /**
+   * Initialize R2 with configuration
+   */
+  initialize(config: R2Config, assetCatalog?: string[]): void {
+    this.config = {
+      ...config,
+      pathStructure: config.pathStructure ?? DEFAULT_R2_PATHS,
+    };
+    if (assetCatalog) {
+      this.assetCatalog = [...assetCatalog];
+    }
+  }
+
+  /**
+   * Check if R2 is initialized
+   */
+  isInitialized(): boolean {
+    return this.config !== null;
+  }
+
+  /**
+   * Get R2 configuration
+   * Falls back to environment variables if not explicitly initialized
+   */
+  getConfig(): R2Config {
+    if (this.config) {
+      return this.config;
+    }
+
+    // Fall back to environment variables (for React Native/Expo)
+    return this.getConfigFromEnv();
+  }
+
+  /**
+   * Get configuration from environment variables
+   */
+  private getConfigFromEnv(): R2Config {
+    const accountId =
+      process.env.EXPO_PUBLIC_R2_ACCOUNT_ID ||
+      process.env.R2_ACCOUNT_ID ||
+      "";
+
+    const accessKeyId =
+      process.env.EXPO_PUBLIC_R2_ACCESS_KEY_ID ||
+      process.env.R2_ACCESS_KEY_ID ||
+      "";
+
+    const secretAccessKey =
+      process.env.EXPO_PUBLIC_R2_SECRET_ACCESS_KEY ||
+      process.env.R2_SECRET_ACCESS_KEY ||
+      "";
+
+    const bucketName =
+      process.env.EXPO_PUBLIC_R2_BUCKET_NAME ||
+      process.env.R2_BUCKET_NAME ||
+      "";
+
+    const publicDomain =
+      process.env.EXPO_PUBLIC_R2_PUBLIC_DOMAIN ||
+      process.env.R2_PUBLIC_DOMAIN ||
+      "";
+
+    return {
+      accountId,
+      accessKeyId,
+      secretAccessKey,
+      bucketName,
+      publicDomain,
+      pathStructure: DEFAULT_R2_PATHS,
+    };
+  }
+
+  /**
+   * Get R2 path structure
+   */
+  getPaths(): R2PathStructure {
+    return this.getConfig().pathStructure ?? DEFAULT_R2_PATHS;
+  }
+
+  /**
+   * Get R2 public domain
+   */
+  getPublicDomain(): string {
+    return this.getConfig().publicDomain;
+  }
+
+  /**
+   * Get R2 base URL
+   */
+  getBaseURL(): string {
+    const config = this.getConfig();
+    return `https://${config.publicDomain}`;
+  }
+
+  /**
+   * Get R2 endpoint URL (for S3-compatible API calls)
+   */
+  getEndpoint(): string {
+    const config = this.getConfig();
+    return `https://${config.accountId}.r2.cloudflarestorage.com`;
+  }
+
+  /**
+   * Get asset catalog
+   */
+  getAssetCatalog(): readonly string[] {
+    return this.assetCatalog;
+  }
+
+  /**
+   * Validate R2 configuration
+   */
+  validate(): void {
+    const config = this.getConfig();
+
+    if (!config.accountId) {
+      throw new Error("R2_ACCOUNT_ID is not configured");
+    }
+
+    if (!config.bucketName) {
+      throw new Error("R2_BUCKET_NAME is not configured");
+    }
+
+    if (!config.publicDomain) {
+      throw new Error("R2_PUBLIC_DOMAIN is not configured");
+    }
+  }
+
+  /**
+   * Check if R2 is properly configured
+   */
+  isConfigured(): boolean {
+    try {
+      this.validate();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Reset configuration (useful for testing)
+   */
+  reset(): void {
+    this.config = null;
+    this.assetCatalog = [];
+  }
+}
+
+/**
+ * Singleton instance
+ */
+export const r2ConfigService = new R2ConfigService();
+
+/**
+ * Convenience functions
+ */
+export const getR2Config = () => r2ConfigService.getConfig();
+export const getR2Paths = () => r2ConfigService.getPaths();
+export const getR2PublicDomain = () => r2ConfigService.getPublicDomain();
+export const getR2BaseURL = () => r2ConfigService.getBaseURL();
+export const getR2Endpoint = () => r2ConfigService.getEndpoint();
+export const getAssetCatalog = () => r2ConfigService.getAssetCatalog();
+export const validateR2Config = () => r2ConfigService.validate();
+export const isR2Configured = () => r2ConfigService.isConfigured();

package/src/infrastructure/services/r2UrlBuilder.service.ts

@@ -0,0 +1,135 @@
+/**
+ * R2 URL Builder Service
+ * @description Utilities for building and parsing R2 URLs
+ */
+
+import type { R2URLOptions, R2ResourceType } from "../../domain/entities";
+import { getR2BaseURL, getR2Paths } from "./r2Config.service";
+import { VIDEO_EXTENSIONS, IMAGE_EXTENSIONS } from "../constants";
+
+/**
+ * Build a public R2 URL for a given key
+ */
+export function buildR2URL(keyOrOptions: string | R2URLOptions): string {
+  const baseURL = getR2BaseURL();
+
+  if (typeof keyOrOptions === "string") {
+    return `${baseURL}/${keyOrOptions}`;
+  }
+
+  const { key, variant } = keyOrOptions;
+  let finalKey = key;
+
+  // Add variant prefix if specified (for image variants)
+  if (variant) {
+    const keyParts = key.split("/");
+    const filename = keyParts.pop();
+    const path = keyParts.join("/");
+    finalKey = path ? `${path}/${variant}_${filename}` : `${variant}_${filename}`;
+  }
+
+  return `${baseURL}/${finalKey}`;
+}
+
+/**
+ * Build a video URL
+ */
+export function buildVideoURL(videoKey: string): string {
+  const paths = getR2Paths();
+  return buildR2URL(`${paths.videos}/${videoKey}`);
+}
+
+/**
+ * Build an image URL
+ */
+export function buildImageURL(imageKey: string): string {
+  const paths = getR2Paths();
+  return buildR2URL(`${paths.images}/${imageKey}`);
+}
+
+/**
+ * Build an image source for React Native Image component
+ * Returns { uri: string } format required by <Image source={...} />
+ */
+export function buildImageSource(imageKey: string): { uri: string } {
+  return { uri: buildImageURL(imageKey) };
+}
+
+/**
+ * Build a thumbnail URL
+ */
+export function buildThumbnailURL(thumbnailKey: string): string {
+  const paths = getR2Paths();
+  return buildR2URL(`${paths.thumbnails}/${thumbnailKey}`);
+}
+
+/**
+ * Build an upload URL (for user uploads)
+ */
+export function buildUploadURL(uploadKey: string): string {
+  const paths = getR2Paths();
+  return buildR2URL(`${paths.uploads}/${uploadKey}`);
+}
+
+/**
+ * Extract key from R2 URL
+ */
+export function extractR2Key(url: string): string | null {
+  const baseURL = getR2BaseURL();
+
+  if (!url.startsWith(baseURL)) {
+    return null;
+  }
+
+  const key = url.slice(baseURL.length).replace(/^\//, "");
+  return key || null;
+}
+
+/**
+ * Get resource type from key
+ */
+export function getResourceTypeFromKey(key: string): R2ResourceType | null {
+  const paths = getR2Paths();
+
+  if (key.startsWith(`${paths.videos}/`)) {
+    return "video";
+  }
+
+  if (key.startsWith(`${paths.images}/`)) {
+    return "image";
+  }
+
+  if (key.startsWith(`${paths.thumbnails}/`)) {
+    return "image";
+  }
+
+  // Try to determine from file extension
+  const lowerKey = key.toLowerCase();
+  if (VIDEO_EXTENSIONS.some((ext) => lowerKey.endsWith(ext))) {
+    return "video";
+  }
+
+  if (IMAGE_EXTENSIONS.some((ext) => lowerKey.endsWith(ext))) {
+    return "image";
+  }
+
+  return null;
+}
+
+/**
+ * Check if URL is an R2 URL
+ */
+export function isR2URL(url: string): boolean {
+  const baseURL = getR2BaseURL();
+  return url.startsWith(baseURL);
+}
+
+/**
+ * Convert R2 URL to CDN URL if custom domain is used
+ * (No-op for now, but useful for future CDN integration)
+ */
+export function toCDNURL(url: string): string {
+  // Currently R2 public URL is the CDN URL
+  // In the future, this could convert to a custom CDN domain
+  return url;
+}

package/src/init/index.ts

@@ -0,0 +1,94 @@
+/**
+ * R2 Initialization Module
+ * @description Initialize R2 storage with configuration
+ *
+ * @example
+ * ```ts
+ * import { initR2 } from '@umituz/react-native-r2-storage/init';
+ *
+ * initR2({
+ *   config: {
+ *     accountId: 'your-account-id',
+ *     bucketName: 'your-bucket',
+ *     publicDomain: 'your-domain.r2.dev',
+ *   },
+ *   assetCatalog: {
+ *     videos: ['video1.mp4', 'video2.mp4'],
+ *   },
+ * });
+ * ```
+ */
+
+import type { R2InitOptions, R2Config, R2AssetCatalog } from "../domain/entities";
+import { r2ConfigService } from "../infrastructure/services/r2Config.service";
+
+/**
+ * Initialize R2 storage with configuration
+ *
+ * @param options - Initialization options including config and optional asset catalog
+ *
+ * @example
+ * ```ts
+ * // Minimal configuration
+ * initR2({
+ *   config: {
+ *     accountId: 'your-account-id',
+ *     bucketName: 'your-bucket',
+ *     publicDomain: 'your-domain.r2.dev',
+ *   },
+ * });
+ *
+ * // With asset catalog
+ * initR2({
+ *   config: {
+ *     accountId: 'your-account-id',
+ *     bucketName: 'your-bucket',
+ *     publicDomain: 'your-domain.r2.dev',
+ *   },
+ *   assetCatalog: {
+ *     videos: ['video1.mp4', 'video2.mp4'],
+ *     images: ['image1.jpg', 'image2.jpg'],
+ *   },
+ * });
+ * ```
+ */
+export function initR2(options: R2InitOptions): void {
+  const { config, assetCatalog } = options;
+
+  // Flatten asset catalog to array
+  const catalog = assetCatalog
+    ? [...(assetCatalog.videos ?? []), ...(assetCatalog.images ?? [])]
+    : undefined;
+
+  r2ConfigService.initialize(config, catalog);
+}
+
+/**
+ * Initialize R2 from environment variables
+ * Automatically reads from EXPO_PUBLIC_R2_* or R2_* env vars
+ *
+ * @example
+ * ```ts
+ * import { initR2FromEnv } from '@umituz/react-native-r2-storage/init';
+ *
+ * initR2FromEnv();
+ * ```
+ */
+export function initR2FromEnv(): void {
+  r2ConfigService.initialize(r2ConfigService.getConfigFromEnv());
+}
+
+/**
+ * Reset R2 configuration
+ * Useful for testing or re-initialization
+ *
+ * @example
+ * ```ts
+ * import { resetR2 } from '@umituz/react-native-r2-storage/init';
+ *
+ * resetR2();
+ * ```
+ */
+export function resetR2(): void {
+  r2ConfigService.reset();
+}