@devultur/server 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cristhian De Marchena
+
+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

@@ -1,3 +1,39 @@
-# Temporary Holding Version
+# @devultur/server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Server SDK for Devultur media: create upload URLs, issue viewer tokens, sign and verify delivery URLs, trigger
+transcodes and captions, and handle webhooks. Point it at your self-hosted media Worker, or straight at your own
+Cloudflare R2 bucket.
+
+## Install
+
+```bash
+pnpm add @devultur/server
+```
+
+## Example
+
+```typescript
+import { createMediaRouter } from "@devultur/server";
+
+export const media = createMediaRouter({
+  baseUrl: "https://media.example.com", // your media Worker
+  secret: process.env.WORKER_AUTH_SECRET!, // never ship it to the browser
+});
+
+// In an authenticated route: the browser uploads to `url`, you store `key`.
+const { url, key } = await media.createUploadUrl({ filename: "lesson-1.mp4", contentType: "video/mp4" });
+
+// A short-lived token that lets this user play private media.
+const { token } = await media.issueToken("user_123");
+```
+
+Without a Worker, pass `storage` (R2 credentials) and `delivery` (`signSecret`) instead of `baseUrl` and `secret`.
+`@devultur/server/node` adds `uploadLargeFile`, a parallel multipart upload of a large file from disk (Node 20+).
+
+## Documentation
+
+Guides and API reference: [github.com/devultur/devultur/tree/main/docs](https://github.com/devultur/devultur/tree/main/docs).
+
+## License
+
+[MIT](https://github.com/devultur/devultur/blob/main/LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+import { MediaEvent, MediaRouter, UploadUrlResult } from '@devultur/core';
+export { AssetUploadResult, CreateUploadTokenOptions, CreateUploadUrlOptions, DeliveryConfig, DevulturApiError, DevulturKind, DevulturMedia, DirectStorageConfig, DownloadLink, DownloadLinkOptions, DownloadUrlOptions, FileBuilderConfig, FileHead, FilesClient, ImageBuilderConfig, MediaEvent, MediaEventName, MediaRouter, MediaRouterConfig, MediaUrlOptions, SignOptions, StorageClient, StorageConfig, UploadAssetOptions, UploadToken, UploadUrlResult, UploadsClient, VideoBuilderConfig, Visibility, WebhookVerifyOptions, WorkerClient, WorkerConfig, assetKey, buildMediaUrl, createMediaRouter, createStorageClient, createWorkerClient, file, getDownloadUrl, image, mediaCaptionPath, mediaPath, mediaThumbnailPath, mediaUrl, normalizeAssetPath, normalizeAssetPrefix, publicUrl, resolveVisibility, signPayload, signUrl, verifySignature, verifySignedUrl, video, visibilityFromKey } from '@devultur/core';
+
+interface DevulturRequest {
+    method: string;
+    url: string;
+    headers: Record<string, string | undefined>;
+    body: unknown;
+}
+interface DevulturResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: unknown;
+}
+interface HandleUploadOptions {
+    filename: string;
+    contentType: string;
+    metadata?: Record<string, string>;
+}
+/** One event of the media Worker's webhook, narrowed by its `event` name. */
+type MediaEventOf<Name extends MediaEvent["event"]> = Extract<MediaEvent, {
+    event: Name;
+}>;
+interface WebhookHandlerConfig {
+    /** The secret the Worker sends as `Authorization: Bearer <secret>`. */
+    secret: string;
+    /** Every authenticated event, including `transcode.started` and `transcode.progress`. */
+    onEvent?: (event: MediaEvent) => Promise<void>;
+    onTranscodeComplete?: (event: MediaEventOf<"transcode.complete">) => Promise<void>;
+    onTranscodeFailed?: (event: MediaEventOf<"transcode.failed">) => Promise<void>;
+    onCaptionsComplete?: (event: MediaEventOf<"captions.complete">) => Promise<void>;
+    onCaptionsFailed?: (event: MediaEventOf<"captions.failed">) => Promise<void>;
+}
+
+declare function fromWebRequest(request: Request): Promise<DevulturRequest>;
+declare function toWebResponse(response: DevulturResponse): Response;
+
+declare function createUploadHandler(router: MediaRouter): (options: HandleUploadOptions) => Promise<UploadUrlResult>;
+declare function createSignedUrlHandler(router: MediaRouter): (url: string, expiresIn?: number) => Promise<string>;
+declare function createWebhookHandler(router: MediaRouter, config: WebhookHandlerConfig): (request: DevulturRequest) => Promise<DevulturResponse>;
+
+interface DevulturMiddlewareOptions {
+    prefix?: string;
+}
+
+export { type DevulturMiddlewareOptions, type DevulturRequest, type DevulturResponse, type HandleUploadOptions, type MediaEventOf, type WebhookHandlerConfig, createSignedUrlHandler, createUploadHandler, createWebhookHandler, fromWebRequest, toWebResponse };

package/dist/index.js

@@ -0,0 +1,133 @@
+// src/index.ts
+import {
+  assetKey,
+  buildMediaUrl,
+  createMediaRouter,
+  createStorageClient,
+  createWorkerClient,
+  DevulturApiError,
+  file,
+  getDownloadUrl,
+  image,
+  MediaEventName as MediaEventName2,
+  mediaCaptionPath,
+  mediaPath,
+  mediaThumbnailPath,
+  mediaUrl,
+  normalizeAssetPath,
+  normalizeAssetPrefix,
+  publicUrl,
+  resolveVisibility,
+  signPayload,
+  signUrl,
+  verifySignature,
+  verifySignedUrl,
+  video,
+  visibilityFromKey
+} from "@devultur/core";
+
+// src/adapters/web.ts
+async function fromWebRequest(request) {
+  const headers = {};
+  request.headers.forEach((value, key) => {
+    headers[key] = value;
+  });
+  let body = null;
+  if (request.method !== "GET" && request.method !== "HEAD") {
+    const contentType = request.headers.get("content-type") ?? "";
+    if (contentType.includes("application/json")) {
+      body = await request.json();
+    } else {
+      body = await request.text();
+    }
+  }
+  return {
+    method: request.method,
+    url: request.url,
+    headers,
+    body
+  };
+}
+function toWebResponse(response) {
+  const body = typeof response.body === "string" ? response.body : JSON.stringify(response.body);
+  return new Response(body, {
+    status: response.status,
+    headers: response.headers
+  });
+}
+
+// src/handlers.ts
+import { MediaEventName } from "@devultur/core";
+function createUploadHandler(router) {
+  return async (options) => {
+    return router.createUploadUrl({
+      filename: options.filename,
+      contentType: options.contentType,
+      metadata: options.metadata
+    });
+  };
+}
+function createSignedUrlHandler(router) {
+  return async (url, expiresIn) => {
+    return router.sign(url, { expiresIn });
+  };
+}
+function createWebhookHandler(router, config) {
+  return async (request) => {
+    let event;
+    try {
+      event = await router.handleWebhook(request.body, {
+        authorization: request.headers.authorization ?? request.headers.Authorization,
+        secret: config.secret
+      });
+    } catch {
+      return { status: 401, headers: { "content-type": "application/json" }, body: { error: "Unauthorized" } };
+    }
+    await config.onEvent?.(event);
+    await dispatchEvent(event, config);
+    return { status: 200, headers: { "content-type": "application/json" }, body: { received: true } };
+  };
+}
+async function dispatchEvent(event, config) {
+  switch (event.event) {
+    case MediaEventName.TRANSCODE_COMPLETE:
+      return config.onTranscodeComplete?.(event);
+    case MediaEventName.TRANSCODE_FAILED:
+      return config.onTranscodeFailed?.(event);
+    case MediaEventName.CAPTIONS_COMPLETE:
+      return config.onCaptionsComplete?.(event);
+    case MediaEventName.CAPTIONS_FAILED:
+      return config.onCaptionsFailed?.(event);
+  }
+}
+export {
+  DevulturApiError,
+  MediaEventName2 as MediaEventName,
+  assetKey,
+  buildMediaUrl,
+  createMediaRouter,
+  createSignedUrlHandler,
+  createStorageClient,
+  createUploadHandler,
+  createWebhookHandler,
+  createWorkerClient,
+  file,
+  fromWebRequest,
+  getDownloadUrl,
+  image,
+  mediaCaptionPath,
+  mediaPath,
+  mediaThumbnailPath,
+  mediaUrl,
+  normalizeAssetPath,
+  normalizeAssetPrefix,
+  publicUrl,
+  resolveVisibility,
+  signPayload,
+  signUrl,
+  toWebResponse,
+  verifySignature,
+  verifySignedUrl,
+  video,
+  visibilityFromKey
+};

package/dist/node.d.ts

@@ -0,0 +1,32 @@
+import { AssetUploadResult, Visibility } from '@devultur/core';
+
+interface UploadLargeFileOptions {
+    /** Prefix inside `asset/` (`exports/inst-1/`). */
+    prefix: string;
+    /** File name in the prefix. Default: the local file's basename. */
+    name?: string;
+    /** TTL in seconds (with an upload token, at most the token's own). */
+    expiresIn?: number;
+    /** Upload token or the worker's credential. Default: `DEVULTUR_UPLOAD_TOKEN` or `DEVULTUR_SECRET`. */
+    credential?: string;
+    /** Worker origin (`https://media.example.com`). */
+    baseUrl: string;
+    contentType?: string;
+    overwrite?: boolean;
+    visibility?: Visibility;
+    /** `Cache-Control`: preset (`immutable` | `revalidate` | `no-cache`) or a string validated by the worker. */
+    cacheControl?: string;
+    /** Already-computed sha256 hex (e.g. from a sync script): used instead of reading the file again. */
+    sha256?: string;
+    /** Parts in flight at once (default 4). */
+    concurrency?: number;
+    onProgress?: (percent: number) => void;
+    signal?: AbortSignal;
+}
+interface LargeFileUploadResult extends AssetUploadResult {
+    /** sha256 computed locally (the one declared to the worker). */
+    sha256: string;
+}
+declare function uploadLargeFile(filePath: string, options: UploadLargeFileOptions): Promise<LargeFileUploadResult>;
+
+export { type LargeFileUploadResult, type UploadLargeFileOptions, uploadLargeFile };

package/dist/node.js

@@ -0,0 +1,42 @@
+// src/upload-large-file.ts
+import { createWorkerClient } from "@devultur/core";
+async function sha256OfFile(filePath) {
+  const { createHash } = await import("crypto");
+  const { createReadStream } = await import("fs");
+  const hash = createHash("sha256");
+  for await (const chunk of createReadStream(filePath)) hash.update(chunk);
+  return hash.digest("hex");
+}
+function resolveCredential(explicit) {
+  const credential = explicit ?? process.env.DEVULTUR_UPLOAD_TOKEN ?? process.env.DEVULTUR_SECRET;
+  if (!credential) throw new Error("uploadLargeFile needs a credential (DEVULTUR_UPLOAD_TOKEN or DEVULTUR_SECRET)");
+  return credential;
+}
+async function uploadLargeFile(filePath, options) {
+  const { openAsBlob } = await import("fs");
+  const { basename } = await import("path");
+  const credential = resolveCredential(options.credential);
+  const prefix = options.prefix.endsWith("/") ? options.prefix : `${options.prefix}/`;
+  const sha256 = options.sha256 ?? await sha256OfFile(filePath);
+  const file = await openAsBlob(filePath, { type: options.contentType ?? "application/octet-stream" });
+  const client = createWorkerClient(credential, options.baseUrl);
+  const result = await client.uploads.uploadAsset(file, {
+    path: `${prefix}${options.name ?? basename(filePath)}`,
+    contentType: options.contentType,
+    sha256,
+    expiresIn: options.expiresIn,
+    overwrite: options.overwrite,
+    visibility: options.visibility,
+    cacheControl: options.cacheControl,
+    concurrency: options.concurrency,
+    onProgress: options.onProgress,
+    signal: options.signal
+  });
+  if (result.sha256 && result.sha256 !== sha256) {
+    throw new Error(`sha256 mismatch for ${result.key}: local ${sha256}, stored ${result.sha256}`);
+  }
+  return { ...result, sha256 };
+}
+export {
+  uploadLargeFile
+};

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@devultur/server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.1",
+  "description": "Server SDK for Devultur media: upload URLs, viewer tokens, signed delivery URLs, transcodes, captions and webhooks",
+  "keywords": [
+    "media",
+    "video",
+    "r2",
+    "cloudflare",
+    "hls",
+    "upload",
+    "webhooks",
+    "signed-url"
+  ],
+  "private": false,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/devultur/devultur",
+    "directory": "packages/server"
+  },
+  "homepage": "https://github.com/devultur/devultur#readme",
+  "bugs": {
+    "url": "https://github.com/devultur/devultur/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./node": {
+      "import": "./dist/node.js",
+      "types": "./dist/node.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@devultur/core": "1.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.8.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/node.ts --format esm --dts",
+    "dev": "tsup src/index.ts src/node.ts --format esm --dts --watch",
+    "typecheck": "tsc --noEmit"
+  }
 }