@snaptrude/plugin-core 0.2.4 → 0.2.5

package/dist/api/units/index.d.ts

@@ -0,0 +1,163 @@
+import * as z from "zod";
+import { PluginApiReturn } from "../../types";
+/**
+ * Unit conversion between real-world units and Snaptrude's internal
+ * (Babylon) coordinate system.
+ *
+ * Snaptrude uses an internal unit system (Babylon units) for all
+ * coordinates and dimensions. Use these methods to convert between
+ * real-world measurements and Babylon units.
+ *
+ * Accessed via `snaptrude.units`.
+ */
+export declare abstract class PluginUnitsApi {
+    constructor();
+    /**
+     * Convert a value from a real-world unit to Snaptrude's internal (Babylon) units.
+     *
+     * Use this when you have a measurement in real-world units (e.g. meters, feet)
+     * and need to convert it to the coordinate system used by Snaptrude internally.
+     *
+     * @param args - An object containing:
+     *   - {@linkcode PluginUnitsConvertFromArgs.unit args.unit} — The source unit
+     *     to convert from. See {@linkcode PUnitType} for supported values.
+     *   - {@linkcode PluginUnitsConvertFromArgs.value args.value} — The numeric
+     *     value in the source unit
+     *   - {@linkcode PluginUnitsConvertFromArgs.degree args.degree} — (Optional)
+     *     Degree of the unit: 1 for length, 2 for area, 3 for volume. Defaults to 1
+     * @returns A {@linkcode PluginUnitsConvertFromResult} containing the converted
+     *   `value` in Babylon units
+     *
+     * # Example
+     * ```ts
+     * // Convert 5 meters to Babylon units for use in API calls
+     * const result = await snaptrude.units.convertFrom({ unit: "meters", value: 5 })
+     * const { spaceId } = await snaptrude.entity.space.createRectangular({
+     *   position: snaptrude.core.math.vec3.new(0, 0, 0),
+     *   dimensions: { width: result.value, height: result.value, depth: result.value },
+     * })
+     * ```
+     */
+    abstract convertFrom(args: PluginUnitsConvertFromArgs): PluginApiReturn<PluginUnitsConvertFromResult>;
+    /**
+     * Convert a value from Snaptrude's internal (Babylon) units to a real-world unit.
+     *
+     * Use this when you have a value in Snaptrude's internal coordinate system
+     * and need to express it in real-world units (e.g. meters, feet).
+     *
+     * @param args - An object containing:
+     *   - {@linkcode PluginUnitsConvertToArgs.unit args.unit} — The target unit
+     *     to convert to. See {@linkcode PUnitType} for supported values.
+     *   - {@linkcode PluginUnitsConvertToArgs.value args.value} — The numeric
+     *     value in Babylon units
+     *   - {@linkcode PluginUnitsConvertToArgs.degree args.degree} — (Optional)
+     *     Degree of the unit: 1 for length, 2 for area, 3 for volume. Defaults to 1
+     * @returns A {@linkcode PluginUnitsConvertToResult} containing the converted
+     *   `value` in the target unit
+     *
+     * # Example
+     * ```ts
+     * // Get a space's area in square meters
+     * const info = await snaptrude.entity.space.get({
+     *   spaceId: "some-id",
+     *   properties: ["area"],
+     * })
+     * const areaInMeters = await snaptrude.units.convertTo({
+     *   unit: "meters",
+     *   value: info.area!,
+     *   degree: 2,
+     * })
+     * ```
+     */
+    abstract convertTo(args: PluginUnitsConvertToArgs): PluginApiReturn<PluginUnitsConvertToResult>;
+}
+/**
+ * Supported unit types for conversion.
+ *
+ * - `meters` — Metric meters
+ * - `feet-inches` — Imperial feet (1 foot = 12 inches)
+ * - `inches` — Imperial inches
+ * - `centimeters` — Metric centimeters
+ * - `millimeters` — Metric millimeters
+ * - `kilometers` — Metric kilometers
+ * - `miles` — Imperial miles
+ */
+export declare const PUnitType: z.ZodEnum<{
+    meters: "meters";
+    "feet-inches": "feet-inches";
+    inches: "inches";
+    centimeters: "centimeters";
+    millimeters: "millimeters";
+    kilometers: "kilometers";
+    miles: "miles";
+}>;
+export type PUnitType = z.infer<typeof PUnitType>;
+/**
+ * Arguments for {@linkcode PluginUnitsApi.convertFrom}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `unit` | {@linkcode PUnitType} | Source real-world unit |
+ * | `value` | `number` | Numeric value in the source unit |
+ * | `degree` | `1 \| 2 \| 3` | (Optional) Degree of the unit (e.g. 1 for length, 2 for area, 3 for volume). Defaults to 1 |
+ */
+export declare const PluginUnitsConvertFromArgs: z.ZodObject<{
+    unit: z.ZodEnum<{
+        meters: "meters";
+        "feet-inches": "feet-inches";
+        inches: "inches";
+        centimeters: "centimeters";
+        millimeters: "millimeters";
+        kilometers: "kilometers";
+        miles: "miles";
+    }>;
+    value: z.ZodNumber;
+    degree: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type PluginUnitsConvertFromArgs = z.infer<typeof PluginUnitsConvertFromArgs>;
+/**
+ * Result of {@linkcode PluginUnitsApi.convertFrom}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `value` | `number` | The converted value in Babylon units |
+ */
+export declare const PluginUnitsConvertFromResult: z.ZodObject<{
+    value: z.ZodNumber;
+}, z.core.$strip>;
+export type PluginUnitsConvertFromResult = z.infer<typeof PluginUnitsConvertFromResult>;
+/**
+ * Arguments for {@linkcode PluginUnitsApi.convertTo}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `unit` | {@linkcode PUnitType} | Target real-world unit |
+ * | `value` | `number` | Numeric value in Babylon units |
+ * | `degree` | `1 \| 2 \| 3` | (Optional) Degree of the unit (e.g. 1 for length, 2 for area, 3 for volume). Defaults to 1 |
+ */
+export declare const PluginUnitsConvertToArgs: z.ZodObject<{
+    unit: z.ZodEnum<{
+        meters: "meters";
+        "feet-inches": "feet-inches";
+        inches: "inches";
+        centimeters: "centimeters";
+        millimeters: "millimeters";
+        kilometers: "kilometers";
+        miles: "miles";
+    }>;
+    value: z.ZodNumber;
+    degree: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type PluginUnitsConvertToArgs = z.infer<typeof PluginUnitsConvertToArgs>;
+/**
+ * Result of {@linkcode PluginUnitsApi.convertTo}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `value` | `number` | The converted value in the target unit |
+ */
+export declare const PluginUnitsConvertToResult: z.ZodObject<{
+    value: z.ZodNumber;
+}, z.core.$strip>;
+export type PluginUnitsConvertToResult = z.infer<typeof PluginUnitsConvertToResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/api/units/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/units/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAE7C;;;;;;;;;GASG;AACH,8BAAsB,cAAc;;IAGlC;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;aACa,WAAW,CACzB,IAAI,EAAE,0BAA0B,GAC/B,eAAe,CAAC,4BAA4B,CAAC;IAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;aACa,SAAS,CACvB,IAAI,EAAE,wBAAwB,GAC7B,eAAe,CAAC,0BAA0B,CAAC;CAC/C;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS;;;;;;;;EAQpB,CAAA;AAEF,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAA;AAEjD;;;;;;;;GAQG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;iBAIrC,CAAA;AAEF,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAA;AAEnF;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B;;iBAEvC,CAAA;AAEF,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAA;AAEvF;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;iBAInC,CAAA;AAEF,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAA;AAE/E;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B;;iBAErC,CAAA;AAEF,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAA"}

package/dist/host-utils.d.ts

@@ -0,0 +1,41 @@
+import type { PluginApi } from "./api";
+/**
+ * UnionToIntersection is a type utility that converts a union type to an intersection type.
+ */
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+type Flatten<T> = {
+    [K in keyof T]: T[K];
+};
+type MethodArgs<F extends (...args: any[]) => any> = Parameters<F> extends [infer A] ? A : void;
+type MethodReturn<F extends (...args: any[]) => any> = Awaited<ReturnType<F>>;
+/**
+ * Recursively walks a type tree and produces a union of single-key Records
+ * for every leaf method, using dot-separated paths as keys.
+ */
+type ExtractMethodPaths<T, Prefix extends string = ""> = {
+    [K in keyof T & string]: T[K] extends (...args: any[]) => any ? Record<`${Prefix}${K}`, {
+        args: MethodArgs<T[K]>;
+        return: MethodReturn<T[K]>;
+    }> : T[K] extends object ? ExtractMethodPaths<T[K], `${Prefix}${K}.`> : never;
+}[keyof T & string];
+/**
+ * Maps every plugin API method path to its argument and return types.
+ * Automatically inferred from the PluginApi abstract class hierarchy.
+ */
+export type PluginApiMethodMap = Flatten<UnionToIntersection<ExtractMethodPaths<PluginApi>>>;
+export type PluginApiMethod = keyof PluginApiMethodMap;
+export type PluginApiCallPayload<M extends PluginApiMethod = PluginApiMethod> = PluginApiMethodMap[M]["args"] extends void ? {
+    method: M;
+    args?: void;
+} : {
+    method: M;
+    args: PluginApiMethodMap[M]["args"];
+};
+export type PluginApiCallResult<M extends PluginApiMethod> = PluginApiMethodMap[M]["return"];
+export type PluginApiCallWrappedResult<M extends PluginApiMethod> = {
+    success: boolean;
+    data?: PluginApiCallResult<M>;
+    error?: string;
+};
+export {};
+//# sourceMappingURL=host-utils.d.ts.map

package/dist/host-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-utils.d.ts","sourceRoot":"","sources":["../src/host-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC;;GAEG;AACH,KAAK,mBAAmB,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,GAAG,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,IAAI,GAAG,KAAK,CAAC,SAAS,CAC7E,CAAC,EAAE,MAAM,CAAC,KACP,IAAI,GACL,CAAC,GACD,KAAK,CAAA;AAET,KAAK,OAAO,CAAC,CAAC,IAAI;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAAE,CAAA;AAE1C,KAAK,UAAU,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,IAC/C,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,IAAI,CAAA;AAE5C,KAAK,YAAY,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAA;AAE7E;;;GAGG;AACH,KAAK,kBAAkB,CAAC,CAAC,EAAE,MAAM,SAAS,MAAM,GAAG,EAAE,IAAI;KACtD,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,GACzD,MAAM,CACJ,GAAG,MAAM,GAAG,CAAC,EAAE,EACf;QAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;KAAE,CACvD,GACD,CAAC,CAAC,CAAC,CAAC,SAAS,MAAM,GACjB,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,GAAG,CAAC,GAAG,CAAC,GAC1C,KAAK;CACZ,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,CAAA;AAInB;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,OAAO,CACtC,mBAAmB,CAAC,kBAAkB,CAAC,SAAS,CAAC,CAAC,CACnD,CAAA;AAED,MAAM,MAAM,eAAe,GAAG,MAAM,kBAAkB,CAAA;AAEtD,MAAM,MAAM,oBAAoB,CAAC,CAAC,SAAS,eAAe,GAAG,eAAe,IAC1E,kBAAkB,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,IAAI,GACtC;IAAE,MAAM,EAAE,CAAC,CAAC;IAAC,IAAI,CAAC,EAAE,IAAI,CAAA;CAAE,GAC1B;IAAE,MAAM,EAAE,CAAC,CAAC;IAAC,IAAI,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAA;CAAE,CAAA;AAExD,MAAM,MAAM,mBAAmB,CAAC,CAAC,SAAS,eAAe,IACvD,kBAAkB,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAA;AAEjC,MAAM,MAAM,0BAA0B,CAAC,CAAC,SAAS,eAAe,IAAI;IAClE,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,mBAAmB,CAAC,CAAC,CAAC,CAAC;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAA"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./api";
+export * from "./types";
+export * from "./host-utils";
+//# 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,cAAc,OAAO,CAAA;AACrB,cAAc,SAAS,CAAA;AACvB,cAAc,cAAc,CAAA"}

package/dist/types.d.ts

@@ -0,0 +1,16 @@
+/**
+ * A unique identifier for a component in the Snaptrude scene.
+ *
+ * Component IDs are returned by entity creation methods (e.g.
+ * {@linkcode PluginSpaceApi.createRectangular}) and can be used with
+ * query and transform methods throughout the API.
+ */
+export type ComponentId = string;
+/**
+ * Return type for a plugin API method.
+ *
+ * Methods that require a host round-trip return `Promise<T>`,
+ * while pure local computations may return `T` directly.
+ */
+export type PluginApiReturn<T> = Promise<T> | T;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAA;AAEhC;;;;;GAKG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snaptrude/plugin-core",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",