@open-pets/plugin-sdk 2.1.1

package/README.md

@@ -0,0 +1,42 @@
+# @open-pets/plugin-sdk
+
+Type definitions for building [OpenPets](https://openpets.dev) desktop pet plugins.
+
+This package is **types only**. There is no runtime to import — the OpenPets
+desktop app injects the `OpenPetsPlugin` global into your plugin's sandbox and
+passes your `start(ctx)` handler the SDK. Installing this package gives your
+editor autocomplete and type-checking; it never ships in your plugin.
+
+## Install
+
+```bash
+npm i -D @open-pets/plugin-sdk
+```
+
+## Use
+
+A plugin is a single browser-style JavaScript file. Reference the types for
+IntelliSense:
+
+```js
+/// <reference types="@open-pets/plugin-sdk" />
+
+OpenPetsPlugin.register({
+  async start(ctx) {
+    await ctx.pet.speak("Hello!")
+    await ctx.pet.react("waving")
+  },
+})
+```
+
+Or, in TypeScript, import the contract directly:
+
+```ts
+import type { OpenPetsContext, OpenPetsPluginDefinition } from "@open-pets/plugin-sdk"
+```
+
+## Docs
+
+- SDK guide: https://openpets.dev/sdk
+- Full reference: https://openpets.dev/docs/plugin-sdk
+- Example plugins: https://github.com/alvinunreal/openpets/tree/main/plugins/official

package/dist/check-plugin-sdk.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Contract test for @open-pets/plugin-sdk.
+ *
+ * This file does double duty: it only compiles if the exported types match the
+ * real SDK surface, and at runtime it exercises a sample plugin against a mock
+ * context. The `createMockContext` helper below is the recommended pattern for
+ * unit-testing a plugin's `start` handler without the desktop app.
+ */
+import type { OpenPetsContext, OpenPetsStatus } from "./index.js";
+interface MockCalls {
+    speak: string[];
+    react: string[];
+    status: OpenPetsStatus[];
+    storage: Map<string, unknown>;
+    schedules: Map<string, () => void | Promise<void>>;
+    commands: Map<string, (values?: Record<string, unknown>) => void | Promise<void>>;
+}
+/** Build a recording {@link OpenPetsContext} for tests. Copy this into your plugin's tests. */
+export declare function createMockContext(config?: Record<string, unknown>): {
+    ctx: OpenPetsContext;
+    calls: MockCalls;
+};
+export {};
+//# sourceMappingURL=check-plugin-sdk.d.ts.map

package/dist/check-plugin-sdk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-plugin-sdk.d.ts","sourceRoot":"","sources":["../src/check-plugin-sdk.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EACV,eAAe,EAEf,cAAc,EACf,MAAM,YAAY,CAAC;AAkBpB,UAAU,SAAS;IACjB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACnD,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;CACnF;AAED,+FAA+F;AAC/F,wBAAgB,iBAAiB,CAAC,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG;IACvE,GAAG,EAAE,eAAe,CAAC;IACrB,KAAK,EAAE,SAAS,CAAC;CAClB,CAoDA"}

package/dist/check-plugin-sdk.js

@@ -0,0 +1,97 @@
+const assert = {
+    ok(value, message) {
+        if (!value)
+            throw new Error(message ?? "Assertion failed.");
+    },
+    equal(actual, expected, message) {
+        if (actual !== expected)
+            throw new Error(message ?? `Expected ${String(expected)}, got ${String(actual)}.`);
+    },
+    deepEqual(actual, expected, message) {
+        if (JSON.stringify(actual) !== JSON.stringify(expected)) {
+            throw new Error(message ?? `Expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}.`);
+        }
+    },
+};
+/** Build a recording {@link OpenPetsContext} for tests. Copy this into your plugin's tests. */
+export function createMockContext(config = {}) {
+    const calls = {
+        speak: [],
+        react: [],
+        status: [],
+        storage: new Map(),
+        schedules: new Map(),
+        commands: new Map(),
+    };
+    const ctx = {
+        pet: {
+            speak: async (message) => void calls.speak.push(message),
+            react: async (reaction) => void calls.react.push(reaction),
+            moveBy: async () => undefined,
+            wander: async () => undefined,
+            moveToHome: async () => undefined,
+        },
+        schedule: {
+            once: async (id, _delayMs, handler) => void calls.schedules.set(id, handler),
+            every: async (id, _intervalMs, handler) => void calls.schedules.set(id, handler),
+            daily: async (id, _spec, handler) => void calls.schedules.set(id, handler),
+            cancel: async (id) => void calls.schedules.delete(id),
+            cancelAll: async () => void calls.schedules.clear(),
+        },
+        storage: {
+            get: async (key) => calls.storage.get(key),
+            set: async (key, value) => void calls.storage.set(key, value),
+            delete: async (key) => void calls.storage.delete(key),
+        },
+        config: {
+            get: async () => config,
+            onChange: () => () => undefined,
+        },
+        commands: {
+            register: async (command, handler) => void calls.commands.set(command.id, handler),
+            unregister: async (id) => void calls.commands.delete(id),
+        },
+        status: {
+            set: async (status) => void calls.status.push(status),
+            clear: async () => undefined,
+        },
+        http: {
+            fetch: async () => ({ status: 200, ok: true, headers: {}, text: "" }),
+        },
+        log: {
+            debug: async () => undefined,
+            info: async () => undefined,
+            warn: async () => undefined,
+            error: async () => undefined,
+        },
+    };
+    return { ctx, calls };
+}
+// A representative plugin, typed against the public contract.
+const plugin = {
+    async start(ctx) {
+        await ctx.status.set({ text: "Ready", tone: "info" });
+        await ctx.pet.speak("Hello!");
+        await ctx.pet.react("waving");
+        await ctx.schedule.every("tick", 60_000, async () => {
+            await ctx.storage.set("lastTick", "now");
+        });
+        await ctx.commands.register({ id: "greet", title: "Greet" }, async () => {
+            await ctx.pet.speak("Hi again!");
+        });
+    },
+};
+const { ctx, calls } = createMockContext();
+await plugin.start(ctx);
+assert.deepEqual(calls.speak, ["Hello!"]);
+assert.deepEqual(calls.react, ["waving"]);
+assert.equal(calls.status.length, 1);
+assert.ok(calls.schedules.has("tick"));
+assert.ok(calls.commands.has("greet"));
+// Registered callbacks behave as expected.
+await calls.schedules.get("tick")?.();
+assert.equal(calls.storage.get("lastTick"), "now");
+await calls.commands.get("greet")?.();
+assert.deepEqual(calls.speak, ["Hello!", "Hi again!"]);
+console.log("Plugin SDK contract tests passed.");
+//# sourceMappingURL=check-plugin-sdk.js.map

package/dist/check-plugin-sdk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-plugin-sdk.js","sourceRoot":"","sources":["../src/check-plugin-sdk.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Type definitions for OpenPets plugins.
+ *
+ * This package ships **types only**. There is no runtime to import — the
+ * OpenPets desktop app injects the `OpenPetsPlugin` global into the plugin
+ * sandbox and passes your `start(ctx)` handler an {@link OpenPetsContext}.
+ *
+ * In a plain JavaScript plugin, reference these types for editor IntelliSense:
+ *
+ * ```js
+ * /// <reference types="@open-pets/plugin-sdk" />
+ *
+ * OpenPetsPlugin.register({
+ *   async start(ctx) {
+ *     await ctx.pet.speak("Hello!")
+ *   },
+ * })
+ * ```
+ *
+ * @packageDocumentation
+ */
+/** Capabilities a plugin can request in its manifest's `permissions` array. */
+export type OpenPetsPermission = "pet:speak" | "pet:reaction" | "pet:move" | "schedule" | "storage" | "status" | "commands" | "network";
+/**
+ * Reaction name passed to {@link OpenPetsPetApi.react}. Common values are
+ * listed for autocomplete; any string the host accepts is allowed.
+ */
+export type OpenPetsReaction = "idle" | "thinking" | "working" | "editing" | "running" | "testing" | "waiting" | "waving" | "success" | "error" | "celebrating" | (string & {});
+/** Tone shown alongside a plugin's status line in the Plugins window. */
+export type OpenPetsStatusTone = "info" | "success" | "warning" | "error";
+/** A status line, either a bare string or text plus a {@link OpenPetsStatusTone}. */
+export type OpenPetsStatus = string | {
+    text: string;
+    tone?: OpenPetsStatusTone;
+};
+/** A single field in a command's input form. */
+export interface OpenPetsCommandFormField {
+    /** Identifier for this field; the submitted value is keyed by it. */
+    id: string;
+    type: "text" | "textarea" | "number";
+    label: string;
+    default?: string | number;
+    /** Minimum value (number fields only). */
+    min?: number;
+    /** Maximum value (number fields only). */
+    max?: number;
+    /** Maximum length (text/textarea fields only). */
+    maxLength?: number;
+    required?: boolean;
+}
+/** Optional input form attached to a command. */
+export interface OpenPetsCommandForm {
+    fields: OpenPetsCommandFormField[];
+    submitLabel?: string;
+}
+/** A right-click pet action registered via {@link OpenPetsCommandsApi.register}. */
+export interface OpenPetsCommand {
+    /** Short, stable id (`[A-Za-z0-9._:-]`, 1–64 chars). */
+    id: string;
+    title: string;
+    description?: string;
+    /** When present, the host opens a dialog and passes validated values to the handler. */
+    form?: OpenPetsCommandForm;
+}
+/** A daily schedule time, optionally restricted to specific weekdays. */
+export type OpenPetsDailySpec = string | {
+    time: string;
+    days?: number[];
+};
+/** Options for {@link OpenPetsPetApi.moveBy}. */
+export interface OpenPetsMoveByOptions {
+    x: number;
+    y: number;
+    durationMs?: number;
+}
+/** Options for {@link OpenPetsPetApi.wander}. */
+export interface OpenPetsWanderOptions {
+    distance?: number;
+    durationMs?: number;
+}
+/** Options for {@link OpenPetsHttpApi.fetch}. GET-only by design. */
+export interface OpenPetsHttpOptions {
+    method?: "GET";
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+}
+/** Response returned by {@link OpenPetsHttpApi.fetch}. */
+export interface OpenPetsHttpResponse {
+    status: number;
+    ok: boolean;
+    headers: Record<string, string>;
+    text: string;
+    json?: unknown;
+}
+/** Make the default pet speak, react, or move. */
+export interface OpenPetsPetApi {
+    /** Requires `pet:speak`. Messages are capped at 140 chars and content-filtered. */
+    speak(message: string): Promise<void>;
+    /** Requires `pet:reaction`. */
+    react(reaction: OpenPetsReaction): Promise<void>;
+    /** Requires `pet:move`. Movement is bounded to the work area. */
+    moveBy(options: OpenPetsMoveByOptions): Promise<void>;
+    /** Requires `pet:move`. */
+    wander(options?: OpenPetsWanderOptions): Promise<void>;
+    /** Requires `pet:move`. */
+    moveToHome(): Promise<void>;
+}
+/** A callback fired by a schedule. */
+export type OpenPetsScheduleHandler = () => void | Promise<void>;
+/** Run callbacks once, on an interval, or daily. Requires `schedule`. */
+export interface OpenPetsScheduleApi {
+    /** Fire once after `delayMs`. */
+    once(id: string, delayMs: number, handler: OpenPetsScheduleHandler): Promise<void>;
+    /** Fire repeatedly every `intervalMs` (a minimum interval is enforced). */
+    every(id: string, intervalMs: number, handler: OpenPetsScheduleHandler): Promise<void>;
+    /** Fire daily at `HH:mm`, optionally only on the given weekdays (0–6, Sunday = 0). */
+    daily(id: string, spec: OpenPetsDailySpec, handler: OpenPetsScheduleHandler): Promise<void>;
+    cancel(id: string): Promise<void>;
+    cancelAll(): Promise<void>;
+}
+/** Persist small per-plugin state across restarts. Requires `storage`. */
+export interface OpenPetsStorageApi {
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set(key: string, value: unknown): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+/** Read user configuration and react to changes. Always available. */
+export interface OpenPetsConfigApi {
+    get<T = Record<string, unknown>>(): Promise<T>;
+    /** Subscribe to config changes. Returns an unsubscribe function. */
+    onChange<T = Record<string, unknown>>(handler: (config: T) => void | Promise<void>): () => void;
+}
+/** Handler invoked when a command runs, with validated form values when present. */
+export type OpenPetsCommandHandler = (values?: Record<string, unknown>) => void | Promise<void>;
+/** Register right-click pet actions. Requires `commands`. */
+export interface OpenPetsCommandsApi {
+    register(command: OpenPetsCommand, handler: OpenPetsCommandHandler): Promise<void>;
+    unregister(id: string): Promise<void>;
+}
+/** Show a short status line in the Plugins window. Requires `status`. */
+export interface OpenPetsStatusApi {
+    set(status: OpenPetsStatus): Promise<void>;
+    clear(): Promise<void>;
+}
+/** Fetch approved HTTPS hosts through the OpenPets proxy. Requires `network`. */
+export interface OpenPetsHttpApi {
+    fetch(url: string, options?: OpenPetsHttpOptions): Promise<OpenPetsHttpResponse>;
+}
+/** Write to the desktop app log under the `plugin` scope. Always available. */
+export interface OpenPetsLogApi {
+    debug(...args: unknown[]): Promise<void>;
+    info(...args: unknown[]): Promise<void>;
+    warn(...args: unknown[]): Promise<void>;
+    error(...args: unknown[]): Promise<void>;
+}
+/**
+ * The capability object passed to {@link OpenPetsPluginDefinition.start}.
+ *
+ * Each namespace is only functional when the matching permission is approved
+ * in the manifest. `config` and `log` are always available.
+ */
+export interface OpenPetsContext {
+    pet: OpenPetsPetApi;
+    schedule: OpenPetsScheduleApi;
+    storage: OpenPetsStorageApi;
+    config: OpenPetsConfigApi;
+    commands: OpenPetsCommandsApi;
+    status: OpenPetsStatusApi;
+    http: OpenPetsHttpApi;
+    log: OpenPetsLogApi;
+}
+/** The object you pass to {@link OpenPetsPluginApi.register}. */
+export interface OpenPetsPluginDefinition {
+    /** Runs when the plugin is enabled or the app launches. */
+    start(ctx: OpenPetsContext): void | Promise<void>;
+    /** Optional cleanup. Schedules and commands are torn down for you. */
+    stop?(ctx?: OpenPetsContext): void | Promise<void>;
+}
+/** The injected global used to register a plugin. */
+export interface OpenPetsPluginApi {
+    register(definition: OpenPetsPluginDefinition): void;
+}
+/**
+ * The signature of an exported `register` function — the testable plugin
+ * style used by the official plugins:
+ *
+ * ```ts
+ * export function register(OpenPetsPlugin: OpenPetsPluginApi) {
+ *   OpenPetsPlugin.register({ async start(ctx) {} })
+ * }
+ * ```
+ */
+export type OpenPetsPluginEntry = (api: OpenPetsPluginApi) => void | Promise<void>;
+/** Field types supported by `configSchema` in the manifest. */
+export type OpenPetsConfigFieldType = "text" | "textarea" | "number" | "boolean" | "select" | "time" | "list" | "multiselect";
+declare global {
+    /**
+     * Injected by the OpenPets runtime. Call once at the top level of your
+     * entry file to register your plugin.
+     */
+    const OpenPetsPlugin: OpenPetsPluginApi;
+}
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,+EAA+E;AAC/E,MAAM,MAAM,kBAAkB,GAC1B,WAAW,GACX,cAAc,GACd,UAAU,GACV,UAAU,GACV,SAAS,GACT,QAAQ,GACR,UAAU,GACV,SAAS,CAAC;AAEd;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GACxB,MAAM,GACN,UAAU,GACV,SAAS,GACT,SAAS,GACT,SAAS,GACT,SAAS,GACT,SAAS,GACT,QAAQ,GACR,SAAS,GACT,OAAO,GACP,aAAa,GAEb,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAElB,yEAAyE;AACzE,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;AAE1E,qFAAqF;AACrF,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,kBAAkB,CAAA;CAAE,CAAC;AAElF,gDAAgD;AAChD,MAAM,WAAW,wBAAwB;IACvC,qEAAqE;IACrE,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,QAAQ,CAAC;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1B,0CAA0C;IAC1C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,iDAAiD;AACjD,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,wBAAwB,EAAE,CAAC;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,oFAAoF;AACpF,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wFAAwF;IACxF,IAAI,CAAC,EAAE,mBAAmB,CAAC;CAC5B;AAED,yEAAyE;AACzE,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAE3E,iDAAiD;AACjD,MAAM,WAAW,qBAAqB;IACpC,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,iDAAiD;AACjD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qEAAqE;AACrE,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,KAAK,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,0DAA0D;AAC1D,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,kDAAkD;AAClD,MAAM,WAAW,cAAc;IAC7B,mFAAmF;IACnF,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,+BAA+B;IAC/B,KAAK,CAAC,QAAQ,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,iEAAiE;IACjE,MAAM,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,2BAA2B;IAC3B,MAAM,CAAC,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD,2BAA2B;IAC3B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B;AAED,sCAAsC;AACtC,MAAM,MAAM,uBAAuB,GAAG,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAEjE,yEAAyE;AACzE,MAAM,WAAW,mBAAmB;IAClC,iCAAiC;IACjC,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnF,2EAA2E;IAC3E,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvF,sFAAsF;IACtF,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5F,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AAED,0EAA0E;AAC1E,MAAM,WAAW,kBAAkB;IACjC,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IACtD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AAED,sEAAsE;AACtE,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAC/C,oEAAoE;IACpE,QAAQ,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,MAAM,IAAI,CAAC;CACjG;AAED,oFAAoF;AACpF,MAAM,MAAM,sBAAsB,GAAG,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAEhG,6DAA6D;AAC7D,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,eAAe,EAAE,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnF,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAED,yEAAyE;AACzE,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,iFAAiF;AACjF,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;CAClF;AAED,+EAA+E;AAC/E,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1C;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,cAAc,CAAC;IACpB,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,OAAO,EAAE,kBAAkB,CAAC;IAC5B,MAAM,EAAE,iBAAiB,CAAC;IAC1B,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,MAAM,EAAE,iBAAiB,CAAC;IAC1B,IAAI,EAAE,eAAe,CAAC;IACtB,GAAG,EAAE,cAAc,CAAC;CACrB;AAED,iEAAiE;AACjE,MAAM,WAAW,wBAAwB;IACvC,2DAA2D;IAC3D,KAAK,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,sEAAsE;IACtE,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,eAAe,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpD;AAED,qDAAqD;AACrD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,UAAU,EAAE,wBAAwB,GAAG,IAAI,CAAC;CACtD;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,GAAG,EAAE,iBAAiB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnF,+DAA+D;AAC/D,MAAM,MAAM,uBAAuB,GAC/B,MAAM,GACN,UAAU,GACV,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,MAAM,GACN,MAAM,GACN,aAAa,CAAC;AAElB,OAAO,CAAC,MAAM,CAAC;IACb;;;OAGG;IACH,MAAM,cAAc,EAAE,iBAAiB,CAAC;CACzC;AAED,OAAO,EAAE,CAAC"}

package/dist/index.js

@@ -0,0 +1,23 @@
+/**
+ * Type definitions for OpenPets plugins.
+ *
+ * This package ships **types only**. There is no runtime to import — the
+ * OpenPets desktop app injects the `OpenPetsPlugin` global into the plugin
+ * sandbox and passes your `start(ctx)` handler an {@link OpenPetsContext}.
+ *
+ * In a plain JavaScript plugin, reference these types for editor IntelliSense:
+ *
+ * ```js
+ * /// <reference types="@open-pets/plugin-sdk" />
+ *
+ * OpenPetsPlugin.register({
+ *   async start(ctx) {
+ *     await ctx.pet.speak("Hello!")
+ *   },
+ * })
+ * ```
+ *
+ * @packageDocumentation
+ */
+export {};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG"}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@open-pets/plugin-sdk",
+  "version": "2.1.1",
+  "description": "Type definitions for building OpenPets desktop pet plugins. Types only — the OpenPets runtime injects the SDK implementation at load time.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alvinunreal/openpets.git",
+    "directory": "packages/sdk"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "openpets",
+    "plugin",
+    "sdk",
+    "types",
+    "desktop-pet"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "test": "node dist/check-plugin-sdk.js",
+    "check": "pnpm typecheck && pnpm build && pnpm test",
+    "typecheck": "tsc --noEmit",
+    "build": "tsc"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3"
+  }
+}