@konvert7/promoot 0.1.0

package/README.md

@@ -0,0 +1,78 @@
+# @konvert7/promoot
+
+Render a [Promoot](https://promootlabs.com) sponsor slot inline, as part of your own
+markup, instead of in an iframe.
+
+```bash
+bun add @konvert7/promoot
+```
+
+```tsx
+import { PromootBlock } from "@konvert7/promoot";
+
+<PromootBlock url="https://promootlabs.com/embed/YOUR_SLOT_ID" />;
+```
+
+The `url` is the embed URL from your Promoot dashboard — the same string the iframe
+snippet uses, so one value serves either method.
+
+## Why inline
+
+An iframe fails closed. If a content filter ever blocks the frame, your sponsor's ad
+disappears and they get nothing. An inline block renders inside your own document, so the
+worst a filter can do is drop the creative or the view beacon: the ad is still seen.
+
+It also participates in your layout. No fixed-height box to defend, no frame to style
+around.
+
+## What it costs you
+
+The creative lives in your DOM, so this is a weaker guarantee for sponsors than the
+iframe: nothing stops a site owner swapping or hiding it after approval. If you want that
+guarantee, keep the iframe. Both count views identically.
+
+## Props
+
+| Prop | Type | Default | |
+|---|---|---|---|
+| `url` | `string` | — | Required. The dashboard embed URL. |
+| `className` | `string` | — | Applied to the container. |
+| `style` | `CSSProperties` | — | Applied to the container. |
+| `fallback` | `ReactNode` | `null` | Rendered when the slot is paused, empty, or unreachable. |
+
+## Requirements
+
+A React Server Components framework — Next.js App Router or equivalent. The block fetches
+on the server and ships **no client JavaScript**; the view is counted by a plain `<img>`
+the visitor's browser loads, which is what keeps the count a first-hand observation rather
+than something your server claims.
+
+**The page must render dynamically.** The block fetches with `cache: "no-store"`, but if
+your route is statically generated the fetch runs once at build time and an expired ad
+keeps rendering — the sponsor gets free time and the next buyer never appears. In Next.js:
+
+```ts
+export const dynamic = "force-dynamic";
+// or a short revalidate window
+export const revalidate = 30;
+```
+
+Counting is unaffected by caching, because the beacon is a tag in your HTML that every
+visitor's browser fetches regardless of how that HTML was produced.
+
+## Styling
+
+`className` and `style` land on the container, and the internal structure carries
+`data-promoot-*` attributes plus `promoot-*` class names you can target.
+
+The block **never declares a colour scheme of its own**. Its palette uses `light-dark()`,
+which resolves against the scheme it inherits from your page — so a light-only site keeps
+a light panel even for a visitor whose OS prefers dark, and a dark site gets a dark one.
+All of its CSS is scoped to the block; nothing is defined on `:root`.
+
+The one thing you cannot restyle is the "Sponsored" label, which renders from inline
+styles. Disclosure of a paid placement is not the site owner's to remove.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { PromootBlock, type PromootBlockProps } from "./promoot-block.js";
+export type { BlockPayload, BlockRender } from "./types.js";

package/dist/index.js

@@ -0,0 +1 @@
+export { PromootBlock } from "./promoot-block.js";

package/dist/promoot-block.d.ts

@@ -0,0 +1,15 @@
+import type { CSSProperties, ReactNode } from "react";
+import type { BlockPayload } from "./types.js";
+export type PromootBlockProps = {
+    /** The embed URL from your Promoot dashboard, the same one the iframe uses. */
+    url: string;
+    /** Applied to the block's container. */
+    className?: string;
+    /** Applied to the block's container. */
+    style?: CSSProperties;
+    /** Rendered when the slot is paused, empty, or unreachable. */
+    fallback?: ReactNode;
+};
+export declare function blockEndpoint(embedUrl: string): string;
+export declare function scopedCss(payload: BlockPayload): string;
+export declare function PromootBlock({ url, className, style, fallback, }: PromootBlockProps): Promise<import("react").JSX.Element>;

package/dist/promoot-block.js

@@ -0,0 +1,52 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export function blockEndpoint(embedUrl) {
+    return embedUrl.replace("/embed/", "/api/block/");
+}
+// no-store, because a cached render keeps showing a creative whose run has
+// already ended: the sponsor gets free time and the next buyer never appears.
+async function loadBlock(embedUrl) {
+    try {
+        const response = await fetch(blockEndpoint(embedUrl), { cache: "no-store" });
+        return response.ok ? (await response.json()) : null;
+    }
+    catch {
+        return null;
+    }
+}
+// Every rule is scoped to this one block, and it never declares a colour scheme
+// of its own: the palette uses light-dark(), which resolves against the scheme
+// inherited from the host page, so a light-only site keeps a light panel.
+export function scopedCss(payload) {
+    const scope = `[data-promoot-slot="${payload.slot.id}"]`;
+    return `${scope} { ${payload.paletteVars}; position: relative; display: block; width: 100%; max-width: ${payload.slot.widthPx}px; height: auto; max-height: ${payload.slot.heightPx}px; aspect-ratio: ${payload.slot.widthPx} / ${payload.slot.heightPx}; }
+${scope} a { text-decoration: none; }
+${scope} .promoot-ad { display: block; position: relative; height: 100%; width: 100%; }
+${scope} .promoot-ad img { display: block; height: 100%; width: 100%; object-fit: cover; }
+${scope} .promoot-cta { display: flex; flex-direction: column; align-items: center; gap: 3px; width: 100%; height: 100%; justify-content: center; padding: 0 10px; text-align: center; border: 1px dashed var(--edge); border-radius: 10px; box-sizing: border-box; color: var(--muted); background: var(--surface); font-family: system-ui, -apple-system, sans-serif; }
+${scope} .promoot-cta:hover { border-color: var(--edge-hover); background: var(--surface-hover); }
+${scope} .promoot-cta strong { font-size: 14px; color: var(--ink); }
+${scope} .promoot-cta .promoot-pitch { font-size: 13px; color: var(--ink); }
+${scope} .promoot-cta .promoot-proof { font-size: 11px; color: var(--muted); }
+${scope} .promoot-cta .promoot-terms { font-size: 12px; }
+${scope} .promoot-beacon { position: absolute; bottom: 0; right: 0; width: 1px; height: 1px; }`;
+}
+// Inline, not a class: a host can restyle everything else, but the disclosure
+// is not theirs to remove.
+const labelStyle = {
+    position: "absolute",
+    right: "4px",
+    bottom: "4px",
+    fontSize: "10px",
+    lineHeight: "1.4",
+    color: "#ffffff",
+    background: "rgba(0,0,0,.55)",
+    borderRadius: "4px",
+    padding: "1px 5px",
+};
+export async function PromootBlock({ url, className, style, fallback = null, }) {
+    const block = await loadBlock(url);
+    if (!block || block.render === "blank") {
+        return _jsx(_Fragment, { children: fallback });
+    }
+    return (_jsxs("div", { "data-promoot-slot": block.slot.id, className: className, style: style, children: [_jsx("style", { dangerouslySetInnerHTML: { __html: scopedCss(block) } }), block.ad && (_jsxs("a", { className: "promoot-ad", href: block.ad.clickUrl, target: "_blank", rel: "noopener nofollow sponsored", children: [_jsx("img", { src: block.ad.imageUrl, alt: block.ad.title }), block.slot.sponsoredLabel && (_jsx("span", { style: labelStyle, children: block.slot.sponsoredLabel }))] })), block.pitch && (_jsxs("a", { className: "promoot-cta", href: block.pitch.purchaseUrl, target: "_blank", rel: "noopener", children: [_jsx("strong", { children: block.pitch.headline }), block.pitch.pitch && _jsx("span", { className: "promoot-pitch", children: block.pitch.pitch }), block.pitch.proof && _jsx("span", { className: "promoot-proof", children: block.pitch.proof }), _jsx("span", { className: "promoot-terms", children: block.pitch.terms })] })), _jsx("img", { className: "promoot-beacon", src: block.beaconUrl, width: 1, height: 1, alt: "", "aria-hidden": "true" })] }));
+}

package/dist/types.d.ts

@@ -0,0 +1,26 @@
+export type BlockRender = "ad" | "pitch" | "blank";
+/** What GET /api/block/:slotId answers with. */
+export type BlockPayload = {
+    slot: {
+        id: string;
+        widthPx: number;
+        heightPx: number;
+        sponsoredLabel: string | null;
+    };
+    render: BlockRender;
+    ad: {
+        title: string;
+        imageUrl: string;
+        clickUrl: string;
+        expiresAt: string | null;
+    } | null;
+    pitch: {
+        headline: string;
+        pitch: string | null;
+        proof: string | null;
+        terms: string;
+        purchaseUrl: string;
+    } | null;
+    beaconUrl: string;
+    paletteVars: string;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@konvert7/promoot",
+  "version": "0.1.0",
+  "description": "Render a Promoot sponsor slot inline as a React server component, with views counted by the visitor's own browser.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md"],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "react": ">=19"
+  },
+  "keywords": ["promoot", "sponsor", "slot", "react", "rsc", "server-component"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/konvert7/promoot.git"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "type-check": "tsc --noEmit",
+    "test": "bun test",
+    "prepublishOnly": "bun run build"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.13",
+    "@types/react": "19.2.17",
+    "@types/react-dom": "19.2.3",
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "typescript": "6.0.3"
+  }
+}