@saltcorn/meta-marketing-api 0.1.0 → 0.1.2

package/index.js

@@ -24,6 +24,13 @@ const {
   getAdCreatives,
   getAdCreative,
   getAdPreview,
+  getAdText,
+  getAdHeadline,
+  getAdBody,
+  getAdMedia,
+  getAdMediaType,
+  getAdMediaUrl,
+  getPageAccessToken,
   getInsights,
   getInsightsAsync,
   exchangeLongLivedToken,
@@ -383,6 +390,72 @@ module.exports = {
         { name: "query", type: "JSON" },
       ],
     },
+    get_meta_ad_headline: {
+      async run(ad, cfgOverRide) {
+        return await getAdHeadline(ad, { ...cfg, ...cfgOverRide });
+      },
+      isAsync: true,
+      description:
+        "Get the headline of an ad, wherever Meta keeps it for that kind of ad. Takes an ad id or an ad row that already has its creative.",
+      arguments: [{ name: "ad", type: "String" }],
+    },
+    get_meta_ad_body: {
+      async run(ad, cfgOverRide) {
+        return await getAdBody(ad, { ...cfg, ...cfgOverRide });
+      },
+      isAsync: true,
+      description:
+        "Get the primary text of an ad, the longer wording above the image. Takes an ad id or an ad row that already has its creative.",
+      arguments: [{ name: "ad", type: "String" }],
+    },
+    get_meta_ad_text: {
+      async run(ad, cfgOverRide) {
+        return await getAdText(ad, { ...cfg, ...cfgOverRide });
+      },
+      isAsync: true,
+      description:
+        "Get the headline and the primary text of an ad together, as { headline, body }, in one read",
+      arguments: [{ name: "ad", type: "String" }],
+    },
+    get_meta_ad_media: {
+      async run(ad, opts, cfgOverRide) {
+        return await getAdMedia(ad, { ...cfg, ...cfgOverRide }, opts || {});
+      },
+      isAsync: true,
+      description:
+        "Get what an ad is made of and where to download it: { type, carousel, media }, where type is image, video, mixed or unknown and each entry in media has a url. Takes an ad id or an ad row that already has its creative. Set resolve_urls false in the options to only work out the type, without reading the address of every file.",
+      arguments: [
+        { name: "ad", type: "String" },
+        { name: "opts", type: "JSON" },
+      ],
+    },
+    get_meta_ad_media_type: {
+      async run(ad, cfgOverRide) {
+        return await getAdMediaType(ad, { ...cfg, ...cfgOverRide });
+      },
+      isAsync: true,
+      description:
+        "Whether an ad is an image, a video, mixed or unknown. Takes an ad id or an ad row that already has its creative.",
+      arguments: [{ name: "ad", type: "String" }],
+    },
+    get_meta_ad_media_url: {
+      async run(ad, cfgOverRide) {
+        return await getAdMediaUrl(ad, { ...cfg, ...cfgOverRide });
+      },
+      isAsync: true,
+      description:
+        "The address of the picture or the film in an ad, ready to download. Video addresses are signed and short lived, so download the file straight away.",
+      arguments: [{ name: "ad", type: "String" }],
+    },
+    get_meta_page_access_token: {
+      async run(pageId, cfgOverRide) {
+        return await getPageAccessToken(pageId, { ...cfg, ...cfgOverRide });
+      },
+      isAsync: true,
+      description:
+        "A token for one of your pages, or nothing when your access token has no say over that page. Use it to check why an ad that boosts a page post shows nothing.",
+      arguments: [{ name: "pageId", type: "String" }],
+    },
     get_meta_ad_preview: {
       async run(adId, adFormat, cfgOverRide) {
         return await getAdPreview(adId, adFormat, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saltcorn/meta-marketing-api",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Read ads on Facebook and Instagram with the Meta Marketing API",
   "main": "index.js",
   "dependencies": {

package/tests/api.test.js

@@ -6,6 +6,10 @@ const {
   isTransientError,
   insightsFields,
   DEFAULT_FIELDS,
+  creativeHeadlines,
+  creativeBodies,
+  creativeMedia,
+  mediaType,
 } = require("../api");
 
 describe("query string encoding", () => {
@@ -92,3 +96,222 @@ describe("default fields", () => {
     });
   });
 });
+
+describe("finding the headline on a creative", () => {
+  it("reads the headline of a link ad", () => {
+    expect(
+      creativeHeadlines({
+        object_story_spec: {
+          link_data: { name: "Half price today", message: "Primary text" },
+        },
+      })
+    ).toEqual(["Half price today"]);
+  });
+  it("reads the headline of a video ad", () => {
+    expect(
+      creativeHeadlines({ object_story_spec: { video_data: { title: "Watch" } } })
+    ).toEqual(["Watch"]);
+  });
+  it("reads the old style title field", () => {
+    expect(creativeHeadlines({ title: "Legacy headline" })).toEqual([
+      "Legacy headline",
+    ]);
+  });
+  it("returns one headline per carousel card", () => {
+    expect(
+      creativeHeadlines({
+        object_story_spec: {
+          link_data: {
+            name: "Our shop",
+            child_attachments: [{ name: "Shoes" }, { name: "Hats" }],
+          },
+        },
+      })
+    ).toEqual(["Our shop", "Shoes", "Hats"]);
+  });
+  it("returns every headline of a dynamic creative, without repeats", () => {
+    expect(
+      creativeHeadlines({
+        title: "Half price",
+        asset_feed_spec: {
+          titles: [{ text: "Half price" }, { text: "50% off" }],
+        },
+      })
+    ).toEqual(["Half price", "50% off"]);
+  });
+  it("comes back empty when there is no headline to find", () => {
+    expect(creativeHeadlines({ effective_object_story_id: "1_2" })).toEqual([]);
+    expect(creativeHeadlines(null)).toEqual([]);
+  });
+});
+
+describe("finding the primary text on a creative", () => {
+  it("reads the text above the image of a link ad", () => {
+    expect(
+      creativeBodies({
+        object_story_spec: {
+          link_data: { name: "A headline", message: "The longer wording" },
+        },
+      })
+    ).toEqual(["The longer wording"]);
+  });
+  it("reads the text of video, photo and text only ads", () => {
+    expect(
+      creativeBodies({ object_story_spec: { video_data: { message: "Video" } } })
+    ).toEqual(["Video"]);
+    expect(
+      creativeBodies({ object_story_spec: { photo_data: { caption: "Photo" } } })
+    ).toEqual(["Photo"]);
+    expect(
+      creativeBodies({ object_story_spec: { text_data: { message: "Text" } } })
+    ).toEqual(["Text"]);
+  });
+  it("reads the old style body field", () => {
+    expect(creativeBodies({ body: "Legacy body" })).toEqual(["Legacy body"]);
+  });
+  it("returns every primary text of a dynamic creative, without repeats", () => {
+    expect(
+      creativeBodies({
+        body: "Shop the sale",
+        asset_feed_spec: {
+          bodies: [{ text: "Shop the sale" }, { text: "Everything reduced" }],
+        },
+      })
+    ).toEqual(["Shop the sale", "Everything reduced"]);
+  });
+  it("does not mistake the headline for the primary text", () => {
+    const creative = {
+      title: "A headline",
+      object_story_spec: { link_data: { name: "A headline" } },
+    };
+    expect(creativeBodies(creative)).toEqual([]);
+    expect(creativeHeadlines(creative)).toEqual(["A headline"]);
+  });
+  it("comes back empty when there is no text to find", () => {
+    expect(creativeBodies({ effective_object_story_id: "1_2" })).toEqual([]);
+    expect(creativeBodies(null)).toEqual([]);
+  });
+});
+
+describe("default fields", () => {
+  it("asks for the dynamic creative assets", () => {
+    expect(DEFAULT_FIELDS.adcreative).toContain("asset_feed_spec");
+    expect(DEFAULT_FIELDS.adcreative).toContain("effective_object_story_id");
+  });
+  it("asks for both the headline and the primary text", () => {
+    expect(DEFAULT_FIELDS.adcreative).toContain("title");
+    expect(DEFAULT_FIELDS.adcreative).toContain("body");
+  });
+});
+
+describe("finding the media on a creative", () => {
+  it("reads the film of a video ad, with its still as the thumbnail", () => {
+    const media = creativeMedia({
+      video_id: "77",
+      object_story_spec: {
+        video_data: {
+          video_id: "77",
+          title: "Watch",
+          image_url: "https://example.com/still.jpg",
+          image_hash: "abc",
+        },
+      },
+    });
+    expect(media).toEqual([
+      {
+        kind: "video",
+        video_id: "77",
+        thumbnail_url: "https://example.com/still.jpg",
+        thumbnail_hash: "abc",
+        name: "Watch",
+      },
+    ]);
+    // the still of a film is not a picture of its own
+    expect(mediaType(media)).toBe("video");
+  });
+  it("reads the picture of a link ad", () => {
+    const media = creativeMedia({
+      object_story_spec: {
+        link_data: {
+          name: "Half price",
+          image_hash: "hash1",
+          picture: "https://example.com/pic.jpg",
+          link: "https://example.com",
+        },
+      },
+    });
+    expect(media).toEqual([
+      {
+        kind: "image",
+        url: "https://example.com/pic.jpg",
+        image_hash: "hash1",
+        name: "Half price",
+        link: "https://example.com",
+      },
+    ]);
+    expect(mediaType(media)).toBe("image");
+  });
+  it("reads a photo ad", () => {
+    expect(
+      creativeMedia({
+        object_story_spec: {
+          photo_data: { url: "https://example.com/photo.jpg", image_hash: "h" },
+        },
+      })
+    ).toEqual([
+      { kind: "image", url: "https://example.com/photo.jpg", image_hash: "h" },
+    ]);
+  });
+  it("returns one entry per carousel card, in order", () => {
+    const media = creativeMedia({
+      object_story_spec: {
+        link_data: {
+          image_hash: "cover",
+          child_attachments: [
+            { image_hash: "h1", name: "Shoes" },
+            { video_id: "v2", name: "Hats", picture: "https://x/2.jpg" },
+          ],
+        },
+      },
+    });
+    expect(media.map((m) => m.kind)).toEqual(["image", "video"]);
+    expect(media.map((m) => m.name)).toEqual(["Shoes", "Hats"]);
+    // a carousel with a film in it counts as a mixed ad
+    expect(mediaType(media)).toBe("mixed");
+  });
+  it("reads the assets of a dynamic creative, without repeats", () => {
+    const media = creativeMedia({
+      image_url: "https://example.com/a.jpg",
+      asset_feed_spec: {
+        images: [{ hash: "h1", url: "https://example.com/a.jpg" }],
+        videos: [{ video_id: "v1", thumbnail_url: "https://example.com/t.jpg" }],
+      },
+    });
+    expect(media).toHaveLength(2);
+    expect(mediaType(media)).toBe("mixed");
+  });
+  it("does not repeat the same picture reached by two routes", () => {
+    const media = creativeMedia({
+      image_hash: "h1",
+      image_url: "https://example.com/a.jpg",
+      object_story_spec: {
+        link_data: { image_hash: "h1", picture: "https://example.com/a.jpg" },
+      },
+    });
+    expect(media).toHaveLength(1);
+  });
+  it("comes back empty for an ad that promotes an existing post", () => {
+    expect(creativeMedia({ effective_object_story_id: "1_2" })).toEqual([]);
+    expect(creativeMedia(null)).toEqual([]);
+    expect(mediaType([])).toBe("unknown");
+  });
+});
+
+describe("default fields", () => {
+  it("asks what kind of ad each ad is", () => {
+    const creative = DEFAULT_FIELDS.ad.find((f) => f.startsWith("creative{"));
+    expect(creative).toContain("object_type");
+    expect(creative).toContain("video_id");
+    expect(creative).toContain("image_url");
+  });
+});

package/tests/media.test.js

@@ -0,0 +1,291 @@
+jest.mock("node-fetch");
+const fetch = require("node-fetch");
+const { getAdMedia, getAdMediaType, getAdText } = require("../api");
+
+const cfg = { access_token: "USERTOKEN", max_retries: 0 };
+
+// Answer each call from a list of [what the address must contain, the reply],
+// and keep what was asked so a test can check which token was used
+let calls;
+const serve = (routes) => {
+  calls = [];
+  fetch.mockImplementation(async (url, opts) => {
+    calls.push({ url, auth: opts?.headers?.Authorization });
+    const hit = routes.find(([match]) => url.includes(match));
+    return {
+      status: 200,
+      headers: { get: () => null },
+      text: async () => JSON.stringify(hit ? hit[1] : { error: { code: 100, message: `no route for ${url}` } }),
+    };
+  });
+};
+
+// An ad that boosts a post already on the page: the creative names the page
+// and the post, and carries no media of its own
+const boostedAd = {
+  id: "120242825926110547",
+  name: "Version AI Remake",
+  creative: {
+    id: "782942930901202",
+    object_type: "SHARE",
+    object_story_spec: { page_id: "106755536029753", instagram_user_id: "17841401937168196" },
+    effective_object_story_id: "106755536029753_1333493868811467",
+  },
+};
+
+const videoPost = {
+  permalink_url: "https://facebook.com/post",
+  full_picture: "https://example.com/full.jpg",
+  attachments: {
+    data: [
+      {
+        media_type: "video",
+        media: { image: { src: "https://example.com/still.jpg" } },
+        target: { id: "999" },
+      },
+    ],
+  },
+};
+
+describe("an ad that boosts a page post", () => {
+  it("reads the post with a token for the page", async () => {
+    serve([
+      ["/120242825926110547", { account_id: "1", creative: { ...boostedAd.creative, thumbnail_url: "https://example.com/thumb.jpg" } }],
+      ["/106755536029753?", { access_token: "PAGETOKEN" }],
+      ["/106755536029753_1333493868811467", videoPost],
+      ["/999", { id: "999", source: "https://video.fb/film.mp4", picture: "https://example.com/still.jpg", length: 15 }],
+    ]);
+    const res = await getAdMedia(boostedAd, cfg);
+    expect(res.type).toBe("video");
+    expect(res.from_post).toBe(true);
+    expect(res.story_id).toBe("106755536029753_1333493868811467");
+    expect(res.media).toHaveLength(1);
+    expect(res.media[0].url).toBe("https://video.fb/film.mp4");
+    expect(res.media[0].thumbnail_url).toBe("https://example.com/still.jpg");
+    expect(res.error).toBeUndefined();
+    // the post is read as the page, not as the user
+    const post = calls.find((c) => c.url.includes("106755536029753_1333"));
+    expect(post.auth).toBe("Bearer PAGETOKEN");
+  });
+
+  it("says why when the token has no say over the page", async () => {
+    const ad = {
+      ...boostedAd,
+      creative: {
+        ...boostedAd.creative,
+        object_story_spec: { page_id: "222" },
+        effective_object_story_id: "222_333",
+      },
+    };
+    serve([
+      ["/120242825926110547", { account_id: "1", creative: { ...ad.creative, thumbnail_url: "https://example.com/thumb.jpg" } }],
+      ["/222?", { error: { code: 190, message: "no page access" } }],
+      ["/222_333", { error: { code: 100, message: "Unsupported get request" } }],
+    ]);
+    const res = await getAdMedia(ad, cfg);
+    expect(res.type).toBe("unknown");
+    expect(res.media).toEqual([]);
+    // not silence: the reason, and something to look at
+    expect(res.error).toMatch(/could not read the post 222_333/);
+    expect(res.error).toMatch(/pages_read_engagement/);
+    expect(res.thumbnail_url).toBe("https://example.com/thumb.jpg");
+  });
+});
+
+describe("reading the ad again", () => {
+  it("asks for every media field when handed a creative with none", async () => {
+    serve([
+      ["/120242825926110547", { account_id: "1", creative: { id: "782942930901202", video_id: "555", thumbnail_url: "https://example.com/t.jpg" } }],
+      ["/555", { id: "555", source: "https://video.fb/film.mp4" }],
+    ]);
+    // the caller asked Meta for a narrow set of fields, so image_hash,
+    // video_id and asset_feed_spec were never in the ad we were given
+    const res = await getAdMedia(boostedAd, cfg);
+    expect(res.type).toBe("video");
+    expect(res.media[0].url).toBe("https://video.fb/film.mp4");
+    const asked = calls[0].url;
+    expect(asked).toContain("video_id");
+    expect(asked).toContain("asset_feed_spec");
+    expect(asked).toContain("image_hash");
+  });
+
+  it("does not read the ad again when the creative already has media", async () => {
+    serve([["/act_", { data: [] }]]);
+    const ad = {
+      id: "1",
+      account_id: "9",
+      creative: {
+        id: "2",
+        object_story_spec: {
+          link_data: { image_hash: "h", picture: "https://example.com/p.jpg" },
+        },
+      },
+    };
+    const res = await getAdMedia(ad, cfg, { resolve_urls: false });
+    expect(res.type).toBe("image");
+    expect(calls).toHaveLength(0);
+  });
+
+  it("works out the type without looking up every address", async () => {
+    serve([
+      ["/1?", { account_id: "9", creative: { id: "2", video_id: "555" } }],
+    ]);
+    expect(await getAdMediaType({ id: "1" }, cfg)).toBe("video");
+    // one read for the ad, and no read of the video
+    expect(calls).toHaveLength(1);
+  });
+});
+
+describe("what counts as a carousel", () => {
+  it("a post with several pictures in it does", async () => {
+    serve([
+      ["/1?", { account_id: "9", creative: { id: "2", object_story_spec: { page_id: "444" }, effective_object_story_id: "444_555" } }],
+      ["/444?", { access_token: "PAGETOKEN" }],
+      ["/444_555", {
+        attachments: {
+          data: [
+            {
+              media_type: "album",
+              subattachments: {
+                data: [
+                  { media_type: "photo", media: { image: { src: "https://example.com/1.jpg" } } },
+                  { media_type: "photo", media: { image: { src: "https://example.com/2.jpg" } } },
+                ],
+              },
+            },
+          ],
+        },
+      }],
+    ]);
+    const res = await getAdMedia({ id: "1" }, cfg);
+    expect(res.type).toBe("image");
+    expect(res.carousel).toBe(true);
+    expect(res.media).toHaveLength(2);
+  });
+
+  it("a dynamic creative offering Meta a choice does not", async () => {
+    serve([["/act_", { data: [] }]]);
+    const ad = {
+      id: "1",
+      account_id: "9",
+      creative: {
+        id: "2",
+        asset_feed_spec: {
+          images: [
+            { hash: "h1", url: "https://example.com/1.jpg" },
+            { hash: "h2", url: "https://example.com/2.jpg" },
+          ],
+          videos: [{ video_id: "v1" }],
+        },
+      },
+    };
+    const res = await getAdMedia(ad, cfg, { resolve_urls: false });
+    expect(res.carousel).toBe(false);
+    expect(res.type).toBe("mixed");
+    expect(res.media).toHaveLength(3);
+  });
+});
+
+describe("the wording of an ad that boosts a post", () => {
+  it("reads the post with a token for the page", async () => {
+    serve([
+      ["/7?", { creative: { id: "2", object_story_spec: { page_id: "888" }, effective_object_story_id: "888_999" } }],
+      ["/888?", { access_token: "PAGETOKEN" }],
+      ["/888_999", { message: "The primary text", attachments: { data: [{ title: "The headline" }] } }],
+    ]);
+    expect(await getAdText("7", cfg)).toEqual({
+      headline: "The headline",
+      body: "The primary text",
+    });
+    const post = calls.find((c) => c.url.includes("888_999"));
+    expect(post.auth).toBe("Bearer PAGETOKEN");
+  });
+});
+
+// A flexible creative names its pictures by hash only. The address of each
+// one is held by the ad account's picture library.
+const hashAd = {
+  id: "120254266274370547",
+  name: "3_STJ16890_FB_Dental",
+  creative: {
+    id: "1700780627695097",
+    object_type: "SHARE",
+    object_story_spec: { page_id: "106755536029753" },
+    effective_object_story_id: "106755536029753_1515321970628655",
+  },
+};
+
+const hashCreative = {
+  ...hashAd.creative,
+  asset_feed_spec: {
+    images: [{ hash: "aaa" }, { hash: "bbb" }],
+  },
+};
+
+describe("pictures named by hash", () => {
+  it("asks the picture library as a list, which is how Meta wants hashes", async () => {
+    serve([
+      ["/120254266274370547", { account_id: "998", creative: hashCreative }],
+      ["/adimages", {
+        data: [
+          { hash: "aaa", url: "https://example.com/a.jpg", width: 1080, height: 1080 },
+          { hash: "bbb", url: "https://example.com/b.jpg", width: 1080, height: 1080 },
+        ],
+      }],
+    ]);
+    const res = await getAdMedia(hashAd, cfg);
+    expect(res.type).toBe("image");
+    expect(res.media.map((m) => m.url)).toEqual([
+      "https://example.com/a.jpg",
+      "https://example.com/b.jpg",
+    ]);
+    expect(res.media[0].width).toBe(1080);
+    expect(res.error).toBeUndefined();
+    const lookup = calls.find((c) => c.url.includes("adimages"));
+    expect(lookup.url).toContain("act_998");
+    // a JSON list, not the comma separated kind Meta takes for fields
+    expect(decodeURIComponent(lookup.url)).toContain('hashes=["aaa","bbb"]');
+  });
+
+  it("falls back to the post when the ad account does not hold them", async () => {
+    serve([
+      ["/120254266274370547", { account_id: "998", creative: hashCreative }],
+      ["/adimages", { data: [] }],
+      ["/106755536029753?", { access_token: "PAGETOKEN" }],
+      ["/106755536029753_1515321970628655", {
+        attachments: {
+          data: [{ media_type: "photo", media: { image: { src: "https://example.com/post.jpg" } } }],
+        },
+      }],
+    ]);
+    const res = await getAdMedia(hashAd, cfg);
+    expect(res.type).toBe("image");
+    expect(res.from_post).toBe(true);
+    expect(res.media).toEqual([{ kind: "image", url: "https://example.com/post.jpg" }]);
+    expect(res.error).toBeUndefined();
+  });
+
+  it("says why when neither the library nor the post has them", async () => {
+    serve([
+      ["/120254266274370547", { account_id: "998", creative: hashCreative }],
+      ["/adimages", { error: { code: 100, message: "Invalid hashes" } }],
+      ["/106755536029753?", { error: { code: 190, message: "no page access" } }],
+      ["/106755536029753_1515321970628655", { error: { code: 100, message: "Unsupported get request" } }],
+    ]);
+    const res = await getAdMedia(hashAd, cfg);
+    expect(res.type).toBe("image");
+    expect(res.media.every((m) => !m.url)).toBe(true);
+    expect(res.error).toMatch(/2 of 2 could not be reached/);
+    expect(res.error).toMatch(/could not read the pictures of ad account act_998/);
+  });
+
+  it("says so when there is no ad account to ask", async () => {
+    serve([]);
+    const ad = {
+      id: "1",
+      creative: { id: "2", asset_feed_spec: { images: [{ hash: "aaa" }] } },
+    };
+    const res = await getAdMedia(ad, {});
+    expect(res.error).toMatch(/held by the ad account/);
+  });
+});