@dev-crew-berlin/enter-js-utils 0.98.11 → 0.99.0

package/dist/lib/email-links.test.js

@@ -0,0 +1,348 @@
+import { describe, it, expect } from 'vitest';
+import jws from 'jws';
+import { makeGoogleWalletLink, makeQrCodeLink, makeRegistrationLink, makeTrackingLink, makeUnsubscribeLink, makeWalletLink } from './email-links';
+
+/**
+ * Mirrors FrontendConfig's link builders
+ * (enter-core/common/models/frontend_config.py) -- each describe block
+ * below corresponds to one make_*_link method there. Split into
+ * single-assertion cases (enter-core/tests/unittests/common/models/
+ * frontend_config_test.py follows the same style) so a failure names
+ * exactly which behaviour broke.
+ */
+
+const options = {
+  jwtSecret: 'test-secret',
+  instanceName: 'my-instance',
+  domain: 'example.com'
+};
+function decode(link) {
+  const token = link.split('/').pop();
+  return jws.decode(token)?.payload;
+}
+function decodeQueryToken(link) {
+  const token = link.split('token=')[1];
+  return jws.decode(token)?.payload;
+}
+describe('makeTrackingLink', () => {
+  describe('tracking disabled', () => {
+    it('returns the raw target url unsigned', () => {
+      const link = makeTrackingLink(options, {
+        attendeeId: 'att-1',
+        emailName: 'welcome',
+        urlLink: '/home',
+        trackingEnabled: false
+      });
+      expect(link).toBe('https://example.com/home');
+    });
+    it('does not prefix an external url', () => {
+      const link = makeTrackingLink(options, {
+        attendeeId: 'att-1',
+        emailName: 'welcome',
+        urlLink: 'https://google.com',
+        trackingEnabled: false
+      });
+      expect(link).toBe('https://google.com/');
+    });
+  });
+  describe('tracking enabled', () => {
+    it('returns a /link/{token} url', () => {
+      const link = makeTrackingLink(options, {
+        attendeeId: 'att-1',
+        emailName: 'welcome',
+        urlLink: '/home',
+        trackingEnabled: true
+      });
+      expect(link.startsWith('https://example.com/link/')).toBe(true);
+    });
+    it('includes the instance name in the token', () => {
+      const link = makeTrackingLink(options, {
+        attendeeId: 'att-1',
+        emailName: 'welcome',
+        urlLink: '/home',
+        trackingEnabled: true
+      });
+      expect(decode(link).instance_name).toBe('my-instance');
+    });
+    it('includes the attendee id in the token', () => {
+      const link = makeTrackingLink(options, {
+        attendeeId: 'att-1',
+        emailName: 'welcome',
+        urlLink: '/home',
+        trackingEnabled: true
+      });
+      expect(decode(link).attendee_id).toBe('att-1');
+    });
+    it('includes the email name in the token', () => {
+      const link = makeTrackingLink(options, {
+        attendeeId: 'att-1',
+        emailName: 'welcome',
+        urlLink: '/home',
+        trackingEnabled: true
+      });
+      expect(decode(link).email_name).toBe('welcome');
+    });
+    it('resolves a relative url into an absolute target in the token', () => {
+      const link = makeTrackingLink(options, {
+        attendeeId: 'att-1',
+        emailName: 'welcome',
+        urlLink: '/home',
+        trackingEnabled: true
+      });
+      expect(decode(link).target).toBe('https://example.com/home');
+    });
+    it('does not prefix an external url in the token target either', () => {
+      const link = makeTrackingLink(options, {
+        attendeeId: 'att-1',
+        emailName: 'welcome',
+        urlLink: 'https://google.com',
+        trackingEnabled: true
+      });
+      expect(decode(link).target).toBe('https://google.com/');
+    });
+    it('defaults the mailing id to null when not provided', () => {
+      const link = makeTrackingLink(options, {
+        attendeeId: 'att-1',
+        emailName: 'welcome',
+        urlLink: '/home',
+        trackingEnabled: true
+      });
+      expect(decode(link).mailing_id).toBeNull();
+    });
+    it('includes the mailing id in the token when provided', () => {
+      const link = makeTrackingLink(options, {
+        attendeeId: 'att-1',
+        emailName: 'welcome',
+        urlLink: '/home',
+        mailingId: 'mailing-1',
+        trackingEnabled: true
+      });
+      expect(decode(link).mailing_id).toBe('mailing-1');
+    });
+    it('has no exp claim (permanent link)', () => {
+      const link = makeTrackingLink(options, {
+        attendeeId: 'att-1',
+        emailName: 'welcome',
+        urlLink: '/home',
+        trackingEnabled: true
+      });
+      expect(decode(link).exp).toBeUndefined();
+    });
+  });
+});
+describe('makeUnsubscribeLink', () => {
+  it('builds a link under /unsubscribe with a query-string token', () => {
+    const link = makeUnsubscribeLink(options, {
+      attendeeId: 'att-1',
+      emailName: 'welcome',
+      emailAddress: 'a@b.com'
+    });
+    expect(link.startsWith('https://example.com/unsubscribe?token=')).toBe(true);
+  });
+  it('includes the instance name in the token', () => {
+    const link = makeUnsubscribeLink(options, {
+      attendeeId: 'att-1',
+      emailName: 'welcome',
+      emailAddress: 'a@b.com'
+    });
+    expect(decodeQueryToken(link).instance_name).toBe('my-instance');
+  });
+  it('includes the attendee id in the token', () => {
+    const link = makeUnsubscribeLink(options, {
+      attendeeId: 'att-1',
+      emailName: 'welcome',
+      emailAddress: 'a@b.com'
+    });
+    expect(decodeQueryToken(link).attendee_id).toBe('att-1');
+  });
+  it('includes the email address in the token', () => {
+    const link = makeUnsubscribeLink(options, {
+      attendeeId: 'att-1',
+      emailName: 'welcome',
+      emailAddress: 'a@b.com'
+    });
+    expect(decodeQueryToken(link).email_address).toBe('a@b.com');
+  });
+  it('includes the email name in the token', () => {
+    const link = makeUnsubscribeLink(options, {
+      attendeeId: 'att-1',
+      emailName: 'welcome',
+      emailAddress: 'a@b.com'
+    });
+    expect(decodeQueryToken(link).email_name).toBe('welcome');
+  });
+  it('has no exp claim -- an unsubscribe link never expires', () => {
+    const link = makeUnsubscribeLink(options, {
+      attendeeId: 'att-1',
+      emailName: 'welcome',
+      emailAddress: 'a@b.com'
+    });
+    expect(decodeQueryToken(link).exp).toBeUndefined();
+  });
+});
+describe('makeRegistrationLink', () => {
+  it('builds a link under /register/{token}', () => {
+    const link = makeRegistrationLink(options, {
+      attendeeId: 'att-1'
+    });
+    expect(link.startsWith('https://example.com/register/')).toBe(true);
+  });
+  it('includes the attendee id in the token', () => {
+    const link = makeRegistrationLink(options, {
+      attendeeId: 'att-1'
+    });
+    expect(decode(link).attendee_id).toBe('att-1');
+  });
+  it('includes the instance name in the token', () => {
+    const link = makeRegistrationLink(options, {
+      attendeeId: 'att-1'
+    });
+    expect(decode(link).instance_name).toBe('my-instance');
+  });
+  it('defaults session_type to "register"', () => {
+    const link = makeRegistrationLink(options, {
+      attendeeId: 'att-1'
+    });
+    expect(decode(link).session_type).toBe('register');
+  });
+  it('uses a custom session_type when provided', () => {
+    const link = makeRegistrationLink(options, {
+      attendeeId: 'att-1',
+      sessionType: 'edit'
+    });
+    expect(decode(link).session_type).toBe('edit');
+  });
+  it('defaults flags to an empty object', () => {
+    const link = makeRegistrationLink(options, {
+      attendeeId: 'att-1'
+    });
+    expect(decode(link).flags).toEqual({});
+  });
+  it('passes custom flags through', () => {
+    const link = makeRegistrationLink(options, {
+      attendeeId: 'att-1',
+      flags: {
+        skipPayment: true
+      }
+    });
+    expect(decode(link).flags).toEqual({
+      skipPayment: true
+    });
+  });
+  it('omits the email claim entirely when not provided', () => {
+    const link = makeRegistrationLink(options, {
+      attendeeId: 'att-1'
+    });
+    expect(decode(link).email).toBeUndefined();
+  });
+  it('includes the email name/mailing id when provided', () => {
+    const link = makeRegistrationLink(options, {
+      attendeeId: 'att-1',
+      email: {
+        name: 'welcome',
+        mailingId: 'mailing-1'
+      }
+    });
+    expect(decode(link).email).toEqual({
+      name: 'welcome',
+      mailing_id: 'mailing-1'
+    });
+  });
+  it('defaults to a 15 day expiry', () => {
+    const before = Math.floor(Date.now() / 1000);
+    const link = makeRegistrationLink(options, {
+      attendeeId: 'att-1'
+    });
+    const fifteenDays = 15 * 24 * 60 * 60;
+    expect(decode(link).exp).toBeGreaterThanOrEqual(before + fifteenDays);
+    expect(decode(link).exp).toBeLessThanOrEqual(before + fifteenDays + 1);
+  });
+  it('uses a custom expiry when provided', () => {
+    const before = Math.floor(Date.now() / 1000);
+    const link = makeRegistrationLink(options, {
+      attendeeId: 'att-1',
+      expiresInSeconds: 3600
+    });
+    expect(decode(link).exp).toBeGreaterThanOrEqual(before + 3600);
+    expect(decode(link).exp).toBeLessThanOrEqual(before + 3601);
+  });
+});
+describe('makeWalletLink', () => {
+  it('builds an unsigned /wallet/{attendeeId} link', () => {
+    expect(makeWalletLink(options, 'att-1')).toBe('https://example.com/wallet/att-1');
+  });
+});
+describe('makeGoogleWalletLink', () => {
+  it('builds an unsigned /google-wallet/{attendeeId} link', () => {
+    expect(makeGoogleWalletLink(options, 'att-1')).toBe('https://example.com/google-wallet/att-1');
+  });
+});
+describe('makeQrCodeLink', () => {
+  it('builds a link under /qr/', () => {
+    const link = makeQrCodeLink(options, {
+      content: 'WAR-140'
+    });
+    expect(link.startsWith('https://example.com/qr/?')).toBe(true);
+  });
+  it('encodes the given content', () => {
+    const url = new URL(makeQrCodeLink(options, {
+      content: 'WAR-140'
+    }));
+    expect(url.searchParams.get('content')).toBe('WAR-140');
+  });
+  it('defaults size to 600', () => {
+    const url = new URL(makeQrCodeLink(options, {
+      content: 'WAR-140'
+    }));
+    expect(url.searchParams.get('size')).toBe('600');
+  });
+  it('defaults background to white', () => {
+    const url = new URL(makeQrCodeLink(options, {
+      content: 'WAR-140'
+    }));
+    expect(url.searchParams.get('background')).toBe('white');
+  });
+  it('defaults body to black', () => {
+    const url = new URL(makeQrCodeLink(options, {
+      content: 'WAR-140'
+    }));
+    expect(url.searchParams.get('body')).toBe('black');
+  });
+  it('defaults corners to black', () => {
+    const url = new URL(makeQrCodeLink(options, {
+      content: 'WAR-140'
+    }));
+    expect(url.searchParams.get('corners')).toBe('black');
+  });
+  it('defaults fancy to 0', () => {
+    const url = new URL(makeQrCodeLink(options, {
+      content: 'WAR-140'
+    }));
+    expect(url.searchParams.get('fancy')).toBe('0');
+  });
+  it('applies a custom size', () => {
+    const url = new URL(makeQrCodeLink(options, {
+      content: 'WAR-140',
+      size: 300
+    }));
+    expect(url.searchParams.get('size')).toBe('300');
+  });
+  it('applies custom background/body/corners colors', () => {
+    const url = new URL(makeQrCodeLink(options, {
+      content: 'WAR-140',
+      background: 'red',
+      body: 'blue',
+      corners: 'green'
+    }));
+    expect(url.searchParams.get('background')).toBe('red');
+    expect(url.searchParams.get('body')).toBe('blue');
+    expect(url.searchParams.get('corners')).toBe('green');
+  });
+  it('applies a custom fancy flag', () => {
+    const url = new URL(makeQrCodeLink(options, {
+      content: 'WAR-140',
+      fancy: 1
+    }));
+    expect(url.searchParams.get('fancy')).toBe('1');
+  });
+});

