@pickleball/server-sdk 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @pickleball/server-sdk
 
+## 0.3.0
+
+### Minor Changes
+
+- 0d74c20: Camera grant (ADR-0002) cho điện thoại của user đối tác: namespace mới
+  `liveSessions` trên `createPickleballLiveClient` — `createCameraSession`
+  (`POST /api/v1/live-sessions {cameraGrant:true}`, idempotent theo matchRef),
+  `cameraGrant` (cấp lại grant, thu hồi grant cũ), `end`, `get`, `getRecordings`
+  đi đường REST v1 với `x-api-key`, không cần `appId` (option này thành tuỳ chọn).
+  Lỗi REST v1 `{error, code, ...extra}` thành `PickleballPartnerApiError`
+  (`partnerCode`, `details`). Contract `CameraGrant` (superset của
+  `SdkSessionGrant`). Các thao tác `/api/v2/sdk/*` và subpath `./proxy` được đánh
+  dấu deprecated, giữ nguyên hành vi.
+
+## 0.2.0
+
+### Minor Changes
+
+- Device registry endpoints for the partner proxy: `devices.register` and
+  `devices.heartbeat` on `createPickleballLiveClient`, plus the proxy handlers
+  `handleDeviceRegister` / `handleDeviceHeartbeat` (routes `/devices/register`
+  and `/devices/heartbeat`). The heartbeat response carries a one-time control
+  session grant so an operator dashboard can remote-start a livestream on a
+  device that is open but idle.
+- New authorization operations `device_register` and `device_heartbeat`.
+  **Production authz gateways must allow these two operation names**; the
+  staging stub already allows everything.
+- Version aligned with `@pickleball/expo-sdk@0.2.0` (both packages share a
+  stable dist-tag promotion).
+
 ## 0.1.1
 
 ### Patch Changes

package/README.md

@@ -56,6 +56,28 @@ Never expose this package's API key to a native/web bundle or log it. Put the
 client in a server route, Worker, serverless function, or other trusted runtime.
 The SDK never logs the API key, participant token, or webhook secret.
 
+## Camera grant — điện thoại của user đối tác (ADR-0002)
+
+Backend đối tác tạo phiên theo `matchRef` và nhận **camera grant**; app đối tác
+(`@pickleball/expo-sdk` chế độ grant) dùng `cameraGrant.telemetry.token` làm
+Bearer để nói thẳng với Picklive — không proxy, không cần `appId`:
+
+```ts
+const client = createPickleballLiveClient({ baseUrl, apiKey });
+const { id, watchUrl, cameraGrant } = await client.liveSessions.createCameraSession({
+  matchRef: match.id,
+  title: match.title,
+  quality: 720,
+  // courtRef: "san-3", // tuỳ chọn: đậu vào sân giải để dùng match-start/match-end
+});
+// Trả `cameraGrant` NGUYÊN TRẠNG cho app qua auth riêng của bạn. Không log grant.
+// App bị xoá/cài lại hoặc token hết hạn: client.liveSessions.cameraGrant(id) cấp lại
+// (grant cũ bị thu hồi — máy cũ dừng, không tranh sóng với máy mới).
+```
+
+Lỗi REST v1 ném `PickleballPartnerApiError` với `partnerCode` (VD
+`COURT_HAS_DEVICE`, `COURT_BUSY`, `CAPACITY`, `SESSION_EXPIRED`) và `details`.
+
 ## Webhook verification
 
 Verify the exact raw request bytes before parsing. Delivery is at-least-once:

package/dist/{chunk-HBTNLURN.js → chunk-UPS4VFER.js}

@@ -19,6 +19,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");
@@ -247,6 +256,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 {
@@ -284,6 +336,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),
@@ -314,6 +367,29 @@ function validateRecordings(value, sessionId) {
   if (!Array.isArray(value)) invalid();
   return value.map((item) => validateRecording(item, sessionId));
 }
+function validateDeviceRegister(value) {
+  const data = record(value);
+  const heartbeatIntervalMs = finite(data.heartbeatIntervalMs);
+  if (heartbeatIntervalMs <= 0) invalid();
+  return {
+    deviceId: nonblank(data.deviceId),
+    heartbeatIntervalMs
+  };
+}
+function validateDeviceHeartbeat(value) {
+  const data = record(value);
+  if (data.controlSession === null || data.controlSession === void 0) {
+    return { controlSession: null };
+  }
+  const grant = record(data.controlSession);
+  return {
+    controlSession: {
+      id: nonblank(grant.id),
+      token: nonblank(grant.token),
+      convexUrl: nonblank(grant.convexUrl)
+    }
+  };
+}
 
 // src/contracts.ts
 var SDK_TELEMETRY_EVENT_NAMES = [
@@ -459,7 +535,23 @@ async function readBoundedResponseText(response) {
   }
   return new TextDecoder().decode(bytes);
 }
-async function decodeResponse(response, 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(response, apiKey, validate, options = {
+  errorStyle: "sdk",
+  envelope: "data"
+}) {
   if (response.status >= 300 && response.status < 400) {
     await response.body?.cancel().catch(() => void 0);
     throw new PickleballHttpError(response.status);
@@ -471,7 +563,10 @@ async function decodeResponse(response, apiKey, validate) {
   } catch {
     throw new PickleballInvalidResponseError();
   }
-  if (!response.ok) throw parseSdkError(payload, response.status, apiKey);
+  if (!response.ok) {
+    throw options.errorStyle === "v1" ? parsePartnerError(payload, response.status, apiKey) : parseSdkError(payload, response.status, apiKey);
+  }
+  if (options.envelope === "raw") return validate(payload);
   if (!isRecord(payload) || !("data" in payload)) {
     throw new PickleballInvalidResponseError();
   }
@@ -479,7 +574,15 @@ async function decodeResponse(response, 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") {
@@ -492,7 +595,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) {
@@ -513,14 +618,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(response, apiKey, validate);
+          return await decodeResponse(response, apiKey, validate, { errorStyle, envelope });
         } catch (error) {
           if (isTransientStatus(response.status) && attempt < retryLimit && isRetryableResponseError(error)) {
             clearTimeout(timer);
@@ -532,7 +637,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) {
@@ -551,54 +656,115 @@ 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: async (input) => post(
+        "/api/v2/sdk/devices/register",
+        { ...input, appId: requireAppId() },
+        "transient",
+        validateDeviceRegister
+      ),
+      heartbeat: async (input) => post(
+        "/api/v2/sdk/devices/heartbeat",
+        { ...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",
+        validateDeviceHeartbeat
+      )
+    },
     webhooks: { verify: verifyWebhook }
   };
 }
@@ -607,6 +773,7 @@ export {
   PickleballLiveError,
   PickleballConfigurationError,
   PickleballApiError,
+  PickleballPartnerApiError,
   PickleballHttpError,
   PickleballInvalidResponseError,
   PickleballTimeoutError,