@pickleball/server-sdk 0.1.1

package/dist/chunk-HBTNLURN.js

@@ -0,0 +1,618 @@
+// src/errors.ts
+var PickleballLiveError = class extends Error {
+  constructor(message, code, options) {
+    super(message, options);
+    this.code = code;
+    this.name = "PickleballLiveError";
+  }
+};
+var PickleballConfigurationError = class extends PickleballLiveError {
+  constructor(message) {
+    super(message, "CONFIGURATION_ERROR");
+    this.name = "PickleballConfigurationError";
+  }
+};
+var PickleballApiError = class extends PickleballLiveError {
+  constructor(message, code, status) {
+    super(message, code);
+    this.status = status;
+    this.name = "PickleballApiError";
+  }
+};
+var PickleballHttpError = class extends PickleballLiveError {
+  constructor(status) {
+    super(`Request failed with HTTP ${status}`, "HTTP_ERROR");
+    this.status = status;
+    this.name = "PickleballHttpError";
+  }
+};
+var PickleballInvalidResponseError = class extends PickleballLiveError {
+  constructor() {
+    super("The server returned an invalid response", "INVALID_RESPONSE");
+    this.name = "PickleballInvalidResponseError";
+  }
+};
+var PickleballTimeoutError = class extends PickleballLiveError {
+  constructor() {
+    super("The request timed out", "TIMEOUT");
+    this.name = "PickleballTimeoutError";
+  }
+};
+var PickleballNetworkError = class extends PickleballLiveError {
+  constructor() {
+    super("The request failed because of a network error", "NETWORK_ERROR");
+    this.name = "PickleballNetworkError";
+  }
+};
+var PickleballWebhookVerificationError = class extends PickleballLiveError {
+  constructor(message = "Webhook verification failed") {
+    super(message, "WEBHOOK_VERIFICATION_FAILED");
+    this.name = "PickleballWebhookVerificationError";
+  }
+};
+
+// src/webhooks.ts
+function fail() {
+  throw new PickleballWebhookVerificationError();
+}
+function headerValue(headers, name) {
+  if (headers instanceof Headers) return headers.get(name);
+  const entry = Object.entries(headers).find(([key]) => key.toLowerCase() === name);
+  if (!entry) return null;
+  const value = entry[1];
+  return Array.isArray(value) ? value.join(",") : value ?? null;
+}
+function bodyBytes(rawBody) {
+  return typeof rawBody === "string" ? new TextEncoder().encode(rawBody) : rawBody;
+}
+function signedBytes(timestamp, rawBody) {
+  const prefix = new TextEncoder().encode(`${timestamp}.`);
+  const body = bodyBytes(rawBody);
+  const result = new Uint8Array(prefix.length + body.length);
+  result.set(prefix);
+  result.set(body, prefix.length);
+  return result;
+}
+function decodeHex(value) {
+  if (!/^[0-9a-fA-F]{64}$/.test(value)) return null;
+  const bytes = new Uint8Array(value.length / 2);
+  for (let index = 0; index < bytes.length; index += 1) {
+    bytes[index] = Number.parseInt(value.slice(index * 2, index * 2 + 2), 16);
+  }
+  return bytes;
+}
+function constantTimeEqual(left, right) {
+  let difference = left.length ^ right.length;
+  const length = Math.max(left.length, right.length);
+  for (let index = 0; index < length; index += 1) {
+    difference |= (left[index] ?? 0) ^ (right[index] ?? 0);
+  }
+  return difference === 0;
+}
+function encodeHex(value) {
+  return Array.from(value, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function parseSignature(header) {
+  let timestamp = null;
+  const signatures = [];
+  for (const field of header.split(",")) {
+    const separator = field.indexOf("=");
+    if (separator === -1) continue;
+    const key = field.slice(0, separator).trim();
+    const value = field.slice(separator + 1).trim();
+    if (key === "t" && /^\d+$/.test(value)) timestamp = Number(value);
+    if (key === "v1") {
+      const decoded = decodeHex(value);
+      if (decoded) signatures.push(decoded);
+    }
+  }
+  if (timestamp === null || !Number.isSafeInteger(timestamp) || signatures.length === 0) fail();
+  return { timestamp, signatures };
+}
+function decodeJson(rawBody) {
+  let text;
+  try {
+    text = typeof rawBody === "string" ? rawBody : new TextDecoder("utf-8", { fatal: true }).decode(rawBody);
+    return JSON.parse(text);
+  } catch {
+    fail();
+  }
+}
+async function verifyWebhook(rawBody, headers, secret, options = {}) {
+  const id = headerValue(headers, "webhook-id");
+  const transportEvent = headerValue(headers, "webhook-event");
+  const signatureHeader = headerValue(headers, "webhook-signature");
+  if (!id?.trim() || !transportEvent?.trim() || !signatureHeader || typeof secret !== "string" || !secret.trim()) {
+    fail();
+  }
+  const toleranceSeconds = options.toleranceSeconds ?? 300;
+  const now = options.now ?? Date.now();
+  if (!Number.isFinite(toleranceSeconds) || toleranceSeconds < 0 || !Number.isFinite(now)) fail();
+  const { timestamp, signatures } = parseSignature(signatureHeader);
+  if (Math.abs(now / 1e3 - timestamp) > toleranceSeconds) fail();
+  const body = decodeJson(rawBody);
+  if (typeof body !== "object" || body === null || typeof body.event !== "string") fail();
+  if (!body.event.trim() || body.event !== transportEvent) fail();
+  const key = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const mac = new Uint8Array(
+    await crypto.subtle.sign(
+      "HMAC",
+      key,
+      Uint8Array.from(signedBytes(timestamp, rawBody)).buffer
+    )
+  );
+  let verified = false;
+  for (const signature of signatures) {
+    verified = constantTimeEqual(mac, signature) || verified;
+  }
+  if (!verified) fail();
+  const bodyHash = new Uint8Array(
+    await crypto.subtle.digest(
+      "SHA-256",
+      Uint8Array.from(bodyBytes(rawBody)).buffer
+    )
+  );
+  return {
+    transportId: id,
+    dedupeKey: `body-sha256:${encodeHex(bodyHash)}`,
+    event: body.event,
+    timestamp,
+    body
+  };
+}
+
+// src/validators.ts
+function invalid() {
+  throw new PickleballInvalidResponseError();
+}
+function record(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) invalid();
+  return value;
+}
+function nonblank(value) {
+  if (typeof value !== "string" || value.trim() === "") invalid();
+  return value;
+}
+function finite(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) invalid();
+  return value;
+}
+function nullableString(value) {
+  if (value === null) return null;
+  return nonblank(value);
+}
+function nullableNumber(value) {
+  if (value === null) return null;
+  return finite(value);
+}
+function validateRemoteConfig(value) {
+  const data = record(value);
+  if (typeof data.enabled !== "boolean" || data.protocolVersion !== 1 || data.videoQuality !== 720 && data.videoQuality !== 1080) {
+    invalid();
+  }
+  const reconnectTimeoutMs = finite(data.reconnectTimeoutMs);
+  const backgroundGraceMs = finite(data.backgroundGraceMs);
+  const telemetryIntervalMs = finite(data.telemetryIntervalMs);
+  const maxSessionDurationMs = finite(data.maxSessionDurationMs);
+  if (reconnectTimeoutMs < 0 || backgroundGraceMs < 0 || telemetryIntervalMs <= 0 || maxSessionDurationMs <= 0) {
+    invalid();
+  }
+  return {
+    enabled: data.enabled,
+    protocolVersion: 1,
+    minSdkVersion: nonblank(data.minSdkVersion),
+    recommendedSdkVersion: nonblank(data.recommendedSdkVersion),
+    videoQuality: data.videoQuality,
+    reconnectTimeoutMs,
+    backgroundGraceMs,
+    telemetryIntervalMs,
+    maxSessionDurationMs,
+    ...data.standbyTimeoutMs === void 0 ? {} : { standbyTimeoutMs: finite(data.standbyTimeoutMs) }
+  };
+}
+function validateBootstrap(value) {
+  const data = record(value);
+  if (typeof data.rolloutEnabled !== "boolean") invalid();
+  if (data.message !== void 0 && typeof data.message !== "string") invalid();
+  return {
+    config: validateRemoteConfig(data.config),
+    serverTime: finite(data.serverTime),
+    rolloutEnabled: data.rolloutEnabled,
+    ...data.message === void 0 ? {} : { message: data.message }
+  };
+}
+function validateTelemetry(value) {
+  const data = record(value);
+  return {
+    endpoint: nonblank(data.endpoint),
+    token: nonblank(data.token),
+    expiresAt: finite(data.expiresAt)
+  };
+}
+function validateGrant(value) {
+  const data = record(value);
+  return {
+    sessionId: nonblank(data.sessionId),
+    serverUrl: nonblank(data.serverUrl),
+    participantToken: nonblank(data.participantToken),
+    playbackUrl: nullableString(data.playbackUrl),
+    tokenExpiresAt: finite(data.tokenExpiresAt),
+    telemetry: validateTelemetry(data.telemetry),
+    config: validateRemoteConfig(data.config)
+  };
+}
+function validateRefresh(value) {
+  const data = record(value);
+  return {
+    ...data.participantToken === void 0 ? {} : { participantToken: nonblank(data.participantToken) },
+    ...data.tokenExpiresAt === void 0 ? {} : { tokenExpiresAt: finite(data.tokenExpiresAt) },
+    ...data.telemetry === void 0 ? {} : { telemetry: validateTelemetry(data.telemetry) },
+    config: validateRemoteConfig(data.config)
+  };
+}
+function validateEnd(value, sessionId) {
+  const data = record(value);
+  if (data.sessionId !== sessionId || data.status !== "ended") invalid();
+}
+function validatePublishState(value, sessionId) {
+  const data = record(value);
+  if (data.sessionId !== sessionId) invalid();
+  if (data.status !== "scheduled" && data.status !== "live") invalid();
+  return { sessionId, status: data.status };
+}
+function validateSession(value) {
+  const data = record(value);
+  if (data.status !== "scheduled" && data.status !== "live" && data.status !== "ended") {
+    invalid();
+  }
+  if (data.visibility !== "public" && data.visibility !== "private") invalid();
+  const viewerCount = finite(data.viewerCount);
+  const likeCount = finite(data.likeCount);
+  const shareCount = finite(data.shareCount);
+  if (viewerCount < 0 || likeCount < 0 || shareCount < 0) invalid();
+  return {
+    id: nonblank(data.id),
+    title: nonblank(data.title),
+    status: data.status,
+    visibility: data.visibility,
+    matchRef: nullableString(data.matchRef),
+    playbackUrl: nullableString(data.playbackUrl),
+    watchUrl: nullableString(data.watchUrl),
+    scheduledAt: nullableNumber(data.scheduledAt),
+    startedAt: nullableNumber(data.startedAt),
+    endedAt: nullableNumber(data.endedAt),
+    viewerCount,
+    likeCount,
+    shareCount
+  };
+}
+function validateRecording(value, sessionId) {
+  const data = record(value);
+  if (data.sessionId !== sessionId) invalid();
+  if (data.type !== "clean" && data.type !== "derived" && data.type !== "device") invalid();
+  if (data.status !== "recording" && data.status !== "ready" && data.status !== "failed") {
+    invalid();
+  }
+  const durationSec = nullableNumber(data.durationSec);
+  if (durationSec !== null && durationSec < 0) invalid();
+  return {
+    id: nonblank(data.id),
+    sessionId,
+    type: data.type,
+    status: data.status,
+    url: nullableString(data.url),
+    durationSec
+  };
+}
+function validateRecordings(value, sessionId) {
+  if (!Array.isArray(value)) invalid();
+  return value.map((item) => validateRecording(item, sessionId));
+}
+
+// src/contracts.ts
+var SDK_TELEMETRY_EVENT_NAMES = [
+  "state_changed",
+  "connection_quality",
+  "reconnect",
+  "error",
+  "heartbeat",
+  "session_ended"
+];
+
+// src/index.ts
+var TRANSIENT_STATUSES = /* @__PURE__ */ new Set([408, 429]);
+var RETRY_BASE_MS = 100;
+var RETRY_MAX_MS = 2e3;
+var RETRY_AFTER_MAX_MS = 3e4;
+var RESPONSE_BODY_MAX_BYTES = 1024 * 1024;
+var SDK_ERROR_CODES = /* @__PURE__ */ new Set([
+  "PERMISSION_DENIED",
+  "NETWORK_UNAVAILABLE",
+  "TOKEN_EXPIRED",
+  "SDK_UPGRADE_REQUIRED",
+  "SESSION_CONFLICT",
+  "RECORDING_FAILED",
+  "CONSENT_REQUIRED",
+  "SDK_DISABLED",
+  "UNKNOWN"
+]);
+var DETERMINISTIC_ERROR_CODES = /* @__PURE__ */ new Set([
+  "PERMISSION_DENIED",
+  "TOKEN_EXPIRED",
+  "SDK_UPGRADE_REQUIRED",
+  "SESSION_CONFLICT",
+  "RECORDING_FAILED",
+  "CONSENT_REQUIRED",
+  "SDK_DISABLED"
+]);
+function requiredNonblank(value, name) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new PickleballConfigurationError(`${name} must be a non-empty string`);
+  }
+  return value;
+}
+function validatedBaseUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new PickleballConfigurationError("baseUrl must be an absolute HTTP(S) URL");
+  }
+  const loopbackHosts = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::1]"]);
+  const secure = url.protocol === "https:";
+  const localDevelopment = url.protocol === "http:" && loopbackHosts.has(url.hostname);
+  if (!secure && !localDevelopment || url.username || url.password) {
+    throw new PickleballConfigurationError(
+      "baseUrl must use HTTPS (HTTP is allowed only for localhost loopback)"
+    );
+  }
+  url.pathname = url.pathname.replace(/\/+$/, "");
+  url.search = "";
+  url.hash = "";
+  return url.toString().replace(/\/$/, "");
+}
+function positiveFinite(value, name) {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new PickleballConfigurationError(`${name} must be a positive finite number`);
+  }
+  return value;
+}
+function validRetryCount(value) {
+  if (!Number.isInteger(value) || value < 0 || value > 10) {
+    throw new PickleballConfigurationError("maxRetries must be an integer between 0 and 10");
+  }
+  return value;
+}
+function isTransientStatus(status) {
+  return TRANSIENT_STATUSES.has(status) || status >= 500;
+}
+function isRetryableResponseError(error) {
+  return !(error instanceof PickleballApiError && DETERMINISTIC_ERROR_CODES.has(error.code));
+}
+function retryAfterMs(response, now = Date.now()) {
+  const raw = response.headers.get("retry-after");
+  if (raw === null) return null;
+  const seconds = Number(raw);
+  const delay = Number.isFinite(seconds) ? seconds * 1e3 : Date.parse(raw) - now;
+  if (!Number.isFinite(delay) || delay < 0) return null;
+  return Math.min(delay, RETRY_AFTER_MAX_MS);
+}
+function wait(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function parseSdkError(payload, status, apiKey) {
+  if (!isRecord(payload) || !("error" in payload)) {
+    return new PickleballInvalidResponseError();
+  }
+  if (typeof payload.error === "string") {
+    return new PickleballHttpError(status);
+  }
+  if (!isRecord(payload.error)) {
+    return new PickleballInvalidResponseError();
+  }
+  const { code, message } = payload.error;
+  if (typeof code !== "string" || code.trim() === "" || typeof message !== "string") {
+    return new PickleballInvalidResponseError();
+  }
+  const safeMessage = apiKey === "" ? message : message.split(apiKey).join("[REDACTED]");
+  const safeCode = SDK_ERROR_CODES.has(code) ? code : "UNKNOWN";
+  return new PickleballApiError(safeMessage, safeCode, status);
+}
+async function readBoundedResponseText(response) {
+  const declaredLength = Number(response.headers.get("content-length"));
+  if (Number.isFinite(declaredLength) && declaredLength > RESPONSE_BODY_MAX_BYTES) {
+    await response.body?.cancel().catch(() => void 0);
+    throw new PickleballInvalidResponseError();
+  }
+  if (!response.body) return "";
+  const reader = response.body.getReader();
+  const chunks = [];
+  let total = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      total += value.byteLength;
+      if (total > RESPONSE_BODY_MAX_BYTES) {
+        await reader.cancel().catch(() => void 0);
+        throw new PickleballInvalidResponseError();
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return new TextDecoder().decode(bytes);
+}
+async function decodeResponse(response, apiKey, validate) {
+  if (response.status >= 300 && response.status < 400) {
+    await response.body?.cancel().catch(() => void 0);
+    throw new PickleballHttpError(response.status);
+  }
+  const text = await readBoundedResponseText(response);
+  let payload;
+  try {
+    payload = JSON.parse(text);
+  } catch {
+    throw new PickleballInvalidResponseError();
+  }
+  if (!response.ok) throw parseSdkError(payload, response.status, apiKey);
+  if (!isRecord(payload) || !("data" in payload)) {
+    throw new PickleballInvalidResponseError();
+  }
+  return validate(payload.data);
+}
+function createPickleballLiveClient(options) {
+  const baseUrl = validatedBaseUrl(options.baseUrl);
+  const appId = requiredNonblank(options.appId, "appId");
+  const apiKey = requiredNonblank(options.apiKey, "apiKey");
+  const fetchImplementation = options.fetch ?? globalThis.fetch;
+  if (typeof fetchImplementation !== "function") {
+    throw new PickleballConfigurationError("fetch must be available");
+  }
+  const timeoutMs = positiveFinite(options.timeoutMs ?? 1e4, "timeoutMs");
+  const maxRetries = validRetryCount(options.maxRetries ?? 2);
+  async function request({
+    method,
+    path,
+    body,
+    retryPolicy,
+    validate
+  }) {
+    const retryLimit = retryPolicy === "transient" ? maxRetries : 0;
+    for (let attempt = 0; attempt <= retryLimit; attempt += 1) {
+      const controller = new AbortController();
+      let response;
+      let timedOut = false;
+      const timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+      }, timeoutMs);
+      try {
+        response = await fetchImplementation(`${baseUrl}${path}`, {
+          method,
+          headers: method === "POST" ? {
+            accept: "application/json",
+            "content-type": "application/json",
+            "x-api-key": apiKey
+          } : {
+            accept: "application/json",
+            "x-api-key": apiKey,
+            "x-pickleball-app-id": appId
+          },
+          ...body === void 0 ? {} : { body: JSON.stringify(body) },
+          signal: controller.signal,
+          redirect: "error"
+        });
+        try {
+          return await decodeResponse(response, apiKey, validate);
+        } catch (error) {
+          if (isTransientStatus(response.status) && attempt < retryLimit && isRetryableResponseError(error)) {
+            clearTimeout(timer);
+            const delay = retryAfterMs(response) ?? Math.min(RETRY_BASE_MS * 2 ** attempt, RETRY_MAX_MS);
+            await response.body?.cancel().catch(() => void 0);
+            await wait(delay);
+            continue;
+          }
+          throw error;
+        }
+      } catch (error) {
+        if (error instanceof PickleballApiError || error instanceof PickleballHttpError || error instanceof PickleballInvalidResponseError) {
+          throw error;
+        }
+        if (attempt < retryLimit) {
+          await wait(Math.min(RETRY_BASE_MS * 2 ** attempt, RETRY_MAX_MS));
+          continue;
+        }
+        if (timedOut) throw new PickleballTimeoutError();
+        throw new PickleballNetworkError();
+      } finally {
+        clearTimeout(timer);
+        if (timedOut) await response?.body?.cancel().catch(() => void 0);
+      }
+    }
+    throw new PickleballNetworkError();
+  }
+  const post = (path, body, retryPolicy, validate) => request({ method: "POST", path, body, retryPolicy, validate });
+  const get = (path, validate) => request({ method: "GET", path, retryPolicy: "transient", validate });
+  const sessionPath = (sessionId) => `/api/v2/sdk/sessions/${encodeURIComponent(sessionId)}`;
+  return {
+    apps: {
+      bootstrap: (input) => post(
+        "/api/v2/sdk/bootstrap",
+        { ...input, appId },
+        "transient",
+        validateBootstrap
+      )
+    },
+    sessions: {
+      start: (input) => post(
+        "/api/v2/sdk/sessions",
+        { ...input, appId },
+        "transient",
+        validateGrant
+      ),
+      refresh: (sessionId, input) => post(
+        `${sessionPath(sessionId)}/refresh`,
+        { ...input, appId },
+        "never",
+        validateRefresh
+      ),
+      end: async (input) => {
+        await post(
+          `${sessionPath(input.sessionId)}/end`,
+          { ...input, appId },
+          "transient",
+          (value) => validateEnd(value, input.sessionId)
+        );
+      },
+      publish: (sessionId) => post(
+        `${sessionPath(sessionId)}/publish`,
+        { sessionId, appId },
+        "transient",
+        (value) => validatePublishState(value, sessionId)
+      ),
+      unpublish: (sessionId) => post(
+        `${sessionPath(sessionId)}/unpublish`,
+        { sessionId, appId },
+        "transient",
+        (value) => validatePublishState(value, sessionId)
+      ),
+      get: (sessionId) => get(sessionPath(sessionId), validateSession),
+      getRecordings: (sessionId) => get(
+        `${sessionPath(sessionId)}/recordings`,
+        (value) => validateRecordings(value, sessionId)
+      )
+    },
+    webhooks: { verify: verifyWebhook }
+  };
+}
+
+export {
+  PickleballLiveError,
+  PickleballConfigurationError,
+  PickleballApiError,
+  PickleballHttpError,
+  PickleballInvalidResponseError,
+  PickleballTimeoutError,
+  PickleballNetworkError,
+  PickleballWebhookVerificationError,
+  verifyWebhook,
+  SDK_TELEMETRY_EVENT_NAMES,
+  createPickleballLiveClient
+};