Developer Integration API

[Arukuen]

fixes #65

Adds developer integration support for Cimo pre-upload optimization.

• Exposes window.cimo.optimizeFiles(files, { showProgress }) so plugins/themes can optimize File / FileList objects before running their own upload flow.
• Adds PHP selector filters so third-party upload UIs can opt into Cimo’s automatic file-input/drop-zone interception.
• Adds cimo_enqueue_assets() so custom frontend or non-standard screens can explicitly load Cimo assets.
• Adds DEVELOPER.md with integration examples and behavior notes.
  Behavior

How To Test

1. Test Frontend Enqueue

In a custom PHP plugin, enqueue Cimo assets on a frontend page:

add_action( 'wp_enqueue_scripts', function () {
	if ( function_exists( 'cimo_enqueue_assets' ) ) {
		cimo_enqueue_assets();
	}
} );

Visit the frontend page and run this in the browser console:

console.log(window.cimoSettings);
console.log(window.cimo);
console.log(window.cimo?.optimizeFiles);

Expected:

• window.cimoSettings is available.
• window.cimo is available.
• window.cimo.optimizeFiles is a function.

2. Test PHP Selector Filters

In the custom PHP plugin, add selector locations:

add_filter( 'cimo/select_files/allowed_locations', function ( $locations ) {
	$locations[] = '.my-plugin-uploader';
	return $locations;
} );

add_filter( 'cimo/drop_zone/allowed_locations', function ( $locations ) {
	$locations[] = '.my-plugin-dropzone';
	return $locations;
} );

Visit the frontend page and run:

console.log(window.cimoSettings.selectFilesAllowedLocations);
console.log(window.cimoSettings.dropZoneAllowedLocations);

Expected:

• window.cimoSettings.selectFilesAllowedLocations includes .my-plugin-uploader.
• window.cimoSettings.dropZoneAllowedLocations includes .my-plugin-dropzone.

3. Test Automatic File Input Interception

Add this Custom HTML to the frontend page:

<div class="my-plugin-uploader">
	<input type="file" accept="image/*" />
</div>

Select an image from the input.

Expected:

• Cimo intercepts the file input because .my-plugin-uploader was added through the PHP filter.
• The image should be converted to webp.

4. Test window.cimo.optimizeFiles

Run this in the frontend browser console:

(async () => {
	const input = document.createElement('input');
	input.type = 'file';
	input.accept = 'image/*';

	input.onchange = async () => {
		const results = await window.cimo.optimizeFiles(input.files, {
			showProgress: true,
		});

		console.log('Optimized results:', results);

		console.table(results.map(({ file, metadata }) => ({
			name: file.name,
			type: file.type,
			size: file.size,
			hasMetadata: !!metadata,
		})));
	};

	input.click();
})();

Expected:

• Cimo opens the progress modal when applicable (large image).
• results is an array of { file, metadata }.
• Upload code should use results.map(result => result.file).

Summary by CodeRabbit

• New Features
  • Added a public browser API for optimizing files before upload.
  • Added support for automatically optimizing files selected through configured upload fields and drag-and-drop areas.
  • Added configurable selector locations for controlling which upload areas are intercepted.
  • Premium conversion support is now enabled by default.
• Documentation
  • Added WordPress integration guidance, API usage examples, configuration options, supported inputs, and current limitations.

[coderabbitai]

📝 Walkthrough

Walkthrough

Cimo now provides a frontend enqueue helper, a window.cimo.optimizeFiles() API, PHP-configurable selector interception, and shared optimization handling for direct and intercepted uploads. The default build is premium, and developer integration guidance is documented in DEVELOPER.md.

Changes

Developer integration

Layer / File(s)	Summary
PHP integration and selector localization cimo.php, src/admin/class-script-loader.php	Adds cimo_enqueue_assets(), changes the default CIMO_BUILD to premium, and localizes filtered, sanitized file-input and drop-zone selector lists.
Shared optimization pipeline and public API src/admin/js/optimize-files.js, src/admin/js/public-api.js, src/admin/js/index.js	Adds shared file optimization with conversion, metadata persistence, progress handling, cancellation, and bypass behavior, then exposes it as window.cimo.optimizeFiles.
Selector matching and interceptor integration src/admin/js/media-manager/allowed-locations.js, src/admin/js/media-manager/select-files.js, src/admin/js/media-manager/drop-zone.js	Centralizes selector normalization and matching, and routes file selection and drop-zone processing through the shared optimization helper.
Integration documentation DEVELOPER.md	Documents enqueueing, the public optimization API, selector filters, free and premium behavior, and pre-upload limitations.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Integrator
  participant window.cimo.optimizeFiles
  participant optimizeFileConverters
  participant UploadControl
  Integrator->>window.cimo.optimizeFiles: provide files before upload
  window.cimo.optimizeFiles->>optimizeFileConverters: resolve converters and optimize
  optimizeFileConverters-->>window.cimo.optimizeFiles: optimized files and metadata
  window.cimo.optimizeFiles-->>Integrator: return results
  Integrator->>UploadControl: upload result files

Loading

Possibly related PRs

• gambitph/Cimo#19: Overlaps with the refactored drop-zone handling and allowed-location matching.
• gambitph/Cimo#25: Also changes selector computation and upload interception in the file-selection and drop-zone handlers.
• gambitph/Cimo#34: Overlaps with converter selection and the shared upload optimization pipeline.

Suggested reviewers: bfintal

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The PR addresses #65 by adding optimizeFiles, selector filters, cimo_enqueue_assets(), and developer documentation.
Out of Scope Changes check	✅ Passed	No clearly unrelated changes are evident; the edits align with the developer API and documentation goals.
Docstring Coverage	✅ Passed	Docstring coverage is 87.50% which is sufficient. The required threshold is 80.00%.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title matches the PR’s main theme of adding a developer integration API.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/dev-api

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

🤖 Pull request artifacts

file	commit
pr67-cimo-67-merge.zip	89e4b77

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@DEVELOPER.md`:
- Around line 12-16: Update the documentation around the cimo_enqueue_assets
example to explicitly require registering selector filters before enqueueing
Cimo assets. Ensure the documented order places all selector filter registration
ahead of the wp_enqueue_scripts hook that calls cimo_enqueue_assets(), so
localized selectors use the custom values.
- Around line 24-28: Update the optimizeFiles example in DEVELOPER.md to wrap
the await and subsequent filesToUpload mapping in an async function, preserving
the existing behavior and making the snippet valid in a classic script.

In `@src/admin/js/public-api.js`:
- Around line 5-7: Update the comment above the public optimizeFiles assignment
to document that the API returns an array of objects shaped as {file, metadata},
with file as a File and metadata possibly null, rather than raw File objects.
Keep the window.cimo.optimizeFiles assignment unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b5658e52-1162-41c3-9c0c-12918c9f32c5

📥 Commits

Reviewing files that changed from the base of the PR and between 6041597 and 89e4b77.

📒 Files selected for processing (9)

• DEVELOPER.md
• cimo.php
• src/admin/class-script-loader.php
• src/admin/js/index.js
• src/admin/js/media-manager/allowed-locations.js
• src/admin/js/media-manager/drop-zone.js
• src/admin/js/media-manager/select-files.js
• src/admin/js/optimize-files.js
• src/admin/js/public-api.js