hablcast-sdk 1.0.0

package/README.md

@@ -0,0 +1,87 @@
+# HABLCAST Mini-App Bridge SDK
+
+The official SDK for integrating third-party mini-applications with the HABLCAST host application shell. 
+
+It handles cross-origin message passing (`window.postMessage`) between the child iframe (mini-app) and the parent window (HABLCAST).
+
+## Installation
+
+### Via NPM
+
+```bash
+npm install @hablcast/sdk
+```
+
+### Via CDN (Script Tag)
+
+```html
+<script src="https://hablcast.vercel.app/sdk/v1/hablcast-sdk.js"></script>
+```
+
+---
+
+## Quickstart
+
+### 1. Initialize Handshake
+
+Your mini-app should call `hablcast.ready()` as soon as it is loaded to start the handshake with the parent application.
+
+```javascript
+import { hablcast } from '@hablcast/sdk';
+
+// Start handshake
+hablcast.ready();
+```
+
+### 2. Subscribe to Context Updates
+
+Listen to user profiles, current theme, and environment configuration changes.
+
+```javascript
+const unsubscribe = hablcast.onContext((context) => {
+  console.log("Current Username:", context.user.username);
+  console.log("Wallet Address:", context.user.address);
+  console.log("Theme:", context.theme); // "light" or "dark"
+});
+
+// To unsubscribe later:
+// unsubscribe();
+```
+
+### 3. Request Signature
+
+Request the user to sign a message using their connected wallet.
+
+```javascript
+try {
+  const { signature } = await hablcast.requestSignature("Sign in to Predict-a-Friend");
+  console.log("Signed message successfully:", signature);
+} catch (error) {
+  console.error("Signature request rejected:", error.message);
+}
+```
+
+### 4. Send Transaction
+
+Trigger on-chain interactions. The HABLCAST parent will present a transaction confirmation modal to the user.
+
+```javascript
+try {
+  const { txHash } = await hablcast.sendTransaction({
+    to: "0x000000000000000000000000000000000000dEaD",
+    data: "0x",
+    value: "10000000000000000" // 0.01 ETH in wei
+  });
+  console.log("Transaction executed. Hash:", txHash);
+} catch (error) {
+  console.error("Transaction failed or was rejected:", error.message);
+}
+```
+
+### 5. Close Mini-App
+
+Request the parent application to close your mini-app.
+
+```javascript
+hablcast.close();
+```

package/dist/index.d.mts

@@ -0,0 +1,23 @@
+/**
+ * HABLCAST Mini-App Client SDK
+ * This file contains the client-side library that third-party mini-apps run inside their iframes.
+ * It establishes a secure postMessage bridge with the HABLCAST host parent window.
+ */
+interface UserProfile {
+    address: string;
+    username: string;
+    avatar?: string;
+}
+interface HablcastContext {
+    user: UserProfile;
+    theme: "light" | "dark";
+    environment: "development" | "production";
+}
+interface TransactionRequest {
+    to: `0x${string}`;
+    data: `0x${string}`;
+    value?: string;
+}
+declare const hablcast: any;
+
+export { type HablcastContext, type TransactionRequest, type UserProfile, hablcast };

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * HABLCAST Mini-App Client SDK
+ * This file contains the client-side library that third-party mini-apps run inside their iframes.
+ * It establishes a secure postMessage bridge with the HABLCAST host parent window.
+ */
+interface UserProfile {
+    address: string;
+    username: string;
+    avatar?: string;
+}
+interface HablcastContext {
+    user: UserProfile;
+    theme: "light" | "dark";
+    environment: "development" | "production";
+}
+interface TransactionRequest {
+    to: `0x${string}`;
+    data: `0x${string}`;
+    value?: string;
+}
+declare const hablcast: any;
+
+export { type HablcastContext, type TransactionRequest, type UserProfile, hablcast };

package/dist/index.global.js

