@hostwebhook/platform-node 0.2.0 → 0.3.0

package/dist/presets-de-oauth/linkedin-oauth-presets.js

@@ -0,0 +1,338 @@
+"use strict";
+/**
+ * LinkedIn OAuth 2.0 configuration for HostWebhook.
+ *
+ * LinkedIn's auth model is plain OAuth 2.0 (NOT PKCE) with a
+ * confidential client. No per-instance dance like Mastodon — single
+ * HW-wide registered app, env-var-driven client credentials.
+ *
+ * ## SON DOS APPS DE LINKEDIN, no una
+ *
+ * LinkedIn exige que **Community Management API sea el unico producto** de su
+ * aplicacion, «due to legal and security constraints». En una app que ya tenga
+ * Share o Sign In with LinkedIn, la opcion de pedirlo sale en gris; y donde ya
+ * esta concedido, activar OIDC lo deshabilita. No es un fallo de configuracion
+ * ni algo que se arregle insistiendo: son dos aplicaciones.
+ *
+ *   App MIEMBRO — https://www.linkedin.com/developers/apps
+ *     Products: "Sign In with LinkedIn using OpenID Connect" + "Share on
+ *     LinkedIn". Gratuitas y automaticas.
+ *     Da: openid, profile, email, w_member_social.
+ *     Sirve para: publicar en un perfil personal.
+ *     Env: LINKEDIN_OAUTH_CLIENT_ID / LINKEDIN_OAUTH_CLIENT_SECRET.
+ *
+ *   App PAGINA — otra aplicacion, creada limpia y SIN anadirle ningun otro
+ *     producto antes de pedirlo.
+ *     Products: "Community Management API", y nada mas. Pasa por revision.
+ *     Da: r_organization_social, w_organization_social, rw_organization_admin.
+ *     Sirve para: publicar como pagina Y SONDEAR sus posts (lo unico que
+ *     desbloquea el trigger).
+ *     Env: LINKEDIN_ORG_OAUTH_CLIENT_ID / LINKEDIN_ORG_OAUTH_CLIENT_SECRET.
+ *
+ * Las dos registran el MISMO redirect: `{API_URL}/api/credentials/linkedin/
+ * oauth/callback`. No hay ambiguedad al volver porque el `state` guardado en
+ * Redis dice de que app salio, y con el la pareja de credenciales correcta.
+ *
+ * ## Lo que NO tiene la app de pagina
+ *
+ * OIDC. Ahi no hay `openid`, asi que `/v2/userinfo` no se puede llamar y esa
+ * conexion no conoce a la persona: se identifica por las paginas que
+ * administra (`organizationAcls`). De ahi que `memberId` y `personUrn` sean
+ * opcionales — ver `LinkedInOAuthStoredAuth`.
+ *
+ * Token lifetime: 60 days (default). Refresh tokens optional and
+ * issued only when LinkedIn deems necessary — most HW deployments
+ * just persist the access token until expiry, then prompt reconnect.
+ *
+ * ## Las dos identidades
+ *
+ * Una credencial de LinkedIn representa **a quien se publica y a quien se
+ * sondea**, y eso puede ser una persona (`urn:li:person:{sub}`) o una pagina
+ * de empresa (`urn:li:organization:{id}`). Todo el provider ya trabajaba con
+ * un solo `authorUrn`, asi que la eleccion vive en la credencial y ni el nodo
+ * ni el trigger tienen que enterarse: cambiar de identidad es cambiar ese URN.
+ *
+ * La diferencia que importa esta en la LECTURA, no en la escritura:
+ *
+ *   - publicar como persona -> `w_member_social`, producto gratuito.
+ *   - publicar como pagina  -> `w_organization_social`, Community Management.
+ *   - LEER los posts propios de una persona -> `r_member_social`, que LinkedIn
+ *     describe como «restricted and available to approved users only» y no
+ *     esta concediendo. Por eso el trigger sobre un perfil personal no puede
+ *     funcionar por mucho que la app este bien montada.
+ *   - LEER los posts de una pagina -> `r_organization_social`, y ese SI se
+ *     concede via Community Management API.
+ *
+ * De ahi que el trigger sea una funcion de la identidad elegida y de los
+ * scopes concedidos, no de una tabla fija: si LinkedIn cambiara de criterio y
+ * concediera `r_member_social`, el perfil personal empieza a sondear solo, sin
+ * tocar una linea. Ver `pollBlockReason`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LINKEDIN_ORG_ADMIN_SCOPE = exports.LINKEDIN_ORG_WRITE_SCOPE = exports.LINKEDIN_ORG_READ_SCOPE = exports.LINKEDIN_MEMBER_READ_SCOPE = exports.LINKEDIN_REST_VERSION = exports.LINKEDIN_OAUTH_CONFIG = void 0;
+exports.resolveDefaultScopes = resolveDefaultScopes;
+exports.resolveOrgScopes = resolveOrgScopes;
+exports.appConfigFor = appConfigFor;
+exports.parseScopeList = parseScopeList;
+exports.authorKindOf = authorKindOf;
+exports.parseOrganizationAcls = parseOrganizationAcls;
+exports.personUrnOf = personUrnOf;
+exports.toOrganizations = toOrganizations;
+exports.pollBlockReason = pollBlockReason;
+exports.postBlockReason = postBlockReason;
+exports.LINKEDIN_OAUTH_CONFIG = {
+    authorizationEndpoint: 'https://www.linkedin.com/oauth/v2/authorization',
+    tokenEndpoint: 'https://www.linkedin.com/oauth/v2/accessToken',
+    /** OpenID Connect userinfo — returns sub (member id), name, email, etc. */
+    userInfoWebhook: 'https://api.linkedin.com/v2/userinfo',
+    /** Env var names holding HW's registered client credentials. */
+    clientIdEnv: 'LINKEDIN_OAUTH_CLIENT_ID',
+    clientSecretEnv: 'LINKEDIN_OAUTH_CLIENT_SECRET',
+    /**
+     * Scopes extra que este despliegue puede pedir, separados por coma.
+     *
+     * ## Por que es una variable y no una constante
+     *
+     * LinkedIn rechaza la autorizacion ENTERA con `unauthorized_scope_error` si
+     * pides un scope que la app no tiene habilitado — no lo ignora. Meter los
+     * scopes de pagina en la lista fija romperia el conector personal, que hoy
+     * funciona, en todos los despliegues cuya app aun no tenga aprobado
+     * Community Management API.
+     *
+     * Asi que la lista base es la que garantizan los dos productos gratuitos, y
+     * lo que dependa de una aprobacion se enciende aqui cuando LinkedIn la
+     * concede:
+     *
+     *     LINKEDIN_OAUTH_EXTRA_SCOPES=r_organization_social,w_organization_social,rw_organization_admin
+     *
+     * Es una variable y no un booleano a proposito: LinkedIn renombra y trocea
+     * sus permisos cada pocos meses, y asi ajustarlo no pide un despliegue de
+     * codigo.
+     */
+    extraScopesEnv: 'LINKEDIN_OAUTH_EXTRA_SCOPES',
+    /** Default scope set:
+     *   - openid profile email — OIDC identity (always required)
+     *   - w_member_social — post on behalf of the authenticated member
+     *
+     * `w_member_social` is "Share on LinkedIn" product scope — must be
+     * enabled on the LinkedIn app via the Products tab. */
+    defaultScopes: ['openid', 'profile', 'email', 'w_member_social'],
+    /** Credenciales de la SEGUNDA app, la de Community Management API. */
+    orgClientIdEnv: 'LINKEDIN_ORG_OAUTH_CLIENT_ID',
+    orgClientSecretEnv: 'LINKEDIN_ORG_OAUTH_CLIENT_SECRET',
+    /** Sobrescribe los scopes de la app de pagina sin desplegar codigo. */
+    orgScopesEnv: 'LINKEDIN_ORG_OAUTH_SCOPES',
+    /**
+     * Lo que concede Community Management API en su nivel de desarrollo:
+     *   - r_organization_social — leer los posts de la pagina (EL TRIGGER)
+     *   - w_organization_social — publicar como la pagina
+     *   - rw_organization_admin — listar que paginas administra el miembro
+     *
+     * Sin `openid` a proposito: esa app no tiene OIDC y pedirlo la tumbaria
+     * entera con `unauthorized_scope_error`.
+     */
+    orgDefaultScopes: [
+        'r_organization_social',
+        'w_organization_social',
+        'rw_organization_admin',
+    ],
+};
+/**
+ * La version de la API de marketing que se declara en cada llamada a `/rest`.
+ *
+ * Iba escrita en el provider, y ahora la necesitan dos sitios: el provider y el
+ * descubrimiento de paginas del OAuth. Una sola copia, porque LinkedIn RETIRA
+ * las versiones viejas cada pocos meses («The Marketing Version 202507 has been
+ * sunset») y en `/rest` una version retirada no es un aviso, es un fallo. Con
+ * dos copias, subir una y olvidar la otra deja media integracion rota.
+ *
+ * Los `/v2` no la consultan — de ahi que el desfase no diera la cara.
+ */
+exports.LINKEDIN_REST_VERSION = '202607';
+/** Leer los posts propios de una PERSONA. Restringido por LinkedIn. */
+exports.LINKEDIN_MEMBER_READ_SCOPE = 'r_member_social';
+/** Leer los posts de una PAGINA. Community Management API. */
+exports.LINKEDIN_ORG_READ_SCOPE = 'r_organization_social';
+/** Publicar como PAGINA. Community Management API. */
+exports.LINKEDIN_ORG_WRITE_SCOPE = 'w_organization_social';
+/** Listar las paginas que administra el miembro (`organizationAcls`). */
+exports.LINKEDIN_ORG_ADMIN_SCOPE = 'rw_organization_admin';
+/**
+ * Los scopes que se piden en la autorizacion: los base mas los que este
+ * despliegue haya encendido por entorno.
+ *
+ * `env` se inyecta para que la prueba no tenga que tocar `process.env`.
+ */
+function resolveDefaultScopes(env = process.env) {
+    const extra = parseScopeList(env[exports.LINKEDIN_OAUTH_CONFIG.extraScopesEnv]);
+    return dedupe([...exports.LINKEDIN_OAUTH_CONFIG.defaultScopes, ...extra]);
+}
+/** Lo que se le pide a la app de pagina. Sobrescribible por entorno. */
+function resolveOrgScopes(env = process.env) {
+    const override = parseScopeList(env[exports.LINKEDIN_OAUTH_CONFIG.orgScopesEnv]);
+    /* Aqui SUSTITUYE en vez de sumar: si LinkedIn concede un juego distinto al
+       aprobar, sumarle los nuestros pediria uno que no tiene y tumbaria la
+       autorizacion entera — que es justo el accidente del que huimos. */
+    return override.length > 0
+        ? dedupe(override)
+        : [...exports.LINKEDIN_OAUTH_CONFIG.orgDefaultScopes];
+}
+/** Los scopes y los nombres de variable que le tocan a cada app. */
+function appConfigFor(kind) {
+    return kind === 'organization'
+        ? {
+            clientIdEnv: exports.LINKEDIN_OAUTH_CONFIG.orgClientIdEnv,
+            clientSecretEnv: exports.LINKEDIN_OAUTH_CONFIG.orgClientSecretEnv,
+            scopes: resolveOrgScopes,
+        }
+        : {
+            clientIdEnv: exports.LINKEDIN_OAUTH_CONFIG.clientIdEnv,
+            clientSecretEnv: exports.LINKEDIN_OAUTH_CONFIG.clientSecretEnv,
+            scopes: resolveDefaultScopes,
+        };
+}
+/** Trocea una lista de scopes escrita a mano: coma, espacio o salto. */
+function parseScopeList(raw) {
+    if (!raw)
+        return [];
+    return raw
+        .split(/[\s,]+/)
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+function dedupe(items) {
+    return [...new Set(items)];
+}
+function authorKindOf(urn) {
+    if (!urn)
+        return null;
+    if (urn.startsWith('urn:li:person:'))
+        return 'person';
+    if (urn.startsWith('urn:li:organization:'))
+        return 'organization';
+    // `urn:li:organizationBrand:` es una pagina de producto: LinkedIn la trata
+    // como organizacion en los mismos endpoints, asi que cuenta igual.
+    if (urn.startsWith('urn:li:organizationBrand:'))
+        return 'organization';
+    return null;
+}
+/**
+ * Los elementos de `organizationAcls` convertidos en paginas.
+ *
+ * LinkedIn devuelve el URN en `organization` y, cuando la proyeccion cuela,
+ * los datos decorados en `organization~`. Se toleran las dos formas porque la
+ * decoracion es lo primero que deja de venir cuando cambia la version de la
+ * API, y perder el nombre no puede costar la pagina entera: un desplegable que
+ * dice `urn:li:organization:123` es feo, pero elegible; uno vacio no.
+ */
+function parseOrganizationAcls(elements) {
+    const out = [];
+    const vistos = new Set();
+    for (const el of elements ?? []) {
+        const urn = typeof el?.organization === 'string' ? el.organization : '';
+        if (!urn || vistos.has(urn))
+            continue;
+        vistos.add(urn);
+        const decorado = el['organization~'];
+        const name = typeof decorado?.localizedName === 'string' && decorado.localizedName
+            ? decorado.localizedName
+            : urn;
+        const vanityName = typeof decorado?.vanityName === 'string'
+            ? decorado.vanityName
+            : undefined;
+        const role = typeof el.role === 'string' ? el.role : undefined;
+        out.push({
+            urn,
+            name,
+            ...(vanityName ? { vanityName } : {}),
+            ...(role ? { role } : {}),
+        });
+    }
+    return out;
+}
+/**
+ * La persona de una credencial, o cadena vacia si no la hay.
+ *
+ * Las credenciales anteriores a las paginas no guardan `personUrn`: entonces
+ * `authorUrn` solo podia ser la persona, asi que ese es el relleno correcto —
+ * PERO solo si de verdad es un URN de persona. Cayendo a `authorUrn` a secas,
+ * una credencial de la app de pagina devolveria el URN de la pagina como si
+ * fuera su persona, y `setAuthor` la aceptaria como identidad «personal».
+ */
+function personUrnOf(payload) {
+    const person = payload.personUrn;
+    if (typeof person === 'string' && person)
+        return person;
+    const author = payload.authorUrn;
+    if (typeof author === 'string' && authorKindOf(author) === 'person') {
+        return author;
+    }
+    return '';
+}
+function toOrganizations(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw.filter((o) => !!o &&
+        typeof o === 'object' &&
+        typeof o.urn === 'string');
+}
+/**
+ * Por que ESTA credencial no puede sondear, o `null` si puede.
+ *
+ * Un solo sitio lo decide, y lo consultan los tres que opinan: la compuerta de
+ * activacion del trigger, el provider antes de gastar una llamada, y la
+ * pantalla para avisar antes de guardar.
+ *
+ * ## La regla del silencio
+ *
+ * Con `scopes` vacio o ausente NO se bloquea. Las credenciales anteriores a
+ * esto guardan la lista, pero una que no la tenga no es prueba de que falte el
+ * permiso — es prueba de que no lo sabemos, y bloquear por no saber convierte
+ * un fallo nuestro en un «no se puede» del usuario. Se bloquea solo cuando
+ * consta que el scope NO fue concedido.
+ */
+function pollBlockReason(params) {
+    const kind = authorKindOf(params.authorUrn);
+    const scopes = params.scopes ?? [];
+    // Sin lista de scopes no se juzga — ver «la regla del silencio».
+    if (scopes.length === 0)
+        return null;
+    if (kind === 'organization') {
+        if (scopes.includes(exports.LINKEDIN_ORG_READ_SCOPE))
+            return null;
+        return (`This LinkedIn credential points at a Company Page but was connected without ` +
+            `the "${exports.LINKEDIN_ORG_READ_SCOPE}" permission, so its posts cannot be read. ` +
+            `Request the Community Management API product for the LinkedIn app, then ` +
+            `reconnect the credential to grant it.`);
+    }
+    if (kind === 'person') {
+        if (scopes.includes(exports.LINKEDIN_MEMBER_READ_SCOPE))
+            return null;
+        return (`LinkedIn does not let apps read a personal profile's own posts — ` +
+            `"${exports.LINKEDIN_MEMBER_READ_SCOPE}" is restricted and LinkedIn is not granting it. ` +
+            `Point this credential at a Company Page you administer (Settings → ` +
+            `Credentials → the LinkedIn credential → "Publish and poll as"), or use the ` +
+            `credential for posting only.`);
+    }
+    // URN irreconocible: no inventamos un motivo. El fallo saldra en la llamada.
+    return null;
+}
+/**
+ * Por que ESTA credencial no puede publicar, o `null` si puede.
+ *
+ * Misma regla del silencio que `pollBlockReason`. Publicar como persona es el
+ * caso gratuito; como pagina hace falta Community Management.
+ */
+function postBlockReason(params) {
+    const kind = authorKindOf(params.authorUrn);
+    const scopes = params.scopes ?? [];
+    if (scopes.length === 0)
+        return null;
+    if (kind === 'organization' && !scopes.includes(exports.LINKEDIN_ORG_WRITE_SCOPE)) {
+        return (`This LinkedIn credential points at a Company Page but was connected without ` +
+            `the "${exports.LINKEDIN_ORG_WRITE_SCOPE}" permission, so it cannot post as the page. ` +
+            `Request the Community Management API product for the LinkedIn app, then ` +
+            `reconnect the credential.`);
+    }
+    return null;
+}

package/dist/presets-de-oauth/mailchimp-oauth-presets.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Mailchimp OAuth 2.0 configuration for HostWebhook.
+ *
+ * Plain OAuth 2.0 authorization-code flow with a confidential client — one
+ * HW-wide registered app, credentials from env vars. Register it at
+ * <https://us1.admin.mailchimp.com/account/oauth2/> ("Registered Apps" in the
+ * Mailchimp account menu), with the redirect URL set to
+ * `{API_URL}/api/credentials/mailchimp/oauth/callback`.
+ *
+ * ## Three things Mailchimp does NOT have, and none of them are oversights
+ *
+ * **No scopes.** The authorize URL takes `response_type`, `client_id`,
+ * `redirect_uri` and `state`, and nothing else. There is no `scope` parameter
+ * and no scope list to keep in sync — a token grants full access to the
+ * account that issued it. Do not add a `defaultScopes` here to match the other
+ * providers: it would be sent, ignored, and then read back by whoever
+ * maintains this next as if it meant something.
+ *
+ * **No expiry and no refresh token.** Mailchimp's own guide: "Mailchimp
+ * Marketing access tokens do not expire, so you don't need to use a
+ * `refresh_token`. The access token will remain valid unless the user revokes
+ * your application's permission." So there is no expiry timer to run and no
+ * `oauthExpiresAt` to write — a credential is live until the user revokes it.
+ *
+ * **No fixed API host.** Every account lives in a data centre, and the prefix
+ * is part of the base URL: `https://{dc}.api.mailchimp.com/3.0`. It is not
+ * inside the token and cannot be guessed. It comes from the metadata endpoint
+ * below, and it has to be persisted alongside the token — a stored Mailchimp
+ * token without its `dc` is unusable.
+ *
+ * See `docs/ADR-0003-mailchimp.md` for why this provider is OAuth-only.
+ */
+export declare const MAILCHIMP_OAUTH_CONFIG: {
+    readonly authorizationEndpoint: "https://login.mailchimp.com/oauth2/authorize";
+    readonly tokenEndpoint: "https://login.mailchimp.com/oauth2/token";
+    /**
+     * Returns the account's data centre. Called with `Authorization: OAuth
+     * {token}` — note `OAuth`, not `Bearer`; this is the one endpoint in the
+     * flow that does not take a Bearer header.
+     */
+    readonly metadataEndpoint: "https://login.mailchimp.com/oauth2/metadata";
+    /** Env var names holding HW's registered client credentials. */
+    readonly clientIdEnv: "MAILCHIMP_OAUTH_CLIENT_ID";
+    readonly clientSecretEnv: "MAILCHIMP_OAUTH_CLIENT_SECRET";
+};
+/**
+ * What `/oauth2/metadata` gives back.
+ *
+ * **Only `dc` is documented.** The guide's sample code destructures exactly
+ * that one field. The rest show up in real responses and are worth keeping for
+ * the credential's display name, but every one of them is optional here on
+ * purpose: treating an undocumented field as required is how this breaks on a
+ * response shape we never agreed to.
+ */
+export interface MailchimpOAuthMetadata {
+    /** Data centre / server prefix — `us6`, `us21`, … The only required field. */
+    dc: string;
+    /** Account display name, e.g. "Freddie's Bakery". */
+    accountname?: string;
+    /** `owner`, `admin`, `manager`, `author`, `viewer`. */
+    role?: string;
+    /** Convenience base the metadata sometimes returns, e.g. `https://us6.api.mailchimp.com`. */
+    api_endpoint?: string;
+    login?: {
+        email?: string;
+        login_name?: string;
+        login_email?: string;
+    };
+}
+export interface MailchimpOAuthStoredAuth {
+    accessToken: string;
+    /** Server prefix. Without this there is no base URL — see the note above. */
+    dc: string;
+    /** Best-effort, for the credential list. Falls back to the account email. */
+    accountName: string;
+    email?: string;
+    role?: string;
+    /** Whether `GET /ping` answered when the credential was connected. */
+    pingOk: boolean;
+}
+export interface MailchimpOAuthStoredData {
+    accountName: string;
+    email?: string;
+    oauth: MailchimpOAuthStoredAuth;
+}
+export interface PendingMailchimpOAuthState {
+    orgId: string;
+    userId: string;
+    credentialName: string;
+    /** Set on reconnect to update an existing credential instead of creating one. */
+    credentialId?: string;
+    tags?: string[];
+    /** Destination folder chosen in the form. Travels through Redis between
+     *  `start` and the callback; without it the choice was lost on the way. */
+    folderId?: string;
+    clientId: string;
+    clientSecret: string;
+    /** Absolute ms timestamp when this pending state expires. */
+    expiresAt: number;
+}
+export interface MailchimpTokenResponse {
+    access_token?: string;
+    /** Mailchimp sends `0` here. It does not mean "already expired" — it means
+     *  the concept does not apply. Never feed this into an expiry calculation. */
+    expires_in?: number;
+    scope?: string | null;
+    error?: string;
+    error_description?: string;
+}
+/** The credential `type` string. */
+export declare const MAILCHIMP_CREDENTIAL_TYPE = "mailchimp_oauth2";
+/**
+ * Base URL for every Marketing API call made with this credential.
+ *
+ * Lives here rather than being interpolated at each call site so there is one
+ * place that knows the shape, and so a credential missing its `dc` fails
+ * loudly here instead of producing a request to `https://undefined.api…`.
+ */
+export declare function mailchimpApiBase(dc: string): string;
+/**
+ * The authorize URL. No `scope` parameter — see the header.
+ */
+export declare function buildMailchimpAuthorizeUrl(params: {
+    clientId: string;
+    redirectUri: string;
+    state: string;
+}): string;
+/**
+ * The name shown in the credential list.
+ *
+ * Prefers the account name, falls back to the login email, and only then to
+ * the data centre — which is at least true and unique-ish, and beats an empty
+ * row that gives the user nothing to recognise.
+ */
+export declare function mailchimpDisplayName(meta: MailchimpOAuthMetadata): string;

package/dist/presets-de-oauth/mailchimp-oauth-presets.js

@@ -0,0 +1,96 @@
+"use strict";
+/**
+ * Mailchimp OAuth 2.0 configuration for HostWebhook.
+ *
+ * Plain OAuth 2.0 authorization-code flow with a confidential client — one
+ * HW-wide registered app, credentials from env vars. Register it at
+ * <https://us1.admin.mailchimp.com/account/oauth2/> ("Registered Apps" in the
+ * Mailchimp account menu), with the redirect URL set to
+ * `{API_URL}/api/credentials/mailchimp/oauth/callback`.
+ *
+ * ## Three things Mailchimp does NOT have, and none of them are oversights
+ *
+ * **No scopes.** The authorize URL takes `response_type`, `client_id`,
+ * `redirect_uri` and `state`, and nothing else. There is no `scope` parameter
+ * and no scope list to keep in sync — a token grants full access to the
+ * account that issued it. Do not add a `defaultScopes` here to match the other
+ * providers: it would be sent, ignored, and then read back by whoever
+ * maintains this next as if it meant something.
+ *
+ * **No expiry and no refresh token.** Mailchimp's own guide: "Mailchimp
+ * Marketing access tokens do not expire, so you don't need to use a
+ * `refresh_token`. The access token will remain valid unless the user revokes
+ * your application's permission." So there is no expiry timer to run and no
+ * `oauthExpiresAt` to write — a credential is live until the user revokes it.
+ *
+ * **No fixed API host.** Every account lives in a data centre, and the prefix
+ * is part of the base URL: `https://{dc}.api.mailchimp.com/3.0`. It is not
+ * inside the token and cannot be guessed. It comes from the metadata endpoint
+ * below, and it has to be persisted alongside the token — a stored Mailchimp
+ * token without its `dc` is unusable.
+ *
+ * See `docs/ADR-0003-mailchimp.md` for why this provider is OAuth-only.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAILCHIMP_CREDENTIAL_TYPE = exports.MAILCHIMP_OAUTH_CONFIG = void 0;
+exports.mailchimpApiBase = mailchimpApiBase;
+exports.buildMailchimpAuthorizeUrl = buildMailchimpAuthorizeUrl;
+exports.mailchimpDisplayName = mailchimpDisplayName;
+exports.MAILCHIMP_OAUTH_CONFIG = {
+    authorizationEndpoint: 'https://login.mailchimp.com/oauth2/authorize',
+    tokenEndpoint: 'https://login.mailchimp.com/oauth2/token',
+    /**
+     * Returns the account's data centre. Called with `Authorization: OAuth
+     * {token}` — note `OAuth`, not `Bearer`; this is the one endpoint in the
+     * flow that does not take a Bearer header.
+     */
+    metadataEndpoint: 'https://login.mailchimp.com/oauth2/metadata',
+    /** Env var names holding HW's registered client credentials. */
+    clientIdEnv: 'MAILCHIMP_OAUTH_CLIENT_ID',
+    clientSecretEnv: 'MAILCHIMP_OAUTH_CLIENT_SECRET',
+};
+/** The credential `type` string. */
+exports.MAILCHIMP_CREDENTIAL_TYPE = 'mailchimp_oauth2';
+/**
+ * Base URL for every Marketing API call made with this credential.
+ *
+ * Lives here rather than being interpolated at each call site so there is one
+ * place that knows the shape, and so a credential missing its `dc` fails
+ * loudly here instead of producing a request to `https://undefined.api…`.
+ */
+function mailchimpApiBase(dc) {
+    const prefix = String(dc ?? '').trim();
+    if (!/^[a-z]{2}\d{1,3}$/i.test(prefix)) {
+        throw new Error(`Mailchimp credential has no usable data centre prefix (got "${dc}"). ` +
+            `Reconnect the credential — the prefix is captured at connect time.`);
+    }
+    return `https://${prefix.toLowerCase()}.api.mailchimp.com/3.0`;
+}
+/**
+ * The authorize URL. No `scope` parameter — see the header.
+ */
+function buildMailchimpAuthorizeUrl(params) {
+    const qs = new URLSearchParams({
+        response_type: 'code',
+        client_id: params.clientId,
+        redirect_uri: params.redirectUri,
+        state: params.state,
+    });
+    return `${exports.MAILCHIMP_OAUTH_CONFIG.authorizationEndpoint}?${qs.toString()}`;
+}
+/**
+ * The name shown in the credential list.
+ *
+ * Prefers the account name, falls back to the login email, and only then to
+ * the data centre — which is at least true and unique-ish, and beats an empty
+ * row that gives the user nothing to recognise.
+ */
+function mailchimpDisplayName(meta) {
+    const account = meta.accountname?.trim();
+    if (account)
+        return account;
+    const email = (meta.login?.email ?? meta.login?.login_email)?.trim();
+    if (email)
+        return email;
+    return `Mailchimp (${meta.dc})`;
+}