{"_id":"@app-oracle/insights","_rev":"4-73f7d7af20134c0faa713af4855fd9f3","name":"@app-oracle/insights","dist-tags":{"latest":"0.3.0"},"versions":{"0.1.0":{"name":"@app-oracle/insights","version":"0.1.0","keywords":["app-oracle","feedback","deep-link","sdk","redis"],"author":{"name":"Waylan Sands"},"license":"MIT","_id":"@app-oracle/insights@0.1.0","maintainers":[{"name":"waylan","email":"waylansands@gmail.com"}],"homepage":"https://github.com/app-oracle/insights#readme","bugs":{"url":"https://github.com/app-oracle/insights/issues"},"dist":{"shasum":"8345ad74b39d67e73bb1bd20b88a33f48196b767","tarball":"https://registry.npmjs.org/@app-oracle/insights/-/insights-0.1.0.tgz","fileCount":17,"integrity":"sha512-82/eMw2bShYcynrx0qvqZXEKo9b2lqOAFzO8trgxuqUh7emq3i03+BqGHsYxDjMn7ikqsyYTURnJ4c05pPmT0Q==","signatures":[{"sig":"MEUCIQC2wd1plYP7M0SZ0XdFTsJ3jaOcvghSkyB7QmTVuuK2pwIgOd6YJFzfyQK9596k2mhMaPgkQITlis8KLW56ScKBU7A=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":112794},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=20"},"exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}},"./package.json":"./package.json"},"gitHead":"eeeb1d406fbc8c1453cb4eab620adc6b3c9f937e","scripts":{"dev":"tsup --watch","lint":"eslint src test --ext .ts","test":"vitest run","build":"tsup","format":"prettier --write \"src/**/*.ts\" \"test/**/*.ts\"","typecheck":"tsc --noEmit","test:watch":"vitest","format:check":"prettier --check \"src/**/*.ts\" \"test/**/*.ts\"","prepublishOnly":"npm run build"},"_npmUser":{"name":"waylan","email":"waylansands@gmail.com"},"repository":{"url":"git+https://github.com/app-oracle/insights.git","type":"git"},"_npmVersion":"10.9.2","description":"SDK for generating feedback deep links via App Oracle","directories":{},"_nodeVersion":"22.17.0","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.1","vitest":"^1.2.0","typescript":"^5.7.2","@types/node":"^22.10.2"},"_npmOperationalInternal":{"tmp":"tmp/insights_0.1.0_1771671122650_0.8508373374137264","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@app-oracle/insights","version":"0.2.0","keywords":["app-oracle","feedback","deep-link","sdk","redis"],"author":{"name":"Waylan Sands"},"license":"MIT","_id":"@app-oracle/insights@0.2.0","maintainers":[{"name":"waylan","email":"waylansands@gmail.com"}],"homepage":"https://github.com/app-oracle/insights#readme","bugs":{"url":"https://github.com/app-oracle/insights/issues"},"dist":{"shasum":"f94801a1e2e1e7cacc27ab06f5f38515422e7c7e","tarball":"https://registry.npmjs.org/@app-oracle/insights/-/insights-0.2.0.tgz","fileCount":17,"integrity":"sha512-wGPe/RfBTv4+7FzYNmcO9hptq6MPW9QP3IApjmjK+bRYfCY7vJ1gKFcG9teLQ0+ZijJ4IcV7fvupYeqh+GBf3g==","signatures":[{"sig":"MEUCIQCsdauYZULxDKuHHwfHPXiI5o7CEJ9QTun2oMXMu0Mp0gIgREU6DjfegTQVvk5iOai0SrgNvZo/v23YyQaEliQEkiA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":112705},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=20"},"exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}},"./package.json":"./package.json"},"gitHead":"487401a2e6cb1e476fd17270b382e42b84473eec","scripts":{"dev":"tsup --watch","lint":"eslint src test --ext .ts","test":"vitest run","build":"tsup","format":"prettier --write \"src/**/*.ts\" \"test/**/*.ts\"","typecheck":"tsc --noEmit","test:watch":"vitest","format:check":"prettier --check \"src/**/*.ts\" \"test/**/*.ts\"","prepublishOnly":"npm run build"},"_npmUser":{"name":"waylan","email":"waylansands@gmail.com"},"repository":{"url":"git+https://github.com/app-oracle/insights.git","type":"git"},"_npmVersion":"10.9.2","description":"SDK for generating feedback deep links via App Oracle","directories":{},"_nodeVersion":"22.17.0","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.1","vitest":"^1.2.0","typescript":"^5.7.2","@types/node":"^22.10.2"},"_npmOperationalInternal":{"tmp":"tmp/insights_0.2.0_1773310890897_0.8128468544181715","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@app-oracle/insights","version":"0.2.1","keywords":["app-oracle","feedback","deep-link","sdk","redis"],"author":{"name":"Waylan Sands"},"license":"MIT","_id":"@app-oracle/insights@0.2.1","maintainers":[{"name":"waylan","email":"waylansands@gmail.com"}],"homepage":"https://github.com/app-oracle/insights#readme","bugs":{"url":"https://github.com/app-oracle/insights/issues"},"dist":{"shasum":"0c78abff25e577bd62ea7ddffe994db76bad8e4a","tarball":"https://registry.npmjs.org/@app-oracle/insights/-/insights-0.2.1.tgz","fileCount":17,"integrity":"sha512-GM5i5bm6Fi+7ZS5RAT+o5tW5QPeg8Z3lRfG31cyNvJGn1TuhRy1AyU8bl0XTwJFCK5lztPxG2q7DgyiIyCIn0Q==","signatures":[{"sig":"MEUCIACOcCfo1Gt2LcVTKlc4wXEDjKPVWHVgyw9wOjzojFTXAiEAqatOVf0jpxdxxcp7L71gMMOyZqoTDmRQ3rRwGqfiZU8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":112705},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=20"},"exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}},"./package.json":"./package.json"},"gitHead":"aa4ae431d192ed63b22402943f6ae3e143de9590","scripts":{"dev":"tsup --watch","lint":"eslint src test --ext .ts","test":"vitest run","build":"tsup","format":"prettier --write \"src/**/*.ts\" \"test/**/*.ts\"","typecheck":"tsc --noEmit","test:watch":"vitest","format:check":"prettier --check \"src/**/*.ts\" \"test/**/*.ts\"","prepublishOnly":"npm run build"},"_npmUser":{"name":"waylan","email":"waylansands@gmail.com"},"repository":{"url":"git+https://github.com/app-oracle/insights.git","type":"git"},"_npmVersion":"10.9.2","description":"SDK for generating feedback deep links via App Oracle","directories":{},"_nodeVersion":"22.17.0","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.1","vitest":"^1.2.0","typescript":"^5.7.2","@types/node":"^22.10.2"},"_npmOperationalInternal":{"tmp":"tmp/insights_0.2.1_1774916869908_0.8134765593366631","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@app-oracle/insights","version":"0.3.0","description":"SDK for generating feedback deep links via App Oracle","keywords":["app-oracle","feedback","deep-link","sdk","redis"],"license":"MIT","author":{"name":"Waylan Sands"},"repository":{"type":"git","url":"git+https://github.com/app-oracle/insights.git"},"bugs":{"url":"https://github.com/app-oracle/insights/issues"},"type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}},"./package.json":"./package.json"},"engines":{"node":">=20"},"scripts":{"dev":"tsup --watch","build":"tsup","test":"vitest run","test:watch":"vitest","lint":"eslint src test --ext .ts","format":"prettier --write \"src/**/*.ts\" \"test/**/*.ts\"","format:check":"prettier --check \"src/**/*.ts\" \"test/**/*.ts\"","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"devDependencies":{"@types/node":"^22.10.2","tsup":"^8.0.1","typescript":"^5.7.2","vitest":"^1.2.0"},"_id":"@app-oracle/insights@0.3.0","gitHead":"a80152e73fc6ad12a6ed6339dd17c98aca86c66c","homepage":"https://github.com/app-oracle/insights#readme","_nodeVersion":"22.17.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-rXCJyJmYwKFjYrUdShjIost/9Uiz75mfO4+J8sJx+5DS1xtTs7cNWFsxJ0S7l3kZAbv7NWjci1leJnuvtXyexg==","shasum":"872d33e660c4bdd051e46267011dcc7d2f84ae64","tarball":"https://registry.npmjs.org/@app-oracle/insights/-/insights-0.3.0.tgz","fileCount":18,"unpackedSize":150366,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIEFE1/eKuj6d/0HZB33rNuD1RknEomaJ50/RJF6t2gFaAiEAk69aoBjdzRCuSIPwVm//77U+od2RAf+uFB2OqOcX20o="}]},"_npmUser":{"name":"waylan","email":"waylansands@gmail.com"},"directories":{},"maintainers":[{"name":"waylan","email":"waylansands@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/insights_0.3.0_1775649613049_0.2687359306903554"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-21T10:52:02.496Z","modified":"2026-04-08T12:00:13.329Z","0.1.0":"2026-02-21T10:52:02.799Z","0.2.0":"2026-03-12T10:21:31.194Z","0.2.1":"2026-03-31T00:27:50.056Z","0.3.0":"2026-04-08T12:00:13.203Z"},"bugs":{"url":"https://github.com/app-oracle/insights/issues"},"author":{"name":"Waylan Sands"},"license":"MIT","homepage":"https://github.com/app-oracle/insights#readme","keywords":["app-oracle","feedback","deep-link","sdk","redis"],"repository":{"type":"git","url":"git+https://github.com/app-oracle/insights.git"},"description":"SDK for generating feedback deep links via App Oracle","maintainers":[{"name":"waylan","email":"waylansands@gmail.com"}],"readme":"# Insights by App Oracle\n\nA lightweight server-side SDK for generating secure deep links into the [Audience Insights](https://insights.apporacle.world) World mini app.\n\nCollect feedback and reviews enriched with contextual data to support better business decisions. Every signed link cryptographically ties a response to the user experience in your app.\n\n<p align=\"center\">\n  <img src=\"assets/qr-code.png\" alt=\"QR Code\" width=\"200\" />\n</p>\n\n## Installation\n\n```bash\nnpm install @app-oracle/insights\n```\n\n## Quick Start\n\n```typescript\nimport { Insights } from '@app-oracle/insights';\n\nconst APP_VERSION = '1.2.3';\n\nconst insights = new Insights({\n  apiKey: process.env.APP_ORACLE_API_KEY!,\n});\n\nconst result = await insights.getFeedbackLink({\n  appVersion: APP_VERSION,\n  wallet: '0x1234567890abcdef',\n  metadata: {\n    level: 12,\n    itemsCollected: 6,\n    highScore: 32028,\n    joined: joinDate,\n  },\n});\n\nconsole.log(result.url);\n// https://world.org/mini-app?app_id=abc123&path=/leave-feedback/def456\n```\n\n> **Server-side only.** Always store your API key in environment variables and call this SDK from your backend. Never expose your key in client-side code.\n\n## How It Works\n\n**1. Install Audience Insights and register your app.**\nAdd your app inside the [Audience Insights Mini App](https://insights.apporacle.world). Then verify ownership by adding a custom meta tag to your site's `<head>`. Full instructions are available on the Account page.\n\n**2. Grab your API key.**\nOnce verified, Audience Insights provides an API key. Use this to initialise the SDK on your server.\n\n**3. Wire up a feedback button.**\nAdd an async \"Leave Feedback\" button to your frontend. On tap, it calls a server-side function that uses the Insights SDK to generate a signed deep link and returns it to the client.\n\n**4. Deep link the user.**\nThe client opens the returned URL, taking the user directly into Audience Insights. They leave feedback and optionally submit an app review, then get linked back to your app.\n\n<p align=\"center\">\n  <img src=\"assets/demo.gif\" alt=\"Insights Demo\" width=\"300\" />\n</p>\n\n## API Reference\n\n### `getFeedbackLink(options)`\n\nGenerate a signed deep link for collecting feedback, with optional wallet verification and app review prompting.\n\n```typescript\nconst result = await insights.getFeedbackLink({\n  appVersion: APP_VERSION,\n  wallet: '0x1234567890abcdef',\n  metadata: {\n    swaps: swapCount,\n    trades: tradesCount,\n    joinDate: dateJoined,\n    proUser: true,\n  },\n});\n```\n\n**Options**\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `appVersion` | `string` | Yes | The current version of your app (e.g. `\"1.0.0\"`). Used to scope feedback and reviews to a specific release, enabling per-version analysis and trend tracking. |\n| `wallet` | `string` | No | The user's wallet address. Hashed with SHA-256 before transmission. Providing a wallet verifies that the person leaving feedback is the same authenticated user in your app. |\n| `metadata` | `UserMetadata` | No | Up to 4 key-value pairs attached to the feedback record. Use this to surface the context behind a user's sentiment — activity levels, feature usage, subscription status, and so on. |\n| `requestAppReview` | `boolean` | No | Prompt the user for an app review in addition to feedback. Defaults to `true` when a wallet is provided. Reviews are shown on the Audience Insights Discovery page and improve your app's ranking. |\n| `redirectUrl` | `string` | No | A deep link to return the user to after they submit feedback. Falls back to your app's homepage if not set. |\n\n**Response**\n\n```typescript\ninterface DeepLinkResponse {\n  url: string;         // The signed deep link to open on the client\n  expiresAt?: string;  // Link expiry timestamp, if applicable\n}\n```\n\n## Metadata\n\nAttach up to **4 key-value pairs** to any feedback or review link. Metadata is stored alongside each response, giving you the context you need to segment feedback by user behaviour, feature area, or account attributes.\n\n```typescript\ntype UserMetadata = Record<string, string | number | boolean | Date | null>;\n```\n\n```typescript\nconst result = await insights.getFeedbackLink({\n  appVersion: APP_VERSION,\n  metadata: {\n    swaps: swapCount,\n    trades: tradesCount,\n    joinDate: dateJoined,\n    proUser: true,\n  },\n});\n```\n\n## License\n\nMIT","readmeFilename":"README.md"}