@pickleball/server-sdk 0.1.1

package/dist/index.d.cts

@@ -0,0 +1,206 @@
+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";
+declare class PickleballLiveError extends Error {
+    readonly code: ServerSdkErrorCode;
+    constructor(message: string, code: ServerSdkErrorCode, options?: ErrorOptions);
+}
+declare class PickleballConfigurationError extends PickleballLiveError {
+    constructor(message: string);
+}
+declare class PickleballApiError extends PickleballLiveError {
+    readonly status: number;
+    constructor(message: string, 
+    /** Stable allowlisted code. Unknown server codes are normalized to UNKNOWN. */
+    code: SdkErrorCode, status: number);
+}
+declare class PickleballHttpError extends PickleballLiveError {
+    readonly status: number;
+    constructor(status: number);
+}
+declare class PickleballInvalidResponseError extends PickleballLiveError {
+    constructor();
+}
+declare class PickleballTimeoutError extends PickleballLiveError {
+    constructor();
+}
+declare class PickleballNetworkError extends PickleballLiveError {
+    constructor();
+}
+declare class PickleballWebhookVerificationError extends PickleballLiveError {
+    constructor(message?: string);
+}
+
+interface BootstrapInput {
+    sdkVersion: string;
+    platform: "ios" | "android";
+    bundleId: string;
+    installationId: string;
+}
+interface SdkRemoteConfig {
+    enabled: boolean;
+    protocolVersion: 1;
+    minSdkVersion: string;
+    recommendedSdkVersion: string;
+    videoQuality: 720 | 1080;
+    reconnectTimeoutMs: number;
+    backgroundGraceMs: number;
+    telemetryIntervalMs: number;
+    maxSessionDurationMs: number;
+    /** Tự kết thúc phiên nếu thiết bị ngồi standby quá lâu (mặc định 15 phút). */
+    standbyTimeoutMs?: number;
+}
+interface SdkBootstrap {
+    config: SdkRemoteConfig;
+    serverTime: number;
+    rolloutEnabled: boolean;
+    message?: string;
+}
+interface StartLivestreamInput {
+    externalSessionId: string;
+    title: string;
+    visibility?: "public" | "private";
+    consentVersion: string;
+    metadata?: Record<string, string>;
+    /**
+     * true: thiết bị vào phòng ở chế độ chờ (không publish) — server giữ status
+     * "scheduled" và KHÔNG khởi động recording egress cho tới khi publish.
+     */
+    standby?: boolean;
+}
+interface SdkTelemetryCredentials {
+    endpoint: string;
+    token: string;
+    expiresAt: number;
+}
+interface SdkSessionGrant {
+    sessionId: string;
+    serverUrl: string;
+    participantToken: string;
+    playbackUrl: string | null;
+    tokenExpiresAt: number;
+    telemetry: SdkTelemetryCredentials;
+    config: SdkRemoteConfig;
+}
+interface SdkSessionRefresh {
+    participantToken?: string;
+    tokenExpiresAt?: number;
+    telemetry?: SdkTelemetryCredentials;
+    config: SdkRemoteConfig;
+}
+interface EndLivestreamInput {
+    sessionId: string;
+    reason: "user" | "background_timeout" | "network_timeout" | "standby_timeout" | "error";
+}
+/** Kết quả chuyển trạng thái publish/unpublish (standby ↔ live). */
+interface SdkPublishState {
+    sessionId: string;
+    status: "scheduled" | "live";
+}
+type SessionStatus = "scheduled" | "live" | "ended";
+type SessionVisibility = "public" | "private";
+type RecordingType = "clean" | "derived" | "device";
+interface ApiLiveSession {
+    id: string;
+    title: string;
+    status: SessionStatus;
+    visibility: SessionVisibility;
+    matchRef: string | null;
+    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;
+    scheduledAt: number | null;
+    startedAt: number | null;
+    endedAt: number | null;
+    viewerCount: number;
+    likeCount: number;
+    shareCount: number;
+}
+interface ApiRecording {
+    id: string;
+    sessionId: string;
+    type: RecordingType;
+    status: "recording" | "ready" | "failed";
+    url: string | null;
+    durationSec: number | null;
+}
+type StartSdkSessionInput = BootstrapInput & StartLivestreamInput & {
+    idempotencyKey: string;
+};
+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 {
+    sessionId: string;
+    at: number;
+    name: SdkTelemetryEventName;
+    data?: Record<string, unknown>;
+}
+interface LivestreamSessionProvider {
+    bootstrap(input: BootstrapInput): Promise<SdkBootstrap>;
+    start(input: StartLivestreamInput): Promise<SdkSessionGrant>;
+    refresh(sessionId: string): Promise<SdkSessionRefresh>;
+    end(input: EndLivestreamInput): Promise<void>;
+    /**
+     * Báo server bắt đầu phát thật (standby → live) — bật recording egress +
+     * chuyển status live trước khi thiết bị publish track. Optional để giữ
+     * tương thích provider cũ.
+     */
+    publish?(sessionId: string): Promise<void>;
+    /** Báo server tạm dừng phát (live → standby): dừng egress, status về chờ. */
+    unpublish?(sessionId: string): Promise<void>;
+}
+type LivestreamState = "idle" | "preparing" | "preview" | "connecting" | "standby" | "live" | "reconnecting" | "ending" | "ended" | "error";
+interface SdkError {
+    code: SdkErrorCode;
+    message: string;
+}
+
+type WebhookRawBody = string | Uint8Array;
+type WebhookHeaders = Headers | Record<string, string | string[] | undefined>;
+interface VerifyWebhookOptions {
+    toleranceSeconds?: number;
+    /** Epoch milliseconds; primarily useful for deterministic verification. */
+    now?: number;
+}
+interface WebhookPayload {
+    event: string;
+    [key: string]: unknown;
+}
+interface VerifiedWebhook<T extends WebhookPayload = WebhookPayload> {
+    /** Unsigned delivery metadata. Do not use this value alone for deduplication. */
+    transportId: string;
+    /** Stable SHA-256 key derived from the authenticated raw body. */
+    dedupeKey: string;
+    event: string;
+    timestamp: number;
+    body: T;
+}
+declare function verifyWebhook<T extends WebhookPayload = WebhookPayload>(rawBody: WebhookRawBody, headers: WebhookHeaders, secret: string, options?: VerifyWebhookOptions): Promise<VerifiedWebhook<T>>;
+
+interface PickleballLiveClientOptions {
+    baseUrl: string;
+    appId: string;
+    apiKey: string;
+    fetch?: typeof globalThis.fetch;
+    timeoutMs?: number;
+    maxRetries?: number;
+}
+interface PickleballLiveClient {
+    apps: {
+        bootstrap(input: BootstrapInput): Promise<SdkBootstrap>;
+    };
+    sessions: {
+        start(input: StartSdkSessionInput): Promise<SdkSessionGrant>;
+        refresh(sessionId: string, input: BootstrapInput): Promise<SdkSessionRefresh>;
+        end(input: EndLivestreamInput): Promise<void>;
+        publish(sessionId: string): Promise<SdkPublishState>;
+        unpublish(sessionId: string): Promise<SdkPublishState>;
+        get(sessionId: string): Promise<ApiLiveSession>;
+        getRecordings(sessionId: string): Promise<ApiRecording[]>;
+    };
+    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 };

