@uribbon/medusa-plugin

URibbon Product Content integration for Medusa v2 Admin. Version 0.1.0 is validated with Medusa 2.19.0.

Install

npm install @uribbon/medusa-plugin

Register

Register the plugin in your Medusa application's medusa-config.ts:

import { defineConfig } from "@medusajs/framework/utils"

module.exports = defineConfig({
  plugins: [
    {
      resolve: "@uribbon/medusa-plugin",
    },
  ],
})

Database migration

The plugin includes a persistent settings module. After installation and registration, run the normal Medusa migration command from your Medusa application:

npx medusa db:migrate

Configure

Open Settings → URibbon in Medusa Admin and configure:

• URibbon API URL
• API Key
• Default Brand
• Default language
• ProductInsights default

The plugin validates the connection server-side and retrieves only the Brands available to the API-key tenant. Supported language options come from the Medusa Store's configured locales.

If Medusa image URLs are not reachable from URibbon, the optional server environment variable URIBBON_PUBLIC_ASSET_BASE_URL can specify the externally reachable Medusa or CDN origin.

Product usage

On a product detail page:

1. Select the output language and generation options.
2. Choose Generate with URibbon.
3. Preview the generated title, short description, and full description.
4. Explicitly select which fields to apply.
5. Choose Apply to Product.

Generation does not update the product automatically. Apply remains limited to the selected base-product title, subtitle, and description fields. If the product changed after generation, the atomic stale-product check rejects Apply with HTTP 409 and URIBBON_PRODUCT_STALE.

Security

The API key is submitted to an authenticated Medusa Admin endpoint and stored server-side. Normal settings responses expose only whether a key is configured; the saved raw key is never returned to Medusa Admin or browser code.

Version 0.1.0 does not encrypt the API key at rest. Protect access to the Medusa database and backups accordingly.

Destination Content Contract

The plugin declares the content that its current Medusa destination path actually consumes. Contract v1 covers only URibbon productTitle, shortDescription, and fullDescription, which Apply maps to the Medusa product title, subtitle, and description.

Localized content capability uses the existing Medusa Store locale discovery; runtime locale values are not embedded in the static contract. Medusa operational fields—including price, inventory, currency, sales channels, product status, categories, collections, internal IDs, variants, and fulfillment, tax, or location data—remain Plugin and Medusa responsibilities and are excluded from Contract v1.

A future Draft Product importer may expand the destination contract under a later contract version. Ready-product retrieval and Draft Product import are not implemented in this phase.

When valid connection settings and an authorized Brand are saved, the plugin registers the current contract through POST /api/v1/integrations/destination-contracts. Registration uses the server-side API key and is not performed on Admin page loads. A newly created registration and an idempotent same-version/same-hash registration are both successful. URibbon rejects the same contract version with a different hash; the plugin does not change the contract version automatically.

Multilingual behavior in v0.1.0

• Supported Medusa Store locales are discovered by the plugin.
• The locale selected in the product widget is sent to URibbon unchanged as outputLanguage.
• URibbon supports full locale values such as fa-IR.
• Locale-specific Medusa Translation Module Apply is not implemented in v0.1.0.
• Apply continues to update the existing base-product fields rather than locale-specific translations.

Creating a Draft Product from an approved publication re-fetches the exact publication server-side and uses its stable Product Workspace identity for duplicate protection. ImportReceipt is not implemented yet, so a successfully created Draft may remain in Ready from URibbon; repeated creation returns the existing product instead of creating a duplicate.