diff --git a/.cursor/rules/cloudinary.mdc b/.cursor/rules/cloudinary.mdc new file mode 100644 index 0000000..71b1a6a --- /dev/null +++ b/.cursor/rules/cloudinary.mdc @@ -0,0 +1,13 @@ +--- +description: Cloudinary SAP Commerce Cloud (Hybris) integration — agent guide +alwaysApply: true +--- + +See [`AGENTS.md`](../../AGENTS.md) in the repo root for the full agent guide: what this suite is, the extension dependency graph, install/build with the Hybris `ant` toolchain (no CI), configuration via the `CloudinaryConfig` Backoffice item, and conventions/gotchas. + +Key points: +- This is Cloudinary's **SAP Commerce Cloud (Hybris)** integration — nine Hybris extensions installed into a licensed SAP Commerce platform, not an SDK or registry package. +- `cloudinarymediacore` is the root extension; facades sit on core; addons/OCC/web services sit on facades. +- Credentials aren't properties — they're set on the `CloudinaryConfig` item (`cloudinaryURL` field) via Backoffice. +- The Cloudinary Java SDK (1.29.0) is vendored as jars in `cloudinarymediacore/lib/`, not pulled from Maven. Java 21. Package root `uk.ptr.cloudinary`. +- There's no CI — build with `ant clean all` / `ant updatesystem` inside the licensed platform. diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..1098cb1 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,10 @@ +# GitHub Copilot instructions — cloudinary_sap_commerce + +See [`AGENTS.md`](../AGENTS.md) in the repo root for the full agent guide: what this suite is, the extension dependency graph, install/build with the Hybris `ant` toolchain (no CI), configuration via the `CloudinaryConfig` Backoffice item, and conventions/gotchas. + +Key points: +- This is Cloudinary's **SAP Commerce Cloud (Hybris)** integration — nine Hybris extensions installed into a licensed SAP Commerce platform, not an SDK or registry package. +- `cloudinarymediacore` is the root extension; facades sit on core; addons/OCC/web services sit on facades. +- Credentials aren't properties — they're set on the `CloudinaryConfig` item (`cloudinaryURL` field) via Backoffice. +- The Cloudinary Java SDK (1.29.0) is vendored as jars in `cloudinarymediacore/lib/`, not pulled from Maven. Java 21. Package root `uk.ptr.cloudinary`. +- There's no CI — build with `ant clean all` / `ant updatesystem` inside the licensed platform. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..0b2572a --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,69 @@ +# AGENTS.md — cloudinary_sap_commerce + +## What this is (one line) +Cloudinary's integration for SAP Commerce Cloud (Hybris): a suite of nine Hybris extensions (Java + ImpEx + Spring), plus Backoffice, SmartEdit, OCC, and Spartacus pieces, that offloads product/content image and video storage, transformation, optimization, and CDN delivery to Cloudinary. It installs into a licensed SAP Commerce project — it is **not** an SDK or a package you install from Maven/npm. The Java package root for every extension is `uk.ptr.cloudinary` (originally partner-built, PTR). + +## When to use / when NOT to use +- **Use this when:** the target is an **SAP Commerce Cloud (Hybris)** storefront (B2C accelerator, B2B accelerator, or Spartacus composable) that should manage and deliver media through Cloudinary. Extensions get added to `localextensions.xml` and built with the Hybris `ant` toolchain; credentials are set on the `CloudinaryConfig` Backoffice item. +- **Do NOT use this when:** you're building a **custom Java application** that isn't a Hybris project — use [`cloudinary_java`](https://github.com/cloudinary/cloudinary_java) directly (this suite vendors it as jars). For other commerce platforms use the sibling repo below. +- **Siblings:** [`cloudinary_magento2`](https://github.com/cloudinary/cloudinary_magento2) (Magento/Adobe Commerce), [`cloudinary_wordpress`](https://github.com/cloudinary/cloudinary_wordpress) (WordPress/WooCommerce), [`cloudinary_sfcc_site_cartridge`](https://github.com/cloudinary/cloudinary_sfcc_site_cartridge) (Salesforce Commerce Cloud). Agent/no-code path: [Cloudinary MCP servers](https://github.com/cloudinary/mcp-servers). + +## Extension dependency graph (verified against extensioninfo.xml) +All nine live under `ext-cloudinary/cloudinary/`. `cloudinarymediacore` is the root for every extension except the two SmartEdit extensions (`cloudinarymediasmartedit`, `cloudinarymediab2bsmartedit`), which require only the platform `smartedit`/`cmsfacades`/`smartedittools` modules, not core. + +``` +cloudinarymediacore (requires commerceservices, mediaconversion, acceleratorservices) +├── cloudinarymediafacades (requires cloudinarymediacore, acceleratorfacades) +│ ├── cloudinarymediaaddon (B2C storefront AddOn; + acceleratorstorefrontcommons, addonsupport) +│ ├── cloudinarymediab2baddon (B2B storefront AddOn; + acceleratorstorefrontcommons, addonsupport) +│ ├── cloudinarymediaocc (OCC REST for Spartacus; + commercewebservices, cmsocc) +│ └── cloudinarymediawebservices(CMS OCC web services; + webservicescommons, cmsocc, cloudinarymediacore) +├── cloudinarymediabackoffice (Backoffice UI; + backoffice, mediaconversionbackoffice) +├── cloudinarymediasmartedit (B2C SmartEdit; requires smartedit, cmsfacades — not core) +└── cloudinarymediab2bsmartedit (B2B SmartEdit; requires smartedittools, smartedit — not core) +``` + +`cloudinarymediacore` holds the `CloudinaryConfig` item type, the Media/Product/Category attribute enrichment (`cloudinaryURL`, `cloudinaryPublicId`, `cloudinaryResourceType`, `cloudinaryFetchURL`, ...), the cron jobs (`cloudinaryMediaUploadSyncJob`, `cloudinaryMediaTransformationJob`, `cloudinaryMediaTagUpdateJob`), and the vendored Cloudinary Java SDK. The storefront addons hold **no** credentials. + +## Install / build +Nothing installs from a registry — these extensions drop into a **licensed** SAP Commerce platform. Two paths: + +- **Installer recipes:** `recipes/cloudinary_b2c.zip` / `recipes/cloudinary_b2b.zip` → unzip into `installer/recipes/`, then `./install.sh -r cloudinary_b2c`. +- **Manual:** add the extensions to `localextensions.xml` (reference: `ext-config/b2c/localextensions.xml`, `ext-config/b2b/localextensions.xml`), pointing a `` at the folder. Active B2C set: `cloudinarymediacore`, `cloudinarymediafacades`, `cloudinarymediabackoffice`, `cloudinarymediaaddon`, `cloudinarymediaocc`, `cloudinarymediab2bsmartedit`, `spartacussampledata`. Commented out: `cloudinarymediasmartedit`, `cloudinarymediawebservices`, `yb2bacceleratorstorefront`. + +Then the standard Hybris flow (run inside the platform): + +```bash +ant clean all # compile platform + extensions +ant addoninstall -Daddonnames="cloudinarymediaaddon" -DaddonStorefront.yacceleratorstorefront="yacceleratorstorefront" +ant updatesystem # or a HAC System Update, importing the cloudinary* project data +``` + +**There is no CI.** No `.github/workflows`, no GitHub Actions (verified: `contents/.github` → 404). Build/test is the Hybris `ant` toolchain (`ant all` / `ant unittests` / `ant integrationtests`), which needs the licensed SAP Commerce platform and can't run in plain CI. Committed build artifacts (`build/libs/*.jar`) are present in the repo. The Spartacus/Angular apps build separately with `ng build`. + +## Configuration +Credentials are **not** platform properties. They're stored in the DB on the `CloudinaryConfig` item type (`cloudinarymediacore-items.xml`), set through **Backoffice**: +- `cloudinaryURL` — the connection string `cloudinary://:@` (a stored property on `CloudinaryConfig`). Note: `Media.cloudinaryURL` is a *different*, same-named attribute — the per-asset delivery URL, computed by `cloudinaryUrlAttributeHandler` — don't conflate the two. +- `enableCloudinary`, `cloudinaryFolderPath`, `enableCloudinaryGalleryWidget`, `enableCloudinaryVideoPlayer`, plus global transformation/optimization fields. +- Spartacus reads config over OCC; the storefront's endpoint is set with the `cloudinary.config.url` property (`ext-config/b2c/local.properties`), pointing at `.../occ/v2//cloudinary/configuration`. + +Keep the `cloudinaryURL` value out of version control. + +## Conventions & gotchas +- **Package root `uk.ptr.cloudinary`** across every extension (PTR = the original partner author). OCC controllers live under `uk.ptr.cloudinary.occ`. +- **Cloudinary Java SDK is vendored, not Maven.** `cloudinarymediacore/lib/cloudinary-core-1.29.0.jar` and `cloudinary-http44-1.29.0.jar`. `cloudinarymediacore`, `cloudinarymediafacades`, `cloudinarymediabackoffice`, and `cloudinarymediawebservices` set `usemaven="false"` in `extensioninfo.xml`; the rest omit it (SAP defaults to non-Maven). No extension declares Maven dependencies — the SDK is the vendored jars above. `maven.compiler.release=21` (Java 21) where declared. +- **Committed build artifacts.** `build/libs/*.jar` and generated output are checked in — don't treat them as source, and don't hand-edit them. +- **Version tags are mixed.** Extensions carry tags from 2005.2 (core, addon, B2C SmartEdit) to 2211.37 (B2B SmartEdit); OCC and web services are 2211.25. Practically targets the SAP Commerce 2005–2211 accelerator lineage. +- **Spartacus/Angular pieces look partly scaffolded.** The reusable library under `Cloudinary Libraries/` documents `npm install @your-org/cloudinary-spartacus` — a placeholder scope, not a published package — and the Angular/Spartacus version numbers (`@angular/core ^21.2.6`, `@spartacus ~221121.x`) are non-standard and internally inconsistent with the demo store's README (Angular CLI 19.2.11). Treat the composable-storefront path as immature and verify before relying on it. +- **License: MIT** (`Copyright (c) 2020 cloudinary-labs`). Keep new files MIT-compatible. + +## Canonical docs +- Cloudinary documentation: https://cloudinary.com/documentation +- Transformation & API references: https://cloudinary.com/documentation/cloudinary_references +- Cloudinary Java SDK (vendored dependency): https://github.com/cloudinary/cloudinary_java +- MCP servers (agent/no-code path): https://github.com/cloudinary/mcp-servers + +## Commit / PR conventions +- Branch off and PR against `main` (default branch). +- There's no CI gate — verify by building in a real SAP Commerce platform (`ant clean all`, then `ant updatesystem` / a HAC System Update) and exercising the storefront/Backoffice change manually. +- Keep the vendored SDK jar version and each extension's declared version consistent when bumping. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..c92fbac --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,35 @@ +@AGENTS.md + +# CLAUDE.md — cloudinary_sap_commerce + +## Claude Code-specific notes + +**Primary reference:** `AGENTS.md` (imported above) covers the extension dependency graph, install/build, config, and gotchas. Read it before touching any file. + +## What this repo is + +Cloudinary's **SAP Commerce Cloud (Hybris)** integration — a suite of nine Hybris extensions (Java + ImpEx + Spring) plus Backoffice, SmartEdit, OCC, and Spartacus pieces, installed into a **licensed** SAP Commerce platform. It's not an SDK or a registry package. Point custom-Java-app builders to `cloudinary_java` (which this suite vendors as jars) instead. + +## Key constraints + +- **`cloudinarymediacore` is the root.** facades → core; addons/OCC/web services → facades; Backoffice/SmartEdit → core/smartedit. See the dependency graph in `AGENTS.md`. Nothing works without core. +- **Credentials aren't properties.** They live in the DB on the `CloudinaryConfig` item type, set via Backoffice; the field is `cloudinaryURL` = `cloudinary://:@`. Never look for `cloud_name`/`api_key` in `project.properties`. +- **Cloudinary Java SDK is vendored, not Maven.** `cloudinarymediacore/lib/cloudinary-core-1.29.0.jar` + `cloudinary-http44-1.29.0.jar`. All extensions are `usemaven="false"`, Java 21 (`maven.compiler.release=21`). +- **Package root is `uk.ptr.cloudinary`** for every extension. +- **No CI exists.** No `.github/workflows`. Build is the Hybris `ant` toolchain inside the licensed platform — don't invent CI commands or claim tests run in GitHub Actions. Committed `build/libs/*.jar` artifacts are present; don't hand-edit them. +- **Version tags are mixed** (2005.2 to 2211.37); the suite targets the SAP Commerce 2005–2211 accelerator lineage. +- **Spartacus/Angular pieces are partly scaffolded** (placeholder npm scope `@your-org/cloudinary-spartacus`, inconsistent Angular/Spartacus versions). Treat as immature; verify before relying on it. +- **Branch target:** `main`. License is **MIT**. + +## Install / build (no registry, no CI) + +```bash +# Recipe path (from a licensed SAP Commerce platform root): +# unzip recipes/cloudinary_b2c.zip into installer/recipes/, then: +./install.sh -r cloudinary_b2c + +# Manual path — add extensions to localextensions.xml (see ext-config/b2c/localextensions.xml), then: +ant clean all +ant addoninstall -Daddonnames="cloudinarymediaaddon" -DaddonStorefront.yacceleratorstorefront="yacceleratorstorefront" +ant updatesystem # or a HAC System Update, importing the cloudinary* project data +``` diff --git a/README.md b/README.md index 572b982..bf7b225 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,85 @@ -Cloudinary -========== -Cloudinary is a cloud-based service that provides solutions for image and video management, including server or client-side upload, on-the-fly image and video transformations, quick CDN delivery, and a variety of asset management options. +# Cloudinary SAP Commerce Cloud integration -The SAP Commerce Cloudinary Extension provides rich features such as media management, transformations, optimizations and advanced delivery features exposed via the SAP Commerce platform with a plug and play integrated extension. +[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE) -## Get your Cloudinary account information ###################################################################### -If you don’t have a Cloudinary account, sign up for a [free account](https://cloudinary.com/users/register/free) so you can try out image and video transformations and seamless delivery through CDN. -Get your cloudname, api_key and api_secret from your Cloudinary account [as described here](https://cloudinary.com/documentation/how_to_integrate_cloudinary#account_details). +A Cloudinary media-management and delivery integration for SAP Commerce Cloud (Hybris), shipped as a suite of Hybris extensions (Java + ImpEx + Spring) with Backoffice, SmartEdit, OCC, and Spartacus pieces. It offloads product and content image and video storage, transformation, optimization, and CDN delivery to Cloudinary across the B2C and B2B accelerator storefronts and the composable (Spartacus) storefront. The extensions target the SAP Commerce 2005–2211 accelerator lineage (extension version tags range from 2005.2 to 2211.37), build against Java 21, and bundle the Cloudinary Java SDK 1.29.0 as vendored jars in `cloudinarymediacore/lib/`. It installs into a licensed SAP Commerce project — it isn't a standalone application or a Maven/npm package. -## Additional resources ########################################################## +## Extensions -Additional resources are available at: +The nine Cloudinary Hybris extensions live under `ext-cloudinary/cloudinary/`. `cloudinarymediacore` is the base; facades sit on core; the storefront addons, OCC, and web services sit on facades; Backoffice sits on core. The two SmartEdit extensions are the exception — they sit on the platform `smartedit`/`cmsfacades` modules, not on core. Every extension except the SmartEdit pair transitively requires core. -* [Cloudinary Website](https://cloudinary.com) -* [Cloudinary Documentation](https://cloudinary.com/documentation) -* [Knowledge Base](https://support.cloudinary.com/hc/en-us) -* [Video transformations documentation](https://cloudinary.com/documentation/video_manipulation_and_delivery) -* [Image transformations documentation](https://cloudinary.com/documentation/image_transformations) +| Extension | Purpose | Requires | +|---|---|---| +| `cloudinarymediacore` | Base services extension: defines the `CloudinaryConfig` item type (credentials + global transformation/optimization settings), enriches Media/Product/Category with Cloudinary attributes, ships the upload-sync / transformation / tag-update cron jobs, and vendors the Cloudinary Java SDK jars. | `commerceservices`, `mediaconversion`, `acceleratorservices` | +| `cloudinarymediafacades` | Facade layer over core — exposes Cloudinary config and media data to storefront and OCC controllers. | `cloudinarymediacore`, `acceleratorfacades` | +| `cloudinarymediaaddon` | B2C accelerator storefront AddOn: Cloudinary gallery, video, product carousel, variant selector, and responsive product-image JSP tags/CMS components. Holds no credentials. | `cloudinarymediafacades`, `acceleratorstorefrontcommons`, `addonsupport` | +| `cloudinarymediab2baddon` | B2B equivalent of the addon for the `yb2bacceleratorstorefront`. | `cloudinarymediafacades`, `acceleratorstorefrontcommons`, `addonsupport` | +| `cloudinarymediabackoffice` | Backoffice integration — the Cloudinary upload widget / media selector and the admin UI where merchandisers manage Cloudinary media and the `CloudinaryConfig` settings. | `backoffice`, `cloudinarymediacore`, `mediaconversionbackoffice` | +| `cloudinarymediasmartedit` | SmartEdit in-context editing for B2C — a Cloudinary media container field / media selector. | `smartedit`, `cmsfacades` | +| `cloudinarymediab2bsmartedit` | SmartEdit media file selector app for B2B (Angular/TS). Version tag 2211.37 (newest). | `smartedittools`, `smartedit` | +| `cloudinarymediaocc` | OCC REST layer for headless/Spartacus — exposes Cloudinary config (cloud name, gallery config, flags) to the composable storefront. | `commercewebservices`, `cloudinarymediafacades`, `cmsocc` | +| `cloudinarymediawebservices` | CMS OCC web services around Cloudinary media and config. | `webservicescommons`, `cloudinarymediafacades`, `cmsocc`, `cloudinarymediacore` | -## Support +The repo also ships `spartacussampledata` (demo sample data) and a customized `yb2bacceleratorstorefront` at the repo root for the B2B demo, plus Spartacus demo stores and a reusable Angular library under `Cloudinary Libraries/` and `spartacus/`. -Contact us [https://cloudinary.com/contact](https://cloudinary.com/contact). +## Installation -Stay tuned for updates, tips and tutorials: [Blog](https://cloudinary.com/blog), [Twitter](https://twitter.com/cloudinary), [Facebook](https://www.facebook.com/Cloudinary). +These extensions install into an existing, licensed SAP Commerce platform — there's no package to download from a registry. Two paths: -## Join the Community ########################################################## +**Installer recipes.** The repo ships SAP Commerce Cloud installer recipes as `recipes/cloudinary_b2c.zip` and `recipes/cloudinary_b2b.zip`. Unzip the one you want into your platform's `installer/recipes/`, then run the installer from the platform root: -Impact the product, hear updates, test drive new features and more! Join [here](https://www.facebook.com/groups/CloudinaryCommunity). \ No newline at end of file +```bash +./install.sh -r cloudinary_b2c +``` + +**Manual wiring.** Add the extensions to your `localextensions.xml`, using `ext-config/b2c/localextensions.xml` (or `ext-config/b2b/localextensions.xml`) as the reference list. Point a `` at the extensions folder, then declare each extension. The active B2C set is: + +```xml + + + + + + +``` + +`cloudinarymediasmartedit` and `cloudinarymediawebservices` ship commented out in the reference list — enable them if you need B2C SmartEdit or the CMS OCC web services. + +Then build and initialize the platform: + +```bash +ant clean all # compile the platform with the Cloudinary extensions +ant addoninstall -Daddonnames="cloudinarymediaaddon" -DaddonStorefront.yacceleratorstorefront="yacceleratorstorefront" +ant updatesystem # or run a System Update in the HAC, importing the cloudinary* project data +``` + +`ant addoninstall` wires the storefront AddOn into your accelerator storefront (use `cloudinarymediab2baddon` and your B2B storefront for B2B). The ImpEx sample data for each addon lives under its `resources/.../import`. The Spartacus/Angular apps under `spartacus/` build separately with `ng build`. + +## Configuration + +Cloudinary credentials aren't platform properties — they're stored in the database on the `CloudinaryConfig` item type (defined in `cloudinarymediacore-items.xml`) and set through Backoffice. The credential field is `cloudinaryURL`, which takes your Cloudinary connection string in the `cloudinary://:@` format (the `CLOUDINARY_URL` value from the [Cloudinary Console](https://console.cloudinary.com/)). + +Related fields on the same item include `enableCloudinary`, `cloudinaryFolderPath`, `enableCloudinaryGalleryWidget`, and `enableCloudinaryVideoPlayer`, plus the global transformation/optimization settings. Because the credential lives in the database, keep it out of version control. + +For the composable (Spartacus) storefront, the OCC endpoint the storefront reads config from is set with the `cloudinary.config.url` property (in `ext-config/b2c/local.properties` it points at `.../occ/v2//cloudinary/configuration`). + +## For AI agents + +This repo is Cloudinary's integration for SAP Commerce Cloud (Hybris) — a suite of Java/ImpEx/Spring extensions installed into a licensed SAP Commerce project, not a general-purpose SDK. For a different platform or a direct-code path, route to the right repo: + +| Target platform | Repo | +|---|---| +| Magento 2 / Adobe Commerce | [`cloudinary_magento2`](https://github.com/cloudinary/cloudinary_magento2) | +| WordPress / WooCommerce | [`cloudinary_wordpress`](https://github.com/cloudinary/cloudinary_wordpress) | +| Salesforce Commerce Cloud | [`cloudinary_sfcc_site_cartridge`](https://github.com/cloudinary/cloudinary_sfcc_site_cartridge) | +| A custom Java application | [`cloudinary_java`](https://github.com/cloudinary/cloudinary_java) — the SDK this suite vendors | +| Cloudinary operations as agent tools | [Cloudinary MCP servers](https://github.com/cloudinary/mcp-servers) | + +## Links + +- [Repository](https://github.com/cloudinary/cloudinary_sap_commerce) +- [Cloudinary documentation](https://cloudinary.com/documentation) +- [Transformation and API references](https://cloudinary.com/documentation/cloudinary_references) +- [Documentation llms.txt index](https://cloudinary.com/documentation/llms.txt) + +Released under the MIT license.