perspectapi-ts-sdk 2.3.4 → 2.4.0

package/dist/index.d.mts

@@ -276,6 +276,8 @@ interface Content {
     slug_prefix?: string;
     pageStatus: ContentStatus;
     pageType: ContentType;
+    media?: MediaItem[] | MediaItem[][];
+    image?: string;
     userId?: number;
     organizationId?: number;
     createdAt: string;
@@ -376,6 +378,7 @@ interface BlogPost {
     content?: string;
     excerpt?: string;
     image?: string;
+    media?: MediaItem[] | MediaItem[][];
     published?: boolean;
     created_at?: string;
     updated_at?: string;
@@ -1988,6 +1991,32 @@ declare class NewsletterClient extends BaseClient {
         message: string;
         sent: boolean;
     }>>;
+    /**
+     * Track email open event.
+     * Called by client sites when their tracking pixel route is hit.
+     * The client site serves the pixel and calls this to record the open.
+     * @param siteName - The site name
+     * @param token - The tracking token from the pixel URL
+     */
+    trackOpen(siteName: string, token: string): Promise<ApiResponse<{
+        success: boolean;
+    }>>;
+    /**
+     * Track link click event.
+     * Called by client sites when their click tracking route is hit.
+     * The client site redirects to the destination and calls this to record the click.
+     * @param siteName - The site name
+     * @param token - The tracking token from the click URL
+     * @param url - The destination URL that was clicked
+     */
+    trackClick(siteName: string, token: string, url: string): Promise<ApiResponse<{
+        success: boolean;
+    }>>;
+    /**
+     * Get the 1x1 transparent GIF pixel as a Uint8Array.
+     * Client sites can use this to serve the tracking pixel response.
+     */
+    static getTrackingPixel(): Uint8Array;
 }
 
 /**
@@ -2283,7 +2312,7 @@ declare const transformProduct: (perspectProduct: any, logger?: LoaderLogger) =>
 /**
  * Transform PerspectAPI content payload to a simplified BlogPost structure.
  */
-declare const transformContent: (perspectContent: Content | (Content & Record<string, unknown>)) => BlogPost;
+declare const transformContent: (perspectContent: Content | (Content & Record<string, unknown>), logger?: LoaderLogger) => BlogPost;
 interface LoaderOptions {
     /**
      * Pre-configured PerspectAPI client. Pass null/undefined to force fallback behaviour.

package/dist/index.d.ts

@@ -276,6 +276,8 @@ interface Content {
     slug_prefix?: string;
     pageStatus: ContentStatus;
     pageType: ContentType;
+    media?: MediaItem[] | MediaItem[][];
+    image?: string;
     userId?: number;
     organizationId?: number;
     createdAt: string;
@@ -376,6 +378,7 @@ interface BlogPost {
     content?: string;
     excerpt?: string;
     image?: string;
+    media?: MediaItem[] | MediaItem[][];
     published?: boolean;
     created_at?: string;
     updated_at?: string;
@@ -1988,6 +1991,32 @@ declare class NewsletterClient extends BaseClient {
         message: string;
         sent: boolean;
     }>>;
+    /**
+     * Track email open event.
+     * Called by client sites when their tracking pixel route is hit.
+     * The client site serves the pixel and calls this to record the open.
+     * @param siteName - The site name
+     * @param token - The tracking token from the pixel URL
+     */
+    trackOpen(siteName: string, token: string): Promise<ApiResponse<{
+        success: boolean;
+    }>>;
+    /**
+     * Track link click event.
+     * Called by client sites when their click tracking route is hit.
+     * The client site redirects to the destination and calls this to record the click.
+     * @param siteName - The site name
+     * @param token - The tracking token from the click URL
+     * @param url - The destination URL that was clicked
+     */
+    trackClick(siteName: string, token: string, url: string): Promise<ApiResponse<{
+        success: boolean;
+    }>>;
+    /**
+     * Get the 1x1 transparent GIF pixel as a Uint8Array.
+     * Client sites can use this to serve the tracking pixel response.
+     */
+    static getTrackingPixel(): Uint8Array;
 }
 
 /**
@@ -2283,7 +2312,7 @@ declare const transformProduct: (perspectProduct: any, logger?: LoaderLogger) =>
 /**
  * Transform PerspectAPI content payload to a simplified BlogPost structure.
  */
-declare const transformContent: (perspectContent: Content | (Content & Record<string, unknown>)) => BlogPost;
+declare const transformContent: (perspectContent: Content | (Content & Record<string, unknown>), logger?: LoaderLogger) => BlogPost;
 interface LoaderOptions {
     /**
      * Pre-configured PerspectAPI client. Pass null/undefined to force fallback behaviour.

package/dist/index.js

@@ -2076,6 +2076,86 @@ var NewsletterClient = class extends BaseClient {
       data
     );
   }
+  // ============================================
+  // Tracking methods (for first-party tracking)
+  // ============================================
+  /**
+   * Track email open event.
+   * Called by client sites when their tracking pixel route is hit.
+   * The client site serves the pixel and calls this to record the open.
+   * @param siteName - The site name
+   * @param token - The tracking token from the pixel URL
+   */
+  async trackOpen(siteName, token) {
+    return this.http.post(
+      this.buildPath(this.newsletterEndpoint(siteName, `/newsletter/track/open/${encodeURIComponent(token)}`))
+    );
+  }
+  /**
+   * Track link click event.
+   * Called by client sites when their click tracking route is hit.
+   * The client site redirects to the destination and calls this to record the click.
+   * @param siteName - The site name
+   * @param token - The tracking token from the click URL
+   * @param url - The destination URL that was clicked
+   */
+  async trackClick(siteName, token, url) {
+    return this.http.post(
+      this.buildPath(this.newsletterEndpoint(siteName, `/newsletter/track/click/${encodeURIComponent(token)}`)),
+      { url }
+    );
+  }
+  /**
+   * Get the 1x1 transparent GIF pixel as a Uint8Array.
+   * Client sites can use this to serve the tracking pixel response.
+   */
+  static getTrackingPixel() {
+    return new Uint8Array([
+      71,
+      73,
+      70,
+      56,
+      57,
+      97,
+      1,
+      0,
+      1,
+      0,
+      128,
+      0,
+      0,
+      255,
+      255,
+      255,
+      0,
+      0,
+      0,
+      33,
+      249,
+      4,
+      1,
+      0,
+      0,
+      0,
+      0,
+      44,
+      0,
+      0,
+      0,
+      0,
+      1,
+      0,
+      1,
+      0,
+      0,
+      2,
+      2,
+      68,
+      1,
+      0,
+      59
+    ]);
+  }
 };
 
 // src/perspect-api-client.ts
@@ -2323,6 +2403,29 @@ var normalizeMediaList = (rawMedia) => {
   }
   return rawMedia.filter(isMediaItem);
 };
