Bring coffee details into MyBrewFolio

Opening a Bean link shows a public preview; it does not save anything. The visitor chooses Add to own library to import a copy. Guests are invited to sign in or create an account and return to the preview to confirm.

If the Bean is already in the library, the visitor can open the existing Bean or merge missing details. Existing values are protected. There is no automatic import option.

You can also create a link in MyBrewFolio: choose Copy Bean link from the action menu in the library or Bean Details. Export Bean JSON in the same menu provides a file instead.

1. Create one versioned Bean JSON object with a name and any supported product details you know. Omit unknown details.
2. Serialize the entire object and encode it with encodeURIComponent. Append it after #bean= at https://mybrewfolio.com/beans/import.
3. Offer the resulting URL as a link or button. Check the fragment length and offer the same JSON as a .json file when the link is too long.

const payload = {
  format: 'mybrewfolio-bean',
  version: 1,
  exportedAt: new Date().toISOString(), // e.g. 2026-01-01T00:00:00.000Z
  bean: {
    name: 'Example Coffee',
    roaster: 'Example Roaster',
    details: { origins: [{ country: 'Ethiopia' }] },
  },
};
const fragment = '#bean=' + encodeURIComponent(JSON.stringify(payload));
if (fragment.length > 16384) throw new Error('Offer a Bean JSON file instead');
const link = 'https://mybrewfolio.com/beans/import' + fragment;

The outer object must contain format: "mybrewfolio-bean", version: 1, a valid date string exportedAt, and a bean object. The bean requires a non-empty name and a details object, which may be empty. roaster is optional. Name and roaster are trimmed and limited to 200 characters each; exportedAt is limited to 40 characters. Do not add other keys to the wrapper or bean.

Every field in details is optional. Use these exact, case-sensitive keys and enum values; omit unsupported or unknown fields. Text is trimmed. Numeric values must be finite and between 0 and 1,000,000,000, or null; cuppingPoints has a maximum of 100.

For each coffee component, put Arabica or Robusta in its origins entry’s variety text. When both species and a more specific variety are supported, use a value such as "Arabica - Bourbon". Use percentage for that entry’s share of the whole coffee as a number from 0 to 100, without a percent sign. beanType describes single-origin or blend; Arabica alone does not imply either. Do not add a species field.

Assign country and other origin details to the same component only when supported. Do not guess species, shares or countries; omit what is unknown. Do not duplicate known origin entries with a separate generic species breakdown when the association cannot be established. For a blend where only the species shares are known:

{
  "origins": [
    { "variety": "Arabica", "percentage": 80 },
    { "variety": "Robusta", "percentage": 20 }
  ]
}

The encoded fragment including #bean= may contain at most 16,384 characters. Some clients allow shorter URLs. For those cases, offer the same versioned object as a .json file, which can be imported in MyBrewFolio. Bean JSON is limited to 1 MB, and saved details to 50 KB.

Origins allow up to 20 entries and flavors up to 100. Origin text, roastCustom and each flavor allow 500 characters; aromatics, note and cupping notes allow 5,000. url allows 2,000, ean 100, and dates 40. Unsupported keys, invalid values and oversized or incomplete links produce an error rather than an import.

A link contains a snapshot of product details, not a reference to a private library entry. Later edits or deletion do not update or revoke it. Anyone with the link can read its contents, so include only information you intend to share.

The URL fragment is not sent in the page’s HTTP request, but it is part of the copied URL and may remain in browser history. Images and private library values such as personal rating, cost, status, storage and grind history are excluded.

This integration uses a portable link and an explicit user import; it does not define a public write API contract.