Media

The media module of @genuka/whatsapp. One sentence governs the whole module:

Our bucket is the source of truth. Meta is a cache with a 30-day eviction policy nobody gets to tune.

Everything below follows from that.

import { MetaTransport } from "@genuka/whatsapp";
import { CachedMediaResolver, MediaClient } from "@genuka/whatsapp/media";

const resolver = new CachedMediaResolver({
  store,                                              // your storage, behind MediaStorePort
  uploader: new MediaClient({ transport: new MetaTransport({ accessToken }) }),
});

// At send time, and only at send time:
const mediaId = await resolver.resolveMediaId(assetId, phoneNumberId);

Meta's three clocks

limits.MEDIA carries all four. safeReuseDays is 25, five days short of the cliff — the tail of the window is where clock skew, retries and slow queues live, and it buys nothing.

The lifecycle

client upload ──▶ validate (format + size) ──▶ sha256 ──▶ dedupe ──▶ OUR BUCKET
                                                                        │
                                                          at send time, per phone number
                                                                        ▼
                                              POST /{PHONE_NUMBER_ID}/media ──▶ media_id (30 d)
                                                                        │
                                                                        ▼
                                              POST /{PHONE_NUMBER_ID}/messages { image: { id } }

Validation happens at upload, not at send. A campaign built on Monday must not discover on Thursday, 40 000 recipients in, that its header is 7 MB.

MediaResolver

The contract the rest of the library depends on (media/types.ts):

resolveMediaId(assetId, phoneNumberId): Promise<string>
invalidate(assetId, phoneNumberId): Promise<void>

CachedMediaResolver implements it:

1. cached id younger than MEDIA.safeReuseDays → hand it back, no I/O beyond the cache read;
2. otherwise → read the bytes from our storage, re-upload, refresh the cache row;
3. invalidate() → drop the row so the next resolve re-uploads. This is what the send path's retry policy calls on 131052, before its single retry.

The composite key is not an optimisation

A media_id is scoped to the PHONE_NUMBER_ID that uploaded it. Reuse it from another number and Meta answers 131052 — intermittently, only on accounts with more than one number, only in production. The cache key is therefore (assetId, phoneNumberId), never assetId alone.

MediaStorePort

Storage stays injected, so the policy above is testable with zero I/O and the persistence layer stays out of a zero-dependency package:

interface MediaStorePort {
  getCachedUpload(assetId, phoneNumberId): Promise<CachedUpload | null>;
  putCachedUpload({ assetId, phoneNumberId, metaMediaId, uploadedAt }): Promise<void>;
  deleteCachedUpload(assetId, phoneNumberId): Promise<void>;
  readAsset(assetId): Promise<{ bytes, mimeType, filename? }>;
}

Two deliberate asymmetries in the implementation:

• a cache read that throws degrades to a miss — a database hiccup must not fail a campaign when re-uploading is always available;
• a cache write that throws is swallowed — we already hold a working id; losing the row costs one extra upload next time, and failing the send costs a message.

Error classes

A Meta-classified failure keeps its class when the resolver wraps it. Turning a config error into a media one would send the retry policy uploading a file, twice, for a token problem.

Inbound media

const downloaded = await client.download(mediaId, phoneNumberId); // GET /{MEDIA_ID} then GET url

Two things kill integrations here:

1. the download URL needs Authorization: Bearer <token> — without it the lookaside host answers 401, which everybody first misreads as "the URL expired";
2. it really does expire, in five minutes. download() resolves and consumes in one call for exactly that reason. There is no correct version that stores the URL and fetches it later.

Expose your URL to your clients. Never a Meta URL, never a Meta media_id — one is dead in five minutes, the other in 30 days, and both are scoped to credentials the client does not have.

header_handle is not a media_id

The single most expensive confusion in this API. Both are opaque strings Meta returns for a file you uploaded, and they are interchangeable in neither direction:

Passing a header_handle to a send yields 131052; passing a media_id to template creation yields a rejected template with an unrelated-sounding reason. Neither error names the confusion.

import { ResumableUploadClient } from "@genuka/whatsapp/media";

const handle = await new ResumableUploadClient({ appId, accessToken }).uploadHeaderHandle({
  bytes,
  mimeType: "image/png",
  filename: "header.png",
});
// → components: [{ type: "HEADER", format: "IMAGE", example: { header_handle: [handle] } }]

The resumable protocol predates the Cloud API and does not behave like it: Authorization: OAuth <token> (a Bearer is refused), an explicit file_offset header, and a raw binary body rather than multipart. A failed upload resumes from the offset Meta reports rather than re-sending the whole file — once. If nothing landed, the original error stands instead of being paid for twice.

Formats and sizes

Straight from limits.MEDIA / limits.MEDIA_MIME:

Two details worth knowing:

• image/webp is a sticker, not an image. Meta has no other slot for it, and it gets a sticker's budget whatever the caller meant.
• static and animated stickers share one mime type and not one limit, so assertMediaUpload() reads the RIFF/VP8X animation flag from the bytes instead of guessing. Guessing static rejects valid animated stickers; guessing animated defers the rejection to Meta, where the client cannot see it.

Client mime spellings are normalized before judgement (image/jpg, audio/mp3, audio/x-m4a, IMAGE/JPEG; charset=binary…) via limits.MEDIA_MIME_ALIASES. Rejecting image/jpg over a spelling is a support ticket, not a validation win.

Genuka WA API

Responses carry id, url (ours), sha256, mimeType, kind, sizeBytes. There is no field for a Meta identifier, deliberately. Re-uploading identical bytes returns the existing asset with deduplicated: true and a 200 instead of a 201.