@pickleball/server-sdk 0.1.1 → 0.3.0

package/dist/proxy.cjs

@@ -22,6 +22,8 @@ var proxy_exports = {};
 __export(proxy_exports, {
   createStableIdempotencyKey: () => createStableIdempotencyKey,
   handleBootstrap: () => handleBootstrap,
+  handleDeviceHeartbeat: () => handleDeviceHeartbeat,
+  handleDeviceRegister: () => handleDeviceRegister,
   handleSessionAction: () => handleSessionAction,
   handleSessions: () => handleSessions
 });
@@ -48,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");
@@ -276,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 {
@@ -313,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),
@@ -343,6 +398,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/index.ts
 var TRANSIENT_STATUSES = /* @__PURE__ */ new Set([408, 429]);
@@ -478,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);
@@ -490,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();
   }
@@ -498,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") {
@@ -511,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) {
@@ -532,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);
@@ -551,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) {
@@ -570,54 +677,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 }
   };
 }
@@ -752,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) {
@@ -1009,10 +1178,139 @@ async function handleSessionAction(request, params, deps) {
     return null;
   });
 }
+var DEVICE_INFO_FIELDS = ["appVersion", "deviceName", "deviceModel", "osVersion"];
+var DEVICE_METRIC_NUMBER_FIELDS = [
+  "ramFreeMb",
+  "ramTotalMb",
+  "storageFreeGb",
+  "batteryPct",
+  "batteryTempC",
+  "thermal",
+  "linkMbps",
+  "rssi"
+];
+var DEVICE_METRIC_STRING_FIELDS = ["netType", "connQuality"];
+function deviceInfoFields(value) {
+  const info = {};
+  for (const field of DEVICE_INFO_FIELDS) {
+    const entry = value[field];
+    if (entry === void 0) continue;
+    if (!nonblank2(entry, 200)) throw new InvalidRequest();
+    info[field] = entry;
+  }
+  return info;
+}
+function deviceRegisterBody(value) {
+  if (!hasOnlyKeys(value, [
+    "sdkVersion",
+    "platform",
+    "bundleId",
+    "installationId",
+    ...DEVICE_INFO_FIELDS
+  ])) {
+    throw new InvalidRequest();
+  }
+  const identity = bootstrapBody({
+    sdkVersion: value.sdkVersion,
+    platform: value.platform,
+    bundleId: value.bundleId,
+    installationId: value.installationId
+  });
+  return { ...identity, ...deviceInfoFields(value) };
+}
+function deviceMetricsFields(value) {
+  if (value === void 0) return void 0;
+  if (!isObject(value)) throw new InvalidRequest();
+  if (!hasOnlyKeys(value, [...DEVICE_METRIC_NUMBER_FIELDS, ...DEVICE_METRIC_STRING_FIELDS])) {
+    throw new InvalidRequest();
+  }
+  const metrics = {};
+  for (const field of DEVICE_METRIC_NUMBER_FIELDS) {
+    const entry = value[field];
+    if (entry === void 0) continue;
+    if (typeof entry !== "number" || !Number.isFinite(entry)) throw new InvalidRequest();
+    metrics[field] = entry;
+  }
+  for (const field of DEVICE_METRIC_STRING_FIELDS) {
+    const entry = value[field];
+    if (entry === void 0) continue;
+    if (!nonblank2(entry, 50)) throw new InvalidRequest();
+    metrics[field] = entry;
+  }
+  return metrics;
+}
+function deviceHeartbeatBody(value) {
+  if (!hasOnlyKeys(value, [
+    "sdkVersion",
+    "platform",
+    "bundleId",
+    "installationId",
+    "agentState",
+    "currentSessionId",
+    "appVersion",
+    "metrics"
+  ])) {
+    throw new InvalidRequest();
+  }
+  const identity = bootstrapBody({
+    sdkVersion: value.sdkVersion,
+    platform: value.platform,
+    bundleId: value.bundleId,
+    installationId: value.installationId
+  });
+  if (value.agentState !== void 0 && !nonblank2(value.agentState, 50)) {
+    throw new InvalidRequest();
+  }
+  if (value.currentSessionId !== void 0 && value.currentSessionId !== null && !nonblank2(value.currentSessionId, 256)) {
+    throw new InvalidRequest();
+  }
+  if (value.appVersion !== void 0 && !nonblank2(value.appVersion, 200)) {
+    throw new InvalidRequest();
+  }
+  const metrics = deviceMetricsFields(value.metrics);
+  return {
+    ...identity,
+    ...value.agentState === void 0 ? {} : { agentState: value.agentState },
+    ...value.currentSessionId === void 0 ? {} : { currentSessionId: value.currentSessionId },
+    ...value.appVersion === void 0 ? {} : { appVersion: value.appVersion },
+    ...metrics === void 0 ? {} : { metrics }
+  };
+}
+function deviceClientFor(deps) {
+  const client = clientFor(deps);
+  if (!client.devices) {
+    throw new PickleballConfigurationError("Proxy client does not support devices");
+  }
+  return client.devices;
+}
+async function handleDeviceRegister(request, deps) {
+  return execute(deps, async () => {
+    const authorization = userAuthorization(request.headers);
+    const attestation = appAttestation(request.headers);
+    const identity = identityFromHeaders(request.headers);
+    const input = deviceRegisterBody(await bodyObject(request));
+    if (!identitiesMatch(identity, input)) throw new InvalidRequest();
+    await authorize(deps, authorization, "device_register", identity, {}, attestation);
+    return deviceClientFor(deps).register(input);
+  });
+}
+async function handleDeviceHeartbeat(request, deps) {
+  return execute(deps, async () => {
+    const authorization = userAuthorization(request.headers);
+    const attestation = appAttestation(request.headers);
+    const identity = identityFromHeaders(request.headers);
+    const input = deviceHeartbeatBody(await bodyObject(request));
+    if (!identitiesMatch(identity, input)) throw new InvalidRequest();
+    await authorize(deps, authorization, "device_heartbeat", identity, {}, attestation);
+    return deviceClientFor(deps).heartbeat(input);
+  });
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   createStableIdempotencyKey,
   handleBootstrap,
+  handleDeviceHeartbeat,
+  handleDeviceRegister,
   handleSessionAction,
   handleSessions
 });

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;
@@ -21,6 +28,7 @@ interface ProxyDependencies {
 type ProxyClient = {
     apps: Pick<PickleballLiveClient["apps"], "bootstrap">;
     sessions: Pick<PickleballLiveClient["sessions"], "start" | "refresh" | "end" | "publish" | "unpublish">;
+    devices?: Pick<PickleballLiveClient["devices"], "register" | "heartbeat">;
 };
 interface SessionActionParams {
     id: string;
@@ -35,5 +43,7 @@ declare function createStableIdempotencyKey(input: {
 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>;
+declare function handleDeviceRegister(request: Request, deps: ProxyDependencies): Promise<Response>;
+declare function handleDeviceHeartbeat(request: Request, deps: ProxyDependencies): Promise<Response>;
 
-export { type ProxyDependencies, type ProxyEnvironment, type SessionActionParams, createStableIdempotencyKey, handleBootstrap, handleSessionAction, handleSessions };
+export { type ProxyDependencies, type ProxyEnvironment, type SessionActionParams, createStableIdempotencyKey, handleBootstrap, handleDeviceHeartbeat, handleDeviceRegister, handleSessionAction, handleSessions };

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;
@@ -21,6 +28,7 @@ interface ProxyDependencies {
 type ProxyClient = {
     apps: Pick<PickleballLiveClient["apps"], "bootstrap">;
     sessions: Pick<PickleballLiveClient["sessions"], "start" | "refresh" | "end" | "publish" | "unpublish">;
+    devices?: Pick<PickleballLiveClient["devices"], "register" | "heartbeat">;
 };
 interface SessionActionParams {
     id: string;
@@ -35,5 +43,7 @@ declare function createStableIdempotencyKey(input: {
 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>;
+declare function handleDeviceRegister(request: Request, deps: ProxyDependencies): Promise<Response>;
+declare function handleDeviceHeartbeat(request: Request, deps: ProxyDependencies): Promise<Response>;
 
-export { type ProxyDependencies, type ProxyEnvironment, type SessionActionParams, createStableIdempotencyKey, handleBootstrap, handleSessionAction, handleSessions };
+export { type ProxyDependencies, type ProxyEnvironment, type SessionActionParams, createStableIdempotencyKey, handleBootstrap, handleDeviceHeartbeat, handleDeviceRegister, handleSessionAction, handleSessions };