@puzzmo/sdk 0.0.7 → 1.0.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 (75) hide show
  1. package/README.md +80 -260
  2. package/dist/createSimulator-9IxV0l3_.js +2749 -0
  3. package/dist/createSimulator-9IxV0l3_.js.map +1 -0
  4. package/dist/createSimulator-DxhvbnJB.cjs +1428 -0
  5. package/dist/createSimulator-DxhvbnJB.cjs.map +1 -0
  6. package/dist/index.cjs +2 -2
  7. package/dist/index.cjs.map +1 -1
  8. package/dist/index.d.ts +3 -13
  9. package/dist/index.d.ts.map +1 -1
  10. package/dist/index.js +267 -14
  11. package/dist/index.js.map +1 -1
  12. package/dist/objectSpread2-C4RR_HMd.cjs +1 -0
  13. package/dist/objectSpread2-CJo2CZQ6.js +76 -0
  14. package/dist/sdk.d.ts +61 -0
  15. package/dist/sdk.d.ts.map +1 -0
  16. package/dist/simulator/createSimulator.d.ts +41 -0
  17. package/dist/simulator/createSimulator.d.ts.map +1 -0
  18. package/dist/simulator/fixtures.d.ts +18 -0
  19. package/dist/simulator/fixtures.d.ts.map +1 -0
  20. package/dist/simulator/index.cjs +1 -0
  21. package/dist/simulator/index.d.ts +3 -0
  22. package/dist/simulator/index.d.ts.map +1 -0
  23. package/dist/simulator/index.js +2 -0
  24. package/dist/simulator/messaging.d.ts +12 -0
  25. package/dist/simulator/messaging.d.ts.map +1 -0
  26. package/dist/simulator/standalone.cjs +2 -0
  27. package/dist/simulator/standalone.cjs.map +1 -0
  28. package/dist/simulator/standalone.d.ts +7 -0
  29. package/dist/simulator/standalone.d.ts.map +1 -0
  30. package/dist/simulator/standalone.js +19 -0
  31. package/dist/simulator/standalone.js.map +1 -0
  32. package/dist/simulator/state.d.ts +12 -0
  33. package/dist/simulator/state.d.ts.map +1 -0
  34. package/dist/simulator/styles.d.ts +2 -0
  35. package/dist/simulator/styles.d.ts.map +1 -0
  36. package/dist/simulator/types.d.ts +72 -0
  37. package/dist/simulator/types.d.ts.map +1 -0
  38. package/dist/simulator/views/AuthView.d.ts +3 -0
  39. package/dist/simulator/views/AuthView.d.ts.map +1 -0
  40. package/dist/simulator/views/CheckpointsView.d.ts +3 -0
  41. package/dist/simulator/views/CheckpointsView.d.ts.map +1 -0
  42. package/dist/simulator/views/CtrlView.d.ts +3 -0
  43. package/dist/simulator/views/CtrlView.d.ts.map +1 -0
  44. package/dist/simulator/views/DataView.d.ts +3 -0
  45. package/dist/simulator/views/DataView.d.ts.map +1 -0
  46. package/dist/simulator/views/DoneView.d.ts +3 -0
  47. package/dist/simulator/views/DoneView.d.ts.map +1 -0
  48. package/dist/simulator/views/FeaturesView.d.ts +4 -0
  49. package/dist/simulator/views/FeaturesView.d.ts.map +1 -0
  50. package/dist/simulator/views/MsgsView.d.ts +6 -0
  51. package/dist/simulator/views/MsgsView.d.ts.map +1 -0
  52. package/dist/simulator/views/ThemeView.d.ts +3 -0
  53. package/dist/simulator/views/ThemeView.d.ts.map +1 -0
  54. package/dist/simulator/views/ThumbView.d.ts +6 -0
  55. package/dist/simulator/views/ThumbView.d.ts.map +1 -0
  56. package/dist/simulator/views/index.d.ts +10 -0
  57. package/dist/simulator/views/index.d.ts.map +1 -0
  58. package/dist/themes.d.ts +46 -0
  59. package/dist/themes.d.ts.map +1 -0
  60. package/dist/types.d.ts +232 -0
  61. package/dist/types.d.ts.map +1 -0
  62. package/dist/vite.cjs +11 -0
  63. package/dist/vite.cjs.map +1 -0
  64. package/dist/vite.d.ts +16 -0
  65. package/dist/vite.d.ts.map +1 -0
  66. package/dist/vite.js +45 -0
  67. package/dist/vite.js.map +1 -0
  68. package/dist/workshop.d.ts +7 -175
  69. package/dist/workshop.d.ts.map +1 -1
  70. package/package.json +21 -19
  71. package/dist/index.iife.js +0 -2
  72. package/dist/index.iife.js.map +0 -1
  73. package/dist/index.umd.js +0 -2
  74. package/dist/index.umd.js.map +0 -1
  75. package/dist/puzzmoSDK.d.ts +0 -237
