@degallery/node 0.2.2 → 0.4.0

package/README.md

@@ -1,11 +1,103 @@
-# node
+# `@degallery/node`
 
-This library was generated with [Nx](https://nx.dev).
+Node.js helpers for trusted DeGallery integrations. Use this package at a server boundary when you need the framework-neutral `@degallery/sdk` client plus Node-specific signing utilities.
 
-## Building
+This package is not a browser UI library and must not be included in a public client bundle.
 
-Run `nx build node` to build the library.
+## Product and developer links
 
-## Running unit tests
+- [DeGallery landing page](https://degallery.dev)
+- [Developer documentation](https://docs.degallery.dev)
+- [JavaScript installation](https://docs.degallery.dev/docs/javascript/installation)
+- [Production readiness](https://docs.degallery.dev/docs/guides/production-readiness)
+- [Private gallery authorization](https://docs.degallery.dev/docs/how-to/authorize-a-private-gallery)
+- [Image delivery guide](https://docs.degallery.dev/docs/how-to/track-delivery)
+- [Live demo](https://demo.degallery.dev)
+- [Dashboard](https://app.degallery.dev)
+- [Source repository](https://github.com/mmpotulo28/thegallery)
 
-Run `nx test node` to execute the unit tests via [Vitest](https://vitest.dev/).
+## Install
+
+```bash
+pnpm add @degallery/node
+```
+
+The package re-exports `GalleryClient` and selected public SDK types:
+
+```ts
+import { GalleryClient, type GallerySummary } from '@degallery/node';
+```
+
+## Configure a server client
+
+```ts
+import { GalleryClient } from '@degallery/node';
+
+const client = new GalleryClient({
+  apiUrl: process.env.DEGALLERY_API_URL ?? 'https://api.degallery.dev',
+  apiKey: process.env.DEGALLERY_API_KEY,
+});
+
+const gallery = await client.getGallery('gallery-id-or-slug');
+```
+
+Keep `DEGALLERY_API_KEY` in the server secret manager. Never use a `NEXT_PUBLIC_*` variable for a private credential and never return the credential to a browser.
+
+For the full client surface, see the [`@degallery/sdk` README](../sdk/README.md) and the [JavaScript client documentation](https://docs.degallery.dev/docs/javascript/get-started).
+
+## Create a delivery token
+
+`createDeliveryToken` creates a signed token for a delivery resource. Keep the signing secret private and issue tokens only after your server has authorized the requested resource:
+
+```ts
+import { createDeliveryToken } from '@degallery/node';
+
+const token = createDeliveryToken(
+  {
+    organizationId: 'organization-id',
+    environmentId: 'environment-id',
+    resource: 'asset-id',
+    revision: 3,
+    preset: 'large',
+    expiresAt: Math.floor(Date.now() / 1000) + 300,
+    keyId: 'v1',
+  },
+  process.env.DEGALLERY_DELIVERY_SECRET!,
+);
+```
+
+The helper signs the Worker-compatible claims (`iss`, `aud`, `org`, `env`, `resource`, `revision`, `preset`, `iat`, `exp`, and `kid`) with HMAC-SHA256. `expiresAt` is a Unix timestamp in seconds and the lifetime cannot exceed 15 minutes. The token is not an authorization policy by itself: validate ownership, visibility, expiry, and requested transformations before issuing it. Never issue a private delivery token in browser code.
+
+## What this package exports
+
+- `GalleryClient` from `@degallery/sdk`
+- `Asset`, `GalleryDetail`, `GalleryLinkPayload`, and `GallerySummary` types
+- `createDeliveryToken`
+- `node`, the package health-check export
+
+For uploads, use the SDK intent flow from the server:
+
+```ts
+const intent = await client.createUpload({
+  filename: 'image.jpg',
+  contentType: 'image/jpeg',
+  size: bytes.byteLength,
+  visibility: 'private',
+});
+
+await fetch(intent.uploadUrl, {
+  method: intent.method ?? 'PUT',
+  headers: { 'Content-Type': intent.contentType ?? 'image/jpeg' },
+  body: bytes,
+});
+
+await client.completeUpload(intent.intentId);
+```
+
+## Runtime guidance
+
+- Run this package only in Node.js or another trusted server runtime.
+- Store API and delivery secrets in a managed secret store.
+- Keep delivery tokens short-lived.
+- Do not log signed URLs, API keys, or delivery tokens.
+- Treat client-provided asset IDs and presets as untrusted input.

package/dist/lib/node.d.ts

@@ -1,10 +1,15 @@
 export { GalleryClient } from '@degallery/sdk';
 export type { Asset, GalleryDetail, GalleryLinkPayload, GallerySummary, } from '@degallery/sdk';
 export declare function node(): string;
-export declare function createDeliveryToken(input: {
-    resourceId: string;
+export type DeliveryTokenInput = Readonly<{
+    organizationId: string;
     environmentId: string;
-    preset: string;
+    resource: string;
+    revision: number;
+    preset: 'original' | 'thumbnail' | 'large';
     expiresAt: number;
-}, secret: string): string;
+    issuedAt?: number;
+    keyId?: string;
+}>;
+export declare function createDeliveryToken(input: DeliveryTokenInput, secret: string): string;
 //# sourceMappingURL=node.d.ts.map

package/dist/lib/node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../src/lib/node.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,YAAY,EACV,KAAK,EACL,aAAa,EACb,kBAAkB,EAClB,cAAc,GACf,MAAM,gBAAgB,CAAC;AAExB,wBAAgB,IAAI,IAAI,MAAM,CAE7B;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE;IACL,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB,EACD,MAAM,EAAE,MAAM,UAIf"}
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../src/lib/node.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,YAAY,EACV,KAAK,EACL,aAAa,EACb,kBAAkB,EAClB,cAAc,GACf,MAAM,gBAAgB,CAAC;AAExB,wBAAgB,IAAI,IAAI,MAAM,CAE7B;AAED,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC;IACxC,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,UAAU,GAAG,WAAW,GAAG,OAAO,CAAC;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC,CAAC;AAEH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,kBAAkB,EAAE,MAAM,EAAE,MAAM,UA0C5E"}

package/dist/lib/node.js

@@ -10,6 +10,41 @@ function node() {
     return 'node';
 }
 function createDeliveryToken(input, secret) {
-    const payload = Buffer.from(JSON.stringify(input)).toString('base64url');
-    return `${payload}.${(0, node_crypto_1.createHmac)('sha256', secret).update(payload).digest('base64url')}`;
+    if (!secret)
+        throw new TypeError('A delivery signing secret is required.');
+    const issuedAt = input.issuedAt ?? Math.floor(Date.now() / 1000);
+    const lifetime = input.expiresAt - issuedAt;
+    const keyId = input.keyId ?? 'v1';
+    if (!input.organizationId ||
+        input.organizationId.length > 128 ||
+        !input.environmentId ||
+        input.environmentId.length > 128 ||
+        !input.resource ||
+        input.resource.length > 128 ||
+        !Number.isSafeInteger(input.revision) ||
+        input.revision < 1 ||
+        !['original', 'thumbnail', 'large'].includes(input.preset) ||
+        !Number.isSafeInteger(issuedAt) ||
+        !Number.isSafeInteger(input.expiresAt) ||
+        !keyId ||
+        keyId.length > 128 ||
+        lifetime < 1 ||
+        lifetime > 900)
+        throw new TypeError('Delivery token claims are invalid.');
+    const payload = Buffer.from(JSON.stringify({
+        iss: 'thegallery',
+        aud: 'media-delivery',
+        org: input.organizationId,
+        env: input.environmentId,
+        resource: input.resource,
+        revision: input.revision,
+        preset: input.preset,
+        iat: issuedAt,
+        exp: input.expiresAt,
+        kid: keyId,
+    })).toString('base64url');
+    const signature = (0, node_crypto_1.createHmac)('sha256', secret)
+        .update(payload)
+        .digest('base64url');
+    return `${payload}.${signature}`;
 }

package/package.json

@@ -1,12 +1,9 @@
 {
   "name": "@degallery/node",
-  "version": "0.2.2",
+  "version": "0.4.0",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "scripts": {
-    "lib:publish": "npm publish --access public"
-  },
   "exports": {
     "./package.json": "./package.json",
     ".": {
@@ -22,6 +19,9 @@
   ],
   "dependencies": {
     "tslib": "^2.3.0",
-    "@degallery/sdk": "workspace:*"
+    "@degallery/sdk": "0.4.0"
+  },
+  "scripts": {
+    "lib:publish": "pnpm publish --access public"
   }
-}
+}