@pickleball/server-sdk 0.2.0 → 0.3.0

package/dist/proxy.cjs

@@ -50,6 +50,15 @@ var PickleballApiError = class extends PickleballLiveError {
     this.name = "PickleballApiError";
   }
 };
+var PickleballPartnerApiError = class extends PickleballLiveError {
+  constructor(message, partnerCode, status, details = {}) {
+    super(message, "PARTNER_API_ERROR");
+    this.partnerCode = partnerCode;
+    this.status = status;
+    this.details = details;
+    this.name = "PickleballPartnerApiError";
+  }
+};
 var PickleballHttpError = class extends PickleballLiveError {
   constructor(status) {
     super(`Request failed with HTTP ${status}`, "HTTP_ERROR");
@@ -278,6 +287,49 @@ function validateGrant(value) {
     config: validateRemoteConfig(data.config)
   };
 }
+function validateCameraGrant(value) {
+  const data = record(value);
+  const base = validateGrant(data);
+  if (!/^rtmps?:\/\//i.test(base.serverUrl)) invalid();
+  if (data.status !== "scheduled" && data.status !== "live") invalid();
+  return {
+    ...base,
+    status: data.status,
+    matchRef: nullableString(data.matchRef),
+    courtRef: nullableString(data.courtRef),
+    watchUrl: nullableString(data.watchUrl),
+    convexUrl: nullableString(data.convexUrl),
+    issuedAt: finite(data.issuedAt),
+    expiresAt: finite(data.expiresAt)
+  };
+}
+function validateCameraSessionCreated(value) {
+  const data = record(value);
+  if (data.status !== "scheduled" && data.status !== "live" && data.status !== "ended") {
+    invalid();
+  }
+  if (data.visibility !== "public" && data.visibility !== "private") invalid();
+  if (typeof data.reused !== "boolean") invalid();
+  return {
+    id: nonblank(data.id),
+    status: data.status,
+    visibility: data.visibility,
+    quality: finite(data.quality),
+    deliveryMode: nonblank(data.deliveryMode),
+    matchRef: nullableString(data.matchRef),
+    courtRef: nullableString(data.courtRef),
+    playbackUrl: nullableString(data.playbackUrl),
+    whepUrl: nullableString(data.whepUrl),
+    watchUrl: nullableString(data.watchUrl),
+    reused: data.reused,
+    cameraGrant: validateCameraGrant(data.cameraGrant)
+  };
+}
+function validateLegacyEnd(value) {
+  const data = record(value);
+  if (data.ok !== true || data.status !== "ended") invalid();
+  return { status: "ended" };
+}
 function validateRefresh(value) {
   const data = record(value);
   return {
@@ -315,6 +367,7 @@ function validateSession(value) {
     matchRef: nullableString(data.matchRef),
     playbackUrl: nullableString(data.playbackUrl),
     watchUrl: nullableString(data.watchUrl),
+    whepUrl: nullableString(data.whepUrl),
     scheduledAt: nullableNumber(data.scheduledAt),
     startedAt: nullableNumber(data.startedAt),
     endedAt: nullableNumber(data.endedAt),
@@ -503,7 +556,23 @@ async function readBoundedResponseText(response2) {
   }
   return new TextDecoder().decode(bytes);
 }
-async function decodeResponse(response2, apiKey, validate) {
+function parsePartnerError(payload, status, apiKey) {
+  if (!isRecord(payload) || !("error" in payload)) {
+    return new PickleballInvalidResponseError();
+  }
+  if (isRecord(payload.error)) {
+    return parseSdkError(payload, status, apiKey);
+  }
+  if (typeof payload.error !== "string") return new PickleballInvalidResponseError();
+  const { error, code, ...details } = payload;
+  const safeMessage = apiKey === "" ? error : error.split(apiKey).join("[REDACTED]");
+  const partnerCode = typeof code === "string" && code.trim() !== "" ? code : `HTTP_${status}`;
+  return new PickleballPartnerApiError(safeMessage, partnerCode, status, details);
+}
+async function decodeResponse(response2, apiKey, validate, options = {
+  errorStyle: "sdk",
+  envelope: "data"
+}) {
   if (response2.status >= 300 && response2.status < 400) {
     await response2.body?.cancel().catch(() => void 0);
     throw new PickleballHttpError(response2.status);
@@ -515,7 +584,10 @@ async function decodeResponse(response2, apiKey, validate) {
   } catch {
     throw new PickleballInvalidResponseError();
   }
-  if (!response2.ok) throw parseSdkError(payload, response2.status, apiKey);
+  if (!response2.ok) {
+    throw options.errorStyle === "v1" ? parsePartnerError(payload, response2.status, apiKey) : parseSdkError(payload, response2.status, apiKey);
+  }
+  if (options.envelope === "raw") return validate(payload);
   if (!isRecord(payload) || !("data" in payload)) {
     throw new PickleballInvalidResponseError();
   }
@@ -523,7 +595,15 @@ async function decodeResponse(response2, apiKey, validate) {
 }
 function createPickleballLiveClient(options) {
   const baseUrl = validatedBaseUrl(options.baseUrl);
-  const appId = requiredNonblank(options.appId, "appId");
+  const configuredAppId = options.appId === void 0 ? null : requiredNonblank(options.appId, "appId");
+  const requireAppId = () => {
+    if (configuredAppId === null) {
+      throw new PickleballConfigurationError(
+        "appId is required for /api/v2/sdk operations (apps/sessions/devices)"
+      );
+    }
+    return configuredAppId;
+  };
   const apiKey = requiredNonblank(options.apiKey, "apiKey");
   const fetchImplementation = options.fetch ?? globalThis.fetch;
   if (typeof fetchImplementation !== "function") {
@@ -536,7 +616,9 @@ function createPickleballLiveClient(options) {
     path,
     body,
     retryPolicy,
-    validate
+    validate,
+    errorStyle = "sdk",
+    envelope = "data"
   }) {
     const retryLimit = retryPolicy === "transient" ? maxRetries : 0;
     for (let attempt = 0; attempt <= retryLimit; attempt += 1) {
@@ -557,14 +639,14 @@ function createPickleballLiveClient(options) {
           } : {
             accept: "application/json",
             "x-api-key": apiKey,
-            "x-pickleball-app-id": appId
+            ...configuredAppId === null ? {} : { "x-pickleball-app-id": configuredAppId }
           },
           ...body === void 0 ? {} : { body: JSON.stringify(body) },
           signal: controller.signal,
           redirect: "error"
         });
         try {
-          return await decodeResponse(response2, apiKey, validate);
+          return await decodeResponse(response2, apiKey, validate, { errorStyle, envelope });
         } catch (error) {
           if (isTransientStatus(response2.status) && attempt < retryLimit && isRetryableResponseError(error)) {
             clearTimeout(timer);
@@ -576,7 +658,7 @@ function createPickleballLiveClient(options) {
           throw error;
         }
       } catch (error) {
-        if (error instanceof PickleballApiError || error instanceof PickleballHttpError || error instanceof PickleballInvalidResponseError) {
+        if (error instanceof PickleballApiError || error instanceof PickleballPartnerApiError || error instanceof PickleballHttpError || error instanceof PickleballInvalidResponseError) {
           throw error;
         }
         if (attempt < retryLimit) {
@@ -595,64 +677,109 @@ function createPickleballLiveClient(options) {
   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)}`;
+  const v1SessionPath = (sessionId) => `/api/v1/live-sessions/${encodeURIComponent(sessionId)}`;
+  const postV1 = (path, body, retryPolicy, validate, envelope = "data") => request({ method: "POST", path, body, retryPolicy, validate, errorStyle: "v1", envelope });
+  const getV1 = (path, validate) => request({ method: "GET", path, retryPolicy: "transient", validate, errorStyle: "v1" });
   return {
     apps: {
-      bootstrap: (input) => post(
+      bootstrap: async (input) => post(
         "/api/v2/sdk/bootstrap",
-        { ...input, appId },
+        { ...input, appId: requireAppId() },
         "transient",
         validateBootstrap
       )
     },
     sessions: {
-      start: (input) => post(
+      start: async (input) => post(
         "/api/v2/sdk/sessions",
-        { ...input, appId },
+        { ...input, appId: requireAppId() },
         "transient",
         validateGrant
       ),
-      refresh: (sessionId, input) => post(
+      refresh: async (sessionId, input) => post(
         `${sessionPath(sessionId)}/refresh`,
-        { ...input, appId },
+        { ...input, appId: requireAppId() },
         "never",
         validateRefresh
       ),
       end: async (input) => {
         await post(
           `${sessionPath(input.sessionId)}/end`,
-          { ...input, appId },
+          { ...input, appId: requireAppId() },
           "transient",
           (value) => validateEnd(value, input.sessionId)
         );
       },
-      publish: (sessionId) => post(
+      publish: async (sessionId) => post(
         `${sessionPath(sessionId)}/publish`,
-        { sessionId, appId },
+        { sessionId, appId: requireAppId() },
         "transient",
         (value) => validatePublishState(value, sessionId)
       ),
-      unpublish: (sessionId) => post(
+      unpublish: async (sessionId) => post(
         `${sessionPath(sessionId)}/unpublish`,
-        { sessionId, appId },
+        { sessionId, appId: requireAppId() },
         "transient",
         (value) => validatePublishState(value, sessionId)
       ),
-      get: (sessionId) => get(sessionPath(sessionId), validateSession),
-      getRecordings: (sessionId) => get(
-        `${sessionPath(sessionId)}/recordings`,
+      get: async (sessionId) => {
+        requireAppId();
+        return get(sessionPath(sessionId), validateSession);
+      },
+      getRecordings: async (sessionId) => {
+        requireAppId();
+        return get(
+          `${sessionPath(sessionId)}/recordings`,
+          (value) => validateRecordings(value, sessionId)
+        );
+      }
+    },
+    liveSessions: {
+      createCameraSession: (input) => postV1(
+        "/api/v1/live-sessions",
+        {
+          title: input.title,
+          matchRef: input.matchRef,
+          cameraGrant: true,
+          deliveryMode: "device-rtmp",
+          ...input.visibility === void 0 ? {} : { visibility: input.visibility },
+          ...input.description === void 0 ? {} : { description: input.description },
+          ...input.quality === void 0 ? {} : { quality: input.quality },
+          ...input.courtRef === void 0 ? {} : { courtRef: input.courtRef }
+        },
+        // Idempotent theo (host, matchRef): gọi lại chỉ cấp grant mới, an toàn để retry.
+        "transient",
+        validateCameraSessionCreated
+      ),
+      cameraGrant: (sessionId) => postV1(
+        `${v1SessionPath(sessionId)}/camera-grant`,
+        {},
+        "transient",
+        validateCameraGrant
+      ),
+      end: (sessionId) => postV1(
+        `${v1SessionPath(sessionId)}/end`,
+        {},
+        "transient",
+        validateLegacyEnd,
+        "raw"
+      ),
+      get: (sessionId) => getV1(v1SessionPath(sessionId), validateSession),
+      getRecordings: (sessionId) => getV1(
+        `${v1SessionPath(sessionId)}/recordings`,
         (value) => validateRecordings(value, sessionId)
       )
     },
     devices: {
-      register: (input) => post(
+      register: async (input) => post(
         "/api/v2/sdk/devices/register",
-        { ...input, appId },
+        { ...input, appId: requireAppId() },
         "transient",
         validateDeviceRegister
       ),
-      heartbeat: (input) => post(
+      heartbeat: async (input) => post(
         "/api/v2/sdk/devices/heartbeat",
-        { ...input, appId },
+        { ...input, appId: requireAppId() },
         // Heartbeat có side effect trao token 1 lần — không retry để tránh
         // nhận token đã bị đánh dấu delivered ở lần trước
         "never",
@@ -793,8 +920,9 @@ function startBody(value) {
     "visibility",
     "consentVersion",
     "metadata",
-    "standby"
-  ]) || !nonblank2(value.externalSessionId, 256) || !nonblank2(value.title, 200) || !nonblank2(value.consentVersion, 100) || value.visibility !== void 0 && value.visibility !== "public" && value.visibility !== "private" || value.standby !== void 0 && typeof value.standby !== "boolean") {
+    "standby",
+    "quality"
+  ]) || !nonblank2(value.externalSessionId, 256) || !nonblank2(value.title, 200) || !nonblank2(value.consentVersion, 100) || value.visibility !== void 0 && value.visibility !== "public" && value.visibility !== "private" || value.standby !== void 0 && typeof value.standby !== "boolean" || value.quality !== void 0 && value.quality !== 720 && value.quality !== 1080) {
     throw new InvalidRequest();
   }
   if (value.metadata !== void 0) {

package/dist/proxy.d.cts

@@ -1,5 +1,12 @@
 import { PickleballLiveClient } from './index.cjs';
 
+/**
+ * @deprecated Mô hình "proxy do đối tác host" (SDK v2, 6 route + authz gateway)
+ * được giữ để tương thích. Tích hợp mới dùng camera grant (ADR-0002):
+ * `createPickleballLiveClient().liveSessions.createCameraSession()` ở backend
+ * đối tác và `@pickleball/expo-sdk` chế độ grant trên app — không cần proxy.
+ */
+
 interface ProxyEnvironment {
     PICKLEBALL_API_BASE_URL: string;
     PICKLEBALL_APP_ID: string;

package/dist/proxy.d.ts

@@ -1,5 +1,12 @@
 import { PickleballLiveClient } from './index.js';
 
+/**
+ * @deprecated Mô hình "proxy do đối tác host" (SDK v2, 6 route + authz gateway)
+ * được giữ để tương thích. Tích hợp mới dùng camera grant (ADR-0002):
+ * `createPickleballLiveClient().liveSessions.createCameraSession()` ở backend
+ * đối tác và `@pickleball/expo-sdk` chế độ grant trên app — không cần proxy.
+ */
+
 interface ProxyEnvironment {
     PICKLEBALL_API_BASE_URL: string;
     PICKLEBALL_APP_ID: string;

package/dist/proxy.js

@@ -6,7 +6,7 @@ import {
   PickleballNetworkError,
   PickleballTimeoutError,
   createPickleballLiveClient
-} from "./chunk-Y635I73O.js";
+} from "./chunk-UPS4VFER.js";
 
 // src/proxy.ts
 var MAX_BODY_BYTES = 16 * 1024;
@@ -138,8 +138,9 @@ function startBody(value) {
     "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") {
+    "standby",
+    "quality"
+  ]) || !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" || value.quality !== void 0 && value.quality !== 720 && value.quality !== 1080) {
     throw new InvalidRequest();
   }
   if (value.metadata !== void 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pickleball/server-sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Framework-free server SDK for Pickleball Live",
   "license": "MIT",
   "repository": {
@@ -58,7 +58,7 @@
   "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": "tsc --noEmit && pnpm run typecheck:nodenext",
     "typecheck:nodenext": "tsc --noEmit -p tsconfig.nodenext.json",
     "verify:pack": "node scripts/verify-pack.mjs"
   }