@apinteract/plugin-sdk 0.1.0-bootstrap.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 APInteract contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,25 @@
+# `@apinteract/plugin-sdk`
+
+Optional authoring helpers for APInteract plugins.
+
+```sh
+pnpm add --save-dev @apinteract/plugin-api @apinteract/plugin-sdk
+```
+
+Helpers are grouped by target and purpose:
+
+```ts
+import { parseJsonObject } from "@apinteract/plugin-sdk/backend/import";
+import { localize } from "@apinteract/plugin-sdk/frontend/localization";
+```
+
+The SDK is independently versioned from the plugin contract. Plugin builds
+must bundle SDK runtime helpers into their own `dist/` output; an installed
+plugin must not require this package at runtime.
+
+See the [plugin development guide](https://github.com/xirelogy/apinteract/blob/main/docs/plugins/README.md)
+for packaging and compatibility details.
+
+## License
+
+MIT

package/dist/backend/import.d.ts

@@ -0,0 +1,22 @@
+import type { ImportSource } from "@apinteract/plugin-api/backend";
+/** Represents an import-provider failure that the host may safely expose. */
+export declare class ImportProviderError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Reports whether an unknown JSON value is a non-array object. */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/** Narrows an unknown JSON array without exposing an any-valued result. */
+export declare function unknownArray(value: unknown): readonly unknown[];
+/** Parses one JSON import source and requires an object document root. */
+export declare function parseJsonObject(source: ImportSource): Record<string, unknown>;
+/** Reads a string value or returns the supplied fallback. */
+export declare function stringValue(value: unknown, fallback?: string): string;
+/** Converts a JSON-compatible example into one editable text value. */
+export declare function editableValue(value: unknown): string;
+/** Derives a bounded display name after removing one declared extension. */
+export declare function sourceStem(name: string, extensions: readonly string[]): string;
+/** Returns the UTF-8 byte length of one imported text value. */
+export declare function utf8Bytes(value: string): number;
+/** Returns an ISO timestamp only when the source contains a valid instant. */
+export declare function optionalTimestamp(value: unknown): string | null;

package/dist/backend/import.js

@@ -0,0 +1,71 @@
+/** Represents an import-provider failure that the host may safely expose. */
+export class ImportProviderError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+/** Reports whether an unknown JSON value is a non-array object. */
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Narrows an unknown JSON array without exposing an any-valued result. */
+export function unknownArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+/** Parses one JSON import source and requires an object document root. */
+export function parseJsonObject(source) {
+    let value;
+    try {
+        value = JSON.parse(source.text);
+    }
+    catch {
+        throw new ImportProviderError("import_json_invalid", `${source.name} does not contain valid JSON.`);
+    }
+    if (!isRecord(value)) {
+        throw new ImportProviderError("import_json_invalid", `${source.name} must contain a JSON object.`);
+    }
+    return value;
+}
+/** Reads a string value or returns the supplied fallback. */
+export function stringValue(value, fallback = "") {
+    return typeof value === "string" ? value : fallback;
+}
+/** Converts a JSON-compatible example into one editable text value. */
+export function editableValue(value) {
+    if (value === undefined || value === null)
+        return "";
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" || typeof value === "boolean") {
+        return String(value);
+    }
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return "";
+    }
+}
+/** Derives a bounded display name after removing one declared extension. */
+export function sourceStem(name, extensions) {
+    const withoutPath = name.split(/[\\/]/).at(-1) ?? name;
+    const extension = extensions.find((candidate) => withoutPath.toLowerCase().endsWith(candidate.toLowerCase()));
+    const stem = (extension === undefined
+        ? withoutPath
+        : withoutPath.slice(0, -extension.length)).trim();
+    return (stem || "Imported requests").slice(0, 200);
+}
+/** Returns the UTF-8 byte length of one imported text value. */
+export function utf8Bytes(value) {
+    return Buffer.byteLength(value, "utf8");
+}
+/** Returns an ISO timestamp only when the source contains a valid instant. */
+export function optionalTimestamp(value) {
+    if (typeof value !== "string")
+        return null;
+    const timestamp = Date.parse(value);
+    return Number.isFinite(timestamp) ? new Date(timestamp).toISOString() : null;
+}
+//# sourceMappingURL=import.js.map

package/dist/backend/import.js.map

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

package/dist/frontend/localization.d.ts

@@ -0,0 +1,2 @@
+/** Resolves package-owned text through exact locale, base language, and default fallbacks. */
+export declare function localize(fallback: string, translations: Readonly<Record<string, string>>, locale: string): string;

package/dist/frontend/localization.js

@@ -0,0 +1,5 @@
+/** Resolves package-owned text through exact locale, base language, and default fallbacks. */
+export function localize(fallback, translations, locale) {
+    return (translations[locale] ?? translations[locale.split("-")[0] ?? ""] ?? fallback);
+}
+//# sourceMappingURL=localization.js.map

package/dist/frontend/localization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"localization.js","sourceRoot":"","sources":["../../src/frontend/localization.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,MAAM,UAAU,QAAQ,CACtB,QAAgB,EAChB,YAA8C,EAC9C,MAAc;IAEd,OAAO,CACL,YAAY,CAAC,MAAM,CAAC,IAAI,YAAY,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,QAAQ,CAC7E,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@apinteract/plugin-sdk",
+  "version": "0.1.0-bootstrap.0",
+  "description": "Optional authoring helpers for developing APInteract plugins.",
+  "license": "MIT",
+  "homepage": "https://github.com/xirelogy/apinteract/tree/main/packages/plugin-sdk#readme",
+  "bugs": "https://github.com/xirelogy/apinteract/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xirelogy/apinteract.git",
+    "directory": "packages/plugin-sdk"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    "./backend/import": {
+      "types": "./dist/backend/import.d.ts",
+      "default": "./dist/backend/import.js"
+    },
+    "./frontend/localization": {
+      "types": "./dist/frontend/localization.d.ts",
+      "default": "./dist/frontend/localization.js"
+    }
+  },
+  "peerDependencies": {
+    "@apinteract/plugin-api": "^0.1.0-0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@types/node": "24.10.0",
+    "typescript": "5.9.3",
+    "@apinteract/plugin-api": "0.1.0-bootstrap.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit"
+  }
+}