@saltcorn/meta-marketing-api 0.1.1 → 0.1.2

package/README.md

@@ -136,6 +136,10 @@ a different token.
 | `get_meta_ad_headline(ad)` | The headline of an ad, from an ad id or an ad you have already read |
 | `get_meta_ad_body(ad)` | The primary text of an ad: the longer wording above the image |
 | `get_meta_ad_text(ad)` | Both of the above together, as `{ headline, body }`, in one read |
+| `get_meta_ad_media(ad, options)` | What an ad is made of and where to download it |
+| `get_meta_ad_media_type(ad)` | Whether an ad is an `image`, a `video`, `mixed` or `unknown` |
+| `get_meta_ad_media_url(ad)` | The address of the picture or the film in an ad |
+| `get_meta_page_access_token(pageId)` | A token for one of your pages, or nothing when you have no access to it |
 | `get_meta_ad_preview(adId, adFormat)` | A ready made HTML preview of an ad |
 | `get_meta_insights(objectId, query)` | Performance figures for an account, campaign, ad set or ad |
 | `get_meta_insights_async(objectId, query)` | The same, run as a background report, for large date ranges |
@@ -177,11 +181,149 @@ get_meta_ad_text(ad_id)
 
 which gives you `{ headline: "...", body: "..." }`, where the body is the
 longer text above the image. For an ad that is boosting a post already on
-your page, the wording belongs to the post rather than to the ad, and reading
-it needs a token that can also read the page. When it cannot be read you get
+your page, the wording belongs to the post rather than to the ad; the module
+asks Meta for a token for that page and reads it with that, which needs the
+access token in the settings to have a say over the page, as described under
+*Ads that boost a post on your page* below. When it cannot be read you get
 empty text back rather than an error; `get_meta_ad_preview` will still show
 you the ad as it appears.
 
+### The picture or the film in an ad
+
+`get_meta_ad_media` tells you what kind of ad you are looking at and where to
+download the file it is built on:
+
+```
+get_meta_ad_media(ad_id)
+```
+
+gives you
+
+```
+{
+  type: "video",
+  carousel: false,
+  media: [
+    {
+      kind: "video",
+      video_id: "1234",
+      url: "https://video.xx.fbcdn.net/...",
+      thumbnail_url: "https://scontent.xx.fbcdn.net/...",
+      permalink_url: "...",
+      length: 15
+    }
+  ],
+  creative_id: "5678",
+  object_type: "VIDEO",
+  thumbnail_url: "https://scontent.xx.fbcdn.net/...",
+  from_post: false,
+  error: undefined
+}
+```
+
+- **type** is `image`, `video`, `mixed` or `unknown`. `mixed` means the ad
+  offers Meta both to choose between, which is what a flexible or dynamic
+  creative does, or a carousel with both in it. `unknown` means there is no
+  picture or film to be found, as on a text only ad.
+- **carousel** says whether the ad holds more than one card. The cards are
+  the entries in `media`, in the order they are shown.
+- **media** has one entry per picture or film, each with a `url` you can
+  download. The still that a film shows before it plays is on that film's
+  entry as `thumbnail_url`, and does not count as a picture of its own. An
+  entry that could not be reached has no `url` and carries an `error` saying
+  why instead.
+- **thumbnail_url** is a picture of the ad as it appears. It is there even
+  when nothing else is, so it is worth keeping as a fallback: for a film it
+  is a still rather than the film itself, which is why it is not in `media`.
+- **from_post** says the ad is boosting a post that was already on your page,
+  so the media was read from the post rather than from the ad.
+- **error** is there only when something could not be read, and says what.
+  An ad never stops a run over an ad set because of it: you get `unknown`
+  and the reason.
+
+### Ads that boost a post on your page
+
+Much of what is advertised on Facebook and Instagram is a post that already
+exists on a page. Such an ad keeps nothing on the creative but the id of the
+page and of the post:
+
+```
+{
+  "object_type": "SHARE",
+  "object_story_spec": { "page_id": "1067...", "instagram_user_id": "1784..." },
+  "effective_object_story_id": "1067..._1334..."
+}
+```
+
+The picture or the film is on the post, and Meta only shows a post to a token
+that carries that page's own permissions. `get_meta_ad_media` asks for a
+token for the page by itself and reads the post with it, so these ads work
+like any other, as long as the access token in the settings has a say over
+the page. That means:
+
+- the token must have the **pages_read_engagement** permission, and
+- the person or system user it belongs to must have a role on that page. In
+  Business Manager, add the page to the same business as the ad account and
+  give the system user access to it.
+
+When that is missing you get `type: "unknown"` and an `error` saying so,
+rather than silence. To check one page on its own:
+
+```
+get_meta_page_access_token("106755536029753")
+```
+
+Nothing back means the token has no say over that page. `thumbnail_url` is
+still filled in for these ads, so you have a picture of the ad to look at
+even when the post itself cannot be read.
+
+A few things are worth knowing before you download:
+
+- **Video addresses are signed and short lived.** Fetch the file as soon as
+  you have the address rather than storing the address for later. Meta only
+  gives the address out to a token that owns the video: with a read only
+  token you may get the video's id and its thumbnail but no `url`, and the
+  entry then carries an `error` saying why. `permalink_url` is a stable
+  address for watching it, not for downloading it.
+- **Working out the type is cheaper than finding the addresses.** Every film
+  costs one extra read to look up. If all you want is image against video,
+  use `get_meta_ad_media_type`, or pass the options `{ resolve_urls: false }`.
+- **Pictures are often named by a hash rather than by an address.** The
+  address is then held by the ad account's own picture library, which is
+  looked up for you, so reading ads of a second ad account works better when
+  you pass that account's id: `get_meta_ad_media(ad, { account_id: "..." })`,
+  or read the ads with `account_id` among the fields. When the library does
+  not hold the picture and the ad boosts a post, the post is read instead.
+- **An ad whose creative shows no media is read again in full.** You may have
+  asked Meta for only some of the places media can hide, so rather than
+  answer `unknown` too readily it asks for all of them. Handing it an ad you
+  read with the creative fields below saves that second read.
+
+To go through a whole ad set:
+
+```
+const ads = await get_meta_adset_ads(adset_id, {
+  fields:
+    "id,name,account_id,creative{id,name,object_type,image_url,image_hash," +
+    "video_id,thumbnail_url,object_story_spec,asset_feed_spec," +
+    "effective_object_story_id}"
+});
+for (const ad of ads) {
+  const { type, media } = await get_meta_ad_media(ad);
+  console.log(ad.name, type, media.map((m) => m.url));
+}
+```
+
+Asking for those creative fields is worth doing on a loop like this: given an
+ad that already carries them, `get_meta_ad_media` works from what you have
+instead of reading each ad again. Given only an ad id, it asks for them
+itself.
+
+Ads read as a table row, or by `get_meta_ads` without a `fields` of your own,
+carry `creative_object_type`. That is a rough answer on its own: most ads
+that link somewhere are reported as `SHARE` whether the media is a picture or
+a film, so use `get_meta_ad_media` when it matters.
+
 ## Things to know
 
 - **Money is in cents.** Budgets, bids and amounts spent come from Meta as

package/api.js

@@ -74,7 +74,7 @@ const DEFAULT_FIELDS = {
     "configured_status",
     "bid_amount",
     "preview_shareable_link",
-    "creative{id,name,thumbnail_url}",
+    "creative{id,name,object_type,thumbnail_url,image_url,video_id}",
     "created_time",
     "updated_time",
   ],
@@ -109,6 +109,22 @@ const CREATIVE_TEXT_FIELDS = [
   "effective_object_story_id",
 ];
 
+// Where the picture or the film of an ad can be found. As with the wording,
+// Meta keeps this in a different place depending on how the ad was built.
+const CREATIVE_MEDIA_FIELDS = [
+  "id",
+  "name",
+  "account_id",
+  "object_type",
+  "image_url",
+  "image_hash",
+  "video_id",
+  "thumbnail_url",
+  "object_story_spec",
+  "asset_feed_spec",
+  "effective_object_story_id",
+];
+
 // Metrics that are valid at every insights level.
 const BASE_INSIGHTS_FIELDS = [
   "impressions",
@@ -473,6 +489,53 @@ const creativeBodies = (creative) => {
   return [...new Set(found.filter((b) => b))];
 };
 
+// A page post is only shown to a token that carries the page's own
+// permissions. A token for the page can be asked for, once per page.
+const PAGE_TOKEN_TTL_MS = 15 * 60 * 1000;
+const pageTokenCache = new Map();
+
+/**
+ * A token for one page, from the token in the settings. Comes back null when
+ * the settings token has no say over that page, which is the usual reason an
+ * ad that boosts a page post has nothing to show.
+ */
+const getPageAccessToken = async (pageId, cfg) => {
+  if (!pageId) return null;
+  const key = `${pageId}|${cfg?.access_token || ""}`;
+  const hit = pageTokenCache.get(key);
+  if (hit && Date.now() - hit.at < PAGE_TOKEN_TTL_MS) return hit.token;
+  let token = null;
+  try {
+    const json = await graphFetch(
+      `/${pageId}`,
+      { query: { fields: "access_token" } },
+      cfg
+    );
+    token = json?.access_token || null;
+  } catch (e) {
+    if (cfg?.log_requests)
+      console.log(`Meta: no token for page ${pageId}`, e.message);
+  }
+  pageTokenCache.set(key, { token, at: Date.now() });
+  return token;
+};
+
+/**
+ * Which tokens to try when reading the post behind an ad, best first: one
+ * for the page that owns it, then the one from the settings.
+ */
+const postTokens = async (creative, storyId, cfg, opts = {}) => {
+  const pageId =
+    creative?.object_story_spec?.page_id || `${storyId}`.split("_")[0];
+  const pageToken =
+    opts.page_token === false ? null : await getPageAccessToken(pageId, cfg);
+  return {
+    pageId,
+    pageToken,
+    cfgs: pageToken ? [{ ...cfg, access_token: pageToken }, cfg] : [cfg],
+  };
+};
+
 /**
  * The wording of the page post an ad promotes: the post's own text, and the
  * headline of the link it carries.
@@ -500,7 +563,7 @@ const storyText = async (storyId, cfg) => {
  * When that read is not allowed the wording comes back empty rather than
  * throwing.
  */
-const getAdText = async (ad, cfg) => {
+const getAdText = async (ad, cfg, opts = {}) => {
   let creative = typeof ad === "object" ? ad?.creative : null;
   if (!creative?.object_story_spec && !creative?.title && !creative?.body) {
     const fetched = await graphFetch(
@@ -514,17 +577,21 @@ const getAdText = async (ad, cfg) => {
     headline: creativeHeadlines(creative)[0] || "",
     body: creativeBodies(creative)[0] || "",
   };
-  if ((!text.headline || !text.body) && creative?.effective_object_story_id)
-    try {
-      const story = await storyText(creative.effective_object_story_id, cfg);
-      return {
-        headline: text.headline || story.headline,
-        body: text.body || story.body,
-      };
-    } catch (e) {
-      if (cfg?.log_requests)
-        console.log("Meta: could not read the post behind the ad", e.message);
-    }
+  if ((!text.headline || !text.body) && creative?.effective_object_story_id) {
+    const storyId = creative.effective_object_story_id;
+    const { cfgs } = await postTokens(creative, storyId, cfg, opts);
+    for (const useCfg of cfgs)
+      try {
+        const story = await storyText(storyId, useCfg);
+        return {
+          headline: text.headline || story.headline,
+          body: text.body || story.body,
+        };
+      } catch (e) {
+        if (cfg?.log_requests)
+          console.log("Meta: could not read the post behind the ad", e.message);
+      }
+  }
   return text;
 };
 
@@ -534,6 +601,419 @@ const getAdHeadline = async (ad, cfg) => (await getAdText(ad, cfg)).headline;
 /** The primary text of an ad, the wording above the image, as getAdText */
 const getAdBody = async (ad, cfg) => (await getAdText(ad, cfg)).body;
 
+//
+// Media: the picture or the film an ad is built on
+//
+
+// What tells two pieces of media apart. The same picture reached by two
+// routes - once by hash and once by address - is the same picture.
+const MEDIA_IDS = ["video_id", "image_hash", "url"];
+
+/**
+ * Add one piece of media to the list, or, when it is already there under
+ * another of its names, fill in what that entry was missing.
+ */
+const addMedia = (out, m) => {
+  if (!m || !MEDIA_IDS.some((k) => m[k])) return;
+  const same = out.find(
+    (o) => o.kind === m.kind && MEDIA_IDS.some((k) => m[k] && o[k] === m[k])
+  );
+  if (!same) {
+    out.push(m);
+    return;
+  }
+  Object.entries(m).forEach(([k, v]) => {
+    if (v && !same[k]) same[k] = v;
+  });
+};
+
+/** A carousel card, or a plain link ad, which are shaped the same way */
+const linkMedia = (data) =>
+  data.video_id
+    ? {
+        kind: "video",
+        video_id: data.video_id,
+        thumbnail_url: data.picture || data.image_url,
+        image_hash: undefined,
+        thumbnail_hash: data.image_hash,
+        name: data.name,
+        link: data.link,
+      }
+    : {
+        kind: "image",
+        url: data.picture || data.image_url,
+        image_hash: data.image_hash,
+        name: data.name,
+        link: data.link,
+      };
+
+/**
+ * Every piece of media on a creative, without reading anything further. A
+ * video carries its own still as a thumbnail rather than as a picture of its
+ * own, so a film never counts as a picture too.
+ */
+const creativeMedia = (creative) => {
+  const spec = creative?.object_story_spec || {};
+  const feed = creative?.asset_feed_spec || {};
+  const out = [];
+
+  if (spec.video_data)
+    addMedia(out, {
+      kind: "video",
+      video_id: spec.video_data.video_id,
+      thumbnail_url: spec.video_data.image_url,
+      thumbnail_hash: spec.video_data.image_hash,
+      name: spec.video_data.title,
+    });
+  if (spec.photo_data)
+    addMedia(out, {
+      kind: "image",
+      url: spec.photo_data.url,
+      image_hash: spec.photo_data.image_hash,
+    });
+  [spec.link_data, spec.template_data].forEach((data) => {
+    if (!data) return;
+    const children = data.child_attachments || [];
+    if (children.length) children.forEach((c) => addMedia(out, linkMedia(c)));
+    else addMedia(out, linkMedia(data));
+  });
+
+  // Flexible and dynamic creatives keep a pool of assets for Meta to choose
+  // between, rather than one story
+  (feed.videos || []).forEach((v) =>
+    addMedia(out, {
+      kind: "video",
+      video_id: v.video_id,
+      thumbnail_url: v.thumbnail_url,
+      thumbnail_hash: v.thumbnail_hash,
+    })
+  );
+  (feed.images || []).forEach((i) =>
+    addMedia(out, { kind: "image", url: i.url, image_hash: i.hash })
+  );
+
+  // Last, what the creative says about itself. On many ads this is the same
+  // media again, which the key above discards.
+  if (creative?.video_id)
+    addMedia(out, {
+      kind: "video",
+      video_id: creative.video_id,
+      thumbnail_url: creative.thumbnail_url,
+    });
+  else if (creative?.image_url || creative?.image_hash)
+    addMedia(out, {
+      kind: "image",
+      url: creative.image_url,
+      image_hash: creative.image_hash,
+    });
+
+  return out;
+};
+
+/**
+ * The media on a page post an ad promotes, for ads that carry no creative of
+ * their own. An album post holds its pictures one level further down.
+ */
+const storyMedia = async (storyId, cfg) => {
+  const json = await graphFetch(
+    `/${storyId}`,
+    {
+      query: {
+        fields:
+          "permalink_url,full_picture," +
+          "attachments{media_type,media,target,url,subattachments{media_type,media,target}}",
+      },
+    },
+    cfg
+  );
+  const out = [];
+  let album = false;
+  const fromAttachment = (att) => {
+    if (!att) return;
+    const type = `${att.media_type || ""}`.toLowerCase();
+    const still = att.media?.image?.src;
+    if (type.includes("video"))
+      addMedia(out, {
+        kind: "video",
+        video_id: att.target?.id,
+        thumbnail_url: still,
+      });
+    else if (still) addMedia(out, { kind: "image", url: still });
+  };
+  (json?.attachments?.data || []).forEach((att) => {
+    const subs = att.subattachments?.data || [];
+    if (subs.length > 1) album = true;
+    if (subs.length) subs.forEach(fromAttachment);
+    else fromAttachment(att);
+  });
+  // full_picture is whatever the post shows in a feed. For a film that is a
+  // still rather than the film, so it is offered as a thumbnail and never as
+  // a picture in its own right.
+  return {
+    media: out,
+    album,
+    thumbnail_url: json?.full_picture,
+    permalink_url: json?.permalink_url,
+  };
+};
+
+/**
+ * The media on the post an ad boosts, tried first with a token for the page
+ * that owns the post and then with the token from the settings. Never
+ * throws: what went wrong comes back as the reason, to be reported on the ad
+ * rather than stopping a run over a whole ad set.
+ */
+const postMedia = async (creative, cfg, opts = {}) => {
+  const storyId = creative?.effective_object_story_id;
+  if (!storyId) return { media: [] };
+  const { pageId, pageToken, cfgs } = await postTokens(
+    creative,
+    storyId,
+    cfg,
+    opts
+  );
+  let reason;
+  for (const useCfg of cfgs) {
+    try {
+      const post = await storyMedia(storyId, useCfg);
+      if (post.media.length) return { ...post, story_id: storyId };
+      reason = `the post ${storyId} behind this ad carries no picture or film`;
+    } catch (e) {
+      reason = `could not read the post ${storyId} behind this ad: ${e.message}`;
+      if (cfg?.log_requests) console.log(`Meta: ${reason}`);
+    }
+  }
+  if (!pageToken)
+    reason = `${reason}. The access token has no say over page ${pageId}: to see what an ad that boosts a page post is made of, use a token that can also read that page, with the pages_read_engagement permission`;
+  return { media: [], story_id: storyId, error: reason };
+};
+
+/**
+ * Turn the ids and hashes collected above into addresses a file can be
+ * downloaded from. Videos are read one at a time, pictures all in one go.
+ *
+ * The address of a video is only given out to a token that owns it, and it is
+ * signed and short lived, so download it now rather than storing it. When it
+ * cannot be read the entry keeps its id and its thumbnail.
+ */
+const resolveMediaUrls = async (media, accountId, cfg) => {
+  const videos = media.filter((m) => m.kind === "video" && m.video_id);
+  for (const m of videos) {
+    try {
+      const v = await graphFetch(
+        `/${m.video_id}`,
+        {
+          query: {
+            fields: "id,source,picture,permalink_url,length,created_time",
+          },
+        },
+        cfg
+      );
+      m.url = v?.source || m.url;
+      m.thumbnail_url = m.thumbnail_url || v?.picture;
+      m.permalink_url = v?.permalink_url;
+      if (typeof v?.length === "number") m.length = v.length;
+    } catch (e) {
+      m.error = e.message;
+      if (cfg?.log_requests)
+        console.log(`Meta: could not read video ${m.video_id}`, e.message);
+    }
+  }
+
+  const needHash = media.filter((m) => !m.url && m.image_hash);
+  if (!needHash.length) return media;
+  if (!accountId) {
+    needHash.forEach((m) => {
+      m.error =
+        "the address of this picture is held by the ad account, which is not known here: pass the ad account id, or set a default one in the settings";
+    });
+    return media;
+  }
+
+  // The picture library only answers about so many at a time
+  const hashes = [...new Set(needHash.map((m) => m.image_hash))];
+  const byHash = {};
+  let reason;
+  for (let i = 0; i < hashes.length; i += 50) {
+    try {
+      const json = await graphFetch(
+        `/${actId(accountId)}/adimages`,
+        {
+          query: {
+            // a list of its own, not the comma separated kind Meta takes
+            // elsewhere
+            hashes: JSON.stringify(hashes.slice(i, i + 50)),
+            fields: "hash,url,permalink_url,width,height",
+          },
+        },
+        cfg
+      );
+      // Depending on the API version this comes back as a list or as an
+      // object keyed by hash
+      const images = Array.isArray(json?.data)
+        ? json.data
+        : Object.values(json?.images || {});
+      images.forEach((img) => {
+        if (img?.hash) byHash[img.hash] = img;
+      });
+    } catch (e) {
+      reason = `could not read the pictures of ad account ${actId(
+        accountId
+      )}: ${e.message}`;
+      if (cfg?.log_requests) console.log(`Meta: ${reason}`);
+    }
+  }
+  needHash.forEach((m) => {
+    const img = byHash[m.image_hash];
+    if (!img) {
+      m.error =
+        reason ||
+        `the ad account has no picture with the hash ${m.image_hash}. It may belong to another ad account, or to the page rather than to the ad`;
+      return;
+    }
+    m.url = img.url;
+    m.permalink_url = img.permalink_url;
+    m.width = img.width;
+    m.height = img.height;
+  });
+
+  return media;
+};
+
+/**
+ * Why some of what an ad is made of has no address to download it from,
+ * said once rather than once per picture.
+ */
+const mediaErrors = (media) => {
+  const stuck = media.filter((m) => m.error && !m.url);
+  if (!stuck.length) return undefined;
+  const reasons = [...new Set(stuck.map((m) => m.error))];
+  return `${stuck.length} of ${media.length} could not be reached: ${reasons.join(
+    "; "
+  )}`;
+};
+
+/** What kind of ad this is, from the media it was built on */
+const mediaType = (media) => {
+  const hasVideo = media.some((m) => m.kind === "video");
+  const hasImage = media.some((m) => m.kind === "image");
+  if (hasVideo && hasImage) return "mixed";
+  if (hasVideo) return "video";
+  if (hasImage) return "image";
+  return "unknown";
+};
+
+/**
+ * What an ad is made of and where to download it from:
+ *
+ *   { type, carousel, media: [{ kind, url, thumbnail_url, ... }],
+ *     creative_id, object_type, thumbnail_url, from_post, story_id, error }
+ *
+ * type is image, video, mixed - a dynamic creative offering Meta both - or
+ * unknown when nothing could be found. carousel says whether the ad holds
+ * more than one card; the cards are the media list, in the order they are
+ * shown. thumbnail_url is a picture of the ad as it appears, which is there
+ * even when the media itself cannot be reached, and error says why it could
+ * not.
+ *
+ * Takes an ad id, or an ad row that already has its creative. A creative
+ * that carries no media is read again in full, since the caller may have
+ * asked Meta for only some of the places media can hide, so an ad read with
+ * the media fields of its own saves a read here.
+ *
+ * Options: resolve_urls false skips turning video ids and image hashes into
+ * addresses, which saves a read per video when all you want is the type;
+ * page_token false stops it asking for a token for the page behind a boosted
+ * post.
+ */
+const getAdMedia = async (ad, cfg, opts = {}) => {
+  const adId = typeof ad === "object" ? ad?.id : ad;
+  let creative = typeof ad === "object" ? ad?.creative : null;
+  let accountId =
+    opts.account_id ||
+    (typeof ad === "object" ? ad?.account_id : null) ||
+    creative?.account_id;
+  let media = creativeMedia(creative);
+
+  // Nothing on what we were handed. Ask for every field media can arrive in
+  // before giving up on the creative, and for a thumbnail big enough to be
+  // worth looking at.
+  if (!media.length && adId) {
+    const fetched = await graphFetch(
+      `/${adId}`,
+      {
+        query: {
+          fields: `account_id,creative{${CREATIVE_MEDIA_FIELDS.join(",")}}`,
+          thumbnail_width: opts.thumbnail_width || 1200,
+          thumbnail_height: opts.thumbnail_height || 1200,
+        },
+      },
+      cfg
+    );
+    creative = fetched?.creative || creative;
+    accountId = accountId || fetched?.account_id || creative?.account_id;
+    media = creativeMedia(creative);
+  }
+  accountId = accountId || cfg?.ad_account_id;
+
+  // Still nothing: an ad that boosts a post keeps its media on the post
+  let post = {};
+  if (!media.length) {
+    post = await postMedia(creative, cfg, opts);
+    media = post.media;
+  }
+
+  if (opts.resolve_urls !== false) {
+    await resolveMediaUrls(media, accountId, cfg);
+    // Found something, but none of it can be downloaded: a creative can name
+    // pictures the ad account does not hold. The post an ad boosts carries
+    // addresses that work, so it is worth asking after all.
+    if (
+      media.length &&
+      !media.some((m) => m.url) &&
+      !post.media &&
+      creative?.effective_object_story_id
+    ) {
+      const fallback = await postMedia(creative, cfg, opts);
+      await resolveMediaUrls(fallback.media, accountId, cfg);
+      if (fallback.media.some((m) => m.url)) {
+        post = fallback;
+        media = fallback.media;
+      }
+    }
+  }
+
+  const children =
+    creative?.object_story_spec?.link_data?.child_attachments ||
+    creative?.object_story_spec?.template_data?.child_attachments ||
+    [];
+  return {
+    type: mediaType(media),
+    carousel: children.length > 1 || !!post.album,
+    media,
+    creative_id: creative?.id,
+    object_type: creative?.object_type,
+    thumbnail_url: creative?.thumbnail_url || post.thumbnail_url,
+    from_post: !!post.media?.length,
+    story_id: post.story_id,
+    permalink_url: post.permalink_url,
+    error: post.error || mediaErrors(media),
+  };
+};
+
+/** Whether an ad is an image, a video, mixed or unknown, as getAdMedia */
+const getAdMediaType = async (ad, cfg) =>
+  (await getAdMedia(ad, cfg, { resolve_urls: false })).type;
+
+/**
+ * The address of the first picture or film in an ad, ready to download, or
+ * the empty string when there is none
+ */
+const getAdMediaUrl = async (ad, cfg) => {
+  const { media } = await getAdMedia(ad, cfg);
+  return media.find((m) => m.url)?.url || "";
+};
+
 //
 // Insights
 //
@@ -638,6 +1118,7 @@ module.exports = {
   DEFAULT_API_VERSION,
   DEFAULT_FIELDS,
   CREATIVE_TEXT_FIELDS,
+  CREATIVE_MEDIA_FIELDS,
   BASE_INSIGHTS_FIELDS,
   INSIGHTS_LEVEL_FIELDS,
   NUMERIC_INSIGHTS_FIELDS,
@@ -672,6 +1153,16 @@ module.exports = {
   getAdText,
   getAdHeadline,
   getAdBody,
+  creativeMedia,
+  storyMedia,
+  postMedia,
+  postTokens,
+  getPageAccessToken,
+  mediaErrors,
+  mediaType,
+  getAdMedia,
+  getAdMediaType,
+  getAdMediaUrl,
   getInsights,
   startInsightsReport,
   getReportRun,

package/index.js

@@ -27,6 +27,10 @@ const {
   getAdText,
   getAdHeadline,
   getAdBody,
+  getAdMedia,
+  getAdMediaType,
+  getAdMediaUrl,
+  getPageAccessToken,
   getInsights,
   getInsightsAsync,
   exchangeLongLivedToken,
@@ -413,6 +417,45 @@ module.exports = {
         "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.1",
+  "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

@@ -8,6 +8,8 @@ const {
   DEFAULT_FIELDS,
   creativeHeadlines,
   creativeBodies,
+  creativeMedia,
+  mediaType,
 } = require("../api");
 
 describe("query string encoding", () => {
@@ -201,3 +203,115 @@ describe("default fields", () => {
     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/);
+  });
+});