@pickleball/server-sdk 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @pickleball/server-sdk
+
+## 0.1.1
+
+### Patch Changes
+
+- 7718e9a: Prepare the first canary release of the foreground Expo livestream SDK, server
+  control-plane client, config plugin, webhook verification, and First VOD guide.
+
+## 0.1.0
+
+- Initial canary: framework-free API v2 client for Node/Edge and Web Crypto
+  webhook verification.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pickleball Live contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# `@pickleball/server-sdk`
+
+Framework-free TypeScript client for the Pickleball Live control plane. It uses
+the standard Fetch and Web Crypto APIs, so the same build works in Node.js 20+
+and Edge runtimes.
+
+## Client
+
+```ts
+import { createPickleballLiveClient } from "@pickleball/server-sdk";
+
+const live = createPickleballLiveClient({
+  baseUrl: process.env.PICKLEBALL_API_BASE_URL!,
+  appId: process.env.PICKLEBALL_APP_ID!,
+  apiKey: process.env.PICKLEBALL_API_KEY!,
+});
+
+const bootstrap = await live.apps.bootstrap({
+  sdkVersion: "0.1.0",
+  platform: "ios",
+  bundleId: "com.example.matches",
+  installationId: "existing-installation-id",
+});
+
+const grant = await live.sessions.start({
+  sdkVersion: "0.1.0",
+  platform: "ios",
+  bundleId: "com.example.matches",
+  installationId: "existing-installation-id",
+  externalSessionId: "match-42",
+  title: "Court 1",
+  consentVersion: "2026-07",
+  visibility: "private",
+  idempotencyKey: "stable-key-created-by-your-server",
+});
+
+await live.sessions.refresh(grant.sessionId, {
+  sdkVersion: "0.1.0",
+  platform: "ios",
+  bundleId: "com.example.matches",
+  installationId: "existing-installation-id",
+});
+await live.sessions.end({ sessionId: grant.sessionId, reason: "user" });
+
+const session = await live.sessions.get(grant.sessionId);
+const recordings = await live.sessions.getRecordings(grant.sessionId);
+```
+
+Bootstrap, an idempotency-keyed start, end, and GET requests retry bounded
+transient network/HTTP failures. Token refresh is not retried automatically.
+All requests have an abort timeout; failures use typed
+`PickleballLiveError` subclasses. Unknown backend error codes are normalized to
+`UNKNOWN`.
+
+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.
+
+## Webhook verification
+
+Verify the exact raw request bytes before parsing. Delivery is at-least-once:
+store `dedupeKey` under a unique constraint and acknowledge an existing key as
+success.
+
+```ts
+const rawBody = new Uint8Array(await request.arrayBuffer());
+const verified = await live.webhooks.verify(
+  rawBody,
+  request.headers,
+  process.env.PICKLEBALL_WEBHOOK_SECRET!,
+);
+
+if (await alreadyProcessed(verified.dedupeKey)) {
+  return new Response(null, { status: 204 });
+}
+
+await transaction(async () => {
+  await saveEvent(verified.dedupeKey, verified.body);
+  if (verified.event === "recording.ready") {
+    await handleRecording(verified.body.data);
+  }
+});
+return new Response(null, { status: 204 });
+```
+
+`transportId` is unsigned transport metadata and is useful for tracing only.
+`dedupeKey` is derived from the authenticated raw body, so it remains stable
+when a retry gets a new timestamp/signature or transport ID.
+
+See the [First VOD guide](https://github.com/Cabinfood/livestream-pickleball/blob/main/docs/sdk/first-vod.md)
+and [compatibility matrix](https://github.com/Cabinfood/livestream-pickleball/blob/main/docs/sdk/compatibility.md).