{"_id":"@belongnet/bridge-sdk","_rev":"3-9c60de57337da36918532d21bb8231a4","name":"@belongnet/bridge-sdk","dist-tags":{"latest":"0.1.6"},"versions":{"0.1.3":{"name":"@belongnet/bridge-sdk","version":"0.1.3","keywords":["belong","iframe","bridge","penpal","sdk"],"author":{"name":"Belong"},"license":"MIT","_id":"@belongnet/bridge-sdk@0.1.3","maintainers":[{"name":"reslear","email":"reslear@gmail.com"},{"name":"belongfoundation","email":"join@belong.net"}],"dist":{"shasum":"3ef475cc01c72c17052c75f5b659c656fb95640d","tarball":"https://registry.npmjs.org/@belongnet/bridge-sdk/-/bridge-sdk-0.1.3.tgz","fileCount":2,"integrity":"sha512-3sF5qYUm3gEFgg6PSbtvMXm5AZAtWLFraXY450jMldZqyW4wJVGijoKW7340jOiIHb/96aRieBaZTSziKp4hcw==","signatures":[{"sig":"MEUCIQCndlYWBoMyEKWLHRjBcqRoOBOEJsjnLum5N2s9F+ykyAIgG2OtR4/eYJ75yYVFB2TWtEv/kffy+RIKzS4E7iwNQRk=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":3959},"main":"./dist/index.mjs","type":"module","types":"./dist/index.d.mts","module":"./dist/index.mjs","exports":{".":{"types":"./dist/index.d.mts","import":"./dist/index.mjs"}},"gitHead":"d7077ca837e3ce78714294d9bd8fff1ae3c1550f","scripts":{"build":"tsdown","typecheck":"tsc --noEmit"},"_npmUser":{"name":"belongfoundation","email":"join@belong.net"},"_npmVersion":"10.9.4","description":"Type-safe iframe ↔ host bridge for Belong apps","directories":{},"_nodeVersion":"22.21.1","dependencies":{"zod":"^4.2.1","penpal":"^7.0.4"},"_hasShrinkwrap":false,"devDependencies":{"tsdown":"^0.19.0","typescript":"^5.9.3"},"_npmOperationalInternal":{"tmp":"tmp/bridge-sdk_0.1.3_1768323047915_0.9740893203432202","host":"s3://npm-registry-packages-npm-production"}},"0.1.5":{"name":"@belongnet/bridge-sdk","version":"0.1.5","keywords":["belong","iframe","bridge","penpal","sdk"],"author":{"name":"Belong"},"license":"MIT","_id":"@belongnet/bridge-sdk@0.1.5","maintainers":[{"name":"reslear","email":"reslear@gmail.com"},{"name":"belongfoundation","email":"join@belong.net"}],"homepage":"https://github.com/belongnet/bridge-sdk#readme","bugs":{"url":"https://github.com/belongnet/bridge-sdk/issues"},"dist":{"shasum":"03fe80a5dad3e9c8c08d6fedc137e94acc7defb7","tarball":"https://registry.npmjs.org/@belongnet/bridge-sdk/-/bridge-sdk-0.1.5.tgz","fileCount":2,"integrity":"sha512-P0E5MVKnib5j94cyfqlK/zSCcZpHecWiqy3VRrmEfHQbU12fuIa7fNmnC2AgD/xDDI0gbxgTWbdIEM7unyg/kw==","signatures":[{"sig":"MEUCIF9ljF20HImvZOg2O1nIJ+Lp2rf7qzpnr6iB6XhqBgBqAiEA0t6UvV3tyRCf+ngUiQJI8RZH6cspZPR7Fqh+JoU+Mdk=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@belongnet%2fbridge-sdk@0.1.5","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":4054},"main":"./dist/index.mjs","type":"module","types":"./dist/index.d.mts","module":"./dist/index.mjs","exports":{".":{"types":"./dist/index.d.mts","import":"./dist/index.mjs"}},"gitHead":"04f129d71c0ba6d0c28fc84181719fa20c918b9e","scripts":{"build":"tsdown","typecheck":"tsc --noEmit"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:337b32c0-257b-4cae-a412-938c1c5613d4"}},"repository":{"url":"git+https://github.com/belongnet/bridge-sdk.git","type":"git"},"_npmVersion":"11.6.2","description":"Type-safe iframe ↔ host bridge for Belong apps","directories":{},"_nodeVersion":"24.12.0","dependencies":{"zod":"^4.2.1","penpal":"^7.0.4"},"_hasShrinkwrap":false,"devDependencies":{"tsdown":"^0.19.0","typescript":"^5.9.3"},"_npmOperationalInternal":{"tmp":"tmp/bridge-sdk_0.1.5_1768325761601_0.7647188859000993","host":"s3://npm-registry-packages-npm-production"}},"0.1.6":{"name":"@belongnet/bridge-sdk","version":"0.1.6","description":"Type-safe iframe ↔ host bridge for Belong apps","type":"module","main":"./dist/index.mjs","module":"./dist/index.mjs","types":"./dist/index.d.mts","exports":{".":{"types":"./dist/index.d.mts","import":"./dist/index.mjs"}},"scripts":{"build":"tsdown","typecheck":"tsc --noEmit"},"keywords":["belong","iframe","bridge","penpal","sdk"],"author":{"name":"Belong"},"license":"MIT","dependencies":{"penpal":"^7.0.4","zod":"^4.2.1"},"devDependencies":{"tsdown":"^0.19.0","typescript":"^5.9.3"},"repository":{"type":"git","url":"git+https://github.com/belongnet/bridge-sdk.git"},"gitHead":"85829468990c66073e4cc1e2ddbccaa3479bb095","_id":"@belongnet/bridge-sdk@0.1.6","bugs":{"url":"https://github.com/belongnet/bridge-sdk/issues"},"homepage":"https://github.com/belongnet/bridge-sdk#readme","_nodeVersion":"24.12.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-Y7dZ9oef0CnIpI/1JSBA4VoZPen0hl/zvtRjkZjf1V5G5AE/fCi12vBIJz4HC6byUW0jzKVEMGlA2fytngmOfQ==","shasum":"dac9f3b0a70fe1e4bbbd8ada8c59a7172ec60d9e","tarball":"https://registry.npmjs.org/@belongnet/bridge-sdk/-/bridge-sdk-0.1.6.tgz","fileCount":2,"unpackedSize":4054,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@belongnet%2fbridge-sdk@0.1.6","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQC8V9B2djVGFGTExCoKToH9mBLj0ngCC48Pn8BiNmJWiQIhAL2TXkhDi3rOiPtS9q6IrAuNA28FuDQKJDiN3dkXRoOB"}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:337b32c0-257b-4cae-a412-938c1c5613d4"}},"directories":{},"maintainers":[{"name":"reslear","email":"reslear@gmail.com"},{"name":"belongfoundation","email":"join@belong.net"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/bridge-sdk_0.1.6_1768327407337_0.80547730671675"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-13T16:50:47.728Z","modified":"2026-01-13T18:03:27.968Z","0.1.3":"2026-01-13T16:50:48.057Z","0.1.5":"2026-01-13T17:36:01.757Z","0.1.6":"2026-01-13T18:03:27.517Z"},"bugs":{"url":"https://github.com/belongnet/bridge-sdk/issues"},"author":{"name":"Belong"},"license":"MIT","homepage":"https://github.com/belongnet/bridge-sdk#readme","keywords":["belong","iframe","bridge","penpal","sdk"],"repository":{"type":"git","url":"git+https://github.com/belongnet/bridge-sdk.git"},"description":"Type-safe iframe ↔ host bridge for Belong apps","maintainers":[{"name":"reslear","email":"reslear@gmail.com"},{"name":"belongfoundation","email":"join@belong.net"}],"readme":"# @belongnet/bridge-sdk\n\nTyped iframe ↔ host bridge for Belong apps. Provides a safe, validated RPC layer between an embedded frame and its host.\n\n## Installation\n\n```sh\npnpm add @belongnet/bridge-sdk\n```\n\n## Quick start\n\n### Iframe (frame -> host)\n\n```ts\nimport { connectToHost } from '@belongnet/bridge-sdk'\n\nconst { remote, destroy } = await connectToHost({\n  allowedOrigins: ['https://app.belong.net', 'capacitor://localhost'],\n  methods: {\n    async setTheme(theme) {\n      document.documentElement.dataset.theme = theme\n    },\n  },\n})\n\nconst location = await remote.getLocation()\nawait remote.showToast({ message: 'Hello from frame', type: 'success' })\n\ndestroy() // optional cleanup\n```\n\n### Host (host -> frame)\n\n```ts\nimport { connectHost } from '@belongnet/bridge-sdk'\n\nconst iframe = document.querySelector<HTMLIFrameElement>('#belong-frame')!\n\nconst { destroy } = await connectHost({\n  iframe,\n  allowedOrigins: ['https://frame.belong.net'],\n  methods: {\n    async getLocation() {\n      const loc = await CapacitorGeolocation.getCurrentPosition()\n      return {\n        lat: loc.coords.latitude,\n        lng: loc.coords.longitude,\n        accuracy: loc.coords.accuracy,\n        ts: Date.now(),\n      }\n    },\n    async showToast({ message, type }) {\n      const variant = type === 'error' ? 'danger' : 'success'\n      AppToast.show({ message, variant })\n    },\n  },\n})\n\n// Destroy when the iframe is removed or reloaded.\ndestroy()\n```\n\n## Available methods\n\n### Host methods (frame -> host)\n\n#### `getLocation`\n\n- **Signature:** `getLocation(): Promise<LocationPayload>`\n- **Purpose:** Returns the best-known device coordinates (lat/lng) along with optional accuracy and timestamp metadata supplied by the host app.\n- **Schema:** enforced via Zod on both the frame and host side\n\n```ts\nconst locationSchema = z.object({\n  lat: z.number(),\n  lng: z.number(),\n  accuracy: z.number().optional(),\n  ts: z.number().optional(),\n})\n\ntype LocationPayload = z.infer<typeof locationSchema>\n```\n\n#### `showToast`\n\n- **Signature:** `showToast(payload: ToastPayload): Promise<void>`\n- **Purpose:** Allows the frame to display a host-native toast notification.\n- **Schema:** enforced via Zod on both the frame and host side\n\n```ts\nconst toastSchema = z.object({\n  message: z.string().min(1),\n  icon: z.string().optional(),\n  type: z.enum(['error', 'success']),\n})\n\ntype ToastPayload = z.infer<typeof toastSchema>\n```\n\n### Frame methods (host -> frame)\n\n#### `setTheme`\n\n- **Signature:** `setTheme(theme: ThemeMode): Promise<void>`\n- **Purpose:** Lets the host notify the iframe about theme changes.\n- **Schema:** constrained to explicit theme values\n\n```ts\ntype ThemeMode = 'light' | 'dark'\n```\n\nAll responses are validated with Zod before being exposed to callers, ensuring the bridge stays resilient as new native capabilities are added.\n\n## Development\n\nClone the repository and install dependencies:\n\n```sh\npnpm install\npnpm run build\n```\n\nImplement new feature, check build, and make PR.\n\n\n## Stack\n\n- [Penpal](https://github.com/Aaronius/penpal) — RPC + postMessage bridge\n- [Zod](https://zod.dev/) — runtime schema validation\n- [TypeScript](https://www.typescriptlang.org/) — strict type safety\n\n## License\n\nMIT\n","readmeFilename":"README.md"}