@portabyte/node 0.0.1

package/LICENSE

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

@@ -0,0 +1,166 @@
+# Portabyte Node.js SDK
+
+Upload, deliver, and manage files from trusted TypeScript server code. The SDK has no runtime package dependencies and uses your runtime's built-in `fetch`.
+
+> Keep `pbt_sk_live_` API keys on your server. Do not use this SDK in browser code, mobile apps, or browser extensions.
+
+## Install
+
+```sh
+npm install @portabyte/node
+```
+
+The SDK requires Node.js 18 or later.
+
+## Upload a file
+
+Create a client with a project API key, then pass a file to `files.upload`. The SDK creates the upload session, transfers the bytes, confirms the asset, and returns the live file record.
+
+```ts
+import { readFile } from 'node:fs/promises';
+import { Portabyte } from '@portabyte/node';
+
+const portabyte = new Portabyte({
+  apiKey: process.env.PORTABYTE_API_KEY!,
+});
+
+const asset = await portabyte.files.upload({
+  file: await readFile('./summary.pdf'),
+  name: 'summary.pdf',
+  contentType: 'application/pdf',
+  visibility: 'public',
+});
+
+console.log(asset.publicUrl);
+```
+
+When your server receives a web `File`, such as through a route handler's `FormData`, pass it directly. The SDK reads its filename, MIME type, and size:
+
+```ts
+const asset = await portabyte.files.upload({
+  file,
+  path: 'reports/2026/may/summary.pdf',
+  visibility: 'private',
+});
+```
+
+Use `path` when you want one current file at a stable application-owned address. Uploading another confirmed file to that path replaces the current one.
+
+## Deliver a file
+
+Request a delivery URL with the file's ID:
+
+```ts
+const delivery = await portabyte.files.url(asset.id);
+
+if (delivery.public) {
+  console.log(delivery.url);
+} else {
+  console.log(delivery.expiresAt);
+}
+```
+
+Public files return stable URLs. Private files return short-lived signed URLs. Request a new private URL whenever an authorized recipient needs the file.
+
+## Resume a large upload
+
+Files of 32 MiB or larger use multipart upload automatically. For an upload that must survive a process restart, create a session and persist multipart state after each completed part:
+
+```ts
+const session = await portabyte.files.create({
+  name: 'recording.mp4',
+  contentType: 'video/mp4',
+  sizeBytes: video.size,
+});
+
+const asset = await portabyte.files.resume(session, {
+  file: video,
+  state: savedUploadState,
+  onStateChange: saveUploadState,
+});
+```
+
+Resume with the same byte size and MIME type. Multipart upload sessions expire after 12 hours.
+
+## Manage files
+
+Use the file ID to retrieve metadata, list a project page, or delete a file:
+
+```ts
+const file = await portabyte.files.get(asset.id);
+const page = await portabyte.files.list({ limit: 20 });
+await portabyte.files.remove(file.id);
+```
+
+Pass `page.cursor` to `files.list` to retrieve the next page.
+
+## Configure the client
+
+| Option       | Description                                                  | Default                     |
+| ------------ | ------------------------------------------------------------ | --------------------------- |
+| `apiKey`     | Project API key that starts with `pbt_sk_live_`              | Required                    |
+| `baseUrl`    | Control-plane API URL                                        | `https://api.portabyte.dev` |
+| `maxRetries` | Retries for idempotent requests                              | `2`                         |
+| `timeoutMs`  | Timeout for each request in milliseconds; set `0` to disable | `30000`                     |
+| `fetch`      | Custom `fetch` implementation                                | Runtime `fetch`             |
+
+The SDK retries `GET` requests and upload-byte requests after network failures, `429` responses, and `5xx` responses. It does not retry state-changing API calls.
+
+## Upload directly from a browser
+
+Keep your API key on your server. Prepare the upload on your server, return the browser-safe session to the client, then confirm it on your server after the browser has uploaded the bytes.
+
+Before using this flow, set your frontend's origin once in **Console → Project → Settings → Upload defaults → Default CORS origin** (for example, `https://app.example.com`). The SDK uses that project default when `corsOrigin` is omitted. Pass `corsOrigin` only when a particular upload needs a different allowed origin.
+
+```ts
+// Your server route: POST /api/uploads/prepare
+const upload = await portabyte.files.prepareBrowserUpload({
+  name: file.name,
+  contentType: file.type,
+  sizeBytes: file.size,
+  visibility: 'public',
+});
+
+// Return `upload` to the browser. Never return PORTABYTE_API_KEY.
+```
+
+```ts
+// Browser code
+await fetch(upload.uploadUrl, {
+  method: 'PUT',
+  headers: { 'Content-Type': file.type },
+  body: file,
+});
+
+// Tell your server the upload completed, then on the server:
+const asset = await portabyte.files.confirm(upload.assetId);
+```
+
+For multipart sessions, use `uploadMode`, `partSize`, and `maxConcurrency` to upload parts through the same signed upload URL. Your server must still call `confirm` once the multipart upload completes.
+
+## Handle errors
+
+Failed requests throw `PortabyteError`, which includes the HTTP status, a stable error code, and a request ID when the API returns one:
+
+```ts
+import { PortabyteError } from '@portabyte/node';
+
+try {
+  await portabyte.files.upload(uploadRequest);
+} catch (error) {
+  if (error instanceof PortabyteError) {
+    console.error(error.status, error.code, error.requestId);
+  }
+}
+```
+
+## Learn more
+
+- [Getting started](https://portabyte.dev/docs/getting-started/node-sdk)
+- [REST API reference](https://portabyte.dev/docs/api-reference)
+- [Browser uploads](https://portabyte.dev/docs/upload-delivery/browser-uploads)
+- [Public and private files](https://portabyte.dev/docs/upload-delivery/public-and-private-files)
+
+## License
+
+[MIT](./LICENSE)

package/dist/index.cjs

@@ -0,0 +1,462 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Portabyte: () => Portabyte,
+  PortabyteError: () => PortabyteError,
+  VERSION: () => VERSION
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var PortabyteError = class extends Error {
+  status;
+  code;
+  requestId;
+  constructor(message, status, code, requestId) {
+    super(message);
+    this.name = "PortabyteError";
+    this.status = status;
+    this.code = code;
+    this.requestId = requestId;
+  }
+};
+
+// src/client.ts
+var SDK_HEADER_NAME = "X-Portabyte-SDK";
+var RetryableError = class extends Error {
+  constructor(retryAfterMs, fallback) {
+    super("retryable request failure");
+    this.retryAfterMs = retryAfterMs;
+    this.fallback = fallback;
+  }
+  retryAfterMs;
+  fallback;
+};
+var HttpClient = class {
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  async request(options) {
+    const idempotent = options.method === "GET";
+    return this.run(idempotent, async () => {
+      const response = await this.send(this.options.baseUrl + options.path, {
+        method: options.method,
+        headers: {
+          Authorization: `Bearer ${this.options.apiKey}`,
+          [SDK_HEADER_NAME]: this.options.sdkHeaderValue,
+          ...options.body !== void 0 || options.method !== "GET" ? { "Content-Type": "application/json" } : {}
+        },
+        body: options.body === void 0 ? void 0 : JSON.stringify(options.body)
+      });
+      if (!response.ok) {
+        throw await responseError(response, idempotent);
+      }
+      if (response.status === 204) {
+        return void 0;
+      }
+      return await response.json();
+    });
+  }
+  // The gateway's CORS policy allows only Content-Type; the signed URL is
+  // the authorization, and the runtime sets the exact-match Content-Length.
+  async putBytes(uploadUrl, contentType, data) {
+    await this.run(true, async () => {
+      const response = await this.send(uploadUrl, {
+        method: "PUT",
+        headers: { "Content-Type": contentType },
+        body: data
+      });
+      if (!response.ok) {
+        throw await responseError(response, true);
+      }
+    });
+  }
+  async putBytesJSON(uploadUrl, contentType, data) {
+    return this.run(true, async () => {
+      const response = await this.send(uploadUrl, {
+        method: "PUT",
+        headers: { "Content-Type": contentType },
+        body: data
+      });
+      if (!response.ok) {
+        throw await responseError(response, true);
+      }
+      return await response.json();
+    });
+  }
+  async uploadJSON(uploadUrl, method, body, idempotent) {
+    return this.run(idempotent, async () => {
+      const response = await this.send(uploadUrl, {
+        method,
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body)
+      });
+      if (!response.ok) {
+        throw await responseError(response, idempotent);
+      }
+      if (response.status === 204) {
+        return void 0;
+      }
+      return await response.json();
+    });
+  }
+  async send(url, init) {
+    try {
+      return await this.options.fetchImpl(url, {
+        ...init,
+        signal: this.options.timeoutMs > 0 ? AbortSignal.timeout(this.options.timeoutMs) : void 0
+      });
+    } catch (cause) {
+      throw new RetryableError(
+        null,
+        new PortabyteError(
+          cause instanceof Error ? cause.message : "Network request failed.",
+          0,
+          "network_error"
+        )
+      );
+    }
+  }
+  async run(idempotent, send) {
+    for (let attempt = 0; ; attempt++) {
+      try {
+        return await send();
+      } catch (error) {
+        const retry = error instanceof RetryableError;
+        if (!retry || !idempotent || attempt >= this.options.maxRetries) {
+          throw retry ? error.fallback : error;
+        }
+        await sleep(error.retryAfterMs ?? backoffMs(attempt));
+      }
+    }
+  }
+};
+async function responseError(response, idempotent) {
+  const error = await errorFromResponse(response);
+  if (idempotent && (response.status === 429 || response.status >= 500)) {
+    const retryAfter = Number(response.headers.get("retry-after"));
+    const retryAfterMs = Number.isFinite(retryAfter) && retryAfter >= 0 ? retryAfter * 1e3 : null;
+    return new RetryableError(retryAfterMs, error);
+  }
+  return error;
+}
+function backoffMs(attempt) {
+  const baseMs = 500;
+  const capMs = 8e3;
+  return Math.floor(Math.random() * Math.min(capMs, baseMs * 2 ** attempt));
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function errorFromResponse(response) {
+  let code = "request_failed";
+  let message = `Request failed with status ${response.status}.`;
+  let requestId;
+  try {
+    const body = await response.json();
+    code = body.code ?? code;
+    message = body.message ?? message;
+    requestId = body.requestId;
+  } catch {
+  }
+  return new PortabyteError(message, response.status, code, requestId);
+}
+
+// src/assets.ts
+var FilesAPI = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** Creates a signed upload session. Prefer {@link upload}, which runs every step. */
+  async create(input) {
+    const body = {
+      name: input.name,
+      contentType: input.contentType,
+      sizeBytes: input.sizeBytes,
+      ...input.path !== void 0 && { path: input.path },
+      ...input.visibility !== void 0 && { visibility: input.visibility },
+      ...input.corsOrigin !== void 0 && { corsOrigin: input.corsOrigin }
+    };
+    return this.http.request({
+      method: "POST",
+      path: this.path("assets"),
+      body
+    });
+  }
+  /**
+   * Prepares a direct browser upload. Call this only from your trusted server,
+   * then return the result to the browser. The browser uploads bytes directly
+   * to uploadUrl; call {@link confirm} from your server once it reports success.
+   */
+  async prepareBrowserUpload(input) {
+    const session = await this.create(input);
+    return {
+      assetId: session.id,
+      uploadUrl: session.uploadUrl,
+      uploadExpiresAt: session.uploadExpiresAt,
+      uploadMode: session.uploadMode,
+      ...session.partSize !== void 0 && { partSize: session.partSize },
+      ...session.maxConcurrency !== void 0 && {
+        maxConcurrency: session.maxConcurrency
+      }
+    };
+  }
+  /**
+   * Confirms a completed direct upload and returns its live asset record.
+   * Call this from your trusted server, never from a browser.
+   */
+  async confirm(assetID) {
+    return this.http.request({
+      method: "POST",
+      path: this.path(`assets/${assetID}/uploaded`)
+    });
+  }
+  /** Uploads a File, Blob, or bytes end to end. */
+  async upload(request) {
+    const described = describeUpload(request);
+    const { file, multipart } = request;
+    const createOptions = {
+      ...request.path !== void 0 && { path: request.path },
+      ...request.visibility !== void 0 && { visibility: request.visibility },
+      ...request.corsOrigin !== void 0 && { corsOrigin: request.corsOrigin }
+    };
+    const session = await this.create({ ...described, ...createOptions });
+    await this.transfer(
+      session,
+      file,
+      described.contentType,
+      multipart
+    );
+    try {
+      return await this.confirm(session.id);
+    } catch (error) {
+      if (error instanceof PortabyteError && error.status !== 0) {
+        await this.remove(session.id).catch(() => void 0);
+      }
+      throw error;
+    }
+  }
+  /**
+   * Continues a previously-created session. Persist the create session and
+   * MultipartUploadState after each part to resume after an interruption.
+   */
+  async resume(session, request) {
+    const contentType = request.contentType ?? (request.file instanceof Blob ? request.file.type : "");
+    if (fileSize(request.file) !== session.sizeBytes || contentType !== session.contentType) {
+      throw new PortabyteError(
+        "The selected file does not match this upload session.",
+        0,
+        "invalid_argument"
+      );
+    }
+    await this.transfer(session, request.file, contentType, request);
+    return this.confirm(session.id);
+  }
+  async list(options = {}) {
+    const params = new URLSearchParams();
+    if (options.cursor) params.set("cursor", options.cursor);
+    if (options.limit !== void 0) params.set("limit", String(options.limit));
+    const query = params.size > 0 ? `?${params}` : "";
+    return this.http.request({
+      method: "GET",
+      path: this.path(`assets${query}`)
+    });
+  }
+  async get(assetID) {
+    return this.http.request({
+      method: "GET",
+      path: this.path(`assets/${assetID}`)
+    });
+  }
+  async remove(assetID) {
+    await this.http.request({
+      method: "DELETE",
+      path: this.path(`assets/${assetID}`)
+    });
+  }
+  /**
+   * Cancels a multipart transfer and removes its pending asset. The gateway
+   * abort is best-effort: removing the pending asset guarantees the object
+   * can never be confirmed or delivered, even if its signed URL has expired.
+   */
+  async cancel(session, state) {
+    if (session.uploadMode === "multipart" && state?.uploadId) {
+      await this.http.uploadJSON(
+        `${session.uploadUrl}/multipart/${state.uploadId}`,
+        "DELETE",
+        void 0,
+        false
+      ).catch(() => void 0);
+    }
+    await this.remove(session.id);
+  }
+  /**
+   * Returns the URL the asset is served from: stable and cacheable for
+   * public assets, short-lived signed otherwise.
+   */
+  async url(assetID) {
+    return this.http.request({
+      method: "GET",
+      path: this.path(`assets/${assetID}/url`)
+    });
+  }
+  path(suffix) {
+    return `/v1/${suffix}`;
+  }
+  async transfer(session, body, contentType, options) {
+    if (session.uploadMode === "single") {
+      await this.http.putBytes(session.uploadUrl, contentType, body);
+      return;
+    }
+    await this.uploadMultipart(session, body, contentType, options);
+  }
+  async uploadMultipart(session, body, contentType, options = {}) {
+    if (!session.partSize || session.partSize < 5 * 1024 * 1024) {
+      throw new PortabyteError(
+        "Multipart upload session is missing a valid part size.",
+        0,
+        "invalid_upload"
+      );
+    }
+    const state = {
+      uploadId: options.state?.uploadId,
+      parts: [...options.state?.parts ?? []]
+    };
+    if (!state.uploadId) {
+      const started = await this.http.uploadJSON(
+        `${session.uploadUrl}/multipart`,
+        "POST",
+        {},
+        false
+      );
+      state.uploadId = started.uploadId;
+      await options.onStateChange?.({ ...state, parts: [...state.parts] });
+    }
+    const partCount = Math.ceil(session.sizeBytes / session.partSize);
+    const completed = new Map(
+      state.parts.map((part) => [part.partNumber, part])
+    );
+    const concurrency = Math.max(
+      1,
+      Math.min(options.concurrency ?? session.maxConcurrency ?? 3, 3)
+    );
+    let nextPart = 1;
+    const uploadNext = async () => {
+      for (; ; ) {
+        const partNumber = nextPart;
+        nextPart += 1;
+        if (partNumber > partCount) return;
+        if (completed.has(partNumber)) continue;
+        const start = (partNumber - 1) * session.partSize;
+        const end = Math.min(start + session.partSize, session.sizeBytes);
+        const part = await this.http.putBytesJSON(
+          `${session.uploadUrl}/multipart/${state.uploadId}/parts/${partNumber}`,
+          contentType,
+          sliceBody(body, start, end)
+        );
+        completed.set(part.partNumber, part);
+        state.parts = [...completed.values()].sort(
+          (left, right) => left.partNumber - right.partNumber
+        );
+        await options.onStateChange?.({ ...state, parts: [...state.parts] });
+      }
+    };
+    await Promise.all(
+      Array.from({ length: Math.min(concurrency, partCount) }, uploadNext)
+    );
+    await this.http.uploadJSON(
+      `${session.uploadUrl}/multipart/${state.uploadId}/complete`,
+      "POST",
+      { parts: state.parts },
+      true
+    );
+  }
+};
+function describeUpload(request) {
+  const filename = request.name ?? fileName(request.file);
+  const mimeType = request.contentType ?? (request.file instanceof Blob ? request.file.type : "");
+  if (!filename) {
+    throw new PortabyteError(
+      "A file name is required when uploading a Blob or bytes.",
+      0,
+      "invalid_argument"
+    );
+  }
+  if (!mimeType) {
+    throw new PortabyteError(
+      "A content type is required when uploading bytes or a Blob without a type.",
+      0,
+      "invalid_argument"
+    );
+  }
+  return {
+    name: filename,
+    contentType: mimeType,
+    sizeBytes: request.file instanceof Blob ? request.file.size : request.file.byteLength
+  };
+}
+function fileName(file) {
+  if (!(file instanceof Blob)) return void 0;
+  const name = file.name;
+  return typeof name === "string" && name.length > 0 ? name : void 0;
+}
+function fileSize(file) {
+  return file instanceof Blob ? file.size : file.byteLength;
+}
+function sliceBody(body, start, end) {
+  return body instanceof Blob ? body.slice(start, end) : body.slice(start, end);
+}
+
+// src/index.ts
+var VERSION = "0.0.1";
+var DEFAULT_BASE_URL = "https://api.portabyte.dev";
+var Portabyte = class {
+  /** Preferred API for application file uploads. */
+  files;
+  constructor(options) {
+    if (!options.apiKey.startsWith("pbt_sk_live_")) {
+      throw new PortabyteError(
+        'apiKey must be a server API key starting with "pbt_sk_live_".',
+        0,
+        "invalid_argument"
+      );
+    }
+    const http = new HttpClient({
+      baseUrl: (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, ""),
+      apiKey: options.apiKey,
+      fetchImpl: options.fetch ?? fetch,
+      maxRetries: options.maxRetries ?? 2,
+      timeoutMs: options.timeoutMs ?? 3e4,
+      sdkHeaderValue: `typescript/${VERSION}`
+    });
+    this.files = new FilesAPI(http);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Portabyte,
+  PortabyteError,
+  VERSION
+});
+//# sourceMappingURL=index.cjs.map