@hexdn/upload

Framework-neutral HexDN uploads with no runtime dependencies. Media bytes go directly to storage; your backend owns authorization and creates the scoped upload capability. Never pass an environment API key to this package.

Register your application's upload origin in HexDN before browser uploads. Your endpoint checks whether the user may upload and returns the capability; the SDK handles the browser request and transfer.

import { createUploadEndpoint, uploadSource } from "@hexdn/upload";

const getUpload = createUploadEndpoint({ endpoint: "/api/uploads" });
const upload = await getUpload(file);

await uploadSource({
  upload,
  source: file,
  onProgress: ({ phase, uploadedBytes, totalBytes }) => {
    renderProgress(phase, uploadedBytes, totalBytes);
  },
});

The endpoint receives a JSON POST with filename, byteLength, and mimeType, plus an Idempotency-Key header. It authenticates the user, chooses outputs, and forwards the key to server SDK asset creation. Return { upload: { url, token } } or the capability directly. sdk.assets.createUpload(...) already returns the accepted upload field. The browser request uses same-origin credentials and bypasses caches; no environment API key is sent from the browser.

If your application already has the capability, pass it straight to uploadSource. React applications can use <Uploader uploadEndpoint="/api/uploads" /> from @hexdn/react/upload, which also manages selection, cancellation, and retry identity.

uploadSource inspects the upload, prepares its exact byte length, reconciles provider-recorded parts, uploads missing slices in bounded batches, and completes the upload. Completion confirms receipt of the source; processing outputs may still be waiting or processing.

Pass an AbortController's signal to getUpload(file, { signal }) and uploadSource({ upload, source: file, signal }) to stop local work. Aborting does not delete the upload or its asset. cancelUpload({ upload }) is the separate, destructive server cancellation operation and should only follow the user's cancellation decision.

To resume, call uploadSource again with the same capability and original file. The provider's part list is authoritative. Saved part fingerprints prevent a different same-size file from being combined with existing parts. Fingerprinting reads bounded chunks; the default fence uses browser storage when available and otherwise retains proofs for this page. Missing or mismatched proofs fail closed. Use createUploadResumeFence(storage) or implement UploadResumeFence to control proof persistence. Capabilities and part tickets still expire.

PUT retries are bounded and honor Retry-After, cancellation, and ticket expiry. An uncertain completion is checked against authoritative upload state. If it remains unresolved, the operation rejects without cancelling; retry the same upload rather than creating a replacement automatically. Progress is transfer progress, not a verified processing-readiness signal.

If capability creation loses its response, retry the same getUpload resolver with the same File; it retains its creation key until a valid response arrives. An application-owned workflow can pass its own idempotencyKey to getUpload(file, { idempotencyKey, signal }). The React uploader manages that key automatically. Custom request handling can replace getUpload entirely, or use the helper's optional fetch override.

Applications with an authenticated upload proxy can supply an UploadControlClient to uploadSource instead of calling HexDN control URLs directly. The proxy remains responsible for its authorization and safe control-request retries.

For an existing application that already manages upload creation, ticket issuance, and completion, use the smaller transfer boundary:

import { uploadMultipartSource } from "@hexdn/upload";

await uploadMultipartSource(
  {
    file,
    instructions, // Server-provided MultipartUploadPlan.
    issueParts: (partNumbers, signal) =>
      applicationUploadApi.issueParts({ partNumbers, signal }),
  },
  { signal, onProgress: ({ percent }) => renderPercent(percent) },
);

This lower-level function transfers the supplied multipart plan with continuous XHR progress where available, bounded concurrency, and fail-fast sibling aborts. It does not inspect prior provider parts, allocate resources, or complete/cancel an upload. onDelivery exposes safe retry/recovery facts without signed URLs, tokens, or filenames; route those through your application's observability.

Build and verify from the HexDN workspace:

pnpm --filter @hexdn/upload build
pnpm --filter @hexdn/upload typecheck
pnpm --filter @hexdn/upload test

The package publishes ESM JavaScript and TypeScript declarations from dist. It does not import React, the playback engine, analytics, or the server SDK.