Media API SDK

Installation

Install the SDK and peer dependencies:

yarn add @palmetto/result @palmetto/base-sdk-client @palmetto/media-sdk

Usage

Create a client instance

import { MediaClient } from "@palmetto/media-sdk";

const client = new MediaClient({
  apiUrl: app.config("media.api.url"),
  authToken: app.config("media.api.userToken"),
});

Create a new media

Public media and private media work similar ways. Use the isPublic flag to indicate if the media can be access publicly by any internet user.

Properties of CreateMediaInput:

• filename: name of the file to store. The name does not have to be unique. Media API creates unique names for all media.
• contentType: the MIME type of the file. Valid types:
  • application/pdf
  • image/png
  • image/jpeg
  • image/gif
  • image/svg+xml
  • video/mp4
• isPublic: true
  • the file is stored in a publicly accessible bucket
  • publicUrl is defined in the response with a URL that can be placed on any web page.
• isPublic: false
  • the file is stored in a separate private bucket
  • publicUrl is undefined, and you must request a signed URL to access the media.
• expiresAfter: (optional) the time after which the file should be deleted
  • the cleanup process isn't exact. Files may live several hours after the expiresAfter value
• permissions: (optional) an array of Users API grants (entity permissions) allowing access to the media
  • eg: ["customer:customer"] grants access to any user with customer:customer grant.
• associatedEntities: (optional) an array of associated entities for the media

import { CreateMediaInput } from "@palmetto/media-sdk";

const file: File = {}; // get a reference to the <input type="file"> from the browser form

const media: CreateMediaInput = {
  filename: file.name,
  contentType: file.type as CreateMediaInput["contentType"],
  isPublic: true,
  expiresAfter: new Date(Date.now() + 24 * 3600 * 1000), // this media is deleted after 24 hours
};

// create the media itself
const createdMedia = await client.createMedia(media);

if (!createdMedia.ok) {
  toast.error("Failed to create media:", createdMedia.error);
  return;
}

try {
  // next upload the media using the signed URL
  const fetchResponse = await fetch(
    new Request(createdMedia.data.signedUrlForUpload.url, {
      headers: createdMedia.data.signedUrlForUpload.headers,
      body: file,
      method: "PUT",
    }),
  );

  if (!fetchResponse.ok) {
    toast.error("Failed to upload media. Please try again.");
    return;
  }
} catch (error) {
  toast.error("Failed to upload media. Please try again.");
  return;
}

getMediaById

Use getMediaById to access the media details and get a URL to download the file. See examples below.

• id the media ID
• includeSignedUrl: set to true to return the signedUrlForDownload in the response. (default: false)
• inline: set to true so that the download is done inline, false crafts the file download as an attachment. (default: false)

Opening the media in a browser

For public media, you can use the publicUrl property to access the media. Private media must use a signed URL to download.

Public media

Public media URLs never change. They are valid until the media is deleted.

const { publicUrl } = createdMedia.data;

window.location.href = publicUrl;

Private media

Private media you must access using a signed URL. The signed URL is only valid for a few minutes so you must download the file soon after requesting the URL.

const getMediaResult = await client.getMediaById({
  id: createdMedia.data.id,
  includeSignedUrl: true,
  inline: false,
});

if (!getMediaResult.ok) {
  toast.error("Failed to fetch media details:", getMediaResult.error);
  return;
}

const { signedUrlForDownload } = getMediaResult.data;

window.location.href = signedUrlForDownload;

Permissions

Media have permissions. By default, only the API user that created the media can update or delete the media. You can use the permissions property to allow other API users with that permission to modify or delete the media.

const media: CreateMediaInput = {
  filename: file.name,
  contentType: file.type as CreateMediaInput["contentType"],
  isPublic: false,
  permissions: ["customer:customer"],
};

This example allows any user with customer:customer entity grant to access the media. This access is global, it doesn't know that the media belongs to a specific customer, for example. [This feature may be improved later on].

Update Media

You can update a media's permissions, associatedEntities and expiresAfter using updatedMediaById. Your user must have created the media, or have the write operation for one of the permissions on the media.

Delete media

You can delete a media using deleteMediaById. Your user must have created the media, or have the delete operation for one of the permissions on the media.