{"id":17695,"library":"http-post-message","title":"HTTP Post Message","description":"The `http-post-message` package provides a generic messaging component to facilitate HTTP-style communication over the `window.postMessage` API. It abstracts the raw `postMessage` mechanics into familiar HTTP methods like `get`, `post`, `put`, `patch`, and `delete`, allowing developers to send structured requests and receive responses with HTTP semantics (e.g., status codes, headers). The current stable version is `0.3.0`. It does not implement the underlying `postMessage` transport itself but requires an external implementation of an `IPostMessage` interface, most commonly fulfilled by the `window-post-message-proxy` library, which Microsoft also maintains. Its key differentiator is bringing a robust, HTTP-like request/response pattern to cross-window and cross-iframe communication, simplifying complex messaging scenarios.","status":"maintenance","version":"0.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/Microsoft/http-post-message","tags":["javascript","Microsoft","post","message","http","iframe","protocol","typescript"],"install":[{"cmd":"npm install http-post-message","lang":"bash","label":"npm"},{"cmd":"yarn add http-post-message","lang":"bash","label":"yarn"},{"cmd":"pnpm add http-post-message","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This library requires an implementation of `IPostMessage` to handle the actual `window.postMessage` transport. `window-post-message-proxy` is the recommended and typical dependency for this.","package":"window-post-message-proxy","optional":false}],"imports":[{"note":"The primary class for creating an HTTP-style message sender. Named import is standard.","wrong":"const HttpPostMessage = require('http-post-message').HttpPostMessage;","symbol":"HttpPostMessage","correct":"import { HttpPostMessage } from 'http-post-message';"},{"note":"TypeScript interface used to define the contract for the postMessage proxy. Use `type` import where available.","symbol":"IPostMessage","correct":"import type { IPostMessage } from 'http-post-message';"},{"note":"These are static methods on the `HttpPostMessage` class, typically used to configure `window-post-message-proxy` for correct message processing.","wrong":"import { addTrackingProperties } from 'http-post-message';","symbol":"HttpPostMessage.addTrackingProperties","correct":"import { HttpPostMessage } from 'http-post-message';\n// ... then use HttpPostMessage.addTrackingProperties"}],"quickstart":{"code":"import { HttpPostMessage } from 'http-post-message';\nimport { WindowPostMessageProxy } from 'window-post-message-proxy';\n\n// 1. Set up a mock postMessage proxy (for demonstration)\n// In a real app, you would use WindowPostMessageProxy configured correctly.\nconst stubPostMessageProxy = {\n  postMessage: (message: any, targetOrigin?: string, targetWindow?: Window) => {\n    console.log('Sending message:', message);\n    // Simulate receiving a response after a delay\n    return Promise.resolve({\n      id: message.id, // Important for correlation\n      data: { status: 200, body: `Echo: ${JSON.stringify(message.data)}` },\n      error: null\n    });\n  },\n};\n\n// 2. Instantiate HttpPostMessage with the proxy\nconst httpPostMessage = new HttpPostMessage(stubPostMessageProxy);\n\n// 3. Make an HTTP-style GET request\nasync function runExample() {\n  try {\n    console.log('Making GET request to target/path...');\n    const response = await httpPostMessage.get('target/path', { headers: { 'X-Custom-Header': 'value' } });\n    console.log('Received response:', response.body);\n\n    // 4. Make an HTTP-style POST request\n    console.log('\\nMaking POST request to /api/data...');\n    const postResponse = await httpPostMessage.post('/api/data', { item: 'new item' });\n    console.log('Received POST response:', postResponse.body);\n\n  } catch (error) {\n    console.error('Request failed:', error);\n  }\n}\n\nrunExample();\n\n/* Example output (simplified):\nSending message: { id: '...', url: 'target/path', method: 'GET', data: {}, headers: { 'X-Custom-Header': 'value' } }\nReceived response: Echo: {}\n\nMaking POST request to /api/data...\nSending message: { id: '...', url: '/api/data', method: 'POST', data: { item: 'new item' }, headers: {} }\nReceived POST response: Echo: {\"item\":\"new item\"}\n*/","lang":"typescript","description":"Demonstrates how to instantiate `HttpPostMessage` with a basic proxy and perform `get` and `post` requests, illustrating the HTTP-style API."},"warnings":[{"fix":"Ensure you have `window-post-message-proxy` installed and correctly configured and pass its instance to the `HttpPostMessage` constructor.","message":"This package solely provides the HTTP-style abstraction layer and does NOT implement the actual `window.postMessage` transport. It critically depends on an external library (like `window-post-message-proxy`) to handle the sending and receiving of messages.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Pin the exact version (`npm install --save-exact http-post-message@0.3.0`) or thoroughly test updates before deploying to production.","message":"The package is still in a `0.x.x` version range. This implies that the API might not be stable and could introduce breaking changes in minor versions without adhering to strict semver for major API shifts.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"When initializing `WindowPostMessageProxy`, use `hpm.HttpPostMessage.addTrackingProperties`, `hpm.HttpPostMessage.getTrackingProperties`, and `hpm.HttpPostMessage.isErrorMessage` as shown in the package's documentation to ensure proper message tracking and error handling.","message":"Correct configuration of `window-post-message-proxy` is essential for `http-post-message` to interpret responses correctly. Specifically, `processTrackingProperties` and `isErrorMessage` callbacks must be set using `HttpPostMessage`'s static methods.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Ensure an object implementing the `IPostMessage` interface (e.g., an instance of `WindowPostMessageProxy`) is passed as the first argument to the `HttpPostMessage` constructor.","cause":"`HttpPostMessage` was instantiated without a valid `IPostMessage` implementation, or the provided object does not have a `postMessage` method.","error":"TypeError: Cannot read properties of undefined (reading 'postMessage')"},{"fix":"Verify that `window-post-message-proxy` on both sending and receiving sides uses `HttpPostMessage.addTrackingProperties` and `HttpPostMessage.getTrackingProperties` in its `processTrackingProperties` configuration.","cause":"The `window-post-message-proxy` (or equivalent) on the receiving end is not correctly configured to track messages or is not sending back correlation IDs required by `http-post-message`.","error":"Promise never resolves for http-post-message request."},{"fix":"Ensure `window-post-message-proxy` is configured with `isErrorMessage: HttpPostMessage.isErrorMessage` during its instantiation to properly classify incoming messages as errors based on HTTP semantics.","cause":"The `isErrorMessage` configuration in `window-post-message-proxy` is not correctly identifying error responses from the receiving frame.","error":"Error: Request failed with status code 500 (or other HTTP error code), but the underlying message was not an error."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}