@owox/plugin-sdk 0.30.1

package/README.md

@@ -0,0 +1,48 @@
+# @owox/plugin-sdk
+
+Build a plugin that runs inside OWOX Data Marts.
+
+```ts
+import { connect } from '@owox/plugin-sdk';
+
+const ctx = await connect();
+const dataMarts = await ctx.owox.dataMarts.list();
+```
+
+`connect()` completes a handshake with the OWOX host page and returns a context
+carrying `ctx.owox` — a real OWOX API client.
+
+## What to know before you build
+
+Your plugin runs in a cross-origin iframe with an **opaque origin**. That means no
+cookies, no `localStorage`, no `IndexedDB`, no service workers, and requests to your own
+backend arrive with `Origin: null`, so it must send `Access-Control-Allow-Origin: *` and
+cannot use cookie sessions.
+
+The same applies to **your own assets**: an opaque origin matches nothing, not even the
+server that delivered the page, so a bundled `<script type="module">` is fetched in CORS
+mode and needs that header too. Without it the page loads and runs no code at all — the
+failure looks like a plugin that does nothing rather than one that could not start.
+GitHub Pages sends the header; a plain static server usually does not.
+
+Your entry page must **not** send `X-Frame-Options` or a restrictive
+`Content-Security-Policy: frame-ancestors`, or OWOX will refuse to publish it.
+
+`connect()` and the host agree on a protocol version during the handshake, so a page built
+against an SDK the deployment cannot speak fails to start rather than misbehaving.
+
+Your plugin never holds a credential. `ctx.owox` calls are brokered by the host page,
+which attaches the token — so requests act with **the authority of the member who
+installed your plugin**, and never more. Do not assume you are trusted beyond that.
+
+## Context
+
+|                                            |                                                                     |
+| ------------------------------------------ | ------------------------------------------------------------------- |
+| `ctx.owox`                                 | OWOX API client. The SDK owns its transport; you cannot replace it. |
+| `ctx.ui.openExternal(url)`                 | Ask the host to open an external https URL in a new tab.            |
+| `ctx.ui.navigate(path)`                    | Ask the host to go to a page inside OWOX, in place of your frame.   |
+| `ctx.signal`                               | Aborts when the host tears your plugin down.                        |
+| `ctx.userId`, `ctx.projectId`, `ctx.theme` | Display context. No tokens.                                         |
+
+Requests time out after 30 seconds; streamed reads do not. At most 32 may be in flight.

package/dist/iframe-transport.d.ts

@@ -0,0 +1,19 @@
+import type { OWOXTransport } from '@owox/api-client';
+import type { PluginErrorPayload } from './protocol.js';
+export declare class PluginTransportError extends Error {
+    readonly payload: PluginErrorPayload;
+    constructor(payload: PluginErrorPayload);
+}
+/**
+ * Forwards every call to the host over a MessagePort.
+ *
+ * The plugin holds no credential and issues no request to OWOX. It holds one end of a
+ * channel and can only ask the host to make calls the host has already decided are
+ * allowed -- so the worst a compromised plugin can do is ask for something and be
+ * refused.
+ *
+ * Not exported from either package entry point. Plugin code cannot reach this class,
+ * cannot construct one, and cannot swap the port underneath it.
+ */
+export declare function createIframeTransport(port: MessagePort): OWOXTransport;
+//# sourceMappingURL=iframe-transport.d.ts.map

package/dist/iframe-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"iframe-transport.d.ts","sourceRoot":"","sources":["../src/iframe-transport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EACV,kBAAkB,EAInB,MAAM,eAAe,CAAC;AAevB,qBAAa,oBAAqB,SAAQ,KAAK;IACjC,QAAQ,CAAC,OAAO,EAAE,kBAAkB;gBAA3B,OAAO,EAAE,kBAAkB;CAIjD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,WAAW,GAAG,aAAa,CA0FtE"}

package/dist/iframe-transport.js