@@ -0,0 +1 @@
+"use strict";var hablcast=(()=>{var c=Object.defineProperty;var d=Object.getOwnPropertyDescriptor;var u=Object.getOwnPropertyNames;var h=Object.prototype.hasOwnProperty;var p=(i,e)=>{for(var s in e)c(i,s,{get:e[s],enumerable:!0})},f=(i,e,s,n)=>{if(e&&typeof e=="object"||typeof e=="function")for(let t of u(e))!h.call(i,t)&&t!==s&&c(i,t,{get:()=>e[t],enumerable:!(n=d(e,t))||n.enumerable});return i};var b=i=>f(c({},"__esModule",{value:!0}),i);var w={};p(w,{hablcast:()=>g});var o=class{constructor(){this.callbacks=new Map;this.context=null;this.contextListeners=[];this.isInitialized=!1;typeof window<"u"&&window.addEventListener("message",this.handleMessage.bind(this))}ready(){if(typeof window>"u")return;this.isInitialized=!0;let e=()=>{this.context||(window.parent.postMessage({type:"hablcast:ready"},"*"),setTimeout(e,500))};e()}onContext(e){return this.contextListeners.push(e),this.context&&e(this.context),()=>{this.contextListeners=this.contextListeners.filter(s=>s!==e)}}getContext(){return this.context}requestSignature(e){return this.sendRequest("hablcast:request_sign",{message:e})}sendTransaction(e){return this.sendRequest("hablcast:request_transaction",e)}close(){typeof window>"u"||window.parent.postMessage({type:"hablcast:close"},"*")}sendRequest(e,s){if(typeof window>"u")return Promise.reject(new Error("SDK can only be used in browser environment"));let n=Math.random().toString(36).substring(2,9);return new Promise((t,a)=>{this.callbacks.set(n,{resolve:t,reject:a}),window.parent.postMessage({type:e,payload:s,requestId:n},"*")})}handleMessage(e){let s=e.data;if(!s||typeof s!="object")return;let{type:n,requestId:t,payload:a}=s;if(!(typeof n!="string"||!n.startsWith("hablcast:"))){if(n==="hablcast:context")this.context=a,this.contextListeners.forEach(r=>{try{r(a)}catch(l){console.error("Error in onContext listener callback:",l)}});else if(n==="hablcast:response"&&t){let r=this.callbacks.get(t);r&&(r.resolve(a),this.callbacks.delete(t))}else if(n==="hablcast:error"&&t){let r=this.callbacks.get(t);r&&(r.reject(new Error(a.message||"Request failed")),this.callbacks.delete(t))}}}},g=typeof window<"u"?window.hablcast=window.hablcast||new o:new o;return b(w);})();

package/dist/index.js

