@pickleball/server-sdk 0.1.1

package/dist/proxy.d.cts

@@ -0,0 +1,39 @@
+import { PickleballLiveClient } from './index.cjs';
+
+interface ProxyEnvironment {
+    PICKLEBALL_API_BASE_URL: string;
+    PICKLEBALL_APP_ID: string;
+    PICKLEBALL_API_KEY: string;
+    PICKLEBALL_PROXY_AUTHZ_URL: string;
+    PICKLEBALL_PROXY_AUTHZ_SERVICE_TOKEN: string;
+}
+interface PickleballApiEnvironment {
+    PICKLEBALL_API_BASE_URL: string;
+    PICKLEBALL_APP_ID: string;
+    PICKLEBALL_API_KEY: string;
+}
+interface ProxyDependencies {
+    env: Partial<ProxyEnvironment>;
+    createClient?: (env: PickleballApiEnvironment) => ProxyClient;
+    authzFetch?: typeof globalThis.fetch;
+    logger?: Pick<Console, "error">;
+}
+type ProxyClient = {
+    apps: Pick<PickleballLiveClient["apps"], "bootstrap">;
+    sessions: Pick<PickleballLiveClient["sessions"], "start" | "refresh" | "end" | "publish" | "unpublish">;
+};
+interface SessionActionParams {
+    id: string;
+    action: string;
+}
+declare function createStableIdempotencyKey(input: {
+    appId: string;
+    installationId: string;
+    externalSessionId: string;
+    consentVersion: string;
+}): Promise<string>;
+declare function handleBootstrap(request: Request, deps: ProxyDependencies): Promise<Response>;
+declare function handleSessions(request: Request, deps: ProxyDependencies): Promise<Response>;
+declare function handleSessionAction(request: Request, params: SessionActionParams, deps: ProxyDependencies): Promise<Response>;
+
+export { type ProxyDependencies, type ProxyEnvironment, type SessionActionParams, createStableIdempotencyKey, handleBootstrap, handleSessionAction, handleSessions };

package/dist/proxy.d.ts

@@ -0,0 +1,39 @@
+import { PickleballLiveClient } from './index.js';
+
+interface ProxyEnvironment {
+    PICKLEBALL_API_BASE_URL: string;
+    PICKLEBALL_APP_ID: string;
+    PICKLEBALL_API_KEY: string;
+    PICKLEBALL_PROXY_AUTHZ_URL: string;
+    PICKLEBALL_PROXY_AUTHZ_SERVICE_TOKEN: string;
+}
+interface PickleballApiEnvironment {
+    PICKLEBALL_API_BASE_URL: string;
+    PICKLEBALL_APP_ID: string;
+    PICKLEBALL_API_KEY: string;
+}
+interface ProxyDependencies {
+    env: Partial<ProxyEnvironment>;
+    createClient?: (env: PickleballApiEnvironment) => ProxyClient;
+    authzFetch?: typeof globalThis.fetch;
+    logger?: Pick<Console, "error">;
+}
+type ProxyClient = {
+    apps: Pick<PickleballLiveClient["apps"], "bootstrap">;
+    sessions: Pick<PickleballLiveClient["sessions"], "start" | "refresh" | "end" | "publish" | "unpublish">;
+};
+interface SessionActionParams {
+    id: string;
+    action: string;
+}
+declare function createStableIdempotencyKey(input: {
+    appId: string;
+    installationId: string;
+    externalSessionId: string;
+    consentVersion: string;
+}): Promise<string>;
+declare function handleBootstrap(request: Request, deps: ProxyDependencies): Promise<Response>;
+declare function handleSessions(request: Request, deps: ProxyDependencies): Promise<Response>;
+declare function handleSessionAction(request: Request, params: SessionActionParams, deps: ProxyDependencies): Promise<Response>;
+
+export { type ProxyDependencies, type ProxyEnvironment, type SessionActionParams, createStableIdempotencyKey, handleBootstrap, handleSessionAction, handleSessions };

package/dist/proxy.js

