@raster-app/sdk 0.1.0-canary-2e1834e

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Monogram
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# @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.
+
+```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.
+
+```ts
+import { createRasterClient, localStorageCredentialStore } from '@raster-app/sdk'
+
+const raster = createRasterClient({
+	host: { name: 'Sanity', 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),
+	signal: controller.signal,
+})
+
+// Or connect an organization API key.
+await raster.auth.connect({ apiKey })
+
+const libraries = await raster.libraries.list({ organizationId: 'acme' })
+const assets = await raster.assets.list({ organizationId: 'acme', libraryId: 'lib-1' })
+```
+
+## The host
+
+`createRasterClient` takes what differs from one host to the next:
+
+- `host`, a `RasterHost`: the app's name, which Raster's consent page shows, and
+  `openExternal`, which opens a URL in the user's browser.
+- `credentials`, a `CredentialStore`: where the credential is kept. The SDK ships
+  `memoryCredentialStore` and `localStorageCredentialStore`. The credential is bearer tokens
+  in plain text, so it is as private as its store.
+
+Each client has its own session, so several can run on one page.
+
+## 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
+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.
+
+The consent page lets the user grant every organization or narrow the grant to one. A host that
+works in one organization passes `scope: 'org'`, which has the user pick exactly one, and that
+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
+
+A call to Raster that fails rejects with a `RasterApiError`. Branch on its `code`, and show the
+user `toUserMessage(error)`.
+
+## 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.
+
+## 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.
+
+- `formatBytes(bytes)` formats a byte count.
+- `formatFileSize(asset.size)` formats a size that may be missing, and returns an empty string
+  for a null, negative or non-finite size.
+- `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.