Developer Integration API by Arukuen · Pull Request #67 · gambitph/Cimo

Arukuen · 2026-07-21T08:20:06Z

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 to optimize files before upload.
- Automatically optimizes files from configured selection fields and drag-and-drop areas.
- Added configurable interception “allowed locations” to control which upload areas are handled.
- Premium conversion is now enabled by default.
Documentation
- Added WordPress integration guidance, including how to enqueue assets, use the browser API, configure interception selectors, and the current optimization limitations/behavior.

coderabbitai · 2026-07-21T08:20:30Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 4ff76a79-84bd-4241-a928-1ada6616d072

📥 Commits

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

📒 Files selected for processing (2)

DEVELOPER.md
src/admin/js/public-api.js

🚧 Files skipped from review as they are similar to previous changes (2)

src/admin/js/public-api.js
DEVELOPER.md

📝 Walkthrough

Walkthrough

Cimo adds 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, with integration guidance 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

Possibly related PRs

gambitph/Cimo#19: Overlaps with drop-zone handling and allowed-location matching.
gambitph/Cimo#34: Overlaps with converter results and the upload optimization pipeline.
gambitph/Cimo#38: Overlaps with the disable-optimization behavior in the upload interception paths.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is concise and accurately describes the main change: a developer integration API for Cimo.
Linked Issues check	✅ Passed	The PR implements the public optimizeFiles API, selector filters, enqueue helper, shared interceptors, and docs required by `#65`.
Out of Scope Changes check	✅ Passed	The changes stay focused on developer integration, with no clear unrelated feature work beyond the requested API and docs.
Docstring Coverage	✅ Passed	Docstring coverage is 87.50% which is sufficient. The required threshold is 80.00%.

✨ 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

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

github-actions · 2026-07-21T08:21:38Z

🤖 Pull request artifacts

file	commit
`pr67-cimo-67-merge.zip`	`cff1995`

Pull request: #67 Commit: 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

Pull request: #67 Commit: cff1995

Arukuen added 4 commits July 21, 2026 13:08

fix: Public JS API — window.cimo.optimizeFiles

319afb3

fix: PHP filters for upload selectors

da41fb7

fix: Public enqueue helper — cimo_enqueue_assets()

0185b3d

chore: developer docs

89e4b77

github-actions Bot added a commit that referenced this pull request Jul 21, 2026

Upload pr67-cimo-67-merge.zip (89e4b)

fbe8c03

Pull request: #67 Commit: 89e4b77

coderabbitai Bot reviewed Jul 21, 2026

View reviewed changes

Comment thread DEVELOPER.md

Comment thread DEVELOPER.md

Comment thread src/admin/js/public-api.js

Arukuen changed the title ~~Feat/dev api~~ Developer Integration API Jul 22, 2026

chore: dev docs and clearer comment

cff1995

github-actions Bot added a commit that referenced this pull request Jul 22, 2026

Upload pr67-cimo-67-merge.zip (cff19)

6af8629

Pull request: #67 Commit: cff1995

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Developer Integration API#67

Developer Integration API#67
Arukuen wants to merge 5 commits into
developfrom
feat/dev-api

Arukuen commented Jul 21, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jul 21, 2026 •

edited

Loading

Walkthrough

Changes

Sequence Diagram(s)

Uh oh!

github-actions Bot commented Jul 21, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

Arukuen commented Jul 21, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

How To Test

1. Test Frontend Enqueue

2. Test PHP Selector Filters

3. Test Automatic File Input Interception

4. Test window.cimo.optimizeFiles

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

Uh oh!

github-actions Bot commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🤖 Pull request artifacts

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Arukuen commented Jul 21, 2026 •

edited by coderabbitai Bot

Loading

4. Test `window.cimo.optimizeFiles`

coderabbitai Bot commented Jul 21, 2026 •

edited

Loading

github-actions Bot commented Jul 21, 2026 •

edited

Loading