package/README.md CHANGED
@@ -1,303 +1,123 @@
1
1
  # @puzzmo/sdk
2
2
 
3
- The official Puzzmo SDK for runtime and API access for games.
3
+ SDK for building games on the Puzzmo platform. Handles communication between your game and the Puzzmo host (puzzmo.com, embeds, native apps).
4
4
 
5
- ## Installation
6
-
7
- ### npm
5
+ ## Install
8
6
 
9
7
  ```bash
10
8
  npm install @puzzmo/sdk
11
9
  ```
12
10
 
13
- ### yarn
14
-
15
- ```bash
16
- yarn add @puzzmo/sdk
17
- ```
18
-
19
- ### pnpm
20
-
21
- ```bash
22
- pnpm add @puzzmo/sdk
23
- ```
24
-
25
- ## Usage
26
-
27
- ### ES Modules (Node.js, Bundlers)
28
-
29
- ```javascript
30
- import { helloWorld, getVersion } from "@puzzmo/sdk"
31
-
32
- console.log(helloWorld()) // "Hello from Puzzmo SDK!"
33
- console.log(getVersion()) // "0.0.1"
34
- ```
35
-
36
- ### CommonJS (Node.js)
37
-
38
- ```javascript
39
- const { helloWorld, getVersion } = require("@puzzmo/sdk")
40
-
41
- console.log(helloWorld()) // "Hello from Puzzmo SDK!"
42
- console.log(getVersion()) // "0.0.1"
43
- ```
44
-
45
- ### UMD (Browser via CDN)
46
-
47
- ```html
48
- <!DOCTYPE html>
49
- <html>
50
- <head>
51
- <script src="https://unpkg.com/@puzzmo/sdk@latest/dist/index.umd.js"></script>
52
- </head>
53
- <body>
54
- <script>
55
- console.log(PuzzmoSDK.helloWorld()) // "Hello from Puzzmo SDK!"
56
- console.log(PuzzmoSDK.getVersion()) // "0.0.1"
57
- </script>
58
- </body>
59
- </html>
60
- ```
61
-
62
- #### Using a specific version
63
-
64
- ```html
65
- <script src="https://unpkg.com/@puzzmo/sdk@0.0.1/dist/index.umd.js"></script>
66
- ```
67
-
68
- #### Using jsDelivr CDN
69
-
70
- ```html
71
- <script src="https://cdn.jsdelivr.net/npm/@puzzmo/sdk@latest/dist/index.umd.js"></script>
72
- ```
11
+ ## Quick Start
73
12
 