@@ -0,0 +1 @@
+"use strict";var c=Object.defineProperty;var d=Object.getOwnPropertyDescriptor;var u=Object.getOwnPropertyNames;var h=Object.prototype.hasOwnProperty;var p=(i,e)=>{for(var s in e)c(i,s,{get:e[s],enumerable:!0})},f=(i,e,s,n)=>{if(e&&typeof e=="object"||typeof e=="function")for(let t of u(e))!h.call(i,t)&&t!==s&&c(i,t,{get:()=>e[t],enumerable:!(n=d(e,t))||n.enumerable});return i};var b=i=>f(c({},"__esModule",{value:!0}),i);var w={};p(w,{hablcast:()=>g});module.exports=b(w);var o=class{constructor(){this.callbacks=new Map;this.context=null;this.contextListeners=[];this.isInitialized=!1;typeof window<"u"&&window.addEventListener("message",this.handleMessage.bind(this))}ready(){if(typeof window>"u")return;this.isInitialized=!0;let e=()=>{this.context||(window.parent.postMessage({type:"hablcast:ready"},"*"),setTimeout(e,500))};e()}onContext(e){return this.contextListeners.push(e),this.context&&e(this.context),()=>{this.contextListeners=this.contextListeners.filter(s=>s!==e)}}getContext(){return this.context}requestSignature(e){return this.sendRequest("hablcast:request_sign",{message:e})}sendTransaction(e){return this.sendRequest("hablcast:request_transaction",e)}close(){typeof window>"u"||window.parent.postMessage({type:"hablcast:close"},"*")}sendRequest(e,s){if(typeof window>"u")return Promise.reject(new Error("SDK can only be used in browser environment"));let n=Math.random().toString(36).substring(2,9);return new Promise((t,a)=>{this.callbacks.set(n,{resolve:t,reject:a}),window.parent.postMessage({type:e,payload:s,requestId:n},"*")})}handleMessage(e){let s=e.data;if(!s||typeof s!="object")return;let{type:n,requestId:t,payload:a}=s;if(!(typeof n!="string"||!n.startsWith("hablcast:"))){if(n==="hablcast:context")this.context=a,this.contextListeners.forEach(r=>{try{r(a)}catch(l){console.error("Error in onContext listener callback:",l)}});else if(n==="hablcast:response"&&t){let r=this.callbacks.get(t);r&&(r.resolve(a),this.callbacks.delete(t))}else if(n==="hablcast:error"&&t){let r=this.callbacks.get(t);r&&(r.reject(new Error(a.message||"Request failed")),this.callbacks.delete(t))}}}},g=typeof window<"u"?window.hablcast=window.hablcast||new o:new o;0&&(module.exports={hablcast});

package/dist/index.mjs

@@ -0,0 +1 @@
+var a=class{constructor(){this.callbacks=new Map;this.context=null;this.contextListeners=[];this.isInitialized=!1;typeof window<"u"&&window.addEventListener("message",this.handleMessage.bind(this))}ready(){if(typeof window>"u")return;this.isInitialized=!0;let e=()=>{this.context||(window.parent.postMessage({type:"hablcast:ready"},"*"),setTimeout(e,500))};e()}onContext(e){return this.contextListeners.push(e),this.context&&e(this.context),()=>{this.contextListeners=this.contextListeners.filter(n=>n!==e)}}getContext(){return this.context}requestSignature(e){return this.sendRequest("hablcast:request_sign",{message:e})}sendTransaction(e){return this.sendRequest("hablcast:request_transaction",e)}close(){typeof window>"u"||window.parent.postMessage({type:"hablcast:close"},"*")}sendRequest(e,n){if(typeof window>"u")return Promise.reject(new Error("SDK can only be used in browser environment"));let t=Math.random().toString(36).substring(2,9);return new Promise((s,r)=>{this.callbacks.set(t,{resolve:s,reject:r}),window.parent.postMessage({type:e,payload:n,requestId:t},"*")})}handleMessage(e){let n=e.data;if(!n||typeof n!="object")return;let{type:t,requestId:s,payload:r}=n;if(!(typeof t!="string"||!t.startsWith("hablcast:"))){if(t==="hablcast:context")this.context=r,this.contextListeners.forEach(i=>{try{i(r)}catch(o){console.error("Error in onContext listener callback:",o)}});else if(t==="hablcast:response"&&s){let i=this.callbacks.get(s);i&&(i.resolve(r),this.callbacks.delete(s))}else if(t==="hablcast:error"&&s){let i=this.callbacks.get(s);i&&(i.reject(new Error(r.message||"Request failed")),this.callbacks.delete(s))}}}},l=typeof window<"u"?window.hablcast=window.hablcast||new a:new a;export{l as hablcast};

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "hablcast-sdk",
+  "version": "1.0.0",
+  "description": "HABLCAST Mini-App Client SDK for postMessage communication bridge",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm,iife --dts --minify --global-name hablcast",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "hablcast",
+    "farcaster",
+    "miniapp",
+    "sdk"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "tsup": "^8.0.2",
+    "typescript": "^5.0.0"
+  }
+}