feat: add `attachment.sidecar` publish option

aleclarson commented 11 months ago

The term "sidecar" is what Threads uses to represent a group of images and/or videos that share the same post.

Upload ID collisions

I also added logic to make sure that upload IDs never collide (i.e. if two publish calls happen at the same time).

Deprecations

As part of this PR, I propose we deprecate the url and image publish options, replacing them with a single attachment option which can be { url }, { image }, or { sidecar }.

Before

await threads.publish({
  text: "Hello",
  url: options.url,
  image: options.image,
  sidecar: options.sidecar,
})

After

await threads.publish({
  text: "Hello",
  attachment: options.attachment,
})

This means we can…

better enforce one property only (i.e. url and image cannot both be defined)
and it gives users a useful PostAttachment type

The example below demonstrates the strict enforcement:

https://www.typescriptlang.org/play?useUnknownInCatchVariables=false&ssl=9&ssc=1&pln=10&pc=1#code/C4TwDgpgBACgrgIwDYEsDOALA8mYKD2AdmgGoCMUAvFAN4BQUjUwEAHsAFxRrABOKhAOYBuOgF8oAMigAKGlDi8kAfi49+QqBIA+tKCgC2AQ0ERV3PgMFaAlHToATCAGMkR3tABmcQs7xEoMERUTAB9ADcyGXxcAmIueGR0bFiiUjIbLnD8FAd7UEgoABkBAGsAQWBgI2cMAwhCYCo9RSQ1S00xOgLoAEljU0rq2vrG5vlDEwh2jWsuugEWXk8a6ESQlP9iEgAmWgYmFnYZq1EmKCMqmrqG4HMAZUs-AFVCOIAeEsIKq5HbqF0-SmQ2uo2AAD5xPYnK53F4fH44oFgskIjtoql4rAUZgcFtSDtMlBsrl7N5fFsoGwjAYwEgIBEojZ9ucPMBFIRkUkwpE5AdzowjpwoAAiAASECQSHwUAA7vglA4RQAafkCgD06rV501UGeaAgvH0aCgACoAHJYAAqprl7kIEAcFwQ+DgTRdwAwUAABpNTN6LoQnd7WgG2Og8EIAHTapia2OMP3TKAAcgwVTAaA4mpQUcMgkUUec+AM6oAouVCHBemgDFGAFaQQQp5VQBMKJRcNMZrOawT4fCCelFksptvnMR2ebkxEBam0+lomTM+isiDs3icoLcjBL1cCwVsYXiyXSuUKpBK1UHxjxm9QXX6w3Gu2bx3MDCXUVJkWBp0i1pf2cIxCEIfB3XAr1wx4KMoAATSMEAAEJ2zvG9LmGG5Gi4eR23OJMu3TYBM2zdVc3zQti1LCsqxrOtGwgZtWzwphWkIntSP7Qdhyosd2zEa8mEnKFunAaB7kMOkUE8EB3itcFxgkaR5AAbRgfROVKCAQHwTwoCtABdLgrTUgytFEUTCkefgXjeIg5IU6gAGESwQAQIFeD55KpdgGgcE0BE8Z9ngOZR9J8lggxNECQDVMKJIXaTZKtKQ9BUgBpDSoDLVhXDgJx3i0nS9OeVsit0-TwQM8wfCcTx3KdMRIXOLgHXCQ0DlaiB2t4CyeigFyDDch1PPs7zqBgFBnFKOSyu0irvMkA4YHcPAjCQd4ZBSo8-OiwgQCgMKZFYYzmUoBSYqgLqeuZHaotkE6NKCo1njOi79sOvUrqgNrDXBUQgA

Finally, I propose that we deprecate the exported types whose name begins with ThreadsAPI (except for ThreadsAPIOptions), since this isn't a naming convention we apply evenly. Therefore, ThreadsAPIImage becomes ImageDefinition (as Image alone seems too vague?). If we wanted to, we could put all types in an export namespace ThreadsAPI block instead. But whatever we do, let's keep it consistent. 👍

vercel[bot] commented 11 months ago

The latest updates on your projects. Learn more about Vercel for Git ↗︎

1 Ignored Deployment

aleclarson commented 11 months ago

I'm onboard with namespacing any unofficial data structure with ThreadsAPI. I propose we go with a namespace ThreadsAPI approach, as it's more readable, requires less importing, and I don't see a reason not to take advantage of TypeScript's namespace feature.

Before

const options: ThreadsAPIOptions = {…}
const image: ThreadsAPIImage = { path: "https://i.imgur.com/EAnuIsm.jpeg" }

After

const options: ThreadsAPI.Options = {…}
const image: ThreadsAPI.Image = { path: "https://i.imgur.com/EAnuIsm.jpeg" }

junhoyeo commented 11 months ago

I'm onboard with namespacing any unofficial data structure with ThreadsAPI. I propose we go with a namespace ThreadsAPI approach, as it's more readable, requires less importing, and I don't see a reason not to take advantage of TypeScript's namespace feature.

Looks great to me! Thanks, I'll merge. 👍

junhoyeo / threads-api

feat: add `attachment.sidecar` publish option #198

Upload ID collisions

Deprecations