74
- ### IIFE (Browser via CDN, smaller build)
75
-
76
- IIFE (Immediately Invoked Function Expression) is a more compact format ideal for modern browsers:
77
-
78
- ```html
79
- <!DOCTYPE html>
80
- <html>
81
- <head>
82
- <script src="https://unpkg.com/@puzzmo/sdk@latest/dist/index.iife.js"></script>
83
- </head>
84
- <body>
85
- <script>
86
- console.log(PuzzmoSDK.helloWorld()) // "Hello from Puzzmo SDK!"
87
- console.log(PuzzmoSDK.getVersion()) // "0.0.1"
88
- </script>
89
- </body>
90
- </html>
91
- ```
13
+ ```ts
14
+ import { createPuzzmoSDK } from "@puzzmo/sdk"
92
15
 
93
- ## API Reference
16
+ const sdk = createPuzzmoSDK()
94
17
 
95
- ### Workshop Bundle
18
+ // 1. Wait for puzzle data from Puzzmo
19
+ const { puzzleString, boardState, theme, completed } = await sdk.gameReady()
96
20
 
97
- The SDK exports the `WorkshopBundle` interface for games to provide Workshop-specific functionality like validation, import, and settings configuration.
21
+ // 2. Set up your game with the puzzle data
22
+ const puzzle = JSON.parse(puzzleString)
23
+ initializeGame(puzzle)
24
+ if (boardState) restoreState(boardState)
98
25
 
99
- ```typescript
100
- import type { WorkshopBundle } from "@puzzmo/sdk"
26
+ // 3. Signal that you're ready
27
+ sdk.gameLoaded()
101
28
 
102
- const bundle: WorkshopBundle = {
103
- validator: {
104
- validate(data: string) {
105
- // Validate puzzle data
106
- return { success: true, issues: [] }
107
- },
108
- },
109
- importer: {
110
- onImport(filename: string, contents: string | ArrayBuffer) {
111
- // Convert external formats to native format
112
- return { data: convertedData }
113
- },
114
- },
115
- settings: {
116
- components: settingsUIComponents(), // GameSettingsUIComponents[]
117
- defaults: defaultSettings(), // Record<string, unknown>
118
- },
119
- }
120
-
121
- export default bundle
29
+ // 4. Listen for lifecycle events
30
+ sdk.on("start", () => startGameLoop())
31
+ sdk.on("pause", () => pauseGameLoop())
32
+ sdk.on("resume", () => resumeGameLoop())
33
+ sdk.on("retry", () => resetGame())
122
34
  ```
123
35
 
124
- #### `WorkshopBundle.validator` (required)
125
-
126
- Validates puzzle data and returns a report of issues.
127
-
128
- #### `WorkshopBundle.importer` (optional)
129
-
130
- Imports external puzzle file formats and converts them to the game's native format.
36
+ ## API
131
37
 
132
- #### `WorkshopBundle.settings` (optional)
38
+ ### `createPuzzmoSDK(options?)`
133
39
 
134
- Provides settings configuration for embed customization in Workshop:
40
+ Creates an SDK instance. Options:
135
41
 
136
- - `components`: Array of `GameSettingsUIComponents` defining the settings form UI
137
- - `defaults`: Object containing default values for all settings
42
+ - `timeout` - Timeout in ms waiting for puzzle data (default: 5000)
138
43
 
139
- ---
44
+ ### Lifecycle
140
45
 
141
- ### `helloWorld(): string`
46
+ | Method | Description |
47
+ | -------------------------- | -------------------------------------------------------------------------- |
48
+ | `sdk.gameReady()` | Async. Signals readiness, returns puzzle data and theme. |
49
+ | `sdk.gameLoaded(state?)` | Signals game UI is ready. Host will send `start`. |
50
+ | `sdk.on(event, handler)` | Listen for events: `start`, `pause`, `resume`, `retry`, `settingsUpdate`. |
51
+ | `sdk.off(event, handler)` | Remove an event listener. |
142
52
 
143
- Returns a hello world message from the Puzzmo SDK.
53
+ ### Game State
144
54
 
145
- **Returns:** `string` - A greeting message
55
+ | Method | Description |
56
+ | ----------------------------------------------------------- | ---------------------------------------------------------- |
57
+ | `sdk.updateGameState(stateString, play?)` | Save current game state for persistence. |
58
+ | `sdk.gameCompleted(play, config?)` | Signal game completion with metrics and deeds. |
59
+ | `sdk.showCompletionScreen(results, gameplay, showRetry?)` | Show the Puzzmo completion UI. |
60
+ | `sdk.hitCheckpoint(name, config, augConfig?)` | Signal a gameplay milestone (for ads, leaderboards). |
146
61
 
147
- **Example:**
62
+ ### Timer
148
63
 
149
- ```javascript
150
- import { helloWorld } from "@puzzmo/sdk"
64
+ The SDK manages a timer automatically (starts on `start`, pauses on `pause`, resets on `retry`).
151
65
 
