@moviie/player-sdk 0.2.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +70 -11
  3. package/package.json +24 -3
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Moviie
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,12 +1,18 @@
1
1
  # @moviie/player-sdk
2
2
 
3
- Vendor-agnostic HTTP client for Moviie playback metadata and telemetry. Works in Node, browsers, and React Native.
3
+ Vendor-agnostic JavaScript SDK for the [Moviie](https://moviie.ai) video platform. Fetch playback metadata, build custom player UIs, and integrate Moviie playback into any runtime — Node.js, browsers, React Native, Expo, or edge workers.
4
4
 
5
- ## Playback (`getPlayback`)
5
+ Full documentation: [docs.moviie.ai](https://docs.moviie.ai).
6
6
 
7
- `MoviieClient.getPlayback(embedId)` calls `GET /v1/embeds/{embedId}/playback` against the configured API base. You **must** configure a **publishable** API key (`mvi_pub_*`) on the client. Missing keys and non-publishable keys throw `MoviieAuthError` before any network request (see `SDK_PLAYBACK_AUTH_ERROR_MESSAGE` in `./constants`).
7
+ ## Prerequisites
8
8
 
9
- Private/admin keys belong only on the server; they are **not** accepted by the playback endpoint.
9
+ You need a **[Moviie](https://moviie.ai) account** and a **publishable API key** (`mvi_pub_*`).
10
+
11
+ 1. Create an account at [app.moviie.ai/signin](https://app.moviie.ai/signin).
12
+ 2. Go to **Organization Settings → API Keys** and create a **Publishable** key.
13
+ 3. Copy the key — it starts with `mvi_pub_`.
14
+
15
+ > **Never** use a secret key (`mvi_sec_*`) in a client app. The playback API rejects it.
10
16
 
11
17
  ## Install
12
18
 
@@ -14,17 +20,70 @@ Private/admin keys belong only on the server; they are **not** accepted by the p
14
20
  pnpm add @moviie/player-sdk
15
21
  ```
16
22
 
17
- ## API base URL
23
+ ## Quick start
24
+
25
+ ```ts
26
+ import { MoviieClient } from "@moviie/player-sdk"
27
+
28
+ const client = new MoviieClient({
29
+ publishableKey: process.env.MOVIIE_PUBLISHABLE_KEY,
30
+ clientInfo: {
31
+ platform: "web",
32
+ sdkVersion: "1.0.0",
33
+ },
34
+ })
35
+
36
+ const playback = await client.getPlayback("YOUR-EMBED-UUID")
37
+ console.log(playback.playback.uri) // HLS stream URL
38
+ ```
39
+
40
+ The returned `MoviiePlaybackData` includes the HLS source, poster, captions, chapters, CTAs, and per-embed control flags (Chromecast, PiP, autoplay, etc.). Wire it into any video element or player library.
41
+
42
+ ## API
18
43
 
19
- The default base is **`MOVIIE_DEFAULT_API_BASE_URL`** (`https://api.moviie.ai/v1`), aligned with the public OpenAPI production server.
44
+ ### `new MoviieClient(options)`
20
45
 
21
- - **Expo:** pass **`apiBaseUrl`** on the `@moviie/player-expo` config plugin. It is written to `expo.extra` and applied at runtime via `configureMoviieEndpoints`.
22
- - **Node / scripts / tests:** call **`configureMoviieEndpoints({ apiBaseUrl: "https://your-host/v1" })`** before using `MoviieClient`, or rely on the default. Use **`resetMoviieEndpointsConfiguration()`** in tests between cases.
46
+ | Option | Type | Required | Description |
47
+ |--------|------|:--------:|-------------|
48
+ | `publishableKey` | `string` | ✓ | Publishable key (`mvi_pub_*`) from your [Moviie](https://moviie.ai) organization settings. |
49
+ | `clientInfo` | `MoviieClientInfo` | — | Optional bundle ID, platform, and SDK version. Sent as request headers for analytics and bundle-ID allowlisting. |
50
+ | `sdkVersion` | `string` | — | Optional SDK version string sent with requests. |
51
+
52
+ ### `client.getPlayback(embedId)`
53
+
54
+ Fetches playback metadata for a public embed. Returns `Promise<MoviiePlaybackData>`. Throws a typed error on failure:
55
+
56
+ | Class | `.code` | Cause |
57
+ |-------|---------|-------|
58
+ | `MoviieAuthError` | `auth` | Invalid or missing publishable key. |
59
+ | `MoviieNotFoundError` | `not_found` | Embed UUID does not exist. |
60
+ | `MoviieBundleBlockedError` | `bundle_blocked` | Bundle ID not on the embed allowlist. |
61
+ | `MoviieReferrerBlockedError` | `referrer_blocked` | Request origin not on the embed allowlist. |
62
+ | `MoviieSubscriptionInactiveError` | `subscription_inactive` | Organization subscription is paused or expired. |
63
+ | `MoviieNetworkError` | `network` | Network request failed (timeout, unreachable). |
64
+ | `MoviieRateLimitError` | `rate_limit` | Too many requests in a short period. |
65
+
66
+ Detect by class or code string:
67
+
68
+ ```ts
69
+ import { MoviieBundleBlockedError } from "@moviie/player-sdk"
70
+
71
+ try {
72
+ await client.getPlayback(embedId)
73
+ } catch (error) {
74
+ if (error instanceof MoviieBundleBlockedError) {
75
+ // ask the user to update the allowlist in the Moviie dashboard
76
+ }
77
+ if (error?.code === "network") {
78
+ // retry
79
+ }
80
+ }
81
+ ```
23
82
 
24
- Telemetry uses the **same origin** as the Public API with path **`MOVIIE_TELEMETRY_API_PATH_PREFIX`** (`/telemetry/v1`). `getMoviieEventsBaseUrl()` derives `{apiOrigin}/telemetry/v1` from `getMoviieApiBaseUrl()` unless you pass **`eventsBaseUrl`** into **`configureMoviieEndpoints`** (or the Expo plugin sets **`moviieEventsBaseUrl`** in `expo.extra`).
83
+ ## Looking for the React Native / Expo player?
25
84
 
26
- Pass **`publishableKey`** and optional **`clientInfo`** when constructing **`MoviieClient`**.
85
+ If you're building a mobile app with Expo or React Native, use [`@moviie/player-expo`](https://www.npmjs.com/package/@moviie/player-expo) — it wraps this SDK with a ready-to-use video component, custom chrome, Picture-in-Picture, background audio, and optional Chromecast.
27
86
 
28
87
  ## License
29
88
 
30
- UNLICENSED — Moviie proprietary.
89
+ MIT — see [`LICENSE`](./LICENSE). Copyright (c) 2026 [Moviie](https://moviie.ai).
package/package.json CHANGED
@@ -1,9 +1,28 @@
1
1
  {
2
2
  "name": "@moviie/player-sdk",
3
- "version": "0.2.0",
3
+ "version": "0.2.1",
4
4
  "private": false,
5
5
  "description": "Vendor-agnostic Moviie player SDK — playback metadata, HTTP client, telemetry.",
6
- "license": "UNLICENSED",
6
+ "keywords": [
7
+ "moviie",
8
+ "player",
9
+ "video",
10
+ "video-player",
11
+ "video-sdk",
12
+ "sdk",
13
+ "playback",
14
+ "hls",
15
+ "streaming",
16
+ "vod",
17
+ "captions",
18
+ "subtitles",
19
+ "chapters",
20
+ "react-native",
21
+ "expo",
22
+ "browser",
23
+ "node"
24
+ ],
25
+ "license": "MIT",
7
26
  "type": "module",
8
27
  "main": "./dist/index.cjs",
9
28
  "module": "./dist/index.js",
@@ -16,7 +35,9 @@
16
35
  }
17
36
  },
18
37
  "files": [
19
- "dist"
38
+ "dist",
39
+ "README.md",
40
+ "LICENSE"
20
41
  ],
21
42
  "dependencies": {
22
43
  "zod": "^3.25.76",