\r\n );\r\n}\r\n```\r\n\r\n## CLI Setup\r\n\r\nFor a quick setup, use the included CLI:\r\n\r\n```bash\r\nnpx @api-buddy/cloudinary setup\r\n```\r\n\r\nThis will:\r\n1. Install required dependencies\r\n2. Set up environment variables\r\n3. Create example components and API routes\r\n4. Configure your Next.js app to use Cloudinary\r\n\r\n## API Reference\r\n\r\n### `CloudinaryProvider`\r\n\r\nA context provider that makes the Cloudinary client available throughout your application.\r\n\r\n#### Props\r\n\r\n- `config`: Configuration object\r\n - `cloudName`: Your Cloudinary cloud name (required)\r\n - `apiKey`: Your Cloudinary API key (optional, defaults to `process.env.NEXT_PUBLIC_CLOUDINARY_API_KEY`)\r\n - `apiSecret`: Your Cloudinary API secret (optional, defaults to `process.env.CLOUDINARY_API_SECRET`)\r\n - `uploadPreset`: Your Cloudinary upload preset (optional)\r\n - `defaultUploadOptions`: Default options for all uploads\r\n\r\n### `useCloudinary()`\r\n\r\nA hook to access the Cloudinary client from the nearest `CloudinaryProvider`.\r\n\r\n#### Returns\r\n\r\n- `client`: The Cloudinary client instance\r\n- `config`: The current Cloudinary configuration\r\n\r\n### `useCloudinaryUpload(options)`\r\n\r\nA hook for handling file uploads to Cloudinary.\r\n\r\n#### Parameters\r\n\r\n- `options`: Upload options\r\n - `options`: Default upload options for all uploads\r\n - `onSuccess`: Callback when an upload succeeds\r\n - `onError`: Callback when an upload fails\r\n - `onProgress`: Callback with upload progress (0-100)\r\n\r\n#### Returns\r\n\r\n- `uploadFile`: Function to upload a single file\r\n- `uploadFiles`: Function to upload multiple files\r\n- `isUploading`: Boolean indicating if an upload is in progress\r\n- `progress`: Current upload progress (0-100)\r\n- `error`: Error object if an upload failed\r\n- `reset`: Function to reset the hook state\r\n\r\n### `CloudinaryImage`\r\n\r\nA React component for displaying Cloudinary images with automatic optimization.\r\n\r\n#### Props\r\n\r\n- `publicId`: The public ID of the image (required)\r\n- `alt`: Alternative text for the image (required)\r\n- `width`: Width of the image\r\n- `height`: Height of the image\r\n- `className`: CSS class name\r\n- `style`: Inline styles\r\n- `loading`: Loading behavior (`lazy` or `eager`)\r\n- `transformation`: Array of Cloudinary transformations\r\n- `format`: Image format to convert to\r\n- `quality`: Image quality (1-100)\r\n- `responsive`: Whether to generate responsive images\r\n- `sizes`: Sizes attribute for responsive images\r\n- `srcSet`: Custom srcset for responsive images\r\n- `onLoad`: Callback when the image loads\r\n- `onError`: Callback when the image fails to load\r\n\r\n### `CloudinaryVideo`\r\n\r\nA React component for displaying Cloudinary videos.\r\n\r\n#### Props\r\n\r\n- `publicId`: The public ID of the video (required)\r\n- `width`: Width of the video player\r\n- `height`: Height of the video player\r\n- `className`: CSS class name\r\n- `style`: Inline styles\r\n- `autoPlay`: Whether to autoplay the video\r\n- `loop`: Whether to loop the video\r\n- `muted`: Whether to mute the video\r\n- `controls`: Whether to show video controls\r\n- `poster`: URL of the poster image\r\n- `transformation`: Array of Cloudinary transformations\r\n- `onPlay`: Callback when the video starts playing\r\n- `onPause`: Callback when the video is paused\r\n- `onEnded`: Callback when the video ends\r\n- `onError`: Callback when the video fails to load\r\n\r\n### `upload(file, options)`\r\n\r\nUpload a file to Cloudinary.\r\n\r\n#### Parameters\r\n\r\n- `file`: File to upload (Buffer, ReadStream, or base64 string)\r\n- `options`: Upload options (see [Cloudinary documentation](https://cloudinary.com/documentation/image_upload_api_reference#upload_method))\r\n\r\n#### Returns\r\n\r\nA promise that resolves to the upload result.\r\n\r\n### `deleteFile(publicId, options)`\r\n\r\nDelete a file from Cloudinary.\r\n\r\n#### Parameters\r\n\r\n- `publicId`: The public ID of the file to delete\r\n- `options`: Delete options\r\n - `resourceType`: Type of resource (`image`, `video`, `raw`, or `auto`)\r\n - `type`: The type of the resource\r\n - `invalidate`: Whether to invalidate the CDN cache\r\n\r\n#### Returns\r\n\r\nA promise that resolves to the delete result.\r\n\r\n### `getUrl(publicId, options)`\r\n\r\nGenerate a URL for a Cloudinary resource.\r\n\r\n#### Parameters\r\n\r\n- `publicId`: The public ID of the resource\r\n- `options`: URL and transformation options\r\n - `transformation`: Array of Cloudinary transformations\r\n - `resourceType`: Type of resource (`image`, `video`, `raw`, or `auto`)\r\n - `type`: The type of the resource\r\n - `format`: Format to convert the resource to\r\n - `secure`: Whether to use HTTPS\r\n - `signUrl`: Whether to sign the URL\r\n - `version`: The version of the resource\r\n\r\n#### Returns\r\n\r\nThe generated URL as a string.\r\n\r\n## Examples\r\n\r\n### Uploading a File\r\n\r\n```typescript\r\nimport { upload } from '@api-buddy/cloudinary';\r\n\r\n// In an API route or server component\r\nconst file = // your file buffer or stream\r\nconst result = await upload(file, {\r\n folder: 'uploads',\r\n resourceType: 'auto',\r\n public_id: 'my-file',\r\n});\r\n\r\nconsole.log('File uploaded:', result.url);\r\n```\r\n\r\n### Using Transformations\r\n\r\n```typescript\r\nimport { CloudinaryImage } from '@api-buddy/cloudinary';\r\n\r\nfunction ProductImage({ publicId }: { publicId: string }) {\r\n return (\r\n \r\n );\r\n}\r\n```\r\n\r\n### Responsive Images\r\n\r\n```typescript\r\nimport { CloudinaryImage } from '@api-buddy/cloudinary';\r\n\r\nfunction HeroImage({ publicId }: { publicId: string }) {\r\n return (\r\n \r\n );\r\n}\r\n```\r\n\r\n## Error Handling\r\n\r\nAll functions throw a `CloudinaryError` when something goes wrong. You can catch and handle these errors:\r\n\r\n```typescript\r\ntry {\r\n await upload(file, options);\r\n} catch (error) {\r\n if (error.name === 'CloudinaryError') {\r\n console.error('Cloudinary error:', error.message);\r\n // Handle specific error cases\r\n if (error.code === 'LIMIT_FILE_SIZE') {\r\n // Handle file size limit exceeded\r\n } else if (error.code === 'UNAUTHORIZED') {\r\n // Handle authentication error\r\n } else {\r\n // Handle other errors\r\n }\r\n } else {\r\n // Handle non-Cloudinary errors\r\n console.error('Unexpected error:', error);\r\n }\r\n}\r\n```\r\n\r\n## Contributing\r\n\r\nContributions are welcome! Please open an issue or submit a pull request.\r\n\r\n## License\r\n\r\nMIT\r\n\r\n## Acknowledgments\r\n\r\n- [Cloudinary](https://cloudinary.com/) - Cloud-based image and video management\r\n- [@cloudinary/url-builder](https://www.npmjs.com/package/@cloudinary/url-builder) - Official Cloudinary URL builder\r\n- [@cloudinary/react](https://www.npmjs.com/package/@cloudinary/react) - Official Cloudinary React components\r\n","readmeFilename":"README.md"}