152
- const message = helloWorld()
153
- console.log(message) // "Hello from Puzzmo SDK!"
66
+ ```ts
67
+ sdk.timer.timeMs() // Elapsed time in ms
68
+ sdk.timer.timeSecs() // Elapsed time in seconds
69
+ sdk.timer.display() // ["1:23", "0:05"] (elapsed, penalty)
70
+ sdk.timer.addPenalty(5000) // Add 5s penalty
71
+ sdk.timer.isPaused() // Check if paused
72
+ sdk.timer.isRunning() // Check if running
154
73
  ```
155
74
 
156
- ### `getVersion(): string`
75
+ ## Theme
157
76
 
158
- Returns the current SDK version.
77
+ The `theme` object from `gameReady()` contains color tokens for the current Puzzmo theme:
159
78
 
160
- **Returns:** `string` - The SDK version
79
+ ```ts
80
+ const { theme } = await sdk.gameReady()
161
81
 
162
- **Example:**
163
-
164
- ```javascript
165
- import { getVersion } from "@puzzmo/sdk"
166
-
167
- const version = getVersion()
168
- console.log(version) // "0.0.1"
82
+ // Key colors
83
+ theme.g_bg // Game background
84
+ theme.fg // Foreground text
85
+ theme.key // Primary accent
86
+ theme.player // Player color (blue)
87
+ theme.alt1 // Accent green
88
+ theme.alt2 // Accent yellow
89
+ theme.alt3 // Accent purple
90
+ theme.type // "light" or "dark"
169
91
  ```
170
92
 
171
- ## Development
172
-
173
- ### Setup
174
-
175
- ```bash
176
- # Install dependencies (from repository root)
177
- yarn install
178
-
179
- # Build the SDK
180
- yarn workspace @puzzmo/sdk build
181
-
182
- # Generate SDK types from hostAPI.d.ts
183
- yarn workspace @puzzmo/sdk generate-sdk
184
-
185
- # Watch mode for SDK type generation (auto-regenerates on changes)
186
- yarn workspace @puzzmo/sdk generate-sdk:watch
187
-
188
- # Run tests
189
- yarn workspace @puzzmo/sdk test
93
+ See the `Theme` type export for the full list of tokens.
190
94
 
191
- # Watch mode for tests
192
- yarn workspace @puzzmo/sdk test:watch
95
+ ## Deeds
193
96
 
