cloudinary_npm AGENTS.md

Contributor guide for coding agents

This file is for agents contributing to this repository. If you are using the installed cloudinary package in another project, read the bundled docs in node_modules/cloudinary/docs/ instead.

Commands

npm install              # install dependencies
npm test                 # lint + unit tests + type declaration tests
npm run test:unit        # mocha unit tests only (mocked, no network)
npm run lint             # eslint
npm run dtslint          # TypeScript declaration tests
npm run test-with-temp-cloud  # full integration tests against a temporary cloud (CI)

Unit tests require a CLOUDINARY_URL in the environment or a .env file; any syntactically valid value works for mocked tests: CLOUDINARY_URL=cloudinary://key:secret@test-cloud.

Testing

• test/unit/ is mocked and must never perform network calls.
• test/integration/ requires a real or temporary Cloudinary environment; do not run it by default and do not add tests there that consume paid add-ons without a skip guard.
• Nondeterministic AI output (captions, tags, moderation verdicts) must be asserted by request shape, state transition, and response schema — never by exact output values.

Project structure

• cloudinary.js — package entry point; exposes the legacy v1 API and require('cloudinary').v2.
• lib/ — implementation. lib/v2/ wraps the v1 modules with promise support.
• lib/analysis/ — Analyze API (analyze_uri).
• types/index.d.ts — TypeScript declarations, tested by npm run dtslint.
• examples/ — small, runnable task examples shipped in the npm package.
• docs/ — version-matched Markdown docs shipped in the npm package.
• samples/ — legacy full applications; not part of the tested example set.
• test/ — unit/, integration/, shared helpers in spechelper.js and testUtils/.
• tools/scripts/ — shell entry points used by the npm scripts.

Code style

• CommonJS modules, ES6+ syntax, two-space indent; eslint config is authoritative.
• Public API methods accept an options object and an optional Node-style callback and return a Promise, following the existing pattern: