TypeScript SDK

npm install @refmatter/sdk

import { Refmatter } from '@refmatter/sdk';

const refmatter = new Refmatter({ apiKey: process.env.REFMATTER_API_KEY! });

// URL in, reference out, as soon as metadata and transcript are readable.
const { importJob, reference } = await refmatter.importUrl(
  'https://www.youtube.com/watch?v=jNQXAC9IVRw',
  { onUpdate: (update) => console.log(update.state) },
);
if (reference === null) {
  throw new Error(`${importJob.outcomeCode}: ${importJob.outcomeMessage}`);
}

// Browse, annotate, keep the bytes longer, download.
const page = await refmatter.references.list({ limit: 20, platform: 'youtube' });
await refmatter.references.update(reference.id, {
  revision: reference.revision,
  tags: ['hook'],
});
await refmatter.references.setMediaHold(reference.id, 90);
const access = await refmatter.media.access(reference.primaryMediaId!);

const account = await refmatter.accounts.lookup({
  platform: 'youtube',
  handle: '@NASA',
});
const videos = await refmatter.items.list({ account: account.id });
console.log(account.name, videos.data.length, videos.page.nextCursor);

// One list, one selector: the selector names the platform, and each platform
// reads only its own parameters. Instagram pages twelve rows at a time. TikTok
// returns the ten newest videos and no cursor. The Ad Library returns the first
// page of an advertiser's ads and a total the filters narrow.
const reels = await refmatter.items.list({
  account: 'instagram:@nasa',
  type: 'reels',
});
const newest = await refmatter.items.list({ account: 'tiktok:@nasa' });
const advertisers = await refmatter.search.accounts({
  platform: 'meta_ad_library',
  q: 'Dot & Key',
});
const ads = await refmatter.items.list({
  account: advertisers.data[0]!.id,
  status: 'active',
});
console.log(reels.page.nextCursor, newest.data.length, ads.total);

// Comments are named by the item, and search by the platform. `total` on a
// YouTube search is an estimate, which `totalApproximate` says out loud.
const comments = await refmatter.comments.list({ item: 'youtube:jNQXAC9IVRw' });
const found = await refmatter.search.items({
  platform: 'youtube',
  q: 'solar eclipse',
});
console.log(comments.total, found.total, found.totalApproximate);

const first = await refmatter.items.list({ account: 'instagram:@nasa', type: 'reels' });
const next = await refmatter.items.list({ cursor: first.page.nextCursor! });

const found = await refmatter.search.items({ platform: 'youtube', q: 'solar eclipse' });
const more = await refmatter.search.accounts({
  platform: 'youtube',
  cursor: found.page.nextCursor!,
});

const resolution = await refmatter.urls.resolve('https://www.tiktok.com/@creator');
// target 'account', supported false, reason 'account_not_supported'

const item = await refmatter.items.lookup(
  'https://www.tiktok.com/@creator/video/7437269251355921707',
  { include: 'transcript', maxAge: '1h' },
);
console.log(item.kind, item.stats.views, item.usage.creditsCharged, item.cached);