feat: added Zod schema for the effects array in the overlay schema

[nickytonline]

Description

This PR adds the effect schema to the effects property of an overlay. Prior to the change, it was an empty object.

It was mentioned in #169 to update the effects with radius into main/packages/url-loader/src/constants/qualifiers.ts#L90, but the radius schema is already in there.

From what I can tell, only the overlay schema needed to be updated. Side note, but this doesn't just fix the issue with radius not being found, but adds all the available effects settings to the overlay effects array schema. I'm assuming that all effects are available in an overlay @colbyfayock, or is it only a subset of effects that are available to overlays?

~I marked this as a breaking change in case anyone using the cloudinary-util package has a value which is not in the newly introduced Zod enum, as previously it was any string. If that is the case, that gravity option probably never worked for them, but just erring on the safe side for a release.~

I haven't made any documentation updates here as there does not appear to be any docs related to the options including gravity, but if there is a separate repository that requires a documentation update, happy to make changes there as well.

Issue Ticket Number

Closes #169

Type of change

• [ ] Bug fix (non-breaking change which fixes an issue)
• [x] New feature (non-breaking change which adds functionality)
• [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
• [ ] Fix or improve the documentation
• [ ] This change requires a documentation update

Checklist

• [x] I have followed the contributing guidelines of this project as mentioned in CONTRIBUTING.md
• [x] I have created an issue ticket for this PR
• [x] I have checked to ensure there aren't other open Pull Requests for the same update/change?
• [x] I have performed a self-review of my own code
• [x] I have run tests locally to ensure they all pass
• [x] I have commented my code, particularly in hard-to-understand areas
• [x] I have made corresponding changes needed to the documentation

[nickytonline]

I've run the build and tests locally, but just wondering if I need to pnpm link into a project like the getCldOgImageUrl to test, or is the test suite here good enough to confirm the fix?

[colbyfayock]

thanks @nickytonline - yeah the docs will be autogenerated from the zod schema, it may not fully expose it yet, but that's the WIP goal

the overlay effects options are a bit complicated, it accepts a lot of different options: https://github.com/cloudinary-community/cloudinary-util/blob/main/packages/url-loader/src/plugins/overlays.ts#L196-L199

there's also the option of passing in text effects: https://github.com/cloudinary-community/cloudinary-util/blob/main/packages/url-loader/src/plugins/overlays.ts#L311

it may be worth doing something similar to what we did with Gravity, where we configure it so that we can expose all of the available options, but allow someone to free add options, at least for now to avoid over-restricting, until we're more confident everything is covered

i need rework some of that code, both the overlay code itself and ive been slowly reworking how some of hte parameters are organized and managed, but its not a high priority at the moment

got some community input on the breaking change aspect as my instincts were that this shouldnt be a breaking change as it's really fixing a type that isn't accurate

https://x.com/colbyfayock/status/1825542769412297144

few particular points:

IMO allowing an invalid input is a types bug, so this would be ok as a patch release. https://x.com/JoshuaKGoldberg/status/1825546401465729187

I would say it’s a bug fix. The user should not have passed the invalid option and is helped by TypeScript now showing an error. https://x.com/remcohaszing/status/1825565394805063989

the previous path was silently failing, and the type wasn’t helping. Notice that changing the type helps someone fix the runtime bug. https://x.com/chriskrycho/status/1825573173380686035

[colbyfayock]

hey @nickytonline i feel like i saw a comment come across but i can't find it. did you have any thoughts on my notes about the type?

[nickytonline]

I think I had one in draft. I think the same approach as the previous PR makes sense.

[colbyfayock]

sounds good, did you want to do that, or did you want me to?

[nickytonline]

I'm a little busy with work atm, so go for it.

[nickytonline]

Going to close this since you've taken over.