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,
  listAssets,
  listLibraries,
  localStorageCredentialStore,
} from '@raster-app/sdk'

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

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

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

Every function that calls Raster takes the client first. Your bundle keeps only the functions you import.

Configuration

The host

host.name is your app's name on Raster's Connect page and in Profile 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.

Functions

Failed calls reject with a RasterApiError.

Cancelling a call

Library, asset, and search functions 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, searchAssets, toUserMessage } from '@raster-app/sdk'

const controller = new AbortController()

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

Sign-in takes a signal too.

What the credential reaches

getMe(raster) 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

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

Assets

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

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

Uploads

import { uploadAsset, waitUntilProcessed } from '@raster-app/sdk'

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

uploadAsset resolves once Raster has the file, with id, parentId, url, appUrl, and name. Raster then adds dimensions, sizes, and blurhash. 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

import { promoteVariant, waitUntilPromoted } from '@raster-app/sdk'

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

await promoteVariant(raster, promotion)
const asset = await waitUntilPromoted(raster, promotion)

promoteVariant 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). waitUntilPromoted resolves with the asset once the promote lands, or null. Rules: POST …/promote.

Search

import { searchAssets } from '@raster-app/sdk'

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

searchAssets 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, these functions read the credential in use. In React, use useSession().

import { isConfigured, loadSession, onSessionChange } from '@raster-app/sdk'

const credentials = await loadSession(raster)
console.log(isConfigured(credentials))

const unsubscribe = onSessionChange(raster, (next) => {
  console.log(isConfigured(next))
})

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.