Client

createRasterClient creates a client for the Raster REST API. It runs in the browser and Node.js, and @raster-app/react re-exports it.

import { createRasterClient, localStorageCredentialStore } from '@raster-app/sdk'

const raster = createRasterClient({
  host: { name: 'My App', openExternal: (url) => window.open(url, '_blank') },
  credentials: localStorageCredentialStore(),
})

const libraries = await raster.libraries.list({ organizationId: 'acme' })
const assets = await raster.assets.list({ organizationId: 'acme', libraryId: 'lib-1' })

Create one client and reuse it. Each client keeps its own session.

Configuration

The host

host.name is your app's name on Raster's Connect page and in Settings → Connected apps.

host.openExternal(url) opens a URL in the user's browser: the sign-in page, and Open in Raster in RasterPicker. Its return value is ignored, so window.open and async functions both work.

Methods

Failed calls reject with a RasterApiError.

Cancelling a call

Library, asset, and search methods take an optional signal. Aborting it rejects the call with ABORTED; a signal from AbortSignal.timeout() rejects with TIMEOUT. isAbortError(error) tells a cancel from a failure:

import { isAbortError, toUserMessage } from '@raster-app/sdk'

const controller = new AbortController()

try {
  await raster.search({ organizationId: 'acme', query: 'sunset', signal: controller.signal })
} catch (error) {
  if (!isAbortError(error)) alert(toUserMessage(error))
}

Device sign-in takes a signal too.

What the credential reaches

raster.me() resolves with GET /me. To read it:

• meOrganizationList(me): { id, name, libraryCount } per organization.
• meOrganizations(me): { organizationId, organizationName, plan, libraries } per organization.
• meLibraryAccess(me, organizationId, libraryId): 'read', 'write', or null.

Libraries

libraries.list({ organizationId, organizationName?, signal? }) resolves with every Library in the organization, each with organizationId and organizationName (what you passed, or null).

Assets

assets.list({ organizationId, libraryId, page?, pageSize?, signal? }) resolves with one page of assets. page starts at 1; pageSize defaults to 50. assets.hasMorePages(pageLength, pageSize?) is true when a page came back full.

assets.get({ organizationId, libraryId, assetId, signal? }) resolves with one asset and its variants.

Uploads

async function uploadFile(file: File) {
  const uploaded = await raster.assets.upload({
    organizationId: 'acme',
    libraryId: 'lib-1',
    source: file,
  })
  return raster.assets.waitUntilProcessed({
    organizationId: 'acme',
    libraryId: 'lib-1',
    assetId: uploaded.id,
    parentId: uploaded.parentId,
  })
}

assets.upload resolves once Raster has the file, with id, parentId, url, appUrl, and name. Raster then adds dimensions, sizes, and blurhash. assets.waitUntilProcessed resolves with the processed Asset, or null if it's still processing when the wait ends. For a variant, it resolves with the parent. Limits and accepted files: POST …/assets.

Variants

const promotion = {
  organizationId: 'acme',
  libraryId: 'lib-1',
  assetId: 'abc123',
  variantId: 'var789',
}

await raster.assets.promote(promotion)
const asset = await raster.assets.waitUntilPromoted(promotion)

assets.promote makes a variant the asset's default, served at the same URL. It resolves with assetId, promotedVariantId, and demotedVariantId (the new variant holding the previous default). assets.waitUntilPromoted resolves with the asset once the promote lands, or null. Rules: POST …/promote.

Search

const { hits, found } = await raster.search({ organizationId: 'acme', query: 'sunset' })

search resolves with one page of a SearchResult: assets whose name, description, or tags match, ranked by relevance.

Blank queries and unreachable library ids: GET …/search/assets.

Session

Outside React, raster.session tracks whether the user is signed in. In React, use useSession().

Image helpers

Each helper takes an Asset, AssetVariant, or SearchHit.

These URLs change when the asset's file is replaced, as by a promote.

To choose a size yourself:

1. parseSizes(asset.sizes) returns an object from size to URL, or null.
2. pickSizeUrl(sizes, targetEdge) returns the smallest size at least targetEdge pixels on its longest edge, or the largest one.
3. versionedUrl(url, asset.contentVersion) makes the URL change when the file is replaced.

Formatters

Formatters match the Raster app: decimal units (1 MB is 1,000,000 bytes) and en-US dates.

Date formatters take a Date or Unix milliseconds (as in created and updated) and return '' for null.

Constants and types

Asset, AssetVariant, Library, Tag, Uploader, SearchHit, and SearchResult match the API's objects.