@metagptx/web-sdk 0.0.21 → 0.0.23

package/README.md

@@ -26,12 +26,13 @@ const user = await client.auth.me();
 
 ## Modules
 
-The SDK provides four main modules:
+The SDK provides five main modules:
 
 - **auth**: User authentication operations
 - **entities**: Dynamic entity CRUD operations
 - **apiCall**: Custom API calls
 - **integrations**: Integration function invocations
+- **frame**: Frame communication operations for iframe/parent window messaging
 
 ## API Reference
 
@@ -443,6 +444,79 @@ const response = await client.integrations.storage.uploadFile({
 
 ---
 
+### Frame Module
+
+Provides utilities for communicating between iframe and parent window using postMessage API.
+
+#### `frame.postMessage(type, data?, options?)`
+
+Send a message to the parent window using `window.top.postMessage`.
+
+**Parameters:**
+- `type` (required): Message type identifier (must be a valid `FrameMessageType`)
+- `data` (optional): Message data payload (must match the data type for the given message type)
+- `options` (optional): Configuration options
+  - `targetOrigin` (optional): Target origin for the message (defaults to `'*'`)
+  - `targetName` (optional): Target window name (defaults to `window.name`)
+
+**Default Message Types:**
+- `'mgx-appview-error'`: Error message with `errMsg` and `stack` fields
+- `'mgx-create-page'`: Create page message with `path` field
+
+**TypeScript Support:**
+You can extend the `FrameMessageTypes` interface to add custom message types:
+
+```typescript
+import type { FrameMessageTypes } from '@metagptx/web-sdk';
+
+interface CustomMessageTypes extends FrameMessageTypes {
+  'custom-type': { customField: string };
+}
+```
+
+**Example:**
+```typescript
+// Send an error message
+client.frame.postMessage('mgx-appview-error', {
+  errMsg: 'Error message',
+  stack: 'Error stack trace',
+});
+
+// Send a message with custom origin
+client.frame.postMessage('mgx-appview-error', {
+  errMsg: 'Error message',
+  stack: 'Error stack trace',
+}, {
+  targetOrigin: 'https://example.com',
+});
+
+// Send a message with custom target name
+client.frame.postMessage('mgx-appview-error', {
+  errMsg: 'Error message',
+  stack: 'Error stack trace',
+}, {
+  targetName: 'custom-window',
+});
+```
+
+#### `frame.createPage(path?)`
+
+Create a page by sending a `'mgx-create-page'` message to the parent window. This is a convenience method that uses `postMessage` internally.
+
+**Parameters:**
+- `path` (optional): Page path to create. If not provided, uses `window.location.pathname`
+
+**Example:**
+```typescript
+// Create page with current path
+client.frame.createPage();
+
+// Create page with specific path
+client.frame.createPage('/custom/path');
+```
+
+---
+
 ## Configuration
 
 ### Client Configuration Options

package/dist/index.d.ts

@@ -68,6 +68,10 @@ declare const createClient: (config?: ClientConfig) => {
     invoke<T = any>(params: ApiCallParams): Promise<axios0.AxiosResponse<T, any, {}>>;
   };
   integrations: Record<string, Record<string, IntegrationFunction>>;
+  frame: {
+    postMessage<T extends FrameMessageType>(type: T, data?: FrameMessageData<T>, options?: PostMessageOptions): void;
+    createPage(path?: string): void;
+  };
 };
 //#endregion
 //#region src/types/index.d.ts
@@ -93,6 +97,59 @@ interface ApiCallParams {
  * @returns Object containing invoke method for API calls
  */
 //#endregion
+//#region src/modules/frame.d.ts
+/**
+ * Default message type definitions
+ * Extend this interface to add custom message types
+ */
+interface DefaultFrameMessageTypes {
+  'mgx-appview-error': {
+    errMsg: string;
+    stack: string;
+  };
+  'mgx-create-page': {
+    path: string;
+  };
+}
+/**
+ * Message type map interface
+ * Extend this interface to add custom message types and their corresponding data types
+ * @example
+ * ```typescript
+ * interface CustomMessageTypes extends FrameMessageTypes {
+ *   'custom-type': { customField: string };
+ * }
+ * ```
+ */
+interface FrameMessageTypes extends DefaultFrameMessageTypes {}
+/**
+ * Extract message type keys from FrameMessageTypes
+ */
+type FrameMessageType = keyof FrameMessageTypes;
+/**
+ * Extract data type for a specific message type
+ */
+type FrameMessageData<T extends FrameMessageType> = FrameMessageTypes[T];
+/**
+ * PostMessage options interface
+ */
+interface PostMessageOptions {
+  /**
+   * Target origin for the message
+   * @default '*'
+   */
+  targetOrigin?: string;
+  /**
+   * Target window name
+   * @default window.name
+   */
+  targetName?: string;
+}
+/**
+ * Creates a frame module for frame-related operations
+ * @returns Object containing frame operation methods
+ */
+//#endregion
 //#region src/modules/integrations.d.ts
 /**
  * Integration function parameters interface
@@ -113,4 +170,4 @@ type IntegrationFunction = (params?: IntegrationParams) => Promise<AnyType>;
  */
 
 //#endregion
-export { type AnyType, type ApiCallParams, type ClientConfig, type IntegrationFunction, type IntegrationParams, type RequestConfig, createClient };
+export { type AnyType, type ApiCallParams, type ClientConfig, type DefaultFrameMessageTypes, type FrameMessageData, type FrameMessageType, type FrameMessageTypes, type IntegrationFunction, type IntegrationParams, type PostMessageOptions, type RequestConfig, createClient };

package/dist/index.js

@@ -1 +1 @@
-import e from"axios";import t from"qs";const n=e=>{let t=e.response?.status;if(t&&t>=400&&t!==401)try{typeof window<`u`&&window.top&&window.top?.postMessage({type:`mgx-appview-error`,targetName:window.name,data:{errMsg:e.response?.data?.message||e.response?.data?.detail||``,stack:e.response?.data?.error||JSON.stringify(e?.response||{})}},`*`)}catch(e){console.warn(`Failed to notify parent window about API error:`,e)}},r=(r={})=>{let{onUnauthorized:i,...a}=r,o=typeof globalThis<`u`&&`localStorage`in globalThis&&typeof globalThis.localStorage?.getItem==`function`?globalThis.localStorage.getItem(`token`)??void 0:void 0,s={timeout:6e4,paramsSerializer:e=>t.stringify(e,{arrayFormat:`brackets`}),...a,headers:{"Content-Type":`application/json`,...o?{Authorization:`Bearer ${o}`}:{},...a.headers}},c=e.create(s);return c.interceptors.request.use(e=>e,e=>Promise.reject(e)),c.interceptors.response.use(e=>e,e=>{let t=e.response?.status;return t===401&&i&&i(),n(e),Promise.reject(e)}),c},i=e=>typeof e==`string`?e.startsWith(`_`)||e.startsWith(`$`)||e===`constructor`||e===`toString`||e===`valueOf`||e===`inspect`||e===`toJSON`:!0,a=()=>{let e=window.location?.href??``,t=``;e.startsWith(`/`)?t=e:e&&(t=e.replace(/^[a-z][a-z0-9+.-]*:\/\/[^/]+/i,``));let n=new URLSearchParams({from_url:t});window.location.href=`/api/v1/auth/login?${n.toString()}`},o=e=>{let{requestInstance:t}=e;return{async login(){let e=new URLSearchParams(window.location.search),t=e.get(`token`);return t&&typeof globalThis<`u`&&`localStorage`in globalThis&&(globalThis.localStorage?.setItem(`token`,t),window.location.href=`/`),t},async me(){return t.get(`/api/v1/auth/me`)},async logout(){typeof globalThis<`u`&&`localStorage`in globalThis&&globalThis.localStorage?.removeItem(`token`);let e=await t.get(`/api/v1/auth/logout`);return window.location.href=`/`,e},toLogin:a}},s=e=>{let{requestInstance:t,entityName:n}=e,r=`/api/v1/entities/${n}`,i=e=>{if(!e)return;let t={...e};return e.fields&&Array.isArray(e.fields)&&(t.fields=e.fields.join(`,`)),e.query&&typeof e.query==`object`&&(t.query=JSON.stringify(e.query)),t};return{async query(e){let n=i(e);return t.get(r,{params:n})},async queryAll(e){let n=i(e);return t.get(`${r}/all`,{params:n})},async get(e){let{id:n,...a}=e,o=i(a);return t.get(`${r}/${n}`,{params:o})},async create(e){return t.post(r,e.data)},async update(e){return t.put(`${r}/${e.id}`,e.data)},async delete(e){return t.delete(`${r}/${e.id}`)},async deleteBatch(e){return t.delete(`${r}/batch`,{data:{ids:e.ids}})},async createBatch(e){return t.post(`${r}/batch`,e.data)},async updateBatch(e){return t.put(`${r}/batch`,e.data)}}},c=e=>{let{requestInstance:t}=e,n=new Map;return new Proxy({},{get(e,r){if(!i(r))return n.has(r)||n.set(r,s({requestInstance:t,entityName:r})),n.get(r)}})},l=e=>{let{requestInstance:t}=e;return{async invoke(e){let{url:n,method:r=`GET`,data:i,options:a={}}=e,o={method:r.toUpperCase(),url:n,...a};return i&&[`POST`,`PUT`,`PATCH`].includes(o.method)?o.data=i:i&&[`GET`,`DELETE`].includes(o.method)&&(o.params=i),t.request(o)}}},u=e=>{let{requestInstance:t}=e;return new Proxy({},{get(e,n){if(!i(n))return new Proxy({},{get(e,r){if(!i(r))return(e={})=>{let i=`/api/integrations/core/${r}`;n!==`core`&&(i=`/api/integrations/providers/${n}/${r}`);let{payload:a={},option:o={}}=e,s=a instanceof FormData?{...o,headers:{...o.headers,"Content-Type":void 0}}:o;return t.post(i,a,s)}}})}})},d=(e={})=>{let t=r({baseURL:`/`,...e}),n=o({requestInstance:t}),i=c({requestInstance:t}),a=l({requestInstance:t}),s=u({requestInstance:t});return{auth:n,entities:i,apiCall:a,integrations:s}};export{d as createClient};
+import e from"axios";import t from"qs";const n=e=>{let t=e.response?.status;if(t&&t>=400&&t!==401)try{typeof window<`u`&&window.top&&window.top?.postMessage({type:`mgx-appview-error`,targetName:window.name,data:{errMsg:e.response?.data?.message||e.response?.data?.detail||`Server Error`,stack:JSON.stringify({url:e.response?.config?.url,data:e.response?.data,status:e.response?.status})}},`*`)}catch(e){console.warn(`Failed to notify parent window about API error:`,e)}},r=(r={})=>{let{onUnauthorized:i,...a}=r,o=typeof globalThis<`u`&&`localStorage`in globalThis&&typeof globalThis.localStorage?.getItem==`function`?globalThis.localStorage.getItem(`token`)??void 0:void 0,s={timeout:6e4,paramsSerializer:e=>t.stringify(e,{arrayFormat:`brackets`}),...a,headers:{"Content-Type":`application/json`,...o?{Authorization:`Bearer ${o}`}:{},...a.headers}},c=e.create(s);return c.interceptors.request.use(e=>e,e=>Promise.reject(e)),c.interceptors.response.use(e=>e,e=>{let t=e.response?.status;return t===401&&i&&i(),n(e),Promise.reject(e)}),c},i=e=>typeof e==`string`?e.startsWith(`_`)||e.startsWith(`$`)||e===`constructor`||e===`toString`||e===`valueOf`||e===`inspect`||e===`toJSON`:!0,a=()=>{let e=window.location?.href??``,t=``;e.startsWith(`/`)?t=e:e&&(t=e.replace(/^[a-z][a-z0-9+.-]*:\/\/[^/]+/i,``));let n=new URLSearchParams({from_url:t});window.location.href=`/api/v1/auth/login?${n.toString()}`},o=e=>{let{requestInstance:t}=e;return{async login(){let e=new URLSearchParams(window.location.search),t=e.get(`token`);return t&&typeof globalThis<`u`&&`localStorage`in globalThis&&(globalThis.localStorage?.setItem(`token`,t),window.location.href=`/`),t},async me(){return t.get(`/api/v1/auth/me`)},async logout(){typeof globalThis<`u`&&`localStorage`in globalThis&&globalThis.localStorage?.removeItem(`token`);let e=await t.get(`/api/v1/auth/logout`);return window.location.href=`/`,e},toLogin:a}},s=e=>{let{requestInstance:t,entityName:n}=e,r=`/api/v1/entities/${n}`,i=e=>{if(!e)return;let t={...e};return e.fields&&Array.isArray(e.fields)&&(t.fields=e.fields.join(`,`)),e.query&&typeof e.query==`object`&&(t.query=JSON.stringify(e.query)),t};return{async query(e){let n=i(e);return t.get(r,{params:n})},async queryAll(e){let n=i(e);return t.get(`${r}/all`,{params:n})},async get(e){let{id:n,...a}=e,o=i(a);return t.get(`${r}/${n}`,{params:o})},async create(e){return t.post(r,e.data)},async update(e){return t.put(`${r}/${e.id}`,e.data)},async delete(e){return t.delete(`${r}/${e.id}`)},async deleteBatch(e){return t.delete(`${r}/batch`,{data:{ids:e.ids}})},async createBatch(e){return t.post(`${r}/batch`,e.data)},async updateBatch(e){return t.put(`${r}/batch`,e.data)}}},c=e=>{let{requestInstance:t}=e,n=new Map;return new Proxy({},{get(e,r){if(!i(r))return n.has(r)||n.set(r,s({requestInstance:t,entityName:r})),n.get(r)}})},l=e=>{let{requestInstance:t}=e;return{async invoke(e){let{url:n,method:r=`GET`,data:i,options:a={}}=e,o={method:r.toUpperCase(),url:n,...a};return i&&[`POST`,`PUT`,`PATCH`].includes(o.method)?o.data=i:i&&[`GET`,`DELETE`].includes(o.method)&&(o.params=i),t.request(o)}}},u=e=>{let{requestInstance:t}=e;return new Proxy({},{get(e,n){if(!i(n))return new Proxy({},{get(e,r){if(!i(r))return(e={})=>{let i=`/api/integrations/core/${r}`;n!==`core`&&(i=`/api/integrations/providers/${n}/${r}`);let{payload:a={},option:o={}}=e,s=a instanceof FormData?{...o,headers:{...o.headers,"Content-Type":void 0}}:o;return t.post(i,a,s)}}})}})},d=()=>({postMessage(e,t,n){if(typeof window>`u`||!window.top){console.warn(`postMessage: window.top is not available`);return}try{let{targetOrigin:r=`*`,targetName:i=window.name}=n||{},a={type:e,targetName:i,data:t};window.top.postMessage(a,r)}catch(e){console.warn(`Failed to send postMessage:`,e)}},createPage(e){let t=e??window.location.pathname;this.postMessage(`mgx-create-page`,{path:t})}}),f=(e={})=>{let t=r({baseURL:`/`,...e}),n=o({requestInstance:t}),i=c({requestInstance:t}),a=l({requestInstance:t}),s=u({requestInstance:t}),f=d();return{auth:n,entities:i,apiCall:a,integrations:s,frame:f}};export{f as createClient};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@metagptx/web-sdk",
   "type": "module",
-  "version": "0.0.21",
+  "version": "0.0.23",
   "packageManager": "pnpm@10.15.0+sha512.486ebc259d3e999a4e8691ce03b5cac4a71cbeca39372a9b762cb500cfdf0873e2cb16abe3d951b1ee2cf012503f027b98b6584e4df22524e0c7450d9ec7aa7b",
   "description": "TypeScript SDK for interacting with FuncSea API",
   "author": "MetaGPTX",