@guideify/next 0.1.0

package/LICENSE

@@ -0,0 +1,122 @@
+Guideify SDK License
+
+Copyright (c) 2026 Guideify. All rights reserved.
+
+This software is proprietary. It is published to the public npm registry so a
+build tool can install it, not because it is open source. The permission you
+have to use it is written below, and there is no other.
+
+
+1. Definitions
+
+   "Software" means this package and every file it publishes.
+
+   "Service" means the Guideify hosted product at https://guideify.in.
+
+   "You" means the person or organisation installing the Software, and any
+   organisation You install it on behalf of.
+
+   "Your Application" means a product You develop and operate that integrates
+   the Service.
+
+
+2. Grant
+
+   Subject to Your compliance with this license, Guideify grants You a
+   non-exclusive, worldwide, royalty-free, non-transferable, revocable license
+   to:
+
+   (a) install, copy and use the Software in order to integrate the Service
+       into Your Application;
+
+   (b) incorporate the Software into Your Application, including compiling,
+       bundling, minifying and otherwise transforming it as an ordinary build
+       step does; and
+
+   (c) distribute the Software as an incorporated part of Your Application to
+       Your users, including by serving it from Your own origin or from a
+       content delivery network You use.
+
+   Paragraph (c) is the point of the whole document. A browser SDK reaches its
+   audience only by being served from Your pages, and a proprietary license that
+   omitted it would forbid the one thing every user of this package must do.
+
+
+3. Conditions
+
+   (a) You may not distribute the Software on its own, or inside anything whose
+       purpose is to make the Software available to others. It travels inside
+       Your Application or not at all.
+
+   (b) You may not remove or alter a copyright, license or attribution notice in
+       the Software. A build step that strips comments from bundled output is
+       not a breach of this paragraph.
+
+   (c) You may not sublicense the Software except as an inseparable part of Your
+       Application, on terms no more permissive than these.
+
+
+4. Restrictions
+
+   (a) You may not modify the Software, or use it, to connect to or interoperate
+       with any service other than the Service.
+
+   (b) You may not use the Software, or knowledge gained from studying it, to
+       build a product that competes with the Service.
+
+   (c) You may not reverse engineer, decompile or disassemble the Software,
+       except where that restriction is prohibited by applicable law, or where
+       it is necessary to exercise a right applicable law grants You that cannot
+       be waived by contract.
+
+   Nothing in this section restricts what You may do with the Software's public
+   API, with its documented behaviour, or with the data the Service returns to
+   You about Your own product.
+
+
+5. Reservation of rights
+
+   All rights not expressly granted are reserved. The Software is licensed,
+   never sold, and this license transfers no ownership.
+
+
+6. Term and termination
+
+   This license takes effect when You install the Software. It ends when You
+   stop using the Service, or if You breach a term and do not remedy the breach
+   within thirty days of being told about it.
+
+   On termination You must stop distributing new copies of the Software. Copies
+   already embedded in versions of Your Application that You have already
+   distributed are unaffected, and You do not have to recall them.
+
+
+7. No warranty
+
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+
+
+8. Limitation of liability
+
+   TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL THE
+   COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+   IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+   CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+   Nothing here excludes a liability that applicable law does not permit to be
+   excluded.
+
+
+9. Relationship to the Terms of Service
+
+   The Guideify Terms of Service at https://guideify.in/terms govern the
+   Service. This license governs the Software.
+
+   It stands on its own: it is granted by the copyright holder directly, and it
+   does not depend on those terms being in force. Copyright exists without
+   incorporation, and so does a license over it.
+
+
+Questions about this license: hello@guideify.in

package/README.md

@@ -0,0 +1,66 @@
+# @guideify/next
+
+App Router wrapper. It handles the one thing plain React cannot: the CSP nonce.
+
+```bash
+npm i @guideify/next
+```
+
+```tsx
+// app/layout.tsx
+import { Guideify } from '@guideify/next';
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html>
+      <body>
+        <Guideify apiKey={process.env.NEXT_PUBLIC_GUIDEIFY_KEY!}>{children}</Guideify>
+      </body>
+    </html>
+  );
+}
+```
+
+```tsx
+'use client';
+import { useGuideify, GuideifyTarget } from '@guideify/next';
+```
+
+## What it adds over `@guideify/react`
+
+`GuideifyProvider` is already a client component and works in a Next app
+unchanged. What it cannot do is read the request — and a CSP nonce only exists
+there.
+
+`<Guideify>` is a **server** component that reads the nonce and hands it down.
+Without it, a page served with `script-src 'nonce-…'` drops the injected tag:
+no tours, nothing in the console naming us, and a customer who concludes the
+product does not work.
+
+It reads the nonce from the request's own `content-security-policy` header
+rather than from the custom request header Next's nonce recipe suggests, because
+that header's *name* is your choice. Depending on it would work for apps that
+picked ours and fail invisibly for the rest.
+
+Awaiting `headers()` opts the tree into dynamic rendering. That is unavoidable:
+a nonce is per-request by definition, and a statically rendered page would bake
+in a stale one that every policy refuses. Pass `nonce` yourself to override.
+
+`useGuideify` and `GuideifyTarget` are re-exported from `@guideify/react` unchanged
+— there is no Next-specific version of either, and one import beats two.
+
+## What it does not bundle
+
+`@guideify/react` stays external, so your app has one provider and one context.
+Inlining it would give the provider one context to write to and the hook another
+to read — which presents as "the core never arrived" in an app where it did.
+`test/boundary.test.mjs` fails the build if that changes.
+
+The core is not here either, at one remove: it arrives from the CDN through the
+loader tag, which is what keeps a canary (R-03) and the kill switch (R-04) able
+to reach you.
+
+## License
+
+Proprietary — see [LICENSE](./LICENSE). You may bundle this into your own
+application and serve it to your users; you may not redistribute it on its own.

