@rocketman-streamkit/types 1.0.5 → 1.0.7

package/README.md

@@ -14,7 +14,7 @@ API reference, manifest format, permissions, and addon categories are published
 
 **[github.com/RocketMan-StreamKit/types](https://github.com/RocketMan-StreamKit/types)**
 
-Open the branch that matches your target app version (for example `1.0.5`) and start from [`index.md`](https://github.com/RocketMan-StreamKit/types/blob/1.0.5/index.md).
+Open the branch that matches your target app version (for example `1.0.7`) and start from [`index.md`](https://github.com/RocketMan-StreamKit/types/blob/1.0.7/index.md).
 
 This npm package provides **TypeScript typings only**; the docs repo is the full written guide.
 

package/addon.d.ts

@@ -103,6 +103,60 @@ declare global {
     sourceAddonId?: string;
   };
 
+  type OverlayTriggerType = | 'donation'
+    | 'subscribe'
+    | 'subgift'
+    | 'follow'
+    | 'custom';
+
+  type OverlayEventTrigger = {
+    type: OverlayTriggerType;
+    key?: string;
+    value?: string | number | boolean;
+  };
+
+  /**
+   * Currency code key from the built-in exchange rates table.
+   */
+  type CurrencyCode = string;
+
+  type DashboardRecordType = | 'donation'
+    | 'subscribe'
+    | 'follow'
+    | 'custom'
+    | 'timer';
+
+  type DashboardRecordValue = {
+    id: string;
+    type: DashboardRecordType;
+    amount?: [number, CurrencyCode];
+    platform: string;
+    message?: DashboardLocalizedString;
+    from?: string;
+    attach?: { type: string; value: string }[];
+  };
+
+  /**
+   * Payload delivered to addons subscribed via `dashboard.onRecord`.
+   */
+  type DashboardRecordIncomingPayload = {
+    id: string;
+    created: number;
+    updated: number;
+    record: DashboardRecordValue;
+    user?: {
+      id: string;
+      name: string;
+      avatar: string;
+      platform: string;
+      color?: string;
+      icons?: string[];
+    };
+    sourceAddonId?: string;
+    /** Trigger entries used for overlay/sound/hotkey/timer matching. */
+    triggers?: OverlayEventTrigger[];
+  };
+
   type AddonConfigFieldType = | 'text'
     | 'color'
     | 'number'
@@ -350,6 +404,19 @@ declare global {
        * @requires AddonsPermission.NOTIFY
        */
       Send: (payload: { id?: string | undefined; type?: "error" | "success" | "info" | "warning" | undefined; title?: DashboardLocalizedString | undefined; message: DashboardLocalizedString; temp?: boolean | undefined; }) => void;
+      /**
+       * Removes a notification previously created by this addon.
+      Notifications from other addons or the main process are ignored.
+       * @requires AddonsPermission.NOTIFY
+       * @param id Notification record id (same value passed to `Send`).
+       * @example notify.Send({
+        id: `${data.id}_status`,
+        type: 'success',
+        message: { en: 'Connected' },
+      });
+      notify.Remove(`${data.id}_status`);
+       */
+      Remove: (id: string) => void;
     };
     /**
      * Permission helpers for the running addon instance.
@@ -382,9 +449,28 @@ declare global {
     /**
      * In-addon event bus. Used mainly to handle HTTP endpoint callbacks registered via `network.endpoints.create`.
     Handlers run in the integration worker when the main process forwards `customEvent` messages.
+    
+    **Built-in events (main process → addon)**
+    
+    | Event | When | Payload |
+    | --- | --- | --- |
+    | `overlayTriggerValue:{provider}:list\|create\|release` | Dynamic trigger value UI in settings | See `registerTriggers` dynamic contract |
+    | `triggers:applied-changed` | After settings save when trigger bindings for this addon changed | `{ previous, current }` grouped by system (`overlay`, `timer`, `game`, `gameInput`, `sounds`, `hotkeys`) |
+    | `gameInputTrigger` | Matching dashboard event for a game input rule | `{ actionId, trigger, record, user }` |
      * @example events.On('onDonation', payload => {
       console.log('Donation', payload.body);
       return { ok: true };
+    });
+     * @example // React when saved trigger bindings change (e.g. clear internal caches)
+    events.On('triggers:applied-changed', ({ previous, current }) => {
+      const removed = (previous.overlay || []).filter(
+        item => !(current.overlay || []).some(
+          next => next.targetId === item.targetId && next.trigger.value === item.trigger.value
+        )
+      );
+      if (removed.length) {
+        console.log('Overlay rules removed', removed);
+      }
     });
      */
     var events: {
@@ -849,11 +935,20 @@ declare global {
       
       **Dynamic provider contract**
       
-      - `overlayTriggerValue:{provider}:list` → `{ success, items?: [{ id, label, meta? }] }`
-      - `overlayTriggerValue:{provider}:create` → `{ success, valueId?, label?, meta? }`
+      - `overlayTriggerValue:{provider}:list` → `{ success, items?, message?, notify? }`
+      - `overlayTriggerValue:{provider}:create` → `{ success, valueId?, label?, meta?, message?, notify? }`
       (payload includes `title`, `overlayId`, `context` from `requireValue`)
-      - `overlayTriggerValue:{provider}:release` → `{ success }` (payload: `valueId`;
+      - `overlayTriggerValue:{provider}:release` → `{ success, message?, notify? }` (payload: `valueId`;
       called on settings save when the value is no longer referenced)
+      
+      Optional `notify` shows a modal in settings (`variant`: `success` | `error` | `info`; `title?`, `message`).
+      
+      **Trigger bindings after save**
+      
+      When the user saves settings and bindings for this addon change, the main process fires
+      `triggers:applied-changed` with `{ previous, current }`. Each side groups rules by consumer
+      system: `overlay`, `timer`, `game` (as event source), `gameInput` (game addons as target),
+      `sounds`, `hotkeys`. Omitted groups mean no rules in that system.
        * @example // Follow — no value field
       await dashboard.registerTriggers([
         { type: 'follow', label: { en: 'New follower', ru: 'Новый фолловер' } },
@@ -916,9 +1011,15 @@ declare global {
           },
         },
       ]);
-      events.On('overlayTriggerValue:rewards:list', async () => ({
+      events.On('overlayTriggerValue:rewards:create', async ({ title, context }) => ({
         success: true,
-        items: [{ id: 'abc', label: 'My reward', meta: '100' }],
+        valueId: 'abc',
+        label: title,
+        notify: {
+          variant: 'success',
+          title: { en: 'Reward created', ru: 'Награда создана' },
+          message: { en: `Cost: ${context?.cost}`, ru: `Стоимость: ${context?.cost}` },
+        },
       }));
        * @example // Pass matching trigger when pushing dashboard events
       await dashboard.addRecord(
@@ -984,6 +1085,24 @@ declare global {
        * @requires AddonsPermission.DASHBOARD_CHAT_INCOMING
        */
       offChatMessage: () => Promise<unknown>;
+      /**
+       * Subscribes to new event records shown in the latest-events dashboard widget.
+      The handler receives the stored record (including system `attach` entries
+      for matched overlays, sounds, hotkeys, and timers), resolved user info,
+      trigger entries used for matching, and the source addon id (if any).
+      Unlike chat incoming, the source addon also receives its own records so it
+      can inspect match results after `dashboard.addRecord`.
+       * @requires AddonsPermission.DASHBOARD_EVENTS_INCOMING
+       * @example dashboard.onRecord(payload => {
+        console.log(payload.record.type, payload.record.attach, payload.sourceAddonId);
+      });
+       */
+      onRecord: (handler: (payload: DashboardRecordIncomingPayload) => void | Promise<void>) => Promise<unknown>;
+      /**
+       * Unsubscribes from incoming dashboard event records.
+       * @requires AddonsPermission.DASHBOARD_EVENTS_INCOMING
+       */
+      offRecord: () => Promise<unknown>;
     };
     /**
      * Game integration API for `manifest.type: "game"` addons.
@@ -1144,6 +1263,10 @@ declare global {
    * Receive new chat messages from the chat dashboard window
    */
     | 'DASHBOARD_CHAT_INCOMING'
+  /**
+   * Receive new event records from the latest-events dashboard widget
+   */
+    | 'DASHBOARD_EVENTS_INCOMING'
   /**
    * Create Socket.IO namespaces for addon web pages and external clients
    */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rocketman-streamkit/types",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "TypeScript declarations for the StreamKit+ integration addon sandbox API",
   "types": "addon.d.ts",
   "files": [