@pickleball/server-sdk 0.1.1 → 0.3.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 type SdkErrorCode = "PERMISSION_DENIED" | "NETWORK_UNAVAILABLE" | "TOKEN_EXPIRED" | "SDK_UPGRADE_REQUIRED" | "SESSION_CONFLICT" | "RECORDING_FAILED" | "CONSENT_REQUIRED" | "SDK_DISABLED" | "UNKNOWN";
-type ServerSdkErrorCode = SdkErrorCode | "CONFIGURATION_ERROR" | "TIMEOUT" | "NETWORK_ERROR" | "HTTP_ERROR" | "INVALID_RESPONSE" | "WEBHOOK_VERIFICATION_FAILED";
+type ServerSdkErrorCode = SdkErrorCode | "CONFIGURATION_ERROR" | "TIMEOUT" | "NETWORK_ERROR" | "HTTP_ERROR" | "INVALID_RESPONSE" | "PARTNER_API_ERROR" | "WEBHOOK_VERIFICATION_FAILED";
 declare class PickleballLiveError extends Error {
     readonly code: ServerSdkErrorCode;
     constructor(message: string, code: ServerSdkErrorCode, options?: ErrorOptions);
@@ -13,6 +13,19 @@ declare class PickleballApiError extends PickleballLiveError {
     /** Stable allowlisted code. Unknown server codes are normalized to UNKNOWN. */
     code: SdkErrorCode, status: number);
 }