@@ -0,0 +1,403 @@
+import {
+  PickleballApiError,
+  PickleballConfigurationError,
+  PickleballHttpError,
+  PickleballInvalidResponseError,
+  PickleballNetworkError,
+  PickleballTimeoutError,
+  createPickleballLiveClient
+} from "./chunk-HBTNLURN.js";
+
+// src/proxy.ts
+var MAX_BODY_BYTES = 16 * 1024;
+var SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+var BUNDLE_ID = /^[A-Za-z0-9](?:[A-Za-z0-9._-]{1,253}[A-Za-z0-9])?$/;
+var INSTALLATION_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{5,255}$/;
+var SAFE_UPSTREAM_CODES = /* @__PURE__ */ new Set([
+  "PERMISSION_DENIED",
+  "NETWORK_UNAVAILABLE",
+  "TOKEN_EXPIRED",
+  "SDK_UPGRADE_REQUIRED",
+  "SESSION_CONFLICT",
+  "RECORDING_FAILED",
+  "CONSENT_REQUIRED",
+  "SDK_DISABLED",
+  "UNKNOWN"
+]);
+var InvalidRequest = class extends Error {
+};
+var AuthenticationRequired = class extends Error {
+};
+var AuthorizationDecision = class extends Error {
+  constructor(status, code) {
+    super(code);
+    this.status = status;
+    this.code = code;
+  }
+};
+var AuthorizationUnavailable = class extends Error {
+};
+function response(data, status = 200) {
+  return Response.json(data, {
+    status,
+    headers: {
+      "cache-control": "no-store",
+      "content-type": "application/json; charset=utf-8"
+    }
+  });
+}
+function errorResponse(status, code, message) {
+  return response({ error: { code, message } }, status);
+}
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function hasOnlyKeys(value, allowed) {
+  const allowedKeys = new Set(allowed);
+  return Object.keys(value).every((key) => allowedKeys.has(key));
+}
+function nonblank(value, maximum) {
+  return typeof value === "string" && value.trim().length > 0 && value.length <= maximum && !/[\u0000-\u001f\u007f]/.test(value);
+}
+async function bodyObject(request) {
+  const contentType = request.headers.get("content-type")?.split(";", 1)[0].trim();
+  if (contentType !== "application/json") throw new InvalidRequest();
+  const declaredLength = request.headers.get("content-length");
+  if (declaredLength !== null) {
+    if (!/^\d+$/.test(declaredLength) || Number(declaredLength) > MAX_BODY_BYTES) {
+      await request.body?.cancel().catch(() => void 0);
+      throw new InvalidRequest();
+    }
+  }
+  const reader = request.body?.getReader();
+  if (!reader) throw new InvalidRequest();
+  const chunks = [];
+  let byteLength = 0;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    byteLength += value.byteLength;
+    if (byteLength > MAX_BODY_BYTES) {
+      await reader.cancel().catch(() => void 0);
+      throw new InvalidRequest();
+    }
+    chunks.push(value);
+  }
+  const bytes = new Uint8Array(byteLength);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  try {
+    const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    const value = JSON.parse(text);
+    if (!isObject(value)) throw new InvalidRequest();
+    return value;
+  } catch (error) {
+    if (error instanceof InvalidRequest) throw error;
+    throw new InvalidRequest();
+  }
+}
+function userAuthorization(headers) {
+  const value = headers.get("authorization") ?? "";
+  if (!/^Bearer [^\s,]{1,4096}$/.test(value)) throw new AuthenticationRequired();
+  return value;
+}
+function appAttestation(headers) {
+  const value = headers.get("x-pickleball-app-attestation");
+  if (value === null) return void 0;
+  if (!nonblank(value, 8192)) throw new InvalidRequest();
+  return value;
+}
+function identityFromHeaders(headers) {
+  const sdkVersion = headers.get("x-pickleball-sdk-version") ?? "";
+  const platform = headers.get("x-pickleball-platform") ?? "";
+  const bundleId = headers.get("x-pickleball-bundle-id") ?? "";
+  const installationId = headers.get("x-pickleball-installation-id") ?? "";
+  if (!SEMVER.test(sdkVersion) || platform !== "ios" && platform !== "android" || !BUNDLE_ID.test(bundleId) || !INSTALLATION_ID.test(installationId)) {
+    throw new InvalidRequest();
+  }
+  return { sdkVersion, platform, bundleId, installationId };
+}
+function bootstrapBody(value) {
+  if (!hasOnlyKeys(value, ["sdkVersion", "platform", "bundleId", "installationId"]) || !SEMVER.test(typeof value.sdkVersion === "string" ? value.sdkVersion : "") || value.platform !== "ios" && value.platform !== "android" || !BUNDLE_ID.test(typeof value.bundleId === "string" ? value.bundleId : "") || !INSTALLATION_ID.test(
+    typeof value.installationId === "string" ? value.installationId : ""
+  )) {
+    throw new InvalidRequest();
+  }
+  return value;
+}
+function identitiesMatch(left, right) {
+  return left.sdkVersion === right.sdkVersion && left.platform === right.platform && left.bundleId === right.bundleId && left.installationId === right.installationId;
+}
+function startBody(value) {
+  if (!hasOnlyKeys(value, [
+    "externalSessionId",
+    "title",
+    "visibility",
+    "consentVersion",
+    "metadata",
+    "standby"
+  ]) || !nonblank(value.externalSessionId, 256) || !nonblank(value.title, 200) || !nonblank(value.consentVersion, 100) || value.visibility !== void 0 && value.visibility !== "public" && value.visibility !== "private" || value.standby !== void 0 && typeof value.standby !== "boolean") {
+    throw new InvalidRequest();
+  }
+  if (value.metadata !== void 0) {
+    if (!isObject(value.metadata) || Object.keys(value.metadata).length > 50) {
+      throw new InvalidRequest();
+    }
+    for (const [key, entry] of Object.entries(value.metadata)) {
+      if (!nonblank(key, 100) || !nonblank(entry, 500)) throw new InvalidRequest();
+    }
+  }
+  return value;
+}
+function endBody(value, sessionId) {
+  if (!hasOnlyKeys(value, ["sessionId", "reason"]) || value.sessionId !== sessionId || ![
+    "user",
+    "background_timeout",
+    "network_timeout",
+    "standby_timeout",
+    "error"
+  ].includes(typeof value.reason === "string" ? value.reason : "")) {
+    throw new InvalidRequest();
+  }
+  return value;
+}
+function apiEnvironment(value) {
+  if (!nonblank(value.PICKLEBALL_API_BASE_URL, 2048) || !nonblank(value.PICKLEBALL_APP_ID, 256) || !nonblank(value.PICKLEBALL_API_KEY, 1024)) {
+    throw new PickleballConfigurationError("Proxy is not configured");
+  }
+  return {
+    PICKLEBALL_API_BASE_URL: value.PICKLEBALL_API_BASE_URL,
+    PICKLEBALL_APP_ID: value.PICKLEBALL_APP_ID,
+    PICKLEBALL_API_KEY: value.PICKLEBALL_API_KEY
+  };
+}
+function authorizationEnvironment(value) {
+  if (!nonblank(value.PICKLEBALL_PROXY_AUTHZ_URL, 2048) || !nonblank(value.PICKLEBALL_PROXY_AUTHZ_SERVICE_TOKEN, 1024)) {
+    throw new AuthorizationUnavailable();
+  }
+  try {
+    const url = new URL(value.PICKLEBALL_PROXY_AUTHZ_URL);
+    if (url.protocol !== "https:" || url.username || url.password) throw new Error();
+  } catch {
+    throw new AuthorizationUnavailable();
+  }
+  return {
+    url: value.PICKLEBALL_PROXY_AUTHZ_URL,
+    serviceToken: value.PICKLEBALL_PROXY_AUTHZ_SERVICE_TOKEN
+  };
+}
+function defaultCreateClient(env) {
+  return createPickleballLiveClient({
+    baseUrl: env.PICKLEBALL_API_BASE_URL,
+    appId: env.PICKLEBALL_APP_ID,
+    apiKey: env.PICKLEBALL_API_KEY
+  });
+}
+function clientFor(deps) {
+  const configured = apiEnvironment(deps.env);
+  return (deps.createClient ?? defaultCreateClient)(configured);
+}
+async function authorize(deps, authorization, operation, identity, scope = {}, attestation) {
+  const configured = authorizationEnvironment(deps.env);
+  const fetchImplementation = deps.authzFetch ?? globalThis.fetch;
+  if (typeof fetchImplementation !== "function") throw new AuthorizationUnavailable();
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 5e3);
+  let result;
+  try {
+    result = await fetchImplementation(configured.url, {
+      method: "POST",
+      headers: {
+        accept: "application/json",
+        authorization,
+        "content-type": "application/json",
+        "x-pickleball-proxy-service-token": configured.serviceToken,
+        ...attestation === void 0 ? {} : { "x-pickleball-app-attestation": attestation }
+      },
+      body: JSON.stringify({ operation, identity, ...scope }),
+      signal: controller.signal,
+      redirect: "error"
+    });
+  } catch {
+    throw new AuthorizationUnavailable();
+  } finally {
+    clearTimeout(timeout);
+  }
+  if (result.status === 401 || result.status === 403 || result.status === 429) {
+    await result.body?.cancel().catch(() => void 0);
+    if (result.status === 401) throw new AuthorizationDecision(401, "UNAUTHORIZED");
+    if (result.status === 403) throw new AuthorizationDecision(403, "FORBIDDEN");
+    throw new AuthorizationDecision(429, "RATE_LIMITED");
+  }
+  if (!result.ok) {
+    await result.body?.cancel().catch(() => void 0);
+    throw new AuthorizationUnavailable();
+  }
+  let payload;
+  try {
+    payload = await result.json();
+  } catch {
+    throw new AuthorizationUnavailable();
+  }
+  if (!isObject(payload) || !isObject(payload.data) || payload.data.allowed !== true || !nonblank(payload.data.principalId, 256)) {
+    throw new AuthorizationUnavailable();
+  }
+  return { principalId: payload.data.principalId };
+}
+function safeLog(deps, error) {
+  const candidate = error;
+  (deps.logger ?? console).error("Pickleball proxy request failed", {
+    name: typeof candidate?.name === "string" ? candidate.name : "Error",
+    code: typeof candidate?.code === "string" ? candidate.code : "UNKNOWN",
+    status: typeof candidate?.status === "number" ? candidate.status : void 0
+  });
+}
+function mappedError(error, deps) {
+  if (error instanceof InvalidRequest) {
+    return errorResponse(400, "INVALID_REQUEST", "Invalid request");
+  }
+  if (error instanceof AuthenticationRequired) {
+    return errorResponse(401, "UNAUTHORIZED", "Authentication required");
+  }
+  if (error instanceof AuthorizationDecision) {
+    const message = error.code === "UNAUTHORIZED" ? "Authentication required" : error.code === "RATE_LIMITED" ? "Too many requests" : "Operation not permitted";
+    return errorResponse(error.status, error.code, message);
+  }
+  if (error instanceof AuthorizationUnavailable) {
+    safeLog(deps, error);
+    return errorResponse(503, "AUTHZ_UNAVAILABLE", "Authorization service unavailable");
+  }
+  safeLog(deps, error);
+  const candidate = error;
+  if (error instanceof PickleballApiError || candidate?.name === "PickleballApiError") {
+    const status = typeof candidate.status === "number" && candidate.status >= 400 && candidate.status <= 599 ? candidate.status : 502;
+    const code = SAFE_UPSTREAM_CODES.has(candidate.code ?? "") ? candidate.code : "UNKNOWN";
+    return errorResponse(status, code, "Livestream request was rejected");
+  }
+  if (error instanceof PickleballConfigurationError) {
+    return errorResponse(500, "CONFIGURATION_ERROR", "Proxy is not configured");
+  }
+  if (error instanceof PickleballTimeoutError || candidate?.name === "PickleballTimeoutError") {
+    return errorResponse(504, "TIMEOUT", "Upstream request timed out");
+  }
+  if (error instanceof PickleballNetworkError || candidate?.name === "PickleballNetworkError") {
+    return errorResponse(502, "NETWORK_UNAVAILABLE", "Upstream network unavailable");
+  }
+  if (error instanceof PickleballInvalidResponseError || candidate?.name === "PickleballInvalidResponseError") {
+    return errorResponse(502, "INVALID_RESPONSE", "Invalid upstream response");
+  }
+  if (error instanceof PickleballHttpError || candidate?.name === "PickleballHttpError") {
+    return errorResponse(502, "UNKNOWN", "Upstream request failed");
+  }
+  return errorResponse(500, "UNKNOWN", "Proxy request failed");
+}
+async function execute(deps, action) {
+  try {
+    return response({ data: await action() });
+  } catch (error) {
+    return mappedError(error, deps);
+  }
+}
+async function createStableIdempotencyKey(input) {
+  const canonical = [
+    "pickleball-sdk-v1",
+    input.appId,
+    input.installationId,
+    input.externalSessionId,
+    input.consentVersion
+  ].join("\0");
+  const digest = new Uint8Array(
+    await crypto.subtle.digest("SHA-256", new TextEncoder().encode(canonical))
+  );
+  return Array.from(digest, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+async function handleBootstrap(request, deps) {
+  return execute(deps, async () => {
+    const authorization = userAuthorization(request.headers);
+    const attestation = appAttestation(request.headers);
+    const identity = identityFromHeaders(request.headers);
+    const input = bootstrapBody(await bodyObject(request));
+    if (!identitiesMatch(identity, input)) throw new InvalidRequest();
+    await authorize(deps, authorization, "bootstrap", identity, {}, attestation);
+    return clientFor(deps).apps.bootstrap(input);
+  });
+}
+async function handleSessions(request, deps) {
+  return execute(deps, async () => {
+    const authorization = userAuthorization(request.headers);
+    const attestation = appAttestation(request.headers);
+    const identity = identityFromHeaders(request.headers);
+    const input = startBody(await bodyObject(request));
+    const startAuthorization = await authorize(deps, authorization, "start", identity, {
+      externalSessionId: input.externalSessionId
+    }, attestation);
+    const configured = apiEnvironment(deps.env);
+    const idempotencyKey = await createStableIdempotencyKey({
+      appId: configured.PICKLEBALL_APP_ID,
+      installationId: identity.installationId,
+      externalSessionId: input.externalSessionId,
+      consentVersion: input.consentVersion
+    });
+    const client = (deps.createClient ?? defaultCreateClient)(configured);
+    const grant = await client.sessions.start({ ...identity, ...input, idempotencyKey });
+    try {
+      await authorize(deps, authorization, "claim", identity, {
+        sessionId: grant.sessionId,
+        externalSessionId: input.externalSessionId,
+        principalId: startAuthorization.principalId
+      }, attestation);
+    } catch (error) {
+      try {
+        await client.sessions.end({ sessionId: grant.sessionId, reason: "error" });
+      } catch (cleanupError) {
+        safeLog(deps, cleanupError);
+      }
+      throw error;
+    }
+    return grant;
+  });
+}
+async function handleSessionAction(request, params, deps) {
+  if (params.action !== "refresh" && params.action !== "end" && params.action !== "publish" && params.action !== "unpublish") {
+    return errorResponse(404, "NOT_FOUND", "Route not found");
+  }
+  return execute(deps, async () => {
+    const authorization = userAuthorization(request.headers);
+    const attestation = appAttestation(request.headers);
+    if (!nonblank(params.id, 256)) throw new InvalidRequest();
+    const identity = identityFromHeaders(request.headers);
+    const body = await bodyObject(request);
+    if (params.action === "refresh") {
+      if (Object.keys(body).length !== 0) throw new InvalidRequest();
+      await authorize(deps, authorization, "refresh", identity, {
+        sessionId: params.id
+      }, attestation);
+      return clientFor(deps).sessions.refresh(params.id, identity);
+    }
+    if (params.action === "publish" || params.action === "unpublish") {
+      if (!hasOnlyKeys(body, ["sessionId"]) || body.sessionId !== params.id) {
+        throw new InvalidRequest();
+      }
+      await authorize(deps, authorization, params.action, identity, {
+        sessionId: params.id
+      }, attestation);
+      const sessions = clientFor(deps).sessions;
+      return params.action === "publish" ? sessions.publish(params.id) : sessions.unpublish(params.id);
+    }
+    const input = endBody(body, params.id);
+    await authorize(deps, authorization, "end", identity, {
+      sessionId: params.id
+    }, attestation);
+    await clientFor(deps).sessions.end(input);
+    return null;
+  });
+}
+export {
+  createStableIdempotencyKey,
+  handleBootstrap,
+  handleSessionAction,
+  handleSessions
+};

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@pickleball/server-sdk",
+  "version": "0.1.1",
+  "description": "Framework-free server SDK for Pickleball Live",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Cabinfood/livestream-pickleball.git",
+    "directory": "packages/server-sdk"
+  },
+  "homepage": "https://github.com/Cabinfood/livestream-pickleball#readme",
+  "bugs": "https://github.com/Cabinfood/livestream-pickleball/issues",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./proxy": {
+      "import": {
+        "types": "./dist/proxy.d.ts",
+        "default": "./dist/proxy.js"
+      },
+      "require": {
+        "types": "./dist/proxy.d.cts",
+        "default": "./dist/proxy.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.0",
+    "vitest": "^2.1.9",
+    "@pickleball/shared": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/proxy.ts --format esm,cjs --dts --clean",
+    "test": "vitest run",
+    "typecheck": "pnpm run build && tsc --noEmit && pnpm run typecheck:nodenext",
+    "typecheck:nodenext": "tsc --noEmit -p tsconfig.nodenext.json",
+    "verify:pack": "node scripts/verify-pack.mjs"
+  }
+}