@raster-app/sdk 0.1.0-rc.1 → 0.1.0

package/README.md

@@ -1,39 +1,51 @@
 # @raster-app/sdk
 
 A client for the [Raster](https://raster.app) REST API: sign-in, sessions, assets, libraries,
-search and image helpers. It runs in browsers and in Node 24 and later. The blurhash
-placeholder draws on a `document`, so outside a browser it returns null.
+search and image helpers.
+
+## Documentation
+
+[raster.app/docs/api/sdk](https://raster.app/docs/api/sdk)
+
+## Requirements
+
+- A browser, or Node.js 22.12 or later
+- No dependencies
+
+## Installation
 
 ```sh
 npm install @raster-app/sdk
 ```
 
-A React host installs [`@raster-app/react`](https://www.npmjs.com/package/@raster-app/react)
-instead, which re-exports all of this package.
+For React, install [`@raster-app/react`](https://www.npmjs.com/package/@raster-app/react) instead.
+It includes this package.
+
+## Usage
 
 ```ts
 import { createRasterClient, localStorageCredentialStore } from '@raster-app/sdk'
 
 const raster = createRasterClient({
-	host: { name: 'Sanity', openExternal: (url) => window.open(url, '_blank') },
+	host: { name: 'My App', openExternal: (url) => window.open(url, '_blank') },
 	credentials: localStorageCredentialStore(),
 })
 
 // Sign in with the device grant.
 const controller = new AbortController()
 await raster.auth.signInWithDevice({
-	onCode: (device) => showTheUser(device.userCode),
+	onCode: (device) => console.log(`Approve ${device.userCode} in your browser`),
 	signal: controller.signal,
 })
 
 // Or connect an organization API key.
-await raster.auth.connect({ apiKey })
+await raster.auth.connect({ apiKey: 'your-api-key' })
 
 const libraries = await raster.libraries.list({ organizationId: 'acme' })
 const assets = await raster.assets.list({ organizationId: 'acme', libraryId: 'lib-1' })
 ```
 
-## The host
+### The host
 
 `createRasterClient` takes what differs from one host to the next:
 
@@ -45,10 +57,10 @@ const assets = await raster.assets.list({ organizationId: 'acme', libraryId: 'li
 
 Each client has its own session, so several can run on one page.
 
-## Signing in
+### Signing in
 
 `auth.signInWithDevice` runs the OAuth device grant (RFC 8628), which works in every host,
-including a Figma plugin's iframe. `onCode` receives the code to show the user while the
+including a plugin's sandboxed iframe. `onCode` receives the code to show the user while the
 consent page opens in their browser, and the promise settles once they approve.
 `auth.connect({ apiKey })` connects an organization API key. Either way, `/me` checks the
 credential before it is stored, so a bad key fails the call.
@@ -58,19 +70,20 @@ works in one organization passes `scope: 'org'`, which has the user pick exactly
 organization's id as `organizationId`. Any other grant, of another organization or of the whole
 account, then fails with `ORGANIZATION_MISMATCH` and leaves the saved credential as it was.
 
-## Errors
+### Errors
 
 A call to Raster that fails rejects with a `RasterApiError`. Branch on its `code`, and show the
 user `toUserMessage(error)`.
 
-## Images
+### Images
 
 `getThumbUrl(asset)` picks a thumbnail from the asset's `sizes`, `getPreviewUrl(asset)` a larger
 size for an asset shown large, `getFullSizeUrl(asset)` returns the full-size image, and
 `getBlurhashPlaceholder(asset)` a data URL to paint while any of them loads. Each URL carries the
-asset's content version, so a cache never shows a replaced file.
+asset's content version, so a cache never shows a replaced file. The placeholder draws on a
+`document`, so outside a browser it returns null.
 
-## File sizes and dates
+### File sizes and dates
 
 These show file sizes and dates as the Raster app does: decimal units, so 1 MB is 1,000,000
 bytes, and `en-US` dates.
@@ -81,3 +94,7 @@ bytes, and `en-US` dates.
 - `formatDate(asset.created)` gives the date, `formatDateLong` adds the weekday and time, and
   `formatRelativeTime` reads "just now", "5m ago", "3h ago" or "2d ago" within a week, then the
   date. Each takes a `Date` or Unix milliseconds, and returns an empty string for null.
+
+## License
+
+MIT