package/dist/index.d.ts

@@ -0,0 +1,206 @@
+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";
+declare class PickleballLiveError extends Error {
+    readonly code: ServerSdkErrorCode;
+    constructor(message: string, code: ServerSdkErrorCode, options?: ErrorOptions);
+}
+declare class PickleballConfigurationError extends PickleballLiveError {
+    constructor(message: string);
+}
+declare class PickleballApiError extends PickleballLiveError {
+    readonly status: number;
+    constructor(message: string, 
+    /** Stable allowlisted code. Unknown server codes are normalized to UNKNOWN. */
+    code: SdkErrorCode, status: number);
+}
+declare class PickleballHttpError extends PickleballLiveError {
+    readonly status: number;
+    constructor(status: number);
+}
+declare class PickleballInvalidResponseError extends PickleballLiveError {
+    constructor();
+}
+declare class PickleballTimeoutError extends PickleballLiveError {
+    constructor();
+}
+declare class PickleballNetworkError extends PickleballLiveError {
+    constructor();
+}
+declare class PickleballWebhookVerificationError extends PickleballLiveError {
+    constructor(message?: string);
+}
+
+interface BootstrapInput {
+    sdkVersion: string;
+    platform: "ios" | "android";
+    bundleId: string;
+    installationId: string;
+}
+interface SdkRemoteConfig {
+    enabled: boolean;
+    protocolVersion: 1;
+    minSdkVersion: string;
+    recommendedSdkVersion: string;
+    videoQuality: 720 | 1080;
+    reconnectTimeoutMs: number;
+    backgroundGraceMs: number;
+    telemetryIntervalMs: number;
+    maxSessionDurationMs: number;
+    /** Tự kết thúc phiên nếu thiết bị ngồi standby quá lâu (mặc định 15 phút). */
+    standbyTimeoutMs?: number;
+}
+interface SdkBootstrap {
+    config: SdkRemoteConfig;
+    serverTime: number;
+    rolloutEnabled: boolean;
+    message?: string;
+}
+interface StartLivestreamInput {
+    externalSessionId: string;
+    title: string;
+    visibility?: "public" | "private";
+    consentVersion: string;
+    metadata?: Record<string, string>;
+    /**
+     * true: thiết bị vào phòng ở chế độ chờ (không publish) — server giữ status
+     * "scheduled" và KHÔNG khởi động recording egress cho tới khi publish.
+     */
+    standby?: boolean;
+}
+interface SdkTelemetryCredentials {
+    endpoint: string;
+    token: string;
+    expiresAt: number;
+}
+interface SdkSessionGrant {
+    sessionId: string;
+    serverUrl: string;
+    participantToken: string;
+    playbackUrl: string | null;
+    tokenExpiresAt: number;
+    telemetry: SdkTelemetryCredentials;
+    config: SdkRemoteConfig;
+}
+interface SdkSessionRefresh {
+    participantToken?: string;
+    tokenExpiresAt?: number;
+    telemetry?: SdkTelemetryCredentials;
+    config: SdkRemoteConfig;
+}
+interface EndLivestreamInput {
+    sessionId: string;
+    reason: "user" | "background_timeout" | "network_timeout" | "standby_timeout" | "error";
+}
+/** Kết quả chuyển trạng thái publish/unpublish (standby ↔ live). */
+interface SdkPublishState {
+    sessionId: string;
+    status: "scheduled" | "live";
+}
+type SessionStatus = "scheduled" | "live" | "ended";
+type SessionVisibility = "public" | "private";
+type RecordingType = "clean" | "derived" | "device";
+interface ApiLiveSession {
+    id: string;
+    title: string;
+    status: SessionStatus;
+    visibility: SessionVisibility;
+    matchRef: string | null;
+    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;
+    scheduledAt: number | null;
+    startedAt: number | null;
+    endedAt: number | null;
+    viewerCount: number;
+    likeCount: number;
+    shareCount: number;
+}
+interface ApiRecording {
+    id: string;
+    sessionId: string;
+    type: RecordingType;
+    status: "recording" | "ready" | "failed";
+    url: string | null;
+    durationSec: number | null;
+}
+type StartSdkSessionInput = BootstrapInput & StartLivestreamInput & {
+    idempotencyKey: string;
+};
+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 {
+    sessionId: string;
+    at: number;
+    name: SdkTelemetryEventName;
+    data?: Record<string, unknown>;
+}
+interface LivestreamSessionProvider {
+    bootstrap(input: BootstrapInput): Promise<SdkBootstrap>;
+    start(input: StartLivestreamInput): Promise<SdkSessionGrant>;
+    refresh(sessionId: string): Promise<SdkSessionRefresh>;
+    end(input: EndLivestreamInput): Promise<void>;
+    /**
+     * Báo server bắt đầu phát thật (standby → live) — bật recording egress +
+     * chuyển status live trước khi thiết bị publish track. Optional để giữ
+     * tương thích provider cũ.
+     */
+    publish?(sessionId: string): Promise<void>;
+    /** Báo server tạm dừng phát (live → standby): dừng egress, status về chờ. */
+    unpublish?(sessionId: string): Promise<void>;
+}
+type LivestreamState = "idle" | "preparing" | "preview" | "connecting" | "standby" | "live" | "reconnecting" | "ending" | "ended" | "error";
+interface SdkError {
+    code: SdkErrorCode;
+    message: string;
+}
+
+type WebhookRawBody = string | Uint8Array;
+type WebhookHeaders = Headers | Record<string, string | string[] | undefined>;
+interface VerifyWebhookOptions {
+    toleranceSeconds?: number;
+    /** Epoch milliseconds; primarily useful for deterministic verification. */
+    now?: number;
+}
+interface WebhookPayload {
+    event: string;
+    [key: string]: unknown;
+}
+interface VerifiedWebhook<T extends WebhookPayload = WebhookPayload> {
+    /** Unsigned delivery metadata. Do not use this value alone for deduplication. */
+    transportId: string;
+    /** Stable SHA-256 key derived from the authenticated raw body. */
+    dedupeKey: string;
+    event: string;
+    timestamp: number;
+    body: T;
+}
+declare function verifyWebhook<T extends WebhookPayload = WebhookPayload>(rawBody: WebhookRawBody, headers: WebhookHeaders, secret: string, options?: VerifyWebhookOptions): Promise<VerifiedWebhook<T>>;
+
+interface PickleballLiveClientOptions {
+    baseUrl: string;
+    appId: string;
+    apiKey: string;
+    fetch?: typeof globalThis.fetch;
+    timeoutMs?: number;
+    maxRetries?: number;
+}
+interface PickleballLiveClient {
+    apps: {
+        bootstrap(input: BootstrapInput): Promise<SdkBootstrap>;
+    };
+    sessions: {
+        start(input: StartSdkSessionInput): Promise<SdkSessionGrant>;
+        refresh(sessionId: string, input: BootstrapInput): Promise<SdkSessionRefresh>;
+        end(input: EndLivestreamInput): Promise<void>;
+        publish(sessionId: string): Promise<SdkPublishState>;
+        unpublish(sessionId: string): Promise<SdkPublishState>;
+        get(sessionId: string): Promise<ApiLiveSession>;
+        getRecordings(sessionId: string): Promise<ApiRecording[]>;
+    };
+    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 };

package/dist/index.js

@@ -0,0 +1,26 @@
+import {
+  PickleballApiError,
+  PickleballConfigurationError,
+  PickleballHttpError,
+  PickleballInvalidResponseError,
+  PickleballLiveError,
+  PickleballNetworkError,
+  PickleballTimeoutError,
+  PickleballWebhookVerificationError,
+  SDK_TELEMETRY_EVENT_NAMES,
+  createPickleballLiveClient,
+  verifyWebhook
+} from "./chunk-HBTNLURN.js";
+export {
+  PickleballApiError,
+  PickleballConfigurationError,
+  PickleballHttpError,
+  PickleballInvalidResponseError,
+  PickleballLiveError,
+  PickleballNetworkError,
+  PickleballTimeoutError,
+  PickleballWebhookVerificationError,
+  SDK_TELEMETRY_EVENT_NAMES,
+  createPickleballLiveClient,
+  verifyWebhook
+};