package/dist/index.cjs

@@ -0,0 +1,37 @@
+'use strict';
+
+var react = require('@guideify/react');
+var jsxRuntime = require('react/jsx-runtime');
+
+// src/index.ts
+
+// src/nonce.ts
+function readNonce(csp) {
+  if (!csp) return void 0;
+  const match = csp.match(/'nonce-([^']+)'/);
+  return match?.[1];
+}
+async function Guideify({ children, nonce, ...options }) {
+  const resolved = nonce ?? await requestNonce();
+  return /* @__PURE__ */ jsxRuntime.jsx(react.GuideifyProvider, { ...options, nonce: resolved, children });
+}
+async function requestNonce() {
+  const { headers } = await import('next/headers');
+  const store = await headers();
+  return readNonce(store.get("content-security-policy"));
+}
+
+Object.defineProperty(exports, "DEFAULT_CDN", {
+  enumerable: true,
+  get: function () { return react.DEFAULT_CDN; }
+});
+Object.defineProperty(exports, "GuideifyTarget", {
+  enumerable: true,
+  get: function () { return react.GuideifyTarget; }
+});
+Object.defineProperty(exports, "useGuideify", {
+  enumerable: true,
+  get: function () { return react.useGuideify; }
+});
+exports.Guideify = Guideify;
+exports.readNonce = readNonce;

package/dist/index.d.cts

@@ -0,0 +1,71 @@
+import { SnippetOptions } from '@guideify/react';
+export { DEFAULT_CDN, GuideifyApi, GuideifyEvent, GuideifyTarget, GuideifyTargetProps, SnippetOptions, Unsubscribe, useGuideify } from '@guideify/react';
+import { ReactNode } from 'react';
+
+interface GuideifyProps extends Omit<SnippetOptions, 'nonce'> {
+    /**
+     * Supply it to override what the request's CSP says. Rarely needed — the
+     * point of this component is not having to.
+     */
+    nonce?: string | undefined;
+    children: ReactNode;
+}
+/**
+ * Guideify for the App Router — F-06, BUILD_REPORT §6.4.
+ *
+ * ```tsx
+ * // app/layout.tsx
+ * import { Guideify } from '@guideify/next';
+ *
+ * export default function RootLayout({ children }: { children: React.ReactNode }) {
+ *   return (
+ *     <html>
+ *       <body>
+ *         <Guideify apiKey={process.env.NEXT_PUBLIC_GUIDEIFY_KEY!}>{children}</Guideify>
+ *       </body>
+ *     </html>
+ *   );
+ * }
+ * ```
+ *
+ * **A server component wrapping a client one, and that split is the whole
+ * package.** `GuideifyProvider` is `'use client'` and works in a Next app
+ * unchanged; what it cannot do is read the request, and the CSP nonce only
+ * exists there. So this reads the nonce on the server and hands it down — the
+ * one thing an App Router application genuinely needs that plain React cannot
+ * give it.
+ *
+ * Without it the failure is silent in the way that costs the most: a page served
+ * with `script-src 'nonce-…'` drops the injected tag, no tours run, and nothing
+ * in the customer's console names us.
+ *
+ * `headers()` is awaited, which opts the tree into dynamic rendering. That is
+ * unavoidable and not incidental — a nonce is per-request by definition, and a
+ * statically rendered page that baked one in would serve a stale nonce every
+ * policy refuses.
+ */
+declare function Guideify({ children, nonce, ...options }: GuideifyProps): Promise<ReactNode>;
+
+/**
+ * The CSP nonce for this request, or undefined when the app does not use one.
+ *
+ * **Reads the request's own `content-security-policy` header rather than a
+ * header the middleware had to be told to set.** Next's documented pattern for
+ * nonces is middleware that generates one, puts it in the outgoing CSP, and
+ * forwards it on a custom request header — and the name of that custom header is
+ * the application's choice. Depending on it would make this work only for people
+ * who picked the same name we did, and fail silently for everybody else: the tag
+ * loads without a nonce, the browser drops it, and no tours run for a reason
+ * nothing reports.
+ *
+ * The CSP header itself is not a matter of taste. If the middleware set a nonce,
+ * it is in there, spelled `'nonce-…'`, because that is what makes the policy
+ * work at all.
+ *
+ * Returns undefined for a policy without one, which is correct rather than a
+ * fallback: a page with no nonce directive does not need the attribute, and
+ * inventing one would produce a tag that *every* policy refuses.
+ */
+declare function readNonce(csp: string | null | undefined): string | undefined;
+
+export { Guideify, type GuideifyProps, readNonce };

package/dist/index.d.ts

@@ -0,0 +1,71 @@
+import { SnippetOptions } from '@guideify/react';
+export { DEFAULT_CDN, GuideifyApi, GuideifyEvent, GuideifyTarget, GuideifyTargetProps, SnippetOptions, Unsubscribe, useGuideify } from '@guideify/react';
+import { ReactNode } from 'react';
+
+interface GuideifyProps extends Omit<SnippetOptions, 'nonce'> {
+    /**
+     * Supply it to override what the request's CSP says. Rarely needed — the
+     * point of this component is not having to.
+     */
+    nonce?: string | undefined;
+    children: ReactNode;
+}
+/**
+ * Guideify for the App Router — F-06, BUILD_REPORT §6.4.
+ *
+ * ```tsx
+ * // app/layout.tsx
+ * import { Guideify } from '@guideify/next';
+ *
+ * export default function RootLayout({ children }: { children: React.ReactNode }) {
+ *   return (
+ *     <html>
+ *       <body>
+ *         <Guideify apiKey={process.env.NEXT_PUBLIC_GUIDEIFY_KEY!}>{children}</Guideify>
+ *       </body>
+ *     </html>
+ *   );
+ * }
+ * ```
+ *
+ * **A server component wrapping a client one, and that split is the whole
+ * package.** `GuideifyProvider` is `'use client'` and works in a Next app
+ * unchanged; what it cannot do is read the request, and the CSP nonce only
+ * exists there. So this reads the nonce on the server and hands it down — the
+ * one thing an App Router application genuinely needs that plain React cannot
+ * give it.
+ *
+ * Without it the failure is silent in the way that costs the most: a page served
+ * with `script-src 'nonce-…'` drops the injected tag, no tours run, and nothing
+ * in the customer's console names us.
+ *
+ * `headers()` is awaited, which opts the tree into dynamic rendering. That is
+ * unavoidable and not incidental — a nonce is per-request by definition, and a
+ * statically rendered page that baked one in would serve a stale nonce every
+ * policy refuses.
+ */
+declare function Guideify({ children, nonce, ...options }: GuideifyProps): Promise<ReactNode>;
+
+/**
+ * The CSP nonce for this request, or undefined when the app does not use one.
+ *
+ * **Reads the request's own `content-security-policy` header rather than a
+ * header the middleware had to be told to set.** Next's documented pattern for
+ * nonces is middleware that generates one, puts it in the outgoing CSP, and
+ * forwards it on a custom request header — and the name of that custom header is
+ * the application's choice. Depending on it would make this work only for people
+ * who picked the same name we did, and fail silently for everybody else: the tag
+ * loads without a nonce, the browser drops it, and no tours run for a reason
+ * nothing reports.
+ *
+ * The CSP header itself is not a matter of taste. If the middleware set a nonce,
+ * it is in there, spelled `'nonce-…'`, because that is what makes the policy
+ * work at all.
+ *
+ * Returns undefined for a policy without one, which is correct rather than a
+ * fallback: a page with no nonce directive does not need the attribute, and
+ * inventing one would produce a tag that *every* policy refuses.
+ */
+declare function readNonce(csp: string | null | undefined): string | undefined;
+
+export { Guideify, type GuideifyProps, readNonce };

package/dist/index.js

@@ -0,0 +1,23 @@
+import { GuideifyProvider } from '@guideify/react';
+export { DEFAULT_CDN, GuideifyTarget, useGuideify } from '@guideify/react';
+import { jsx } from 'react/jsx-runtime';
+
+// src/index.ts
+
+// src/nonce.ts
+function readNonce(csp) {
+  if (!csp) return void 0;
+  const match = csp.match(/'nonce-([^']+)'/);
+  return match?.[1];
+}
+async function Guideify({ children, nonce, ...options }) {
+  const resolved = nonce ?? await requestNonce();
+  return /* @__PURE__ */ jsx(GuideifyProvider, { ...options, nonce: resolved, children });
+}
+async function requestNonce() {
+  const { headers } = await import('next/headers');
+  const store = await headers();
+  return readNonce(store.get("content-security-policy"));
+}
+
+export { Guideify, readNonce };

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@guideify/next",
+  "version": "0.1.0",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test \"test/*.test.mjs\"",
+    "verify": "npm run typecheck && npm run build && npm run test",
+    "verify:package": "node ../../scripts/verify-package.mjs next",
+    "prepublishOnly": "npm run verify && npm run verify:package"
+  },
+  "dependencies": {
+    "@guideify/react": "^0.1.0"
+  },
+  "peerDependencies": {
+    "next": ">=14",
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.0",
+    "next": "^16.3.1",
+    "react": "^19.2.8",
+    "tsup": "^8.5.0",
+    "typescript": "^5.7.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vikasOzark/guidely.git",
+    "directory": "packages/next"
+  }
+}