+/**
+ * Lỗi của REST v1 (đường đối tác: /api/v1/live-sessions, camera grant). Thân
+ * lỗi là `{error, code, ...extra}` — `partnerCode` là mã máy đọc (VD
+ * COURT_HAS_DEVICE, CAPACITY, SESSION_EXPIRED), `details` là các field kèm
+ * (activeSessionId, deviceId, retryAfterMs, retryable…). Đối tác switch theo
+ * `partnerCode`, KHÔNG parse message.
+ */
+declare class PickleballPartnerApiError extends PickleballLiveError {
+    readonly partnerCode: string;
+    readonly status: number;
+    readonly details: Record<string, unknown>;
+    constructor(message: string, partnerCode: string, status: number, details?: Record<string, unknown>);
+}
 declare class PickleballHttpError extends PickleballLiveError {
     readonly status: number;
     constructor(status: number);
@@ -66,6 +79,13 @@ interface StartLivestreamInput {
      * "scheduled" và KHÔNG khởi động recording egress cho tới khi publish.
      */
     standby?: boolean;
+    /**
+     * Độ phân giải app THỰC SỰ quay, để server ghi đúng vào phiên. Chỉ app biết
+     * con số này: nó là lựa chọn local và app còn override `config.videoQuality`
+     * mà server trả về. Không khai thì server dùng mặc định của nó (1080) và bản
+     * ghi phiên nói dối.
+     */
+    quality?: 720 | 1080;
 }
 interface SdkTelemetryCredentials {
     endpoint: string;
@@ -96,6 +116,64 @@ interface SdkPublishState {
     sessionId: string;
     status: "scheduled" | "live";
 }
+type CameraGrantStatus = "scheduled" | "live";
+/**
+ * Camera grant — điện thoại của user ĐỐI TÁC lên sóng (ADR-0002). Backend đối
+ * tác nhận từ REST v1 (POST /api/v1/live-sessions {cameraGrant:true} hoặc
+ * POST /api/v1/live-sessions/{id}/camera-grant) và chuyển NGUYÊN TRẠNG cho app;
+ * app dùng `telemetry.token` làm Bearer với namespace /api/v2/camera/sessions.
+ *
+ * Superset nghiêm ngặt của SdkSessionGrant: `serverUrl` là RTMP ingest
+ * (`rtmp://host:1935/`), `participantToken` là stream key — SDK 0.2 đã nhận
+ * hình dạng này qua isSessionGrant nên không cần validator mới ở lớp engine.
+ */
+interface CameraGrant extends SdkSessionGrant {
+    /** Không bao giờ "ended" — endpoint trả 409 thay vì grant. */
+    status: CameraGrantStatus;
+    matchRef: string | null;
+    courtRef: string | null;
+    watchUrl: string | null;
+    /**
+     * Origin websocket Convex (https://<dep>.convex.cloud) để SDK subscribe lệnh
+     * thay vì poll HTTP 2s; null khi deployment không lộ origin chuẩn → SDK poll.
+     */
+    convexUrl: string | null;
+    issuedAt: number;
+    /**
+     * Hạn dùng của grant. Phiên chờ mà app CHƯA từng kết nối bị dọn sau 30 phút
+     * (RTMP_STANDBY_SILENT_MS) — xin grant đúng lúc user mở camera, đừng cấp sớm
+     * hàng giờ trước trận.
+     */
+    expiresAt: number;
+}
+/** Thân POST /api/v1/live-sessions với cameraGrant:true (phiên điện thoại đối tác). */
+interface CreateCameraSessionInput {
+    /** Định danh trận phía đối tác — phiên khoá theo trận, gọi lại cùng matchRef là idempotent. */
+    matchRef: string;
+    title: string;
+    visibility?: SessionVisibility;
+    description?: string;
+    /** Độ phân giải app sẽ quay; mặc định 720 cho điện thoại. */
+    quality?: 720 | 1080;
+    /** Đậu phiên vào sân giải để dùng match-start/match-end như camera cố định. */
+    courtRef?: string;
+}
+/** Phản hồi tạo phiên điện thoại: phiên + grant chuyển cho app. */
+interface CameraSessionCreated {
+    id: string;
+    status: SessionStatus;
+    visibility: SessionVisibility;
+    quality: number;
+    deliveryMode: string;
+    matchRef: string | null;
+    courtRef: string | null;
+    playbackUrl: string | null;
+    whepUrl: string | null;
+    watchUrl: string | null;
+    /** true = phiên cũ cùng matchRef còn sống được dùng lại (grant vẫn MỚI). */
+    reused: boolean;
+    cameraGrant: CameraGrant;
+}
 type SessionStatus = "scheduled" | "live" | "ended";
 type SessionVisibility = "public" | "private";
 type RecordingType = "clean" | "derived" | "device";
@@ -108,6 +186,11 @@ interface ApiLiveSession {
     playbackUrl: string | null;
     /** Link trang xem web (`/watch/{id}`); null nếu chưa cấu hình WEB_PUBLIC_BASE_URL. */
     watchUrl: string | null;
+    /**
+     * Endpoint WebRTC/WHEP độ trễ <1s — chỉ khác null khi phiên ĐANG live ở mode
+     * device-rtmp. Chết ngay khi phiên kết thúc, đừng lưu; null = dùng playbackUrl.
+     */
+    whepUrl: string | null;
     scheduledAt: number | null;
     startedAt: number | null;
     endedAt: number | null;
@@ -126,6 +209,46 @@ interface ApiRecording {
 type StartSdkSessionInput = BootstrapInput & StartLivestreamInput & {
     idempotencyKey: string;
 };
+/** Thông tin thiết bị kèm khi đăng ký (từ expo-device). */
+interface DeviceInfoInput {
+    appVersion?: string;
+    deviceName?: string;
+    deviceModel?: string;
+    osVersion?: string;
+}
+interface DeviceMetricsInput {
+    ramFreeMb?: number;
+    ramTotalMb?: number;
+    storageFreeGb?: number;
+    batteryPct?: number;
+    batteryTempC?: number;
+    thermal?: number;
+    netType?: string;
+    linkMbps?: number;
+    rssi?: number;
+    connQuality?: string;
+}
+interface DeviceRegisterResult {
+    deviceId: string;
+    heartbeatIntervalMs: number;
+}
+interface DeviceHeartbeatInput {
+    /** Trạng thái engine hiện tại (idle|standby|live|...). */
+    agentState?: string;
+    /** Id phiên live đang giữ — null = không có phiên (server clear link). */
+    currentSessionId?: string | null;
+    appVersion?: string;
+    metrics?: DeviceMetricsInput;
+}
+/** Kênh điều khiển được dashboard yêu cầu — app dùng token mở Convex websocket. */
+interface DeviceControlSessionGrant {
+    id: string;
+    token: string;
+    convexUrl: string;
+}
+interface DeviceHeartbeatResult {
+    controlSession: DeviceControlSessionGrant | null;
+}
 declare const SDK_TELEMETRY_EVENT_NAMES: readonly ["state_changed", "connection_quality", "reconnect", "error", "heartbeat", "session_ended"];
 type SdkTelemetryEventName = (typeof SDK_TELEMETRY_EVENT_NAMES)[number];
 interface SdkTelemetryEvent {
@@ -149,9 +272,20 @@ interface LivestreamSessionProvider {
     unpublish?(sessionId: string): Promise<void>;
 }
 type LivestreamState = "idle" | "preparing" | "preview" | "connecting" | "standby" | "live" | "reconnecting" | "ending" | "ended" | "error";
+/**
+ * Vì sao 409 SESSION_CONFLICT bị nhận trên namespace /api/v2/camera — mirror
+ * của packages/shared (type-test Equal ghim): superseded = grant bị grant mới
+ * thay (app dừng tại chỗ), ended = phiên đã kết thúc, expired = quá trần
+ * thời lượng credential (xin grant/phiên mới).
+ */
+type SdkConflictReason = "superseded" | "ended" | "expired";
 interface SdkError {
     code: SdkErrorCode;
     message: string;
+    /** Chỉ có ở 409 SESSION_CONFLICT của namespace /api/v2/camera. */
+    reason?: SdkConflictReason;
+    /** Chỉ có ở 429 — cùng số với header `Retry-After` (giây, làm tròn lên). */
+    retryAfterMs?: number;
 }
 
 type WebhookRawBody = string | Uint8Array;
@@ -178,7 +312,11 @@ declare function verifyWebhook<T extends WebhookPayload = WebhookPayload>(rawBod
 
 interface PickleballLiveClientOptions {
     baseUrl: string;
-    appId: string;
+    /**
+     * Chỉ cần cho các thao tác `/api/v2/sdk/*` (mô hình proxy cũ). Đường
+     * `liveSessions.*` (camera grant, REST v1) không dùng appId — bỏ trống được.
+     */
+    appId?: string;
     apiKey: string;
     fetch?: typeof globalThis.fetch;
     timeoutMs?: number;
@@ -186,21 +324,48 @@ interface PickleballLiveClientOptions {
 }
 interface PickleballLiveClient {
     apps: {
+        /** @deprecated Mô hình proxy SDK v2 — dùng `liveSessions.createCameraSession` (ADR-0002). */
         bootstrap(input: BootstrapInput): Promise<SdkBootstrap>;
     };
     sessions: {
+        /** @deprecated Mô hình proxy SDK v2 — dùng `liveSessions.createCameraSession` (ADR-0002). */
         start(input: StartSdkSessionInput): Promise<SdkSessionGrant>;
+        /** @deprecated Mô hình proxy SDK v2 — app tự refresh bằng Bearer grant ở /api/v2/camera. */
         refresh(sessionId: string, input: BootstrapInput): Promise<SdkSessionRefresh>;
+        /** @deprecated Mô hình proxy SDK v2 — dùng `liveSessions.end`. */
         end(input: EndLivestreamInput): Promise<void>;
+        /** @deprecated Mô hình proxy SDK v2 — app tự publish bằng Bearer grant ở /api/v2/camera. */
         publish(sessionId: string): Promise<SdkPublishState>;
+        /** @deprecated Mô hình proxy SDK v2 — app tự unpublish bằng Bearer grant ở /api/v2/camera. */
         unpublish(sessionId: string): Promise<SdkPublishState>;
         get(sessionId: string): Promise<ApiLiveSession>;
         getRecordings(sessionId: string): Promise<ApiRecording[]>;
     };
+    /**
+     * REST v1 — đường của backend đối tác (x-api-key), không cần appId.
+     * Camera grant (ADR-0002): tạo phiên theo matchRef rồi chuyển `cameraGrant`
+     * nguyên trạng cho app; app dùng @pickleball/expo-sdk nói thẳng với Picklive.
+     */
+    liveSessions: {
+        /** POST /api/v1/live-sessions {cameraGrant:true} — idempotent theo (host, matchRef). */
+        createCameraSession(input: CreateCameraSessionInput): Promise<CameraSessionCreated>;
+        /** POST /api/v1/live-sessions/{id}/camera-grant — cấp lại grant, thu hồi grant cũ. */
+        cameraGrant(sessionId: string): Promise<CameraGrant>;
+        /** POST /api/v1/live-sessions/{id}/end — kết thúc phiên từ backend đối tác. */
+        end(sessionId: string): Promise<{
+            status: "ended";
+        }>;
+        get(sessionId: string): Promise<ApiLiveSession>;
+        getRecordings(sessionId: string): Promise<ApiRecording[]>;
+    };
+    devices: {
+        register(input: BootstrapInput & DeviceInfoInput): Promise<DeviceRegisterResult>;
+        heartbeat(input: BootstrapInput & DeviceHeartbeatInput): Promise<DeviceHeartbeatResult>;
+    };
     webhooks: {
         verify<T extends WebhookPayload = WebhookPayload>(rawBody: WebhookRawBody, headers: WebhookHeaders, secret: string, options?: VerifyWebhookOptions): Promise<VerifiedWebhook<T>>;
     };
 }
 declare function createPickleballLiveClient(options: PickleballLiveClientOptions): PickleballLiveClient;
 
-export { type ApiLiveSession, type ApiRecording, type BootstrapInput, type EndLivestreamInput, type LivestreamSessionProvider, type LivestreamState, PickleballApiError, PickleballConfigurationError, PickleballHttpError, PickleballInvalidResponseError, type PickleballLiveClient, type PickleballLiveClientOptions, PickleballLiveError, PickleballNetworkError, PickleballTimeoutError, PickleballWebhookVerificationError, type RecordingType, SDK_TELEMETRY_EVENT_NAMES, type SdkBootstrap, type SdkError, type SdkErrorCode, type SdkPublishState, type SdkRemoteConfig, type SdkSessionGrant, type SdkSessionRefresh, type SdkTelemetryCredentials, type SdkTelemetryEvent, type SdkTelemetryEventName, type ServerSdkErrorCode, type SessionStatus, type SessionVisibility, type StartLivestreamInput, type StartSdkSessionInput, type VerifiedWebhook, type VerifyWebhookOptions, type WebhookHeaders, type WebhookPayload, type WebhookRawBody, createPickleballLiveClient, verifyWebhook };
+export { type ApiLiveSession, type ApiRecording, type BootstrapInput, type CameraGrant, type CameraGrantStatus, type CameraSessionCreated, type CreateCameraSessionInput, type DeviceControlSessionGrant, type DeviceHeartbeatInput, type DeviceHeartbeatResult, type DeviceInfoInput, type DeviceMetricsInput, type DeviceRegisterResult, type EndLivestreamInput, type LivestreamSessionProvider, type LivestreamState, PickleballApiError, PickleballConfigurationError, PickleballHttpError, PickleballInvalidResponseError, type PickleballLiveClient, type PickleballLiveClientOptions, PickleballLiveError, PickleballNetworkError, PickleballPartnerApiError, PickleballTimeoutError, PickleballWebhookVerificationError, type RecordingType, SDK_TELEMETRY_EVENT_NAMES, type SdkBootstrap, type SdkConflictReason, type SdkError, type SdkErrorCode, type SdkPublishState, type SdkRemoteConfig, type SdkSessionGrant, type SdkSessionRefresh, type SdkTelemetryCredentials, type SdkTelemetryEvent, type SdkTelemetryEventName, type ServerSdkErrorCode, type SessionStatus, type SessionVisibility, type StartLivestreamInput, type StartSdkSessionInput, type VerifiedWebhook, type VerifyWebhookOptions, type WebhookHeaders, type WebhookPayload, type WebhookRawBody, createPickleballLiveClient, verifyWebhook };

package/dist/index.js

@@ -5,12 +5,13 @@ import {
   PickleballInvalidResponseError,
   PickleballLiveError,
   PickleballNetworkError,
+  PickleballPartnerApiError,
   PickleballTimeoutError,
   PickleballWebhookVerificationError,
   SDK_TELEMETRY_EVENT_NAMES,
   createPickleballLiveClient,
   verifyWebhook
-} from "./chunk-HBTNLURN.js";
+} from "./chunk-UPS4VFER.js";
 export {
   PickleballApiError,
   PickleballConfigurationError,
@@ -18,6 +19,7 @@ export {
   PickleballInvalidResponseError,
   PickleballLiveError,
   PickleballNetworkError,
+  PickleballPartnerApiError,
   PickleballTimeoutError,
   PickleballWebhookVerificationError,
   SDK_TELEMETRY_EVENT_NAMES,