@picteus/extension-sdk 0.17.0 → 0.19.0

package/dist/generated/backEndIntents.d.ts

@@ -0,0 +1,216 @@
+import type { Buffer } from "node:buffer";
+/**
+ * Unique identity metadata for an intent invocation.
+ *
+ * @remarks
+ * The identity is carried by intent envelopes that inherit from BasisIntent. Producers may use it to correlate an intent with its request or response; it does not identify the user, extension, or target entity.
+ */
+interface Identity {
+    /**
+     * Unique identifier string for the intent invocation.
+     *
+     * @remarks
+     * Opaque correlation value supplied by the producer. Preserve the value unchanged when forwarding or responding to the same invocation.
+     */
+    readonly id: string;
+}
+/**
+ * Unique identity metadata for an intent invocation.
+ *
+ * @remarks
+ * The identity is carried by intent envelopes that inherit from BasisIntent. Producers may use it to correlate an intent with its request or response; it does not identify the user, extension, or target entity.
+ */
+type IntentIdentity = Identity;
+/**
+ * Contextual entity identifiers associated with an intent execution.
+ *
+ * @remarks
+ * Context communicates which entities are currently selected or otherwise relevant to an operation. It is supplementary to the payload and must not be treated as a substitute for an explicit target required by that payload.
+ */
+interface Context {
+    /** Optional collection of image identifiers. */
+    readonly imageIds?: string[];
+}
+/**
+ * Contextual entity identifiers associated with an intent execution.
+ *
+ * @remarks
+ * Context communicates which entities are currently selected or otherwise relevant to an operation. It is supplementary to the payload and must not be treated as a substitute for an explicit target required by that payload.
+ */
+type IntentContext = Context;
+/**
+ * Base intent model providing optional identity tracking.
+ *
+ * @remarks
+ * Intent payload models inherit this envelope when they need request correlation. The identity is optional so intents can also be dispatched without a correlation token.
+ */
+interface BasisIntent {
+    /**
+     * Optional unique identity metadata for the intent invocation.
+     *
+     * @remarks
+     * Correlation metadata for the invocation, should be kept intact during its whole lifecycle.
+     */
+    readonly identity?: IntentIdentity;
+}
+/**
+ * Base intent model extending BasisIntent with execution context references.
+ *
+ * @remarks
+ * It offers additional information about the context of execution the intent.
+ */
+interface WithContextIntent extends BasisIntent {
+    /** Optional execution context containing target entity identifiers such as image identifiers. */
+    readonly context?: IntentContext;
+}
+/**
+ * Configuration for uploading and hosting a static web application bundle on the back-end.
+ *
+ * @remarks
+ * The server accepts a ZIP archive of static assets and hosts it for use in an embedded frame. Configuration is passed to the served application separately from the archive contents.
+ */
+interface ServeBundle {
+    /**
+     * Binary ZIP archive payload containing static web application assets (HTML, CSS, JS).
+     *
+     * @remarks
+     * ZIP-encoded bundle containing the entry HTML document and its static dependencies. The archive must be suitable for extraction and static hosting; this property is the archive bytes, not a URL to an existing bundle.
+     */
+    readonly content: Buffer;
+    /**
+     * Optional initial configuration parameters or settings forwarded to the served bundle.
+     *
+     * @remarks
+     * JSON-compatible key/value settings made available to the hosted application when it is initialized.
+     */
+    readonly settings?: Record<string, unknown>;
+}
+/**
+ * Configuration for uploading and hosting a static web application bundle on the back-end.
+ *
+ * @remarks
+ * The server accepts a ZIP archive of static assets and hosts it for use in an embedded frame. Configuration is passed to the served application separately from the archive contents.
+ */
+export type IntentServeBundle = ServeBundle;
+/**
+ * An intent for uploading and hosting a web application bundle or a plain HTML page on the back-end.
+ *
+ * @remarks
+ * The back-end hosts the supplied static assets and returns a URL that can be used to open the application in a frame.
+ */
+export interface ServeBundleIntent extends BasisIntent {
+    /**
+     * Bundle archive payload and optional configuration settings.
+     *
+     * @remarks
+     * Required data used by the server to host the static application bundle.
+     */
+    readonly serveBundle: IntentServeBundle;
+}
+/**
+ * Parameters for prompting the user to select an existing file through a native file picker dialog.
+ *
+ * @remarks
+ * Specifies the filters and prompt used by the host's file picker. The selected file content is returned by the corresponding read-file operation.
+ */
+interface ReadFile {
+    /**
+     * Optional list of allowed file extension filters (e.g. ['json', 'png']).
+     *
+     * @remarks
+     * File extensions offered as selection filters. Supply extensions without a leading dot; omit this field to leave the available file types unrestricted by the request.
+     */
+    readonly extensions?: string[];
+    /**
+     * Informational dialog prompt message displayed to the user during file selection.
+     *
+     * @remarks
+     * User-facing prompt describing what file should be selected. It is informational and does not enforce the extension filters.
+     */
+    readonly message: string;
+}
+/**
+ * Parameters for prompting the user to select an existing file through a native file picker dialog.
+ *
+ * @remarks
+ * Specifies the filters and prompt used by the host's file picker. The selected file content is returned by the corresponding read-file operation.
+ */
+export type IntentReadFile = ReadFile;
+/**
+ * An intent for prompting the user to select an existing file through a native file picker dialog.
+ *
+ * @remarks
+ * It requests a file picker with the supplied filters and prompt. The selected content is returned to the caller as binary data; the extension does not receive a filesystem path through this contract.
+ */
+export interface ReadFileIntent extends WithContextIntent {
+    /**
+     * File filter extensions and dialog prompt message configuration.
+     *
+     * @remarks
+     * Required file picker request. The selected bytes are returned by the host operation.
+     */
+    readonly readFile: IntentReadFile;
+}
+/**
+ * Parameters for prompting the user to save a file to disk through a native file save dialog.
+ *
+ * @remarks
+ * Specifies the suggested output name, extension, bytes, and prompt for a host-managed save dialog. The host controls the destination path and confirms the write with the user.
+ */
+interface WriteFile {
+    /**
+     * Default suggested filename without extension.
+     *
+     * @remarks
+     * Suggested base name shown in the save dialog. Keep the extension in its separate property to avoid a duplicated suffix.
+     */
+    readonly name: string;
+    /**
+     * File extension to apply to the saved file.
+     *
+     * @remarks
+     * Suffix associated with the saved file. Supply the extension expected by the content format, without relying on the host to infer it from the bytes.
+     */
+    readonly extension: string;
+    /**
+     * Binary byte content to write to disk upon user confirmation.
+     *
+     * @remarks
+     * Complete file payload written if the user confirms the save operation.
+     */
+    readonly content: Buffer;
+    /**
+     * Informational dialog prompt message displayed to the user during file saving.
+     *
+     * @remarks
+     * User-facing explanation of the file being saved. It supplements the suggested name and does not choose the destination path.
+     */
+    readonly message: string;
+}
+/**
+ * Parameters for prompting the user to save a file to disk through a native file save dialog.
+ *
+ * @remarks
+ * Specifies the suggested output name, extension, bytes, and prompt for a host-managed save dialog. The host controls the destination path and confirms the write with the user.
+ */
+export type IntentWriteFile = WriteFile;
+/**
+ * An intent that prompts the user to save some content to disk through a native file saver dialog.
+ *
+ * @remarks
+ * Requests a host-managed save dialog using the proposed filename, extension, and content. The user and host determine the destination; callers should handle cancellation according to the surrounding intent flow.
+ */
+export interface WriteFileIntent extends WithContextIntent {
+    /**
+     * Target file name, extension, binary content, and dialog prompt message configuration.
+     *
+     * @remarks
+     * Required save request containing the suggested name, output extension, content, and user-facing prompt.
+     */
+    readonly writeFile: IntentWriteFile;
+}
+export declare function isServeBundleIntent(intent: unknown): intent is ServeBundleIntent;
+export declare function isReadFileIntent(intent: unknown): intent is ReadFileIntent;
+export declare function isWriteFileIntent(intent: unknown): intent is WriteFileIntent;
+export type BackIntent = ServeBundleIntent | ReadFileIntent | WriteFileIntent;
+export {};

package/dist/generated/backEndIntents.js

@@ -0,0 +1,12 @@
+function hasIntentProperty(intent, propertyName) {
+    return typeof intent === "object" && intent !== null && Reflect.get(intent, propertyName) !== undefined;
+}
+export function isServeBundleIntent(intent) {
+    return hasIntentProperty(intent, "serveBundle");
+}
+export function isReadFileIntent(intent) {
+    return hasIntentProperty(intent, "readFile");
+}
+export function isWriteFileIntent(intent) {
+    return hasIntentProperty(intent, "writeFile");
+}