194
- # Type checking
195
- yarn workspace @puzzmo/sdk type-check
196
- ```
197
-
198
- ### Project Structure
97
+ Deeds are gameplay statistics sent on completion:
199
98
 
99
+ ```ts
100
+ sdk.gameCompleted(metrics, {
101
+ deeds: [
102
+ { id: "moves", value: 42 },
103
+ { id: "accuracy", value: 95 },
104
+ { id: "streak", value: 8 },
105
+ ],
106
+ })
200
107
  ```
201
- packages/sdk/
202
- ├── src/
203
- │ ├── index.ts # Main SDK source
204
- │ └── puzzmoSDK.d.ts # Auto-generated types (DO NOT EDIT)
205
- ├── scripts/
206
- │ └── generateSDK.ts # Type generation script
207
- ├── dist/ # Build output (generated)
208
- │ ├── index.js # ES module build
209
- │ ├── index.cjs # CommonJS build
210
- │ ├── index.umd.js # UMD build (for CDN)
211
- │ ├── index.iife.js # IIFE build (for CDN, smaller)
212
- │ └── index.d.ts # TypeScript declarations
213
- ├── package.json
214
- ├── tsconfig.json
215
- ├── vite.config.ts # Build configuration
216
- └── README.md
217
- ```
218
-
219
- ### Type Generation
220
-
221
- The SDK types in `puzzmoSDK.d.ts` are automatically generated from multiple sources:
222
-
223
- 1. **`@puzzmo-com/shared/hostAPI.d.ts`**: Types marked with `@public` JSDoc tags
224
- 2. **`@puzzmo-com/keyboard/src/types.ts`**: Explicitly included types (e.g., `KeyboardConfig`)
225
-
226
- The generation script processes both files and combines them into a single SDK type file. To add new types:
227
-
228
- - For types from `hostAPI.d.ts`: Add `@public` JSDoc tag
229
- - For types from `keyboard/types.ts`: Add the type name to the `includeTypes` array in `generateSDK.ts`
230
-
231
- **DO NOT edit `puzzmoSDK.d.ts` directly** - it will be overwritten on every build.
232
-
233
- ### Build Outputs
234
-
235
- The SDK provides multiple build outputs to support different environments:
236
-
237
- - **ESM (`index.js`)**: Modern ES module format for bundlers and modern Node.js
238
- - **CommonJS (`index.cjs`)**: Traditional CommonJS format for older Node.js environments
239
- - **UMD (`index.umd.js`)**: Universal Module Definition for browser `<script>` tags via CDN
240
- - **IIFE (`index.iife.js`)**: Immediately Invoked Function Expression for browser `<script>` tags (smaller than UMD)
241
- - **TypeScript (`index.d.ts`)**: Type declarations for TypeScript projects
242
-
243
- ## Publishing
244
-
245
- The SDK is automatically published to npm when changes are pushed to the `main` branch and the version in `package.json` has been updated.
246
108
 
247
- ### OIDC-Based Publishing
109
+ The SDK automatically adds `points` and `time` deeds.
248
110
 
249
- This package uses **OpenID Connect (OIDC)** for secure, auditable publishing:
111
+ ## Workshop Types
250
112
 
251
- - **Signed Provenance**: Every published version includes cryptographic proof it was built in GitHub Actions
252
- - **Supply Chain Security**: Verifiable build attestations prevent tampering
253
- - **Minimal Permissions**: Uses granular npm tokens scoped to this package only
113
+ For games that support puzzle editing in Puzzmo Workshop:
254
114
 
255
- See [PUBLISHING.md](./PUBLISHING.md) for complete setup instructions and security details.
115
+ ```ts
116
+ import type { WorkshopBundle, ValidationReport } from "@puzzmo/sdk"
256
117
 
257
- ### Quick Start: Publishing a New Version
258
-
259
- 1. Update the version in `packages/sdk/package.json`:
260
-
261
- ```bash
262
- npm version patch # or minor/major
263
- ```
264
-
265
- 2. Commit and push to `main`:
266
-
267
- ```bash
268
- git add package.json
269
- git commit -m "chore(sdk): bump version to x.x.x"
270
- git push origin main
271
- ```
272
-
273
- 3. GitHub Actions automatically:
274
- - Builds and tests the package
275
- - Publishes to npm with OIDC provenance
276
- - Creates a git tag for the release
277
-
278
- ### Verifying Published Packages
279
-
280
- Anyone can verify the package was built by this repository:
281
-
282
- ```bash
283
- npm view @puzzmo/sdk
284
- # Look for "provenance" section showing GitHub workflow details
118
+ export const validator = {
119
+ validate(data: string): ValidationReport {
120
+ return { success: true, issues: [] }
121
+ },
122
+ }
285
123
  ```
286
-
287
- **Setup Required**: A granular npm access token must be configured as `NPM_TOKEN` in repository secrets. See [PUBLISHING.md](./PUBLISHING.md) for detailed instructions.
288
-
289
- ## License
290
-
291
- MIT
292
-
293
- ## Contributing
294
-
295
- Contributions are welcome! Please ensure:
296
-
297
- - Tests pass: `yarn workspace @puzzmo/sdk test`
298
- - Types are correct: `yarn workspace @puzzmo/sdk type-check`
299
- - Code is formatted: `yarn prettier --write packages/sdk`
300
-
301
- ## Support
302
-
303
- For issues and questions, please open an issue on the [GitHub repository](https://github.com/puzzmo-com/games/issues).