@@ -0,0 +1,96 @@
+/**
+ * Matches the shared axios timeout in the OWOX web app rather than inventing another.
+ * A streamed response drops this timer once its head arrives, because NDJSON
+ * traversals legitimately run for minutes.
+ */
+const REQUEST_TIMEOUT_MS = 30_000;
+export class PluginTransportError extends Error {
+    payload;
+    constructor(payload) {
+        super(payload.message);
+        this.payload = payload;
+        this.name = 'PluginTransportError';
+    }
+}
+/**
+ * Forwards every call to the host over a MessagePort.
+ *
+ * The plugin holds no credential and issues no request to OWOX. It holds one end of a
+ * channel and can only ask the host to make calls the host has already decided are
+ * allowed -- so the worst a compromised plugin can do is ask for something and be
+ * refused.
+ *
+ * Not exported from either package entry point. Plugin code cannot reach this class,
+ * cannot construct one, and cannot swap the port underneath it.
+ */
+export function createIframeTransport(port) {
+    const pending = new Map();
+    port.onmessage = (event) => {
+        const response = event.data;
+        const waiting = pending.get(response?.id);
+        if (!waiting) {
+            // An unknown id is either a duplicate of something already settled or noise.
+            // Dropping it silently is the only safe reading.
+            return;
+        }
+        pending.delete(response.id);
+        if (waiting.timer) {
+            clearTimeout(waiting.timer);
+        }
+        waiting.resolve(response);
+    };
+    function send(request) {
+        // Generated here, inside the closure: a plugin author never sees a correlation id
+        // and so cannot address someone else's in-flight request.
+        const id = crypto.randomUUID();
+        return new Promise((resolve, reject) => {
+            const isStream = 'stream' in request && request.stream === true;
+            const timer = isStream
+                ? null
+                : setTimeout(() => {
+                    pending.delete(id);
+                    reject(new PluginTransportError({ code: 'TIMEOUT', message: 'The host did not answer' }));
+                }, REQUEST_TIMEOUT_MS);
+            pending.set(id, { resolve, reject, timer });
+            port.postMessage({ ...request, id });
+        });
+    }
+    async function json(request) {
+        const response = await send(request);
+        if (!response.ok) {
+            throw new PluginTransportError(response.error);
+        }
+        return ('body' in response ? response.body : undefined);
+    }
+    return {
+        getJson: (path, query) => json({ kind: 'api', method: 'GET', path, query: query && Object.entries(query) }),
+        postJson: (path, jsonBody, accept) => json({ kind: 'api', method: 'POST', path, body: jsonBody, accept }),
+        putJson: (path, jsonBody) => json({ kind: 'api', method: 'PUT', path, body: jsonBody }),
+        async getStream(path, query) {
+            const response = await send({
+                kind: 'api',
+                method: 'GET',
+                path,
+                // Pairs, not an object: `?column=a&column=b` is how the API client asks for two
+                // columns, and `Object.fromEntries` would keep only the last one.
+                query: query && [...query],
+                stream: true,
+            });
+            if (!response.ok) {
+                throw new PluginTransportError(response.error);
+            }
+            if (!('stream' in response)) {
+                throw new PluginTransportError({
+                    code: 'PROTOCOL_ERROR',
+                    message: 'The host answered a stream request without a stream',
+                });
+            }
+            // Rebuilt into a Response so the existing NDJSON traversal code works unchanged,
+            // including the run-id header it reads.
+            return new Response(response.stream, {
+                status: response.status,
+                headers: response.headers,
+            });
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,52 @@
+import { OWOXApiClient } from '@owox/api-client';
+import { type PluginHostContext } from './protocol.js';
+export { PLUGIN_PROTOCOL_VERSION } from './protocol.js';
+export type { PluginErrorCode, PluginErrorPayload, PluginHostContext } from './protocol.js';
+/** Host-mediated actions. Each is a request; the host validates and decides. */
+export interface PluginUi {
+    /** Opens an external URL in a new tab, because the sandbox denies you popups. */
+    openExternal(url: string): Promise<void>;
+    /**
+     * Goes to a page inside OWOX Data Marts, in place of this plugin.
+     *
+     * `path` is absolute within the app, e.g. `/ui/${ctx.projectId}/data-marts/${id}`. The
+     * host refuses anything that resolves off its own origin, so this cannot become a way
+     * out of the app -- and your frame is unmounted when it does navigate.
+     */
+    navigate(path: string): void;
+}
+export interface PluginContext extends PluginHostContext {
+    /**
+     * A real OWOX API client whose transport is owned by this SDK.
+     *
+     * Plugin code cannot construct, replace or inspect that transport, and no token ever
+     * enters this document -- every call is brokered by the trusted host page.
+     */
+    readonly owox: OWOXApiClient;
+    /**
+     * Things the sandbox forbids you, which the host will do on your behalf if it agrees.
+     *
+     * Grouped rather than spread across the context: each one is a request the host is free
+     * to refuse, which is a different relationship from `owox`, where you are the one acting.
+     */
+    readonly ui: PluginUi;
+    /** Aborts when the host tears this plugin down. */
+    readonly signal: AbortSignal;
+}
+/**
+ * Completes the host handshake and returns the plugin context.
+ *
+ * Idempotent: repeated calls return the same promise, so a plugin cannot open a second
+ * channel by calling twice.
+ */
+export declare function connect(): Promise<PluginContext>;
+/**
+ * Test seam only: the module-level binding is deliberately not resettable in production.
+ *
+ * Detaches any in-flight handshake as well. A reset that clears the flags but leaves the
+ * message listener attached is not a reset -- the stale listener still answers the next
+ * host-init, claims the binding, and silently starves the handshake that is actually
+ * waiting for it.
+ */
+export declare function __resetForTests(): void;
+//# 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,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD,OAAO,EAGL,KAAK,iBAAiB,EAEvB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AACxD,YAAY,EAAE,eAAe,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAO5F,gFAAgF;AAChF,MAAM,WAAW,QAAQ;IACvB,iFAAiF;IACjF,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzC;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,aAAc,SAAQ,iBAAiB;IACtD;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAE7B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;IAEtB,mDAAmD;IACnD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAaD;;;;;GAKG;AACH,wBAAgB,OAAO,IAAI,OAAO,CAAC,aAAa,CAAC,CAGhD;AAuGD;;;;;;;GAOG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAItC"}

package/dist/index.js

@@ -0,0 +1,121 @@
+import { OWOXApiClient } from '@owox/api-client';
+import { createIframeTransport } from './iframe-transport.js';
+import { isHostInit, PLUGIN_PROTOCOL_VERSION, } from './protocol.js';
+export { PLUGIN_PROTOCOL_VERSION } from './protocol.js';
+/** Long enough for a slow host, short enough that a broken embed fails visibly. */
+const HANDSHAKE_TIMEOUT_MS = 10_000;
+/** The host may not be listening yet when we first announce, so keep announcing. */
+const READY_RETRY_MS = 250;
+/**
+ * The port, bound exactly once and unreachable from anything this module exports.
+ *
+ * Module scope rather than a field on the context: a plugin that could reach the port
+ * could read every response the host sends, including ones it never asked for.
+ */
+let boundPort;
+let connectPromise;
+/** Tears down an in-flight handshake: its listener, its announcer and its deadline. */
+let abandonHandshake;
+/**
+ * Completes the host handshake and returns the plugin context.
+ *
+ * Idempotent: repeated calls return the same promise, so a plugin cannot open a second
+ * channel by calling twice.
+ */
+export function connect() {
+    connectPromise ??= performHandshake();
+    return connectPromise;
+}
+function performHandshake() {
+    return new Promise((resolve, reject) => {
+        // An unframed document has no host. Without this the identity check below is
+        // vacuous -- window.parent === window -- and a page could hand itself a channel.
+        if (typeof window === 'undefined' || window.parent === window) {
+            reject(new Error('This page is not running inside an OWOX plugin frame'));
+            return;
+        }
+        const teardown = new AbortController();
+        const announce = () => {
+            window.parent.postMessage({ owox: 'plugin-ready', v: PLUGIN_PROTOCOL_VERSION }, 
+            // A concrete target origin never matches an opaque one, so the message would
+            // be dropped silently. This carries no data precisely because of that.
+            '*');
+        };
+        const stop = () => {
+            window.removeEventListener('message', onMessage);
+            clearInterval(announcer);
+            clearTimeout(deadline);
+            abandonHandshake = undefined;
+        };
+        abandonHandshake = stop;
+        function onMessage(event) {
+            // Identity of the sending window, and deliberately nothing about its origin.
+            //
+            // The opaque origin belongs to *this* document, not to the host: a message coming
+            // the other way carries the host's real origin, which this plugin has no way to
+            // know and no business demanding. Requiring "null" here refused every genuine host
+            // and left connect() timing out -- caught by running the packaged SDK against a
+            // real host, because the unit tests delivered host-init as if the host were opaque
+            // too.
+            if (event.source !== window.parent) {
+                return;
+            }
+            const [port] = event.ports;
+            // Exactly one port: a host-init with none has no channel to offer, and one with
+            // several is not a shape this protocol defines.
+            if (!isHostInit(event.data) || event.ports.length !== 1 || !port) {
+                return;
+            }
+            // Immutable for the document's lifetime: a second host-init, forged or genuine,
+            // cannot redirect an already-running plugin onto another channel.
+            if (boundPort) {
+                return;
+            }
+            stop();
+            resolve(bind(event.data, port, teardown));
+        }
+        window.addEventListener('message', onMessage);
+        announce();
+        const announcer = setInterval(announce, READY_RETRY_MS);
+        const deadline = setTimeout(() => {
+            stop();
+            reject(new Error('The OWOX host did not complete the plugin handshake'));
+        }, HANDSHAKE_TIMEOUT_MS);
+    });
+}
+function bind(init, port, teardown) {
+    boundPort = port;
+    port.start();
+    port.postMessage({ owox: 'plugin-hello', v: PLUGIN_PROTOCOL_VERSION, nonce: init.nonce });
+    window.addEventListener('pagehide', () => {
+        teardown.abort();
+    });
+    const owox = new OWOXApiClient({ transport: createIframeTransport(port) });
+    return {
+        ...init.context,
+        owox,
+        ui: {
+            openExternal: (url) => {
+                port.postMessage({ id: crypto.randomUUID(), kind: 'openExternal', url });
+                return Promise.resolve();
+            },
+            navigate: (path) => {
+                port.postMessage({ id: crypto.randomUUID(), kind: 'navigate', path });
+            },
+        },
+        signal: teardown.signal,
+    };
+}
+/**
+ * Test seam only: the module-level binding is deliberately not resettable in production.
+ *
+ * Detaches any in-flight handshake as well. A reset that clears the flags but leaves the
+ * message listener attached is not a reset -- the stale listener still answers the next
+ * host-init, claims the binding, and silently starves the handshake that is actually
+ * waiting for it.
+ */
+export function __resetForTests() {
+    abandonHandshake?.();
+    boundPort = undefined;
+    connectPromise = undefined;
+}

package/dist/protocol.d.ts

@@ -0,0 +1,139 @@
+/**
+ * The wire format between an OWOX host page and a plugin running in its iframe.
+ *
+ * Exported as its own entry point so the host can import these types without pulling in
+ * the transport. The transport is not exported from anywhere: that is what makes
+ * "plugin code cannot construct or configure it" a property of the package rather than
+ * a rule someone has to remember.
+ */
+export declare const PLUGIN_PROTOCOL_VERSION: 1;
+/**
+ * The plugin's own origin, as the host sees it: a sandboxed frame is opaque, so
+ * `event.origin` on a message from the plugin is the literal string "null", and the
+ * plugin's outbound postMessage must target '*'.
+ *
+ * It is a real check in the one direction it applies -- the host requires it of the
+ * plugin's announcement. It says nothing in the other direction: the host is served on
+ * whatever origin the deployment uses, which the plugin cannot know, so a plugin
+ * verifies the host by window identity instead.
+ */
+export declare const OPAQUE_ORIGIN = "null";
+/** Announces the plugin is listening. Deliberately carries no data. */
+export interface PluginReadyMessage {
+    owox: 'plugin-ready';
+    v: typeof PLUGIN_PROTOCOL_VERSION;
+}
+/** Hands over one end of a MessageChannel, which becomes the only data path. */
+export interface PluginHostInitMessage {
+    owox: 'host-init';
+    v: typeof PLUGIN_PROTOCOL_VERSION;
+    nonce: string;
+    context: PluginHostContext;
+}
+export interface PluginHelloMessage {
+    owox: 'plugin-hello';
+    v: typeof PLUGIN_PROTOCOL_VERSION;
+    nonce: string;
+}
+/** Ambient information the host chooses to reveal. Display only: no tokens, ever. */
+export interface PluginHostContext {
+    readonly pluginId: string;
+    readonly installationId: string;
+    readonly projectId: string;
+    /**
+     * The member this plugin is running for.
+     *
+     * Their name and avatar are deliberately not here: `GET /api/auth/context` already
+     * serves both to a plugin that needs them, and a second copy in the handshake would
+     * only be one that goes stale.
+     */
+    readonly userId: string;
+    readonly theme: 'light' | 'dark';
+}
+/**
+ * Query parameters as ordered pairs rather than an object.
+ *
+ * A `Record` collapses repeated keys, and repeats are meaningful here: the API client
+ * builds `?column=a&column=b` with `URLSearchParams.append`, so flattening would quietly
+ * hand a plugin a different dataset than the same call makes outside the iframe.
+ */
+export type PluginQuery = readonly (readonly [string, string])[];
+export type PluginRequest = {
+    id: string;
+    kind: 'api';
+    method: 'GET' | 'POST' | 'PUT';
+    path: string;
+    query?: PluginQuery;
+    body?: unknown;
+    accept?: string;
+    stream?: false;
+} | {
+    id: string;
+    kind: 'api';
+    method: 'GET';
+    path: string;
+    query?: PluginQuery;
+    stream: true;
+} | {
+    id: string;
+    kind: 'openExternal';
+    url: string;
+}
+/**
+ * A path inside OWOX, opened in place. Distinct from openExternal on purpose: one
+ * leaves the app in a new tab, the other replaces the page the plugin is running on,
+ * and the host validates them by different rules.
+ */
+ | {
+    id: string;
+    kind: 'navigate';
+    path: string;
+};
+/**
+ * A request before the transport stamps its correlation id.
+ *
+ * Distributed on purpose: a plain `Omit` over a union collapses it to the keys every
+ * member shares, which would silently erase `method` and `path`. Distribution only
+ * happens across a naked generic parameter, so the indirection through `T` is
+ * load-bearing.
+ */
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+export type PluginRequestInput = DistributiveOmit<PluginRequest, 'id'>;
+export type PluginErrorCode = 
+/** The backend answered with a non-2xx status. */
+'HTTP_ERROR' | 'NETWORK_ERROR' | 'TIMEOUT'
+/** The plugin was suspended deployment-wide while it was open. */
+ | 'SUSPENDED'
+/** The host refused before making any request -- see its path and method checks. */
+ | 'FORBIDDEN'
+/** Malformed envelope, or too many requests in flight. */
+ | 'PROTOCOL_ERROR';
+export interface PluginErrorPayload {
+    code: PluginErrorCode;
+    status?: number;
+    message: string;
+    details?: unknown;
+}
+export type PluginResponse = {
+    id: string;
+    ok: true;
+    status: number;
+    headers: Record<string, string>;
+    body: unknown;
+} | {
+    id: string;
+    ok: true;
+    status: number;
+    headers: Record<string, string>;
+    /** Transferred rather than copied, so NDJSON traversals stream as they arrive. */
+    stream: ReadableStream<Uint8Array>;
+} | {
+    id: string;
+    ok: false;
+    error: PluginErrorPayload;
+};
+export declare function isPluginReady(value: unknown): value is PluginReadyMessage;
+export declare function isPluginHello(value: unknown): value is PluginHelloMessage;
+export declare function isHostInit(value: unknown): value is PluginHostInitMessage;
+export {};
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

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

package/dist/protocol.js

@@ -0,0 +1,38 @@
+/**
+ * The wire format between an OWOX host page and a plugin running in its iframe.
+ *
+ * Exported as its own entry point so the host can import these types without pulling in
+ * the transport. The transport is not exported from anywhere: that is what makes
+ * "plugin code cannot construct or configure it" a property of the package rather than
+ * a rule someone has to remember.
+ */
+export const PLUGIN_PROTOCOL_VERSION = 1;
+/**
+ * The plugin's own origin, as the host sees it: a sandboxed frame is opaque, so
+ * `event.origin` on a message from the plugin is the literal string "null", and the
+ * plugin's outbound postMessage must target '*'.
+ *
+ * It is a real check in the one direction it applies -- the host requires it of the
+ * plugin's announcement. It says nothing in the other direction: the host is served on
+ * whatever origin the deployment uses, which the plugin cannot know, so a plugin
+ * verifies the host by window identity instead.
+ */
+export const OPAQUE_ORIGIN = 'null';
+export function isPluginReady(value) {
+    const message = value;
+    return message?.owox === 'plugin-ready' && message.v === PLUGIN_PROTOCOL_VERSION;
+}
+export function isPluginHello(value) {
+    const message = value;
+    return (message?.owox === 'plugin-hello' &&
+        // Checked like the other two guards: without it an ack from a future SDK would be
+        // accepted here and then read against this version's rules.
+        message.v === PLUGIN_PROTOCOL_VERSION &&
+        typeof message.nonce === 'string');
+}
+export function isHostInit(value) {
+    const message = value;
+    return (message?.owox === 'host-init' &&
+        message.v === PLUGIN_PROTOCOL_VERSION &&
+        typeof message.nonce === 'string');
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@owox/plugin-sdk",
+  "version": "0.30.1",
+  "description": "SDK for building OWOX Data Marts plugins",
+  "type": "module",
+  "author": "OWOX",
+  "license": "ELv2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.16.0"
+  },
+  "homepage": "https://github.com/OWOX/owox-data-marts",
+  "bugs": "https://github.com/OWOX/owox-data-marts/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OWOX/owox-data-marts.git",
+    "directory": "packages/plugin-sdk"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prebuild": "npm run build:dep",
+    "build:dep": "npm run build -w @owox/api-client --prefix ../..",
+    "clean": "shx rm -rf dist",
+    "test": "vitest run",
+    "lint": "eslint . --config ./eslint.config.js",
+    "lint:fix": "eslint . --fix --config ./eslint.config.js",
+    "format": "prettier --write \"**/*.{ts,js,json,md}\" --ignore-path ../../.prettierignore",
+    "format:check": "prettier --check \"**/*.{ts,js,json,md}\" --ignore-path ../../.prettierignore",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run lint && npm run typecheck"
+  },
+  "keywords": [
+    "owox",
+    "data-marts",
+    "plugin",
+    "sdk"
+  ],
+  "dependencies": {
+    "@owox/api-client": "0.30.1"
+  },
+  "devDependencies": {
+    "@owox/eslint-config": "*",
+    "@owox/prettier-config": "*",
+    "@owox/typescript-config": "*",
+    "happy-dom": "^20.0.0",
+    "vitest": "^4.1.10"
+  },
+  "files": [
+    "README.md",
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./protocol": {
+      "import": "./dist/protocol.js",
+      "types": "./dist/protocol.d.ts"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}