npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@xmtp/content-type-remote-attachment

v2.0.0

Published

An XMTP content type to support sending file attachments that are stored off network

Downloads

9,068

Readme

Remote attachment content type

Status Status

The @xmtp/content-type-remote-attachment package provides an XMTP content type to support sending file attachments that are stored off-network. Use it to enable your app to send and receive message attachments.

Open for feedback
You are welcome to provide feedback on this implementation by commenting on the Remote Attachment Content Type XIP (XMTP Improvement Proposal).

What’s an attachment?

Attachments are files. More specifically, attachments are objects that have:

  • filename Most files have names, at least the most common file types.
  • mimeType What kind of file is it? You can often assume this from the file extension, but it's nice to have a specific field for it. Here's a list of common mime types.
  • data What is this file's data? Most files have data. If the file doesn't have data, then it's probably not the most interesting thing to send.

Why remote attachments?

Because XMTP messages can only be up to 1MB in size, we need to store the attachment somewhere other than the XMTP network. In other words, we need to store it in a remote location.

What about encryption?

End-to-end encryption must apply not only to XMTP messages, but to message attachments as well. For this reason, we need to encrypt the attachment before we store it.

Install the package

# npm
npm i @xmtp/content-type-remote-attachment

# yarn
yarn add @xmtp/content-type-remote-attachment

# pnpm
pnpm i @xmtp/content-type-remote-attachment

Create an attachment object

const attachment: Attachment = {
  filename: "screenshot.png",
  mimeType: "image/png",
  data: [the PNG data]
}

Create a preview attachment object

Once you have the attachment object created, you can also create a preview for what to show in a message input before sending:

URL.createObjectURL(
  new Blob([Buffer.from(somePNGData)], {
    type: attachment.mimeType,
  }),
),

Encrypt the attachment

Use the RemoteAttachmentCodec.encodeEncrypted to encrypt the attachment:

// Import the codecs we're going to use
import {
  AttachmentCodec,
  RemoteAttachmentCodec,
} from "@xmtp/content-type-remote-attachment";

// Encode the attachment and encrypt that encoded content
const encryptedAttachment = await RemoteAttachmentCodec.encodeEncrypted(
  attachment,
  new AttachmentCodec(),
);

Upload the encrypted attachment

Upload the encrypted attachment anywhere where it will be accessible via an HTTPS GET request. For example, you can use web3.storage:

const web3Storage = new Web3Storage({
  token: "your web3.storage token here",
});

const upload = new Upload("XMTPEncryptedContent", encryptedEncoded.payload);
const cid = await web3Storage.put([upload]);
const url = `https://${cid}.ipfs.w3s.link/XMTPEncryptedContent`;

(Upload is a small class that implements Web3Storage's Filelike interface for uploading)

Create a remote attachment

Now that you have a url, you can create a RemoteAttachment.

const remoteAttachment: RemoteAttachment = {
  // This is the URL string where clients can download the encrypted
  // encoded content
  url: url,

  // We hash the encrypted encoded payload and send that along with the
  // remote attachment. On the recipient side, clients can verify that the
  // encrypted encoded payload they've downloaded matches what was uploaded.
  // This is to prevent tampering with the content once it's been uploaded.
  contentDigest: encryptedAttachment.digest,

  // These are the encryption keys that will be used by the recipient to
  // decrypt the remote payload
  salt: encryptedAttachment.salt,
  nonce: encryptedAttachment.nonce,
  secret: encryptedAttachment.secret,

  // For now, all remote attachments MUST be fetchable via HTTPS GET requests.
  // We're investigating IPFS here among other options.
  scheme: "https://",

  // These fields are used by clients to display some information about
  // the remote attachment before it is downloaded and decrypted.
  filename: attachment.filename,
  contentLength: attachment.data.byteLength,
};

Send a remote attachment

Now that you have a remote attachment, you can send it:

await conversation.messages.send(remoteAttachment, {
  contentType: ContentTypeRemoteAttachment,
});

Note
contentFallback text is provided by the codec and gives clients that don't support a content type the option to display some useful context. For cases where clients do support the content type, they can use the content fallback as alt text for accessibility purposes.

Receive a remote attachment

Now that you can send a remote attachment, you need a way to receive a remote attachment. For example:

// Assume `loadLastMessage` is a thing you have
const message: DecodedMessage = await loadLastMessage();

if (!message.contentType.sameAs(ContentTypeRemoteAttachment)) {
  // We do not have a remote attachment. A topic for another blog post.
  return;
}

// We've got a remote attachment.
const remoteAttachment: RemoteAttachment = message.content;

Download, decrypt, and decode the attachment

Now that you can receive a remote attachment, you need to download, decrypt, and decode it so your app can display it. For example:

const attachment: Attachment = await RemoteAttachmentCodec.load(
  remoteAttachment,
  client, // <- Your XMTP Client instance
);

You now have the original attachment:

attachment.filename; // => "screenshot.png"
attachment.mimeType; // => "image/png",
attachment.data; // => [the PNG data]

Display the attachment

Display the attachment in your app as you please. For example, you can display it as an image:

const objectURL = URL.createObjectURL(
  new Blob([Buffer.from(attachment.data)], {
    type: attachment.mimeType,
  }),
);

const img = document.createElement("img");
img.src = objectURL;
img.title = attachment.filename;

To learn more, see Introducing remote media attachments.

Developing

Run yarn dev to build the content type and watch for changes, which will trigger a rebuild.

Testing

Before running unit tests, start the required Docker container at the root of this repository. For more info, see Running tests.

Useful commands

  • yarn build: Builds the content type
  • yarn clean: Removes node_modules, dist, and .turbo folders
  • yarn dev: Builds the content type and watches for changes, which will trigger a rebuild
  • yarn lint: Runs ESLint
  • yarn test:setup: Starts a necessary docker container for testing
  • yarn test:teardown: Stops docker container for testing
  • yarn test: Runs all unit tests
  • yarn typecheck: Runs tsc