@apinteract/plugin-api 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,34 @@
+# `@apinteract/plugin-api`
+
+Stable TypeScript contracts for APInteract plugins.
+
+```sh
+pnpm add --save-dev @apinteract/plugin-api
+```
+
+Import the registration contract from the package root and target-specific
+providers from `@apinteract/plugin-api/frontend` or
+`@apinteract/plugin-api/backend`:
+
+```ts
+import type { PluginRegistrationContext } from "@apinteract/plugin-api";
+import type { FrontendPluginProviders } from "@apinteract/plugin-api/frontend";
+
+export function register(
+  context: PluginRegistrationContext<FrontendPluginProviders>,
+): void {
+  // Register the providers declared by apinteract-plugin.json.
+}
+```
+
+The package contains declarations and the small runtime constants needed to
+author a plugin. It does not depend on the APInteract application source tree.
+Plugin packages should bundle every runtime dependency into their `dist/`
+output.
+
+See the [plugin development guide](https://github.com/xirelogy/apinteract/blob/main/docs/plugins/README.md)
+for the package format, provider contracts, and compatibility rules.
+
+## License
+
+MIT

package/dist/backend.d.ts

@@ -0,0 +1,199 @@
+import type { APInteractPluginModule } from "./core.js";
+export type ImportProviderId = string;
+export type ImportedHttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+/** Describes one variable declaration emitted by an import provider. */
+export type ImportedVariableWrite = {
+    readonly variableId?: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly kind: "value";
+    readonly value: string;
+} | {
+    readonly variableId?: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly kind: "secret";
+    readonly value?: string;
+    readonly clearValue?: boolean;
+} | {
+    readonly variableId?: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly kind: "alias";
+    readonly target: string;
+} | {
+    readonly variableId?: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly kind: "unset";
+};
+/** Declares one source adapter and the normalized features it may produce. */
+export interface ImportProviderManifest {
+    readonly id: ImportProviderId;
+    readonly version: string;
+    readonly label: string;
+    readonly acceptedExtensions: readonly string[];
+    readonly acceptedMediaTypes: readonly string[];
+    readonly inputKinds: readonly ["file"];
+    readonly capabilities: {
+        readonly multipleRequests: boolean;
+        readonly hierarchy: boolean;
+        readonly attachments: boolean;
+        readonly capturedResponses: boolean;
+        readonly responseExamples: boolean;
+        readonly variables: boolean;
+    };
+}
+/** Contains one bounded source presented to import providers without I/O access. */
+export interface ImportSource {
+    readonly name: string;
+    readonly text: string;
+}
+/** Reports how confidently a provider recognizes a bounded source. */
+export interface ImportProbeResult {
+    readonly confidence: number;
+    readonly reason: string;
+}
+export type ImportDiagnosticSeverity = "info" | "warning" | "error";
+/** Represents one editable name/value field emitted by an import provider. */
+export interface ImportedRequestField {
+    readonly name: string;
+    readonly value: string;
+    readonly enabled: boolean;
+    readonly mode?: "override" | "append";
+    readonly description?: string;
+}
+/** Describes one immutable uploaded file referenced by an imported body. */
+export interface ImportedRequestAttachment {
+    readonly attachmentId: string;
+    readonly workspaceId: string;
+    readonly fileName: string;
+    readonly contentType: string;
+    readonly byteLength: number;
+    readonly sha256: string;
+}
+/** Preserves the wire-level request body variants accepted by the backend. */
+export type ImportedRequestBodyDefinition = {
+    readonly kind: "none";
+} | {
+    readonly kind: "text";
+    readonly contentType: string | null;
+    readonly text: string;
+} | {
+    readonly kind: "file";
+    readonly contentType: string | null;
+    readonly attachment: ImportedRequestAttachment;
+} | {
+    readonly kind: "urlencoded";
+    readonly contentType: string | null;
+    readonly fields: readonly ImportedRequestField[];
+} | {
+    readonly kind: "multipart";
+    readonly contentType: string | null;
+    readonly boundary: string;
+    readonly fields: readonly (ImportedRequestField | {
+        readonly kind: "file";
+        readonly name: string;
+        readonly enabled: boolean;
+        readonly description?: string;
+        readonly attachment: ImportedRequestAttachment;
+    })[];
+};
+/** Describes one provider-defined request-body alternative selectable at import time. */
+export interface ImportedRequestBodyOption {
+    readonly optionId: string;
+    readonly label: string;
+    /** Stable provider-defined value used when one choice can apply to many requests. */
+    readonly selectionKey?: string;
+    readonly requestBody: ImportedRequestBodyDefinition;
+    /** Provider-owned Markdown appended to request notes only when this option is selected. */
+    readonly documentation?: string;
+}
+/** Describes a lossy, unsupported, or invalid source construct. */
+export interface ImportDiagnostic {
+    readonly code: string;
+    readonly severity: ImportDiagnosticSeverity;
+    readonly message: string;
+    readonly itemId?: string;
+    readonly itemIds?: readonly string[];
+    readonly sourceLocation?: string;
+    readonly sourceLocations?: readonly string[];
+}
+/** Describes one provider-created collection below the imported root. */
+export interface ImportedCollection {
+    readonly collectionKey: string;
+    readonly parentCollectionKey: string | null;
+    readonly name: string;
+    readonly description: string;
+    readonly notes: string;
+    readonly pathPrefix: string;
+    readonly variables: readonly ImportedVariableWrite[];
+}
+/** Preserves one recorded HTTP response without provider-controlled provenance. */
+export interface ImportedCapturedExchange {
+    readonly capturedExchangeId?: string;
+    readonly label?: string;
+    readonly status: number;
+    readonly statusText: string;
+    readonly headers: readonly {
+        readonly name: string;
+        readonly value: string;
+    }[];
+    readonly contentType: string | null;
+    readonly body: string;
+    readonly bodyEncoding: "text" | "base64";
+    readonly bodyComplete: boolean;
+    readonly bodyBytes: number;
+    readonly recordedAt: string | null;
+    readonly importedAt?: string;
+}
+/** Represents one source request normalized into APInteract draft semantics. */
+export interface ImportedRequest {
+    readonly itemId: string;
+    readonly sourceLocation: string;
+    readonly collectionKey: string | null;
+    readonly name: string;
+    readonly description: string;
+    readonly notes: string;
+    readonly method: ImportedHttpMethod;
+    readonly targetMode: "absolute" | "composed";
+    readonly targetUrl: string;
+    readonly query: readonly ImportedRequestField[];
+    readonly headers: readonly ImportedRequestField[];
+    readonly requestBody: ImportedRequestBodyDefinition;
+    readonly requestBodyOptions?: readonly ImportedRequestBodyOption[];
+    readonly defaultRequestBodyOptionId?: string;
+    readonly body: string;
+    readonly preRequestScript: string;
+    readonly postResponseScript: string;
+    readonly variables: readonly ImportedVariableWrite[];
+    readonly capturedExchange?: ImportedCapturedExchange;
+    readonly capturedExchanges?: readonly ImportedCapturedExchange[];
+}
+/** Describes a mutation-free canonical request and collection import preview. */
+export interface ImportPlan {
+    readonly schemaVersion: 1;
+    readonly providerId: ImportProviderId;
+    readonly providerVersion: string;
+    readonly sourceName: string;
+    readonly sourceFingerprint: string;
+    readonly suggestedName: string;
+    readonly description: string;
+    readonly notes: string;
+    readonly pathPrefix: string;
+    readonly variables: readonly ImportedVariableWrite[];
+    readonly collections: readonly ImportedCollection[];
+    readonly requests: readonly ImportedRequest[];
+    readonly diagnostics: readonly ImportDiagnostic[];
+}
+/** Converts one supported source into a canonical import plan without mutation. */
+export interface ImportProvider {
+    readonly manifest: ImportProviderManifest;
+    probe(source: ImportSource): ImportProbeResult;
+    parse(source: ImportSource): Omit<ImportPlan, "sourceFingerprint"> | Promise<Omit<ImportPlan, "sourceFingerprint">>;
+}
+/** Lists the extension providers available to backend-only plugins. */
+export interface BackendPluginProviders {
+    readonly "request.import": ImportProvider;
+}
+export type BackendPluginModule = APInteractPluginModule<BackendPluginProviders>;

package/dist/backend.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=backend.js.map

package/dist/backend.js.map

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

package/dist/core.d.ts

@@ -0,0 +1,37 @@
+export type PluginTarget = "frontend" | "backend";
+export type PluginSource = "built-in" | "user";
+/** Current JSON manifest format generation accepted by plugin hosts. */
+export declare const PLUGIN_MANIFEST_SCHEMA_VERSION = 1;
+/** Current executable host/plugin compatibility generation. */
+export declare const PLUGIN_API_VERSION = 1;
+/** Identifies one installable plugin package and its single execution target. */
+export interface PluginPackageManifest<TTarget extends PluginTarget = PluginTarget> {
+    /** Selects the JSON manifest format independently of the executable API. */
+    readonly schemaVersion: typeof PLUGIN_MANIFEST_SCHEMA_VERSION;
+    /** Selects one breaking-compatibility generation of the host/plugin API. */
+    readonly apiVersion: typeof PLUGIN_API_VERSION;
+    readonly id: string;
+    readonly name: string;
+    readonly version: string;
+    /** Higher weights are presented before lower-weight plugin contributions. */
+    readonly weight?: number;
+    readonly target: TTarget;
+    readonly entrypoint: string;
+    readonly providers: readonly string[];
+}
+/** Describes one successfully loaded plugin without exposing contributions. */
+export interface EnabledPlugin {
+    readonly id: string;
+    readonly name: string;
+    readonly version: string;
+    readonly target: PluginTarget;
+    readonly source: PluginSource;
+}
+/** Exposes only the typed extension providers owned by one plugin host. */
+export interface PluginRegistrationContext<TProviders extends object> {
+    register<TProvider extends Extract<keyof TProviders, string>>(provider: TProvider, contribution: TProviders[TProvider]): void;
+}
+/** Defines the common package signature shared by single-target plugins. */
+export interface APInteractPluginModule<TProviders extends object> {
+    register(context: PluginRegistrationContext<TProviders>): void;
+}

package/dist/core.js

@@ -0,0 +1,5 @@
+/** Current JSON manifest format generation accepted by plugin hosts. */
+export const PLUGIN_MANIFEST_SCHEMA_VERSION = 1;
+/** Current executable host/plugin compatibility generation. */
+export const PLUGIN_API_VERSION = 1;
+//# sourceMappingURL=core.js.map

package/dist/core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.js","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AAIA,wEAAwE;AACxE,MAAM,CAAC,MAAM,8BAA8B,GAAG,CAAC,CAAC;AAEhD,+DAA+D;AAC/D,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC"}

package/dist/frontend.d.ts

@@ -0,0 +1,198 @@
+import type { APInteractPluginModule } from "./core.js";
+export type RequestBodyHostKind = RequestBodyDefinition["kind"];
+/** Describes one editable name/value field in a structured request body. */
+export interface RequestBodyField {
+    readonly name: string;
+    readonly value: string;
+    readonly enabled: boolean;
+    readonly description?: string;
+    readonly mode?: "override" | "append";
+}
+/** Describes an immutable workspace upload referenced by a request body. */
+export interface RequestAttachment {
+    readonly attachmentId: string;
+    readonly workspaceId: string;
+    readonly fileName: string;
+    readonly contentType: string;
+    readonly byteLength: number;
+    readonly sha256: string;
+}
+/** Describes one file positioned among multipart text fields. */
+export interface MultipartFileField {
+    readonly kind: "file";
+    readonly name: string;
+    readonly enabled: boolean;
+    readonly description?: string;
+    readonly attachment: RequestAttachment;
+}
+/** Preserves the canonical HTTP wire-body forms exchanged with content plugins. */
+export type RequestBodyDefinition = {
+    readonly kind: "none";
+} | {
+    readonly kind: "text";
+    readonly contentType: string | null;
+    readonly text: string;
+} | {
+    readonly kind: "file";
+    readonly contentType: string | null;
+    readonly attachment: RequestAttachment;
+} | {
+    readonly kind: "urlencoded";
+    readonly contentType: string | null;
+    readonly fields: RequestBodyField[];
+} | {
+    readonly kind: "multipart";
+    readonly contentType: string | null;
+    readonly boundary: string;
+    readonly fields: (RequestBodyField | MultipartFileField)[];
+};
+/** Identifies the declaration that supplied one effective variable preview. */
+export interface VariablePreviewSource {
+    readonly scope: "workspace" | "collection" | "environment" | "request";
+    readonly scopeId: string;
+    readonly scopeName: string;
+    readonly revision: number;
+}
+/** Provides secret-safe variable resolution evidence to an editor plugin. */
+export interface VariablePreview {
+    readonly name: string;
+    readonly status: "resolved" | "missing" | "unset" | "error";
+    readonly declaredKind: "value" | "secret" | "alias" | "unset" | null;
+    readonly effectiveKind: "value" | "secret" | null;
+    readonly aliasTarget: string | null;
+    readonly value: string | null;
+    readonly secretVersion: number | null;
+    readonly diagnostic: string | null;
+    readonly source: VariablePreviewSource | null;
+}
+/** Exposes only response fields required by response-content plugins. */
+export interface ResponseExecution {
+    readonly executionId: string;
+    readonly headers?: readonly {
+        readonly name: string;
+        readonly value: string;
+    }[];
+    readonly bodyComplete: boolean;
+    readonly bodyBytes?: number;
+    readonly bodyPreview?: string;
+    readonly bodyBlobId?: string;
+}
+/** Names one editor language understood by a host or safely treated as plain text. */
+export type CodeEditorLanguage = string;
+/** Supplies a stable fallback and optional translations owned by the plugin package. */
+export interface PluginLabel {
+    readonly default: string;
+    readonly translations?: Readonly<Record<string, string>>;
+}
+/** Returns either formatted request source or a safe user-facing parse error. */
+export type RequestContentFormatResult = {
+    readonly valid: true;
+    readonly value: string;
+} | {
+    readonly valid: false;
+    readonly error: string;
+};
+/** Updates or destroys one framework-neutral plugin view instance. */
+export interface FrontendPluginViewHandle<TContext> {
+    update(context: TContext): void;
+    destroy(): void;
+}
+/** Mounts one plugin-owned view into a host-provided DOM container. */
+export type FrontendPluginViewMount<TContext> = (container: HTMLElement, context: TContext) => FrontendPluginViewHandle<TContext>;
+/** Configures the shared CodeMirror mechanism without choosing content semantics. */
+export interface CodeEditorMountOptions {
+    readonly document: string;
+    readonly label: string;
+    readonly language?: CodeEditorLanguage;
+    readonly disabled?: boolean;
+    readonly readOnly?: boolean;
+    readonly foldable?: boolean;
+    readonly onChange?: (document: string) => void;
+}
+/** Configures the generic editor for canonical HTTP wire-body representations. */
+export interface WireBodyEditorMountOptions {
+    readonly body: RequestBodyDefinition;
+    readonly wireKind: RequestBodyHostKind;
+    readonly label: string;
+    readonly disabled: boolean;
+    readonly variablePreviews: readonly VariablePreview[];
+    readonly uploadAttachment?: (file: File) => Promise<RequestAttachment>;
+    readonly codeLanguage?: CodeEditorLanguage;
+    readonly contentTypePlaceholder?: string;
+    readonly format?: (source: string) => RequestContentFormatResult;
+    readonly onChange: (body: RequestBodyDefinition) => void;
+}
+/** Configures an isolated document surface for untrusted response markup. */
+export interface SandboxedDocumentMountOptions {
+    readonly source: string;
+    readonly title: string;
+}
+/** Configures bounded raster decoding through host-owned security policy. */
+export interface ImageViewerMountOptions {
+    readonly executionId: string;
+    readonly mediaType: string;
+    readonly byteLength: number;
+    readonly loadBody: (executionId: string) => Promise<Blob>;
+    /** Interprets bounded header bytes without moving format knowledge into the host. */
+    readonly inspect: (mediaType: string, bytes: Uint8Array) => ImageDimensions | null;
+}
+/** Describes intrinsic raster dimensions returned by a plugin-owned inspector. */
+export interface ImageDimensions {
+    readonly width: number;
+    readonly height: number;
+}
+/** Exposes reusable UI and security mechanisms without application internals. */
+export interface FrontendPluginUi {
+    mountCodeEditor(container: HTMLElement, options: CodeEditorMountOptions): FrontendPluginViewHandle<CodeEditorMountOptions>;
+    mountWireBodyEditor(container: HTMLElement, options: WireBodyEditorMountOptions): FrontendPluginViewHandle<WireBodyEditorMountOptions>;
+    mountSandboxedDocument(container: HTMLElement, options: SandboxedDocumentMountOptions): FrontendPluginViewHandle<SandboxedDocumentMountOptions>;
+    mountImageViewer(container: HTMLElement, options: ImageViewerMountOptions): FrontendPluginViewHandle<ImageViewerMountOptions>;
+}
+/** Supplies canonical wire state and host mechanisms to a request editor. */
+export interface RequestContentEditorContext {
+    readonly body: RequestBodyDefinition;
+    readonly disabled: boolean;
+    readonly locale: string;
+    readonly variablePreviews: readonly VariablePreview[];
+    readonly uploadAttachment?: (file: File) => Promise<RequestAttachment>;
+    readonly updateBody: (body: RequestBodyDefinition) => void;
+    readonly ui: FrontendPluginUi;
+}
+/** Contributes executable request editing over a canonical HTTP wire body. */
+export interface RequestContentContribution {
+    readonly id: string;
+    readonly label: PluginLabel;
+    readonly mediaTypes?: readonly string[];
+    readonly priority?: number;
+    readonly order?: number;
+    createBody(previous: RequestBodyDefinition): RequestBodyDefinition;
+    isDefaultFor(body: RequestBodyDefinition): boolean;
+    effectiveContentType(body: RequestBodyDefinition): string | null;
+    mountEditor: FrontendPluginViewMount<RequestContentEditorContext>;
+}
+/** Provides bounded response data to one selected frontend parser/presenter. */
+export interface ResponseContentPresenterContext {
+    readonly execution: ResponseExecution;
+    readonly mediaType: string;
+    readonly locale: string;
+    readonly previewComplete: boolean;
+    readonly previewTruncated: boolean;
+    readonly loadBody?: (executionId: string) => Promise<Blob>;
+    readonly ui: FrontendPluginUi;
+}
+/** Contributes one executable response viewer for deterministic media-type patterns. */
+export interface ResponseContentContribution {
+    readonly id: string;
+    readonly label: PluginLabel;
+    readonly mediaTypes: readonly string[];
+    readonly priority?: number;
+    isAvailable?(context: Omit<ResponseContentPresenterContext, "ui">): boolean;
+    isDefault?(context: Omit<ResponseContentPresenterContext, "ui">): boolean;
+    mountView: FrontendPluginViewMount<ResponseContentPresenterContext>;
+}
+/** Lists the extension providers available to frontend-only plugins. */
+export interface FrontendPluginProviders {
+    readonly "request.content": RequestContentContribution;
+    readonly "response.content": ResponseContentContribution;
+}
+export type FrontendPluginModule = APInteractPluginModule<FrontendPluginProviders>;

package/dist/frontend.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=frontend.js.map

package/dist/frontend.js.map

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

package/package.json

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