@dalea/sdk
v0.3.0
Published
The official TypeScript & JavaScript SDK for the Dalea data platform.
Maintainers
Readme
@dalea/sdk
The official TypeScript & JavaScript SDK for the Dalea data platform.
Typed, promise-based access to the Dalea API, with dual ESM + CJS builds, bundled type declarations, and zero runtime dependencies.
- Node >= 20 (works in the browser and edge runtimes too)
- Fully typed against the platform's OpenAPI contract
- API-key, session-cookie, and OAuth 2.1 + PKCE auth
- Seven domains:
data,documents,inventory,search,storage,connections,pipelines
Install
npm i @dalea/sdk
# or: pnpm add @dalea/sdk / yarn add @dalea/sdkQuickstart
Create a workspace API key in the Dalea app, then:
import { DaleaClient } from '@dalea/sdk';
const client = new DaleaClient({
baseUrl: 'https://dalea.app',
apiKey: process.env.DALEA_API_KEY, // or set DALEA_API_KEY and omit this
});
// List the data environments in your workspace.
const environments = await client.data.environments.list();
console.log(environments);If DALEA_API_KEY is set in the environment, new DaleaClient({ baseUrl: 'https://dalea.app' })
picks it up automatically — no apiKey needed.
Authentication
Pass exactly one credential to the constructor:
// 1. Workspace API key (server-side; the default) — sent as X-API-Key.
new DaleaClient({ baseUrl: 'https://dalea.app', apiKey: 'dalea_…' });
// 2. Session cookie (browser, same-origin) — omit baseUrl to use the current origin.
new DaleaClient({ sessionCookie: true });
// 3. Any Credential (OAuth 2.1 + PKCE, client-credentials, bearer, …).
import { OAuthPkceCredential } from '@dalea/sdk';
new DaleaClient({ baseUrl: 'https://dalea.app', credential: new OAuthPkceCredential(/* … */) });Scope calls to a workspace with client.setWorkspace(id) (or the workspace config
option), and pass a per-request bearer token with client.as(token).
Domains
The client groups the API into seven domains:
| Domain | What it covers |
| --- | --- |
| client.data | Environments, tables, columns, objects and their values, naming schemes, saved queries, query execution, result batches, schema reads, import mappings and CSV import/export, translators (saved-query rows, file sets and typed rows rendered to a samplesheet, params object or sequence set) and output landing, plus version history and restore for tables, objects and saved queries. |
| client.documents | Document list/create/read/update and the markdown block API: read, outline, parse, append, insert, update, delete and replace-section. |
| client.inventory | Item types, containers and their tree, placements (check-in/out, move), lots, consumption and quantity adjustment, item query, and audit trails. |
| client.search | Unified search across the workspace. |
| client.storage | File list/get/download/preview, file versions and restore, signed URLs, uploads (raw and base64), workspace/organization usage, object storage locations (a bucket and prefix on a connection) and mounts (a location indexed as a folder). |
| client.connections | The external connections registry: Benchling tenants, Seqera workspaces and object storage endpoints, with verify, diagnose, per-user identities and pipeline describe. Secrets are write-only and never returned. |
| client.pipelines | Saved pipeline definitions and their runs on a connected workflow engine: launch, observe, transitions, engine logs, outputs, cancel, abandon and recapture. |
const outline = await client.documents.markdown.outline(documentId);
const { items } = await client.inventory.items.query({ itemTypeIds: [itemTypeId] });
const file = await client.storage.upload.file({ file: blob, filename: 'run.csv' });
const { results } = await client.search.search({ query: 'assay' });
for await (const hit of client.search.searchAll({ query: 'assay' })) {
// … `searchAll` pages for you; `break` stops fetching
}// Translators and landing: render a samplesheet for a pipeline port, land its output.
const { translator } = await client.data.translators.create({ name: 'samplesheet', /* … */ });
const preview = await client.data.translators.preview(translator.id);
const landed = await client.data.outputs.land({ /* output, target */ });
// Connections and storage: register a Seqera workspace and a bucket, mount it as a folder.
const { connections } = await client.connections.list(workspaceId, { kind: 'seqera' });
const description = await client.connections.describePipeline(workspaceId, connections[0].id, { ref: 'nf-core/rnaseq' });
const location = await client.storage.locations.create(workspaceId, { connectionId, name: 'results', bucket, prefix });
const { mount } = await client.storage.mounts.create(workspaceId, { locationId: location.id, folderId });
await client.storage.mounts.requestIndex(workspaceId, mount.id);
// Pipelines: launch a saved definition and follow its runs.
const run = await client.pipelines.definitions.launch(workspaceId, definitionId, { idempotencyKey: 'nightly-1' });
const { transitions } = await client.pipelines.runs.transitions(workspaceId, run.id);
for await (const r of client.pipelines.runs.iterate(workspaceId, { status: 'active' })) {
// … keyset paged on `nextBefore`
}The SDK exposes the platform's public surface only. Entity deletion (connections, locations, mounts, definitions and translators are archived or left in place, never deleted from here), clearing a per-user connection identity, the AI suite, and user/workspace/organization settings are not part of it.
Error handling
Every failure throws a typed DaleaError subclass you can branch on:
import { DaleaRateLimitError, DaleaValidationError } from '@dalea/sdk';
try {
await client.data.environments.list();
} catch (err) {
if (err instanceof DaleaRateLimitError) {
// Retries are automatic (see below); this only fires once they're exhausted.
// err.retryAfterSeconds carries the server's hint.
} else if (err instanceof DaleaValidationError) {
// err.code / err.message / err.data describe what the server rejected.
} else {
throw err;
}
}Other subclasses: DaleaAuthError, DaleaPermissionError, DaleaNotFoundError,
DaleaConflictError, DaleaArchivedError, DaleaQuotaError, DaleaServerError,
DaleaNetworkError.
Retries & backoff
Throttling responses (429) are retried automatically with exponential backoff and
full jitter, honouring the server's Retry-After, so you never need to hand-roll a
backoff loop. Writes retry on a 429 too: a throttle is rejected before the handler
runs, so replaying is safe. A 503 can be emitted after a write has committed, so it
is only replayed for idempotent GETs, never for a write, even with retryWrites: true.
A DaleaRateLimitError surfaces only once retries are exhausted (or when the server asks
for a wait longer than maxRetryDelayMs). Terminal errors like DaleaQuotaError (507)
are never retried. Pass retry in a call's options to override the policy for one
request.
Tune or opt out via the constructor:
| Option | Default | Meaning |
| --- | --- | --- |
| maxRetries | 2 | Max retries per request. |
| retryWrites | true | Retry POST/PATCH/DELETE on a 429, not just GET. Set false for strict, no-replay callers. |
| retryBaseDelayMs | 500 | Base delay for exponential backoff when the server sends no Retry-After. |
| maxRetryDelayMs | 20000 | Ceiling on any single backoff wait; a longer Retry-After fails fast. |
Pagination
List endpoints expose iterate* async iterators built on the exported paginate
primitive, so you can walk every page without managing cursors yourself:
for await (const obj of client.data.tables.iterateObjects(tableId)) {
// … `break` stops fetching the next page
}For whole-table reads, streamObjects streams rows in one request. The server caps a
stream by rows and bytes; if the cap cuts it short the iterator throws
StreamTruncatedError with the number of rows already yielded, so a partial read is
never mistaken for a complete one.
import { StreamTruncatedError } from '@dalea/sdk';
try {
for await (const row of client.data.tables.streamObjects(tableId)) { /* … */ }
} catch (err) {
if (err instanceof StreamTruncatedError) {
// err.rowsYielded rows arrived; fall back to iterateObjects to page the rest.
} else throw err;
}Documentation
- API reference — https://dalea.app/api-docs
- Guides & concepts — the Dalea wiki
License
MIT © Dalea