package/dist/lib/index.d.ts

@@ -7,3 +7,5 @@ export * from './translate';
 export * from './headers';
 export * from './csrf';
 export * from './tokens';
+export * from './email-links';
+export * from './email-handlebars';

package/dist/lib/index.js

@@ -6,4 +6,6 @@ export * as theme from './theme';
 export * from './translate';
 export * from './headers';
 export * from './csrf';
-export * from './tokens';
+export * from './tokens';
+export * from './email-links';
+export * from './email-handlebars';

package/dist/lib/tokens.d.ts

@@ -27,6 +27,12 @@ export type TrackingToken = {
     target: string;
     mailingId: string | null;
 };
+/**
+ * Sign a payload as an HS256 JWS, mirroring
+ * FrontendConfig.encode_jws on the backend -- same shared secret, same
+ * compact-JWS format, so tokens minted here verify there and vice versa.
+ */
+export declare function encodeJWS(payload: Record<string, unknown>, secret: string, expiresInSeconds?: number): string;
 export declare function parseRegistrationToken(tokenString: string | undefined, options: TokenOptions): Result<TokenValidationError, RegistrationToken>;
 export declare function parseTrackingToken(tokenString: string | undefined, options: TokenOptions): Result<TokenValidationError, TrackingToken>;
 export declare function parseUnsubscribeToken(tokenString: string | undefined, options: TokenOptions): Result<TokenValidationError, {
@@ -39,6 +45,20 @@ export declare function parseEmailHtmlToken(tokenString: string | undefined, opt
     emailName: string;
     mailingId?: string;
 }>;
+export type EmailViewToken = {
+    attendeeId: string;
+    emailName: string;
+    mailingId?: string;
+    purpose: 'view' | 'render';
+};
+/**
+ * Parses a /email/{mail_name}/{token} token. `purpose` -- not the
+ * request's Accept header -- is what a route should trust to decide
+ * whether to return a human-facing HTML page ("view") or the full
+ * structured render payload ("render", minted short-lived and used
+ * server-to-server only). See FrontendConfig.make_email_view_link.
+ */
+export declare function parseEmailViewToken(tokenString: string | undefined, options: TokenOptions): Result<TokenValidationError, EmailViewToken>;
 export declare function readRegistrationToken(getCookie: CookieGetter, options: TokenOptions & RegistrationTokenOptions): Result<TokenValidationError, RegistrationToken>;
 export declare function storeRegistrationToken(token: string, setCookie: CookieSetter, options?: RegistrationTokenOptions): void;
 export declare function deleteRegistrationToken(deleteCookie: CookieRemover, options?: RegistrationTokenOptions): void;

package/dist/lib/tokens.js

@@ -10,6 +10,29 @@ function parseJWS(tokenString, options) {
   if (!signatureIsValid) return failure('token_invalid');
   return success(jws.decode(tokenString));
 }
+
+/**
+ * Sign a payload as an HS256 JWS, mirroring
+ * FrontendConfig.encode_jws on the backend -- same shared secret, same
+ * compact-JWS format, so tokens minted here verify there and vice versa.
+ */
+export function encodeJWS(payload, secret, expiresInSeconds) {
+  const finalPayload = expiresInSeconds ? {
+    ...payload,
+    exp: Math.floor(Date.now() / 1000) + expiresInSeconds
+  } : payload;
+  // typ: 'JWT' matters beyond convention here -- jws.decode() only parses
+  // the payload as JSON (rather than leaving it a raw string) when this is
+  // set, and the backend's authlib-signed tokens always set it too.
+  return jws.sign({
+    header: {
+      alg: 'HS256',
+      typ: 'JWT'
+    },
+    payload: finalPayload,
+    secret
+  });
+}
 export function parseRegistrationToken(tokenString, options) {
   const tokenResult = parseJWS(tokenString, options);
   if (!tokenResult.success) return tokenResult;
@@ -75,6 +98,31 @@ export function parseEmailHtmlToken(tokenString, options) {
     mailingId: payload.mailing_id ?? undefined
   });
 }
