Add new PokiSDK methods

README.md

@@ -107,6 +107,44 @@ poki.runWhenInitialized((poki) => {
 })
 ```
 
+#### Extended SDK Surface
+
+The plugin now exposes most Poki SDK methods directly on
+`scene.plugins.get('poki')`, including ad helpers, user/auth helpers, share URL
+helpers, error reporting, playtest capture controls, and misc utility methods.
+
+The raw `PokiSDK.init(options)` method is intentionally **not** exposed on the
+plugin instance because Phaser already uses `plugin.init(data)` for plugin
+bootstrapping. The plugin continues to load and initialize the Poki SDK for you
+automatically.
+
+Async passthrough methods such as `getUser()`, `getToken()`, `login()`, and
+`shareableURL()` wait until the SDK initialization attempt finishes. If the SDK
+is unavailable, they reject with an error instead of hanging forever. Use
+`runWhenInitialized()` as the readiness gate. `getURLParam()` falls back to
+`window.location.search` before the SDK is ready, and `getLanguage()` returns
+an empty string until the SDK can answer.
+
+```javascript
+import { RewardedBreakSize } from '@poki/phaser-3'
+
+const poki = scene.plugins.get('poki')
+
+poki.runWhenInitialized(async (poki) => {
+  const rewarded = await poki.rewardedBreak({
+    onStart: () => {
+      console.log('Rewarded break started')
+    },
+    size: RewardedBreakSize.MEDIUM
+  })
+
+  if (rewarded) {
+    const shareUrl = await poki.shareableURL({ level: 3, score: 1200 })
+    console.log('Share URL:', shareUrl)
+  }
+})
+```
+
 
 ## Example
 

lib/index.d.ts

@@ -0,0 +1,119 @@
+import Phaser = require('phaser')
+
+export declare const EVENT_INITIALIZED: 'poki:initialized'
+
+export declare const RewardedBreakSize: {
+  readonly SMALL: 'small'
+  readonly MEDIUM: 'medium'
+  readonly LARGE: 'large'
+}
+
+export type RewardedBreakSize = typeof RewardedBreakSize[keyof typeof RewardedBreakSize]
+
+export interface InitOptions {
+  debug?: boolean
+  logging?: boolean
+}
+
+export interface User {
+  username: string
+  avatarUrl: string
+}
+
+export interface RewardedBreakParams {
+  onStart?: () => void
+  size?: RewardedBreakSize
+}
+
+export interface PokiPluginConfig {
+  loadingSceneKey?: string
+  gameplaySceneKey?: string
+  autoCommercialBreak?: boolean
+}
+
+export interface PokiSDKGlobal {
+  init: (options?: InitOptions) => Promise<void>
+  rewardedBreak: (onStartOrParams?: (() => void) | RewardedBreakParams) => Promise<boolean>
+  commercialBreak: (onStart?: () => void) => Promise<void>
+  displayAd: (
+    container: HTMLElement,
+    size?: string,
+    onCanDestroy?: () => void,
+    onDisplayRendered?: (isEmpty: boolean) => void
+  ) => void
+  destroyAd: (container: HTMLElement) => void
+  shareableURL: (params?: object) => Promise<string>
+  getURLParam: (key: string) => string
+  getLanguage: () => string
+  getUser: () => Promise<User>
+  getToken: () => Promise<string>
+  login: () => Promise<void>
+  captureError: (error: string | Error) => void
+  gameLoadingStart: () => void
+  gameLoadingFinished: () => void
+  gameplayStart: () => void
+  gameplayStop: () => void
+  setDebug: (toggle: boolean) => void
+  setLogging: (toggle: boolean) => void
+  enableEventTracking: (cmpIndex: number | undefined) => void
+  openExternalLink: (url: string) => void
+  playtestSetCanvas: (canvas: HTMLCanvasElement | HTMLCanvasElement[] | null) => void
+  playtestCaptureHtmlOnce: () => void
+  playtestCaptureHtmlForce: () => void
+  playtestCaptureHtmlOn: () => void
+  playtestCaptureHtmlOff: () => void
+  movePill: (topPercent: number, topPx: number) => void
+  measure: (category: string, what: string, action: string) => void
+}
+
+export declare class PokiPlugin extends Phaser.Plugins.BasePlugin {
+  sdk?: PokiSDKGlobal
+  initialized: boolean
+  hasAdblock: boolean
+
+  init(config?: PokiPluginConfig): void
+  runWhenInitialized(callback: (poki: PokiPlugin) => void): void
+  start(): void
+  stop(): void
+
+  gameLoadingStart(): void
+  gameLoadingFinished(): void
+  gameplayStart(): void
+  gameplayStop(): void
+
+  commercialBreak(onStart?: () => void): Promise<void>
+  rewardedBreak(onStartOrParams?: (() => void) | RewardedBreakParams): Promise<boolean>
+
+  displayAd(
+    container: HTMLElement,
+    size?: string,
+    onCanDestroy?: () => void,
+    onDisplayRendered?: (isEmpty: boolean) => void
+  ): void
+  destroyAd(container: HTMLElement): void
+
+  shareableURL(params?: object): Promise<string>
+  getURLParam(key: string): string
+  getLanguage(): string
+  getUser(): Promise<User>
+  getToken(): Promise<string>
+  login(): Promise<void>
+  captureError(error: string | Error): void
+  setDebug(toggle: boolean): void
+  setLogging(toggle: boolean): void
+  enableEventTracking(cmpIndex: number | undefined): void
+  openExternalLink(url: string): void
+  playtestSetCanvas(canvas: HTMLCanvasElement | HTMLCanvasElement[] | null): void
+  playtestCaptureHtmlOnce(): void
+  playtestCaptureHtmlForce(): void
+  playtestCaptureHtmlOn(): void
+  playtestCaptureHtmlOff(): void
+  movePill(topPercent: number, topPx: number): void
+  measure(category: string, what: string, action: string): void
+}
+
+declare global {
+  interface Window {
+    PokiSDK?: PokiSDKGlobal
+  }
+}