+var describeMedia = (rawMedia) => {
+  const isArray = Array.isArray(rawMedia);
+  const nestedArray = isArray && rawMedia.length > 0 && Array.isArray(rawMedia[0]);
+  const rawCount = isArray ? rawMedia.length : 0;
+  const flattenedCount = nestedArray ? rawMedia.flat().length : rawCount;
+  const firstSample = (() => {
+    if (!isArray) {
+      return rawMedia;
+    }
+    if (nestedArray) {
+      const firstGroup = rawMedia.find(Array.isArray);
+      return firstGroup ? firstGroup[0] : void 0;
+    }
+    return rawMedia[0];
+  })();
+  return {
+    isArray,
+    nestedArray,
+    rawCount,
+    flattenedCount,
+    sampleType: firstSample ? typeof firstSample : "undefined"
+  };
+};
 var normalizeQueryParamList = (value) => {
   if (value === void 0 || value === null) {
     return void 0;
@@ -2365,9 +2468,28 @@ var transformProduct = (perspectProduct, logger) => {
     ...rawProduct
   };
 };
-var transformContent = (perspectContent) => {
+var transformContent = (perspectContent, logger) => {
   const raw = perspectContent ?? {};
+  const mediaItems = normalizeMediaList(raw.media);
+  const image = raw.image;
+  if (raw.media !== void 0) {
+    const mediaDetails = describeMedia(raw.media);
+    const slugOrId = raw.slug ?? raw.id;
+    if (mediaItems.length === 0 && (mediaDetails.rawCount > 0 || mediaDetails.flattenedCount > 0)) {
+      log(logger, "debug", "[PerspectAPI] Content media present but failed normalization", {
+        slug: slugOrId,
+        ...mediaDetails
+      });
+    } else {
+      log(logger, "debug", "[PerspectAPI] Content media normalization", {
+        slug: slugOrId,
+        ...mediaDetails,
+        normalizedCount: mediaItems.length
+      });
+    }
+  }
   return {
+    ...raw,
     id: typeof raw.id === "string" ? raw.id : String(raw.id ?? ""),
     slug: raw.slug ?? `post-${raw.id ?? "unknown"}`,
     slug_prefix: raw.slug_prefix ?? (raw.pageType === "post" ? "blog" : "page"),
@@ -2382,7 +2504,8 @@ var transformContent = (perspectContent) => {
     published_date: raw.published_date,
     author: raw.author,
     tags: raw.tags,
-    image: raw.image
+    image,
+    media: mediaItems
   };
 };
 var getDefaultFallbackProducts = (siteName) => {
@@ -2568,7 +2691,7 @@ async function loadPages(options) {
     if (!response.data) {
       return [];
     }
-    return response.data.map((content) => transformContent(content));
+    return response.data.map((content) => transformContent(content, logger));
   } catch (error) {
     log(logger, "error", "[PerspectAPI] Error loading pages", error);
     return [];
@@ -2602,7 +2725,7 @@ async function loadPosts(options) {
       log(logger, "warn", "[PerspectAPI] Posts response missing data");
       return [];
     }
-    return response.data.map((content) => transformContent(content));
+    return response.data.map((content) => transformContent(content, logger));
   } catch (error) {
     log(logger, "error", "[PerspectAPI] Error loading posts", error);
     return [];
@@ -2628,7 +2751,7 @@ async function loadContentBySlug(options) {
       log(logger, "warn", `[PerspectAPI] Content not found for slug "${slug}"`);
       return null;
     }
-    return transformContent(response.data);
+    return transformContent(response.data, logger);
   } catch (error) {
     log(logger, "error", `[PerspectAPI] Error loading content slug "${slug}"`, error);
     return null;

package/dist/index.mjs

@@ -2015,6 +2015,86 @@ var NewsletterClient = class extends BaseClient {
       data
     );
   }
+  // ============================================
+  // Tracking methods (for first-party tracking)
+  // ============================================
+  /**
+   * Track email open event.
+   * Called by client sites when their tracking pixel route is hit.
+   * The client site serves the pixel and calls this to record the open.
+   * @param siteName - The site name
+   * @param token - The tracking token from the pixel URL
+   */
+  async trackOpen(siteName, token) {
+    return this.http.post(
+      this.buildPath(this.newsletterEndpoint(siteName, `/newsletter/track/open/${encodeURIComponent(token)}`))
+    );
+  }
+  /**
+   * Track link click event.
+   * Called by client sites when their click tracking route is hit.
+   * The client site redirects to the destination and calls this to record the click.
+   * @param siteName - The site name
+   * @param token - The tracking token from the click URL
+   * @param url - The destination URL that was clicked
+   */
+  async trackClick(siteName, token, url) {
+    return this.http.post(
+      this.buildPath(this.newsletterEndpoint(siteName, `/newsletter/track/click/${encodeURIComponent(token)}`)),
+      { url }
+    );
+  }
+  /**
+   * Get the 1x1 transparent GIF pixel as a Uint8Array.
+   * Client sites can use this to serve the tracking pixel response.
+   */
+  static getTrackingPixel() {
+    return new Uint8Array([
+      71,
+      73,
+      70,
+      56,
+      57,
+      97,
+      1,
+      0,
+      1,
+      0,
+      128,
+      0,
+      0,
+      255,
+      255,
+      255,
+      0,
+      0,
+      0,
+      33,
+      249,
+      4,
+      1,
+      0,
+      0,
+      0,
+      0,
+      44,
+      0,
+      0,
+      0,
+      0,
+      1,
+      0,
+      1,
+      0,
+      0,
+      2,
+      2,
+      68,
+      1,
+      0,
+      59
+    ]);
+  }
 };
 
 // src/perspect-api-client.ts
@@ -2262,6 +2342,29 @@ var normalizeMediaList = (rawMedia) => {
   }
   return rawMedia.filter(isMediaItem);
 };
+var describeMedia = (rawMedia) => {
+  const isArray = Array.isArray(rawMedia);
+  const nestedArray = isArray && rawMedia.length > 0 && Array.isArray(rawMedia[0]);
+  const rawCount = isArray ? rawMedia.length : 0;
+  const flattenedCount = nestedArray ? rawMedia.flat().length : rawCount;
+  const firstSample = (() => {
+    if (!isArray) {
+      return rawMedia;
+    }
+    if (nestedArray) {
+      const firstGroup = rawMedia.find(Array.isArray);
+      return firstGroup ? firstGroup[0] : void 0;
+    }
+    return rawMedia[0];
+  })();
+  return {
+    isArray,
+    nestedArray,
+    rawCount,
+    flattenedCount,
+    sampleType: firstSample ? typeof firstSample : "undefined"
+  };
+};
 var normalizeQueryParamList = (value) => {
   if (value === void 0 || value === null) {
     return void 0;
@@ -2304,9 +2407,28 @@ var transformProduct = (perspectProduct, logger) => {
     ...rawProduct
   };
 };
-var transformContent = (perspectContent) => {
+var transformContent = (perspectContent, logger) => {
   const raw = perspectContent ?? {};
+  const mediaItems = normalizeMediaList(raw.media);
+  const image = raw.image;
+  if (raw.media !== void 0) {
+    const mediaDetails = describeMedia(raw.media);
+    const slugOrId = raw.slug ?? raw.id;
+    if (mediaItems.length === 0 && (mediaDetails.rawCount > 0 || mediaDetails.flattenedCount > 0)) {
+      log(logger, "debug", "[PerspectAPI] Content media present but failed normalization", {
+        slug: slugOrId,
+        ...mediaDetails
+      });
+    } else {
+      log(logger, "debug", "[PerspectAPI] Content media normalization", {
+        slug: slugOrId,
+        ...mediaDetails,
+        normalizedCount: mediaItems.length
+      });
+    }
+  }
   return {
+    ...raw,
     id: typeof raw.id === "string" ? raw.id : String(raw.id ?? ""),
     slug: raw.slug ?? `post-${raw.id ?? "unknown"}`,
     slug_prefix: raw.slug_prefix ?? (raw.pageType === "post" ? "blog" : "page"),
@@ -2321,7 +2443,8 @@ var transformContent = (perspectContent) => {
     published_date: raw.published_date,
     author: raw.author,
     tags: raw.tags,
-    image: raw.image
+    image,
+    media: mediaItems
   };
 };
 var getDefaultFallbackProducts = (siteName) => {
@@ -2507,7 +2630,7 @@ async function loadPages(options) {
     if (!response.data) {
       return [];
     }
-    return response.data.map((content) => transformContent(content));
+    return response.data.map((content) => transformContent(content, logger));
   } catch (error) {
     log(logger, "error", "[PerspectAPI] Error loading pages", error);
     return [];
@@ -2541,7 +2664,7 @@ async function loadPosts(options) {
       log(logger, "warn", "[PerspectAPI] Posts response missing data");
       return [];
     }
-    return response.data.map((content) => transformContent(content));
+    return response.data.map((content) => transformContent(content, logger));
   } catch (error) {
     log(logger, "error", "[PerspectAPI] Error loading posts", error);
     return [];
@@ -2567,7 +2690,7 @@ async function loadContentBySlug(options) {
       log(logger, "warn", `[PerspectAPI] Content not found for slug "${slug}"`);
       return null;
     }
-    return transformContent(response.data);
+    return transformContent(response.data, logger);
   } catch (error) {
     log(logger, "error", `[PerspectAPI] Error loading content slug "${slug}"`, error);
     return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "perspectapi-ts-sdk",
-  "version": "2.3.4",
+  "version": "2.4.0",
   "description": "TypeScript SDK for PerspectAPI - Cloudflare Workers compatible",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/client/newsletter-client.ts

@@ -380,4 +380,56 @@ export class NewsletterClient extends BaseClient {
       data
     );
   }
+
+  // ============================================
+  // Tracking methods (for first-party tracking)
+  // ============================================
+
+  /**
+   * Track email open event.
+   * Called by client sites when their tracking pixel route is hit.
+   * The client site serves the pixel and calls this to record the open.
+   * @param siteName - The site name
+   * @param token - The tracking token from the pixel URL
+   */
+  async trackOpen(
+    siteName: string,
+    token: string
+  ): Promise<ApiResponse<{ success: boolean }>> {
+    return this.http.post(
+      this.buildPath(this.newsletterEndpoint(siteName, `/newsletter/track/open/${encodeURIComponent(token)}`))
+    );
+  }
+
+  /**
+   * Track link click event.
+   * Called by client sites when their click tracking route is hit.
+   * The client site redirects to the destination and calls this to record the click.
+   * @param siteName - The site name
+   * @param token - The tracking token from the click URL
+   * @param url - The destination URL that was clicked
+   */
+  async trackClick(
+    siteName: string,
+    token: string,
+    url: string
+  ): Promise<ApiResponse<{ success: boolean }>> {
+    return this.http.post(
+      this.buildPath(this.newsletterEndpoint(siteName, `/newsletter/track/click/${encodeURIComponent(token)}`)),
+      { url }
+    );
+  }
+
+  /**
+   * Get the 1x1 transparent GIF pixel as a Uint8Array.
+   * Client sites can use this to serve the tracking pixel response.
+   */
+  static getTrackingPixel(): Uint8Array {
+    return new Uint8Array([
+      0x47, 0x49, 0x46, 0x38, 0x39, 0x61, 0x01, 0x00, 0x01, 0x00, 0x80, 0x00, 0x00,
+      0xff, 0xff, 0xff, 0x00, 0x00, 0x00, 0x21, 0xf9, 0x04, 0x01, 0x00, 0x00, 0x00,
+      0x00, 0x2c, 0x00, 0x00, 0x00, 0x00, 0x01, 0x00, 0x01, 0x00, 0x00, 0x02, 0x02,
+      0x44, 0x01, 0x00, 0x3b,
+    ]);
+  }
 }

package/src/loaders.ts

@@ -72,6 +72,40 @@ const normalizeMediaList = (rawMedia: unknown): MediaItem[] => {
   return (rawMedia as unknown[]).filter(isMediaItem);
 };
 
+const describeMedia = (rawMedia: unknown) => {
+  const isArray = Array.isArray(rawMedia);
+  const nestedArray =
+    isArray &&
+    (rawMedia as unknown[]).length > 0 &&
+    Array.isArray((rawMedia as unknown[])[0]);
+
+  const rawCount = isArray ? (rawMedia as unknown[]).length : 0;
+  const flattenedCount = nestedArray
+    ? (rawMedia as unknown[]).flat().length
+    : rawCount;
+
+  const firstSample = (() => {
+    if (!isArray) {
+      return rawMedia;
+    }
+    if (nestedArray) {
+      const firstGroup = (rawMedia as unknown[]).find(Array.isArray) as
+        | unknown[]
+        | undefined;
+      return firstGroup ? firstGroup[0] : undefined;
+    }
+    return (rawMedia as unknown[])[0];
+  })();
+
+  return {
+    isArray,
+    nestedArray,
+    rawCount,
+    flattenedCount,
+    sampleType: firstSample ? typeof firstSample : 'undefined'
+  };
+};
+
 const normalizeQueryParamList = (
   value: string | number | Array<string | number> | undefined
 ): string | undefined => {
@@ -148,11 +182,33 @@ export const transformProduct = (
  * Transform PerspectAPI content payload to a simplified BlogPost structure.
  */
 export const transformContent = (
-  perspectContent: Content | (Content & Record<string, unknown>)
+  perspectContent: Content | (Content & Record<string, unknown>),
+  logger?: LoaderLogger
 ): BlogPost => {
   const raw = perspectContent ?? ({} as Content);
+  const mediaItems = normalizeMediaList((raw as any).media);
+  const image = (raw as any).image;
+
+  if ((raw as any).media !== undefined) {
+    const mediaDetails = describeMedia((raw as any).media);
+    const slugOrId = raw.slug ?? raw.id;
+
+    if (mediaItems.length === 0 && (mediaDetails.rawCount > 0 || mediaDetails.flattenedCount > 0)) {
+      log(logger, 'debug', '[PerspectAPI] Content media present but failed normalization', {
+        slug: slugOrId,
+        ...mediaDetails
+      });
+    } else {
+      log(logger, 'debug', '[PerspectAPI] Content media normalization', {
+        slug: slugOrId,
+        ...mediaDetails,
+        normalizedCount: mediaItems.length
+      });
+    }
+  }
 
   return {
+    ...raw,
     id: typeof raw.id === 'string' ? raw.id : String(raw.id ?? ''),
     slug: raw.slug ?? `post-${raw.id ?? 'unknown'}`,
     slug_prefix:
@@ -172,7 +228,8 @@ export const transformContent = (
     published_date: (raw as any).published_date,
     author: (raw as any).author,
     tags: (raw as any).tags,
-    image: (raw as any).image
+    image,
+    media: mediaItems
   };
 };
 
@@ -463,7 +520,7 @@ export async function loadPages(
       return [];
     }
 
-    return response.data.map(content => transformContent(content));
+    return response.data.map(content => transformContent(content, logger));
   } catch (error) {
     log(logger, 'error', '[PerspectAPI] Error loading pages', error);
     return [];
@@ -510,7 +567,7 @@ export async function loadPosts(
       return [];
     }
 
-    return response.data.map(content => transformContent(content));
+    return response.data.map(content => transformContent(content, logger));
   } catch (error) {
     log(logger, 'error', '[PerspectAPI] Error loading posts', error);
     return [];
@@ -551,7 +608,7 @@ export async function loadContentBySlug(
       return null;
     }
 
-    return transformContent(response.data);
+    return transformContent(response.data, logger);
   } catch (error) {
     log(logger, 'error', `[PerspectAPI] Error loading content slug "${slug}"`, error);
     return null;

package/src/types/index.ts

@@ -226,6 +226,8 @@ export interface Content {
   slug_prefix?: string;
   pageStatus: ContentStatus;
   pageType: ContentType;
+  media?: MediaItem[] | MediaItem[][];
+  image?: string;
   userId?: number;
   organizationId?: number;
   createdAt: string;
@@ -338,6 +340,7 @@ export interface BlogPost {
   content?: string;
   excerpt?: string;
   image?: string;
+  media?: MediaItem[] | MediaItem[][];
   published?: boolean;
   created_at?: string;
   updated_at?: string;