Вышел Модуль интеграций 2.0 для MedusaЧитать анонс
K

Kit

Kit by Koda Plus (formerly ConvertKit): the newsletter of the store on the Kit list. The storefront form subscribes customers with tags and double opt-in, the admin shows the account, the list settings and the subscription log.

npm install @koda-plus/medusa-plugin-kit
Категория
Создано
Версия
0.2.2
Последнее обновление
5 дней назад
Ежемесячные загрузки
Загрузка данных

Kit by Koda Plus

The newsletter of a Medusa v2 store on Kit (kit.com, the e-mail marketing service formerly called ConvertKit). The storefront form subscribes customers straight into the store's Kit account, with tags and double opt-in; buyers who are already on the list get tags for what they bought; and the Medusa admin shows the account, the list in numbers, the newest broadcasts, the list settings and a log of every sign-up. The Kit API key never reaches a browser.

The plugin does not send newsletters itself and keeps no copy of the list: Kit stays the list and the sender, Medusa adds the subscribers and the tags.

What it does

  • The storefront form (): an e-mail address, and optionally a first name and a source, becomes a Kit subscriber with the tags of the settings. Kit's create is an upsert by e-mail and tagging answers 200 when the tag is already there, so a repeated sign-up changes nothing on the list: exactly once by construction.
  • Double opt-in: with the switch on, the subscriber is created in the state and added to the chosen double opt-in form, and Kit sends the confirmation e-mail. Without it the subscriber is at once.
  • Tags: picked in the admin from the account's tags, applied to every new subscriber.
  • Tags by source: the storefront sends a with each sign-up (for example for a "notify me about the next drop" button); a source configured in the admin adds its own tags to the general ones.
  • Tags for buyers (on ): an address that is ALREADY an active subscriber gets the buyer tags and, when switched on, one tag per bought product (created in Kit when missing, with a prefix set in the admin). An order never subscribes anyone: buying is not a newsletter consent.
  • The admin page (): the connection check, the list in numbers (active subscribers, growth over 30 and 90 days, open and click rates), the newest broadcasts with recipients, opens, clicks and unsubscribes, the list settings, tags by source and for buyers, the subscription log with every attempt, and a setup guide. The Kit numbers are read only and cached for ten minutes per process.
  • Works with Koda Plus hosts through the contract: the manifest, the customer summary (the subscriber's state in Kit) and the counter of failed sign-ups.

Requirements

  • Medusa 2.12 or newer (peer range ) and Node.js 20+.
  • A Kit account and a Kit API v4 key (Kit: Settings, Developer, API keys).
  • For double opt-in: a Kit embed form with double opt-in switched on. The plugin lists the account's embed forms.

Installation

Yarn and pnpm work the same way: or .

Configuration

Register the plugin in :

Run the migrations, then open Kit in the admin sidebar and click Check connection:

npx medusa db:migrate

The migration () adds two tables: (the subscription log) and (the list settings chosen in the admin).

Set the key in :

Without the plugin registers, the admin says "Not configured", the store route answers without an error and nothing reaches Kit. Missing or broken options never break the boot: broken values fall back to their defaults and the admin lists them as ignored.

Options

Every option is optional. Numbers and switches may come as strings, as environment variables do.

  • (default none): the Kit API v4 key. Sent only in the header to , never to the admin (which sees and the last 4 characters), masked in every log and error.
  • (default , or ): the default of the double opt-in switch. On, a new subscriber is created and added to the double opt-in form, which makes Kit send the confirmation e-mail. The admin switch overrides it.
  • (default none): the default double opt-in form, a Kit form id (a positive integer). Used only with double opt-in on; with double opt-in on and no form, the subscriber stays and Kit sends no confirmation, so choose one. The admin choice overrides it.
  • (default none): the default tags of every new subscriber, Kit tag ids as an array or a comma separated string (). Values that are not positive integers are ignored and listed. The admin choice overrides it.
  • (default none): the public address of the storefront, an http(s) address. Sent to Kit as the referrer when a subscriber is added to the double opt-in form.
  • (default ): a name for the store, shown in the admin with the options. This version does not send it to Kit; the source of a sign-up is the the storefront sends.
  • (default , 1 to 120): a self-imposed limit on the requests to Kit from one process. Kit allows 120 requests per rolling 60 seconds per key.
  • (default , 1000 to 60000): the timeout of one request to Kit.
  • (default , or ): demo mode, see Demo mode. It wins over .

The tags by source, the buyer tags, the product tags and their prefix have no option: they are chosen in the admin (Panel, Tags by source and for buyers) and kept in .

Setup in brief

The admin page has the same steps (Kit, then Setup guide).

  1. In Kit, open Settings, Developer, API keys, create a V4 API key and put it in on the backend.
  2. Create the tags for the store in Kit (Subscribers, Tags), for example and .
  3. For double opt-in, create an embed form in Kit with double opt-in switched on.
  4. Add the plugin to , run , open Kit in the admin and click Check connection.
  5. In the list settings pick the tags and the form, switch double opt-in, save.
  6. Optional: add tags by source (for each place of the storefront that sends a ) and tags for buyers.
  7. Put the form on the storefront (below) and sign a test address up; watch the subscription log.

The storefront form

  • (required): the address, lowercased before it is sent.
  • (optional): at most 80 characters.
  • (optional, default ): where the sign-up came from. It is written to the log, and when the admin has tags for this source (letters, digits, and , compared in lower case) they are added.

Answers:

  • : on the list and active; is true when the address was already there.
  • : created , Kit sends the confirmation e-mail of the form.
  • : the plugin has no key yet; show a neutral message.
  • : not an e-mail address, or Kit refused it.
  • : more than 5 sign-ups from one client IP in 10 minutes, or Kit is busy.
  • : Kit could not be reached.

The of the answers is in Polish, written for the shopper; show your own text by the status if your store speaks another language. A failing tag or form never loses the subscription: the subscriber is kept and the log says what Kit answered.

Tags for buyers

After the plugin reads the order's e-mail and products and asks Kit for the subscriber with that address. Only an subscriber is tagged: an address that is not on the list, or still waits for the confirmation, is left alone, and a canceled order is skipped. The buyer tags come from the admin; with product tags on, every product title becomes a tag (at most 120 characters, the prefix by default, at most 40 characters), created in Kit when missing. A repeated event changes nothing, since tagging an address twice is a no-op in Kit. The order never waits for Kit and never fails because of it: a failure is a warning in the server log and a failed row in the subscription log.

Admin API

Every route needs an admin session or token. Writes take a JSON body or the header (415 otherwise).

  • : the page in one read: whether the key is set, the ignored options, the options in use (the key masked), the account behind the key, the settings in effect and the counters of the subscription log.
  • : the live connection check: the account, its tags and forms. 400 without a key, 401 for a key Kit refuses.
  • : the account's tags, for the settings.
  • : the account's embed forms, with whether each one is double opt-in.
  • : the list settings in effect: , , , , , , .
  • : changes any of those fields; tag and form ids are checked against the account before they are saved (400 for an unknown id or a bad source name).
  • : the subscription log, newest first ( up to 100, default 25).
  • : the list in numbers: active subscribers, growth over 30 and 90 days, the e-mail stats of the last 90 days. Cached for ten minutes; asks Kit again.
  • : the newest broadcasts (drafts included) with recipients, open and click rates and unsubscribes; 1 to 20, default 10. Cached for ten minutes.
  • , , : the koda.integration/1 contract (below).

Store API

  • : the storefront form (see above). It needs Medusa's publishable API key, like every store route, and no customer login.

What it calls in Kit

Kit API v4 at , nothing else: , , , (by e-mail, and the total count), , , , ; (the upsert), (a product tag), (a tag) and (the double opt-in form). Errors are mapped to stable kinds (, , , , ); nothing is retried on its own.

Works with Koda Plus hosts

An app that shows every Koda Plus plugin in one place reads Kit through the shared contract :

  • : the manifest (mode in demo mode, with a key, without, the problem "no API key", entity ).
  • : one line for the customer: the subscriber's state in Kit, looked up by the customer's e-mail (active is green, waiting for the confirmation is orange, anything else grey; cancelled, bounced and complained count as failed).
  • : the counter (orange) of the last 7 days, linked to the Kit page.

Demo mode

Only on explicit request: . The plugin then works on a sample Kit account kept in the memory of the process and never calls Kit, even with an set:

  • the panel shows a Demo badge and a note, the connection check answers with the sample account, its tags and forms, and the list in numbers and the newest broadcasts are fixed sample values;
  • the store route and the buyer tags on run the real flow against the in-memory list (an address signed up once is "already there" the next time), and the log rows are real rows in ;
  • no e-mail goes out (Kit would send the double opt-in confirmation; the demo sends nothing), and the in-memory list is gone after a restart.

Without a key and without the plugin says "Not configured" and sends nothing.

Security and data

  • The API key travels only in the header to , never reaches the admin (it sees and the last 4 characters) and is masked in logs, stored errors and admin screens.
  • The public route is rate limited per client IP (5 sign-ups in 10 minutes, in the memory of each process; the first address of behind a proxy) and checks the address before anything reaches Kit.
  • Writes need the admin. Writes under take a JSON body or the header and answer 415 otherwise, so a form on another site cannot post with Medusa's session cookie. Every GET route only reads.
  • Consent: an order never subscribes anyone; buyer tags go only to addresses that are already active subscribers. With double opt-in on, nobody receives anything before confirming.
  • What the plugin keeps: the subscription log () keeps, for every attempt, the e-mail address, the first name, the Kit subscriber id, the state, the tag ids, the source, the outcome and a masked error. The address is stored in full and the log has no automatic retention: delete rows by hand when a person asks to be forgotten (and remove them in Kit). The settings table keeps tag ids, the form id and the switches.
  • The plugin changes nothing in Medusa: no customer, cart or order is written.

What this plugin does not do

  • It does not send newsletters or broadcasts: Kit does, from the Kit account.
  • It does not import the existing customers of the store into Kit, and it does not sync unsubscribes back to Medusa.
  • It does not subscribe anyone at checkout; a checkbox at checkout can call the store route.
  • It does not manage tags, forms or sequences in Kit, except creating a product tag that is missing.

Uninstall

  1. Remove the plugin from and the package from , and the form from the storefront.
  2. The tables and stay with their data. Drop them by hand when you no longer need them, or run before removing the package. The subscribers stay in Kit.

Compatibility

Medusa 2.12 or newer (peer range ) and Node.js 20+. The tests and the build run on Medusa 2.15.3. The admin libraries (, , , , , ) are optional peers: the plugin uses the copies of Medusa's dashboard. Developing the plugin needs Node.js 22.6+ (the tests run the TypeScript sources directly).

Development

Commercial support

Built and maintained by Koda Plus, a Medusa agency from Poland. Need the newsletter wired into your checkout, your customer accounts or another e-mail marketing service? Write to kontakt@koda.plus.

Trademarks

Kit, ConvertKit and Medusa are trademarks of their owners, used here only to identify the service this plugin connects to and the platform it runs on. This is an independent integration built on the public Kit API, not affiliated with or endorsed by Kit or Medusa.

License

MIT, see LICENSE.

Changelog

Every release is in CHANGELOG.md.

  • 0.2.0 (unreleased): the first release on npm. The storefront form with tags, tags by source and double opt-in, tags for buyers on , the admin page with the list in numbers and the broadcasts, the subscription log, the koda.integration/1 contract. It needs .