@usemogul/connect-common 0.1.0 → 0.3.0

package/README.md

@@ -5,7 +5,7 @@ the `postMessage` contract between the Mogul application and the partner-side
 loader (`@usemogul/connect-js`). Both sides depend on this package so the message
 shapes can't drift.
 
-Zero runtime dependencies. Ships ESM + TypeScript types.
+Zero runtime dependencies. Ships ESM + CJS + TypeScript types.
 
 ## Exports
 
@@ -13,8 +13,17 @@ Zero runtime dependencies. Ships ESM + TypeScript types.
   the session `token` and the partner's public `clientId`)
 - `ConnectedIdentity` — identity payload carried on `mogul:success`
 - `FRAME_EVENT` / `PARENT_EVENT` — event-name constants
-- `parseFrameMessage(data)` — validates untrusted `postMessage` data into a known
-  `FrameMessage`, or `null`.
+- `CONNECT_ERROR_CODE` / `ConnectErrorCode` — the `mogul:error` codes
+  (`token_error`, `invalid_target`, `client_mismatch`, `identity_unavailable`,
+  `origin_not_allowed`, `verification_failed`).
+  `mogul:error.code` stays typed as `string` on the wire, so handle unknown codes.
+- `parseFrameMessage(data)` — for the loader: validates untrusted `postMessage`
+  data into a known `FrameMessage`, or `null`.
+- `parseParentMessage(data)` — for the frame: validates untrusted `postMessage`
+  data into a known `ParentMessage`, or `null`.
+
+Both parsers rebuild the message from the checked fields, so unknown keys are
+dropped. Check the message origin before calling them.
 
 ```ts
 import { parseFrameMessage, type ParentMessage } from '@usemogul/connect-common'

package/dist/index.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const i={ready:"mogul:ready",requestToken:"mogul:request-token",success:"mogul:success",exit:"mogul:exit",error:"mogul:error"},s={init:"mogul:init",logout:"mogul:logout"},u={tokenError:"token_error",invalidTarget:"invalid_target",clientMismatch:"client_mismatch",identityUnavailable:"identity_unavailable",originNotAllowed:"origin_not_allowed",verificationFailed:"verification_failed"},l=t=>{if(typeof t!="object"||t===null)return;const e=t;if(typeof e.id!="string"||typeof e.name!="string"||!Array.isArray(e.accounts))return;const n=[];for(const o of e.accounts){if(typeof o!="object"||o===null)return;const r=o;if(typeof r.id!="string"||typeof r.name!="string")return;n.push({id:r.id,name:r.name})}return{id:e.id,name:e.name,accounts:n}},c=t=>{if(typeof t!="object"||t===null)return null;const e=t;switch(e.type){case"mogul:ready":case"mogul:request-token":case"mogul:exit":return{type:e.type};case"mogul:success":{const n=l(e.connectedIdentity);return typeof e.integrationId=="number"&&typeof e.accountId=="string"&&n?{type:"mogul:success",integrationId:e.integrationId,accountId:e.accountId,connectedIdentity:n}:null}case"mogul:error":return typeof e.code=="string"?{type:"mogul:error",code:e.code}:null;default:return null}},a=t=>{if(typeof t!="object"||t===null)return null;const e=t;switch(e.type){case"mogul:init":{const{token:n,clientId:o,locale:r}=e;return typeof n!="string"||n.length===0||typeof o!="string"||o.length===0?null:typeof r=="string"?{type:"mogul:init",token:n,clientId:o,locale:r}:{type:"mogul:init",token:n,clientId:o}}case"mogul:logout":return{type:"mogul:logout"};default:return null}};exports.CONNECT_ERROR_CODE=u;exports.FRAME_EVENT=i;exports.PARENT_EVENT=s;exports.parseFrameMessage=c;exports.parseParentMessage=a;

package/dist/index.d.cts

@@ -0,0 +1,135 @@
+/** `mogul:error` codes, so neither side hard-codes the raw strings. */
+export declare const CONNECT_ERROR_CODE: {
+    /** Loader: the partner's `getToken()` threw. */
+    readonly tokenError: "token_error";
+    /** Frame: the preselected `/embed/connect/<target>` isn't a known source. */
+    readonly invalidTarget: "invalid_target";
+    /**
+     * Frame: `mogul:init.clientId` doesn't match the session token's `client_id`
+     * claim, so the token is refused.
+     */
+    readonly clientMismatch: "client_mismatch";
+    /**
+     * Frame: the connection succeeded, but the integration ID or a complete
+     * identity couldn't be resolved, so no `mogul:success` is sent.
+     */
+    readonly identityUnavailable: "identity_unavailable";
+    /**
+     * Frame: the embedding page's origin isn't registered for the partner the
+     * session token belongs to (or the token's partner doesn't match `clientId`),
+     * so the token is refused and the flow never loads.
+     */
+    readonly originNotAllowed: "origin_not_allowed";
+    /**
+     * Frame: the frame couldn't reach Mogul to verify the embedding origin, so
+     * the token is refused. Transient: remount (or the next `mogul:init`) retries.
+     */
+    readonly verificationFailed: "verification_failed";
+};
+
+/** Identity the connected source resolved to, parsed from the integration. */
+export declare type ConnectedIdentity = {
+    /** Source-side account/entity id. */
+    id: string;
+    /** Display name (artist / label / handle) as the source reports it. */
+    name: string;
+    /**
+     * One entry per synced account: for a multi-account login, the accounts the
+     * user chose in the picker; a single-account source has exactly one.
+     */
+    accounts: Array<{
+        id: string;
+        name: string;
+    }>;
+};
+
+export declare type ConnectErrorCode = (typeof CONNECT_ERROR_CODE)[keyof typeof CONNECT_ERROR_CODE];
+
+/** Event-name constants, so neither side hard-codes the raw strings. */
+export declare const FRAME_EVENT: {
+    readonly ready: "mogul:ready";
+    readonly requestToken: "mogul:request-token";
+    readonly success: "mogul:success";
+    readonly exit: "mogul:exit";
+    readonly error: "mogul:error";
+};
+
+/** Messages the frame sends to the parent — the loader listens for these. */
+export declare type FrameMessage = {
+    type: 'mogul:ready';
+} | {
+    type: 'mogul:request-token';
+} | {
+    /**
+     * Sent when the user dismisses the success screen (Done), and only when
+     * every field below — including a name for every account — is present.
+     * Otherwise the frame sends `mogul:error` `identity_unavailable` instead.
+     */
+    type: 'mogul:success';
+    /** The created integration — the handle for later royalty-report API calls. */
+    integrationId: number;
+    /** Mogul account the integration belongs to (from the session token). */
+    accountId: string;
+    /** Identity parsed from the connected integration. */
+    connectedIdentity: ConnectedIdentity;
+}
+/**
+* Flow closed. Always follows the `mogul:success` or `mogul:error` for the
+* same completion, so the parent can safely tear the frame down here.
+*/
+| {
+    type: 'mogul:exit';
+} | {
+    type: 'mogul:error';
+    /**
+     * A {@link ConnectErrorCode}, typed as `string` so older loaders keep
+     * working when the frame adds a code.
+     */
+    code: string;
+};
+
+export declare type FrameMessageType = FrameMessage['type'];
+
+export declare const PARENT_EVENT: {
+    readonly init: "mogul:init";
+    readonly logout: "mogul:logout";
+};
+
+/** Messages the parent sends to the frame — the loader posts these. */
+export declare type ParentMessage = {
+    type: 'mogul:init';
+    token: string;
+    /**
+     * Mogul-issued partner client ID (`mcci_…`). Identifies the partner; not a
+     * secret. Must equal the token's `client_id` claim: on a mismatch (or a
+     * token with no claim) the frame refuses the token and answers with
+     * `mogul:error` `client_mismatch`.
+     */
+    clientId: string;
+    locale?: string;
+}
+/** Reserved: the frame accepts and ignores it. */
+| {
+    type: 'mogul:logout';
+};
+
+export declare type ParentMessageType = ParentMessage['type'];
+
+/**
+ * Narrow untrusted `postMessage` data to a known {@link FrameMessage}. Check the
+ * discriminant first, then the payload shape. Anything that doesn't match
+ * returns `null` and must be ignored by the caller — the origin/source checks
+ * happen separately, before this runs.
+ */
+export declare const parseFrameMessage: (data: unknown) => FrameMessage | null;
+
+/**
+ * Narrow untrusted `postMessage` data to a known {@link ParentMessage} — the
+ * frame's counterpart to {@link parseFrameMessage}. The returned object is
+ * rebuilt from the checked fields, so extra keys never reach the frame. Anything
+ * that doesn't match returns `null`; the origin check happens separately, before
+ * this runs.
+ */
+export declare const parseParentMessage: (data: unknown) => ParentMessage | null;
+
+export { }

package/dist/index.d.ts

@@ -1,2 +1,135 @@
-export * from './messages';
-export { parseFrameMessage } from './parse';
+/** `mogul:error` codes, so neither side hard-codes the raw strings. */
+export declare const CONNECT_ERROR_CODE: {
+    /** Loader: the partner's `getToken()` threw. */
+    readonly tokenError: "token_error";
+    /** Frame: the preselected `/embed/connect/<target>` isn't a known source. */
+    readonly invalidTarget: "invalid_target";
+    /**
+     * Frame: `mogul:init.clientId` doesn't match the session token's `client_id`
+     * claim, so the token is refused.
+     */
+    readonly clientMismatch: "client_mismatch";
+    /**
+     * Frame: the connection succeeded, but the integration ID or a complete
+     * identity couldn't be resolved, so no `mogul:success` is sent.
+     */
+    readonly identityUnavailable: "identity_unavailable";
+    /**
+     * Frame: the embedding page's origin isn't registered for the partner the
+     * session token belongs to (or the token's partner doesn't match `clientId`),
+     * so the token is refused and the flow never loads.
+     */
+    readonly originNotAllowed: "origin_not_allowed";
+    /**
+     * Frame: the frame couldn't reach Mogul to verify the embedding origin, so
+     * the token is refused. Transient: remount (or the next `mogul:init`) retries.
+     */
+    readonly verificationFailed: "verification_failed";
+};
+
+/** Identity the connected source resolved to, parsed from the integration. */
+export declare type ConnectedIdentity = {
+    /** Source-side account/entity id. */
+    id: string;
+    /** Display name (artist / label / handle) as the source reports it. */
+    name: string;
+    /**
+     * One entry per synced account: for a multi-account login, the accounts the
+     * user chose in the picker; a single-account source has exactly one.
+     */
+    accounts: Array<{
+        id: string;
+        name: string;
+    }>;
+};
+
+export declare type ConnectErrorCode = (typeof CONNECT_ERROR_CODE)[keyof typeof CONNECT_ERROR_CODE];
+
+/** Event-name constants, so neither side hard-codes the raw strings. */
+export declare const FRAME_EVENT: {
+    readonly ready: "mogul:ready";
+    readonly requestToken: "mogul:request-token";
+    readonly success: "mogul:success";
+    readonly exit: "mogul:exit";
+    readonly error: "mogul:error";
+};
+
+/** Messages the frame sends to the parent — the loader listens for these. */
+export declare type FrameMessage = {
+    type: 'mogul:ready';
+} | {
+    type: 'mogul:request-token';
+} | {
+    /**
+     * Sent when the user dismisses the success screen (Done), and only when
+     * every field below — including a name for every account — is present.
+     * Otherwise the frame sends `mogul:error` `identity_unavailable` instead.
+     */
+    type: 'mogul:success';
+    /** The created integration — the handle for later royalty-report API calls. */
+    integrationId: number;
+    /** Mogul account the integration belongs to (from the session token). */
+    accountId: string;
+    /** Identity parsed from the connected integration. */
+    connectedIdentity: ConnectedIdentity;
+}
+/**
+* Flow closed. Always follows the `mogul:success` or `mogul:error` for the
+* same completion, so the parent can safely tear the frame down here.
+*/
+| {
+    type: 'mogul:exit';
+} | {
+    type: 'mogul:error';
+    /**
+     * A {@link ConnectErrorCode}, typed as `string` so older loaders keep
+     * working when the frame adds a code.
+     */
+    code: string;
+};
+
+export declare type FrameMessageType = FrameMessage['type'];
+
+export declare const PARENT_EVENT: {
+    readonly init: "mogul:init";
+    readonly logout: "mogul:logout";
+};
+
+/** Messages the parent sends to the frame — the loader posts these. */
+export declare type ParentMessage = {
+    type: 'mogul:init';
+    token: string;
+    /**
+     * Mogul-issued partner client ID (`mcci_…`). Identifies the partner; not a
+     * secret. Must equal the token's `client_id` claim: on a mismatch (or a
+     * token with no claim) the frame refuses the token and answers with
+     * `mogul:error` `client_mismatch`.
+     */
+    clientId: string;
+    locale?: string;
+}
+/** Reserved: the frame accepts and ignores it. */
+| {
+    type: 'mogul:logout';
+};
+
+export declare type ParentMessageType = ParentMessage['type'];
+
+/**
+ * Narrow untrusted `postMessage` data to a known {@link FrameMessage}. Check the
+ * discriminant first, then the payload shape. Anything that doesn't match
+ * returns `null` and must be ignored by the caller — the origin/source checks
+ * happen separately, before this runs.
+ */
+export declare const parseFrameMessage: (data: unknown) => FrameMessage | null;
+
+/**
+ * Narrow untrusted `postMessage` data to a known {@link ParentMessage} — the
+ * frame's counterpart to {@link parseFrameMessage}. The returned object is
+ * rebuilt from the checked fields, so extra keys never reach the frame. Anything
+ * that doesn't match returns `null`; the origin check happens separately, before
+ * this runs.
+ */
+export declare const parseParentMessage: (data: unknown) => ParentMessage | null;
+
+export { }

package/dist/index.js

@@ -1,2 +1,93 @@
-export * from './messages';
-export { parseFrameMessage } from './parse';
+const u = {
+  ready: "mogul:ready",
+  requestToken: "mogul:request-token",
+  success: "mogul:success",
+  exit: "mogul:exit",
+  error: "mogul:error"
+}, l = {
+  init: "mogul:init",
+  logout: "mogul:logout"
+}, c = {
+  /** Loader: the partner's `getToken()` threw. */
+  tokenError: "token_error",
+  /** Frame: the preselected `/embed/connect/<target>` isn't a known source. */
+  invalidTarget: "invalid_target",
+  /**
+   * Frame: `mogul:init.clientId` doesn't match the session token's `client_id`
+   * claim, so the token is refused.
+   */
+  clientMismatch: "client_mismatch",
+  /**
+   * Frame: the connection succeeded, but the integration ID or a complete
+   * identity couldn't be resolved, so no `mogul:success` is sent.
+   */
+  identityUnavailable: "identity_unavailable",
+  /**
+   * Frame: the embedding page's origin isn't registered for the partner the
+   * session token belongs to (or the token's partner doesn't match `clientId`),
+   * so the token is refused and the flow never loads.
+   */
+  originNotAllowed: "origin_not_allowed",
+  /**
+   * Frame: the frame couldn't reach Mogul to verify the embedding origin, so
+   * the token is refused. Transient: remount (or the next `mogul:init`) retries.
+   */
+  verificationFailed: "verification_failed"
+}, i = (t) => {
+  if (typeof t != "object" || t === null) return;
+  const e = t;
+  if (typeof e.id != "string" || typeof e.name != "string" || !Array.isArray(e.accounts)) return;
+  const n = [];
+  for (const o of e.accounts) {
+    if (typeof o != "object" || o === null) return;
+    const r = o;
+    if (typeof r.id != "string" || typeof r.name != "string")
+      return;
+    n.push({ id: r.id, name: r.name });
+  }
+  return { id: e.id, name: e.name, accounts: n };
+}, s = (t) => {
+  if (typeof t != "object" || t === null) return null;
+  const e = t;
+  switch (e.type) {
+    case "mogul:ready":
+    case "mogul:request-token":
+    case "mogul:exit":
+      return { type: e.type };
+    case "mogul:success": {
+      const n = i(
+        e.connectedIdentity
+      );
+      return typeof e.integrationId == "number" && typeof e.accountId == "string" && n ? {
+        type: "mogul:success",
+        integrationId: e.integrationId,
+        accountId: e.accountId,
+        connectedIdentity: n
+      } : null;
+    }
+    case "mogul:error":
+      return typeof e.code == "string" ? { type: "mogul:error", code: e.code } : null;
+    default:
+      return null;
+  }
+}, a = (t) => {
+  if (typeof t != "object" || t === null) return null;
+  const e = t;
+  switch (e.type) {
+    case "mogul:init": {
+      const { token: n, clientId: o, locale: r } = e;
+      return typeof n != "string" || n.length === 0 || typeof o != "string" || o.length === 0 ? null : typeof r == "string" ? { type: "mogul:init", token: n, clientId: o, locale: r } : { type: "mogul:init", token: n, clientId: o };
+    }
+    case "mogul:logout":
+      return { type: "mogul:logout" };
+    default:
+      return null;
+  }
+};
+export {
+  c as CONNECT_ERROR_CODE,
+  u as FRAME_EVENT,
+  l as PARENT_EVENT,
+  s as parseFrameMessage,
+  a as parseParentMessage
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usemogul/connect-common",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Shared schemas for the Mogul Connect embedded component: message types, event-name constants, and validators shared by the connect-js loader and the Mogul application.",
   "license": "Apache-2.0",
   "author": "shawn@usemogul.com",
@@ -15,24 +15,30 @@
   },
   "type": "module",
   "sideEffects": false,
-  "main": "./dist/index.js",
+  "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
     }
   },
   "files": [
     "dist"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "vite build",
     "test": "vitest run",
     "typecheck": "tsc --noEmit",
     "prepack": "npm run build",
-    "prepublishOnly": "npm run typecheck && npm run test"
+    "prepublishOnly": "npm run typecheck && npm run test && npm run build && publint && attw --pack ."
   },
   "publishConfig": {
     "access": "public"

package/dist/messages.d.ts

@@ -1,67 +0,0 @@
-/**
- * Mogul Connect — wire message schemas.
- *
- * The single source of truth for the `postMessage` contract between the Mogul
- * application (running in the iframe) and the partner-side loader
- * (`@usemogul/connect-js`). Both sides depend on this package so the shapes
- * can't drift.
- */
-/** Event-name constants, so neither side hard-codes the raw strings. */
-export declare const FRAME_EVENT: {
-    readonly ready: "mogul:ready";
-    readonly requestToken: "mogul:request-token";
-    readonly resize: "mogul:resize";
-    readonly success: "mogul:success";
-    readonly exit: "mogul:exit";
-    readonly error: "mogul:error";
-};
-export declare const PARENT_EVENT: {
-    readonly init: "mogul:init";
-    readonly logout: "mogul:logout";
-};
-/** Identity the connected source resolved to, parsed from the integration. */
-export type ConnectedIdentity = {
-    /** Source-side account/entity id. */
-    id: string;
-    /** Display name (artist / label / handle) as the source reports it. */
-    name: string;
-    /** One entry per connected account (a single-account target has one). */
-    accounts: Array<{
-        id: string;
-        name: string;
-    }>;
-};
-/** Messages the frame sends to the parent — the loader listens for these. */
-export type FrameMessage = {
-    type: 'mogul:ready';
-} | {
-    type: 'mogul:request-token';
-} | {
-    type: 'mogul:resize';
-    height: number;
-} | {
-    type: 'mogul:success';
-    /** The created integration — the handle for later royalty-report API calls. */
-    integrationId: number;
-    /** Mogul account the integration belongs to (from the session token). */
-    accountId: string;
-    /** Identity parsed from the connected integration. */
-    connectedIdentity: ConnectedIdentity;
-} | {
-    type: 'mogul:exit';
-} | {
-    type: 'mogul:error';
-    code: string;
-};
-/** Messages the parent sends to the frame — the loader posts these. */
-export type ParentMessage = {
-    type: 'mogul:init';
-    token: string;
-    /** Mogul-issued partner client ID (`mcci_…`). Identifies the partner; not a secret. */
-    clientId: string;
-    locale?: string;
-} | {
-    type: 'mogul:logout';
-};
-export type FrameMessageType = FrameMessage['type'];
-export type ParentMessageType = ParentMessage['type'];

package/dist/messages.js

@@ -1,21 +0,0 @@
-/**
- * Mogul Connect — wire message schemas.
- *
- * The single source of truth for the `postMessage` contract between the Mogul
- * application (running in the iframe) and the partner-side loader
- * (`@usemogul/connect-js`). Both sides depend on this package so the shapes
- * can't drift.
- */
-/** Event-name constants, so neither side hard-codes the raw strings. */
-export const FRAME_EVENT = {
-    ready: 'mogul:ready',
-    requestToken: 'mogul:request-token',
-    resize: 'mogul:resize',
-    success: 'mogul:success',
-    exit: 'mogul:exit',
-    error: 'mogul:error',
-};
-export const PARENT_EVENT = {
-    init: 'mogul:init',
-    logout: 'mogul:logout',
-};

package/dist/parse.d.ts

@@ -1,8 +0,0 @@
-import type { FrameMessage } from './messages';
-/**
- * Narrow untrusted `postMessage` data to a known {@link FrameMessage}. Check the
- * discriminant first, then the payload shape. Anything that doesn't match
- * returns `null` and must be ignored by the caller — the origin/source checks
- * happen separately, before this runs.
- */
-export declare const parseFrameMessage: (data: unknown) => FrameMessage | null;

package/dist/parse.js

@@ -1,67 +0,0 @@
-/**
- * Parse the optional `connectedIdentity` payload. All fields are required, so a
- * partially-formed identity is rejected entirely (returns `undefined`); the
- * payload itself may still be absent.
- */
-const parseConnectedIdentity = (value) => {
-    if (typeof value !== 'object' || value === null)
-        return undefined;
-    const raw = value;
-    if (typeof raw.id !== 'string')
-        return undefined;
-    if (typeof raw.name !== 'string')
-        return undefined;
-    if (!Array.isArray(raw.accounts))
-        return undefined;
-    const accounts = [];
-    for (const entry of raw.accounts) {
-        if (typeof entry !== 'object' || entry === null)
-            return undefined;
-        const acc = entry;
-        if (typeof acc.id !== 'string' || typeof acc.name !== 'string') {
-            return undefined;
-        }
-        accounts.push({ id: acc.id, name: acc.name });
-    }
-    return { id: raw.id, name: raw.name, accounts };
-};
-/**
- * Narrow untrusted `postMessage` data to a known {@link FrameMessage}. Check the
- * discriminant first, then the payload shape. Anything that doesn't match
- * returns `null` and must be ignored by the caller — the origin/source checks
- * happen separately, before this runs.
- */
-export const parseFrameMessage = (data) => {
-    if (typeof data !== 'object' || data === null)
-        return null;
-    const message = data;
-    switch (message.type) {
-        case 'mogul:ready':
-        case 'mogul:request-token':
-        case 'mogul:exit':
-            return { type: message.type };
-        case 'mogul:resize':
-            return typeof message.height === 'number'
-                ? { type: 'mogul:resize', height: message.height }
-                : null;
-        case 'mogul:success': {
-            const connectedIdentity = parseConnectedIdentity(message.connectedIdentity);
-            return typeof message.integrationId === 'number' &&
-                typeof message.accountId === 'string' &&
-                connectedIdentity
-                ? {
-                    type: 'mogul:success',
-                    integrationId: message.integrationId,
-                    accountId: message.accountId,
-                    connectedIdentity,
-                }
-                : null;
-        }
-        case 'mogul:error':
-            return typeof message.code === 'string'
-                ? { type: 'mogul:error', code: message.code }
-                : null;
-        default:
-            return null;
-    }
-};