degallery-javascript

---
name: degallery-javascript
description: Integrate DeGallery from JavaScript or TypeScript with @degallery/sdk or trusted Node.js code with @degallery/node. Use for client setup, gallery reads, asset uploads, and choosing the right runtime package.
---

# JavaScript and Node.js integration

Use `@degallery/sdk` for framework-neutral TypeScript clients. Use `@degallery/node` only in trusted Node.js/server code when Node-specific helpers are needed. Keep API keys and signing secrets in a server-side secret manager.

## Install and configure

```bash
pnpm add @degallery/sdk
```

```ts
import { GalleryClient } from '@degallery/sdk';

const client = new GalleryClient({
  apiUrl: process.env.DEGALLERY_API_URL ?? 'https://api.degallery.dev',
  apiKey: process.env.DEGALLERY_API_KEY,
});
```

For browser code, do not set `apiKey` to a private API key. Use a publishable key, a short-lived read token, or a server-provided public gallery payload as appropriate. Never expose private keys through `NEXT_PUBLIC_*` variables.

## Read gallery data

```ts
const gallery = await client.getGallery('gallery-id-or-slug');
const page = await client.galleries.retrievePage('gallery-id-or-slug', {
  includeAssets: true,
  limit: 9,
});
```

For public rendering from the media manifest, configure `mediaUrl` and use `getPublicGalleryManifest()` where that route is appropriate. See the [JavaScript client guide](https://docs.degallery.dev/docs/javascript/get-started) for the current API surface and pagination details.

## Upload an image

The upload flow has three steps: create an intent, transfer the exact bytes to the returned upload URL using its method and content type, then complete the intent.

```ts
const intent = await client.createUpload({
  filename: 'studio.jpg',
  contentType: 'image/jpeg',
  size: imageBytes.byteLength,
  visibility: 'public',
});

await fetch(intent.uploadUrl, {
  method: intent.method ?? 'PUT',
  headers: { 'Content-Type': intent.contentType ?? 'image/jpeg' },
  body: imageBytes,
});

const asset = await client.completeUpload(intent.intentId);
```

The upload URL expires. Handle transfer or completion failures safely and retry completion through a trusted integration when appropriate. Do not treat the upload URL alone as proof that an asset was successfully completed.

## Node-only signing helper

Install `@degallery/node` for trusted server code. Its `createDeliveryToken()` helper signs a delivery capability with HMAC-SHA256; authorize the resource before issuing a token and keep the signing secret private. Do not issue private delivery tokens from browser code. See the [integration choice guide](https://docs.degallery.dev/docs/guides/choose-an-integration) and [private gallery guide](https://docs.degallery.dev/docs/how-to/authorize-a-private-gallery).

## Further guidance

- For React rendering, use `degallery-react`.
- For credential and private delivery details, use `degallery-auth-and-private-media`.
- Check the [JavaScript installation guide](https://docs.degallery.dev/docs/javascript/installation) and [client guide](https://docs.degallery.dev/docs/javascript/get-started) when APIs or package versions change.