+/**
+ * Parses a /email/{mail_name}/{token} token. `purpose` -- not the
+ * request's Accept header -- is what a route should trust to decide
+ * whether to return a human-facing HTML page ("view") or the full
+ * structured render payload ("render", minted short-lived and used
+ * server-to-server only). See FrontendConfig.make_email_view_link.
+ */
+export function parseEmailViewToken(tokenString, options) {
+  const tokenResult = parseJWS(tokenString, options);
+  if (!tokenResult.success) return tokenResult;
+  const payload = tokenResult.data.payload;
+  if (payload.instance_name !== options.instanceName || typeof payload.attendee_id !== 'string' || typeof payload.email_name !== 'string' || payload.mailing_id != undefined && typeof payload.mailing_id !== 'string' || payload.purpose !== 'view' && payload.purpose !== 'render' || typeof payload.exp !== 'number') {
+    return failure('token_invalid');
+  }
+  const now = new Date();
+  const expires = new Date(payload.exp * 1000);
+  const isExpired = now >= expires;
+  if (isExpired) return failure('token_expired');
+  return success({
+    attendeeId: payload.attendee_id,
+    emailName: payload.email_name,
+    mailingId: payload.mailing_id ?? undefined,
+    purpose: payload.purpose
+  });
+}
 export function readRegistrationToken(getCookie, options) {
   const {
     registrationTokenCookieName = REGISTRATION_TOKEN_COOKIE_NAME