React

curl -X POST https://api.monetizationos.com/api/v1/surface-decisions \
-H "Authorization: Bearer $PUBLIC_KEY" \
-H "Content-Type: application/json" \
-d '{
  "surfaceSlug": "hello-world",
  "identity": {
    "createAnonymousIdentifier": true
  }
}'

import { useEffect, useState } from "react";

const PUBLIC_KEY = import.meta.env.VITE_MOS_PUBLIC_KEY; // or process.env.NEXT_PUBLIC_MOS_PUBLIC_KEY
const API_URL = "https://api.monetizationos.com/api/v1/surface-decisions";

export type Identity =
  | { anonymousIdentifier: string }
  | { createAnonymousIdentifier: true }
  | { userJwt: string; createAnonymousIdentifierFallback?: boolean };

export interface Resource {
  id: string;
  meta?: Record<string, string>;
}

// A discriminated union, so narrowing on `type` gives you the right fields.
type FeatureProperty =
  | { type: "boolean"; isFallback: boolean; value: boolean | null }
  | {
      type: "meterable";
      isFallback: boolean;
      counterId: string;
      hasAccess: boolean;
      remainingUnits?: number;
      totalUnits?: number;
      uniqueResources?: boolean;
      resourceIdUsed?: boolean;
    };

interface SurfaceDecision {
  status: "success";
  eventId: string;
  identity: {
    identifier: string;
    isAuthenticated: boolean;
    authType: "provided" | "jwt" | "anonymous" | "middleware";
  };
  features: Record<string, { featureSlug: string; properties: Record<string, FeatureProperty> }>;
  surfaceBehavior: Record<string, unknown>;
  componentBehaviors: Record<string, unknown>;
}

export function useSurfaceDecision(
  surfaceSlug: string,
  identity: Identity,
  resource?: Resource,
) {
  const [decision, setDecision] = useState<SurfaceDecision | null>(null);
  const [error, setError] = useState<Error | null>(null);
  const [isLoading, setIsLoading] = useState(true);

  useEffect(() => {
    const controller = new AbortController();
    setIsLoading(true);
    setError(null);

    fetch(API_URL, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${PUBLIC_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ surfaceSlug, identity, resource }),
      signal: controller.signal,
    })
      .then(async (res) => {
        const body = await res.json();
        // Errors carry a `message` worth surfacing, such as "Surface with slug 'x' not found".
        if (!res.ok) throw new Error(body?.message ?? `Decision failed: ${res.status}`);
        return body as SurfaceDecision;
      })
      .then((data) => {
        setDecision(data);
        setIsLoading(false);
      })
      .catch((err) => {
        if (err.name === "AbortError") return;
        setError(err);
        setIsLoading(false);
      });

    // Aborting stops an outdated decision from landing, and stops a fast
    // navigation from leaving a request in flight.
    return () => controller.abort();
    // Serialized so a new object with the same contents doesn't re-request,
    // and a changed resource does. See "Deciding per resource" below.
  }, [surfaceSlug, JSON.stringify(identity), JSON.stringify(resource)]);

  return { decision, error, isLoading };
}

import { useSurfaceDecision } from "./useSurfaceDecision";

export function Article({ articleId }: { articleId: string }) {
  const { decision, isLoading, error } = useSurfaceDecision(
    "hello-world",
    { createAnonymousIdentifier: true },
    { id: articleId },
  );

  if (isLoading) return <Spinner />;
  if (error) return <FullContent />; // fail open, or closed. Your call

  const premium = decision?.features.article?.properties.premium;
  const hasAccess = premium?.type === "boolean" && premium.value;

  return hasAccess ? <FullContent /> : <Paywall />;
}

{
  "surfaceSlug": "hello-world",
  "identity": { "anonymousIdentifier": "mos_anon_v1_8f3c…" },
  "resource": { "id": "article_xyz" }
}

import { useEffect, useState } from "react";
import { useSurfaceDecision, type Identity, type Resource } from "./useSurfaceDecision";

const STORAGE_KEY = "mos_anonymous_id";

export function useAnonymousDecision(surfaceSlug: string, resource?: Resource) {
  // Resolved once at mount and never updated during it, so learning the
  // identifier from the response can't change the identity and re-decide.
  const [identity] = useState<Identity>(() => {
    const stored = typeof window === "undefined" ? null : localStorage.getItem(STORAGE_KEY);
    return stored ? { anonymousIdentifier: stored } : { createAnonymousIdentifier: true };
  });

  const result = useSurfaceDecision(surfaceSlug, identity, resource);

  useEffect(() => {
    const resolved = result.decision?.identity.identifier;
    if (resolved) localStorage.setItem(STORAGE_KEY, resolved);
  }, [result.decision?.identity.identifier]);

  return result;
}

const { decision } = useSurfaceDecision(
  "hello-world",
  { userJwt: session.accessToken },
  { id: articleId },
);

{
  "surfaceSlug": "hello-world",
  "identity": {
    "userJwt": "<jwt>",
    "createAnonymousIdentifierFallback": true
  }
}

import { NextRequest, NextResponse } from "next/server";
import { getSession } from "@/lib/auth"; // your existing auth

const SECRET_KEY = process.env.MOS_SECRET_KEY!; // server-only, never NEXT_PUBLIC_

export async function POST(req: NextRequest) {
  const session = await getSession(req);
  if (!session) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { surfaceSlug, resource } = await req.json();

  const decision = await fetch(
    "https://api.monetizationos.com/api/v1/surface-decisions",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${SECRET_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        surfaceSlug,
        resource,
        // Trusted: the user ID comes from the server session, not the client.
        identity: { userIdentifier: session.userId },
      }),
    },
  );

  return NextResponse.json(await decision.json(), {
    status: decision.status,
  });
}

const decision = await fetch("/api/decision", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ surfaceSlug: "hello-world", resource: { id: articleId } }),
}).then((res) => res.json());