@proveanything/smartlinks 2.0.37 → 2.0.38

package/dist/openapi.yaml

@@ -19459,6 +19459,10 @@ components:
           $ref: "#/components/schemas/AppManifestExecutor"
         functions:
           $ref: "#/components/schemas/AppManifestFunctions"
+        data:
+          $ref: "#/components/schemas/AppDataDeclaration"
+        headless:
+          $ref: "#/components/schemas/AppHeadlessDeclaration"
       required:
         - name
         - version
@@ -25155,6 +25159,161 @@ components:
           type: boolean
     FacetValueDefinition:
       $ref: "#/components/schemas/FacetValue"
+    AppDataField:
+      type: object
+      properties:
+        type:
+          $ref: "#/components/schemas/AppDataFieldType"
+        label:
+          type: string
+        description:
+          type: string
+        required:
+          type: boolean
+        localized:
+          type: boolean
+        zone:
+          type: string
+          enum:
+            - data
+            - owner
+            - admin
+        public:
+          type: boolean
+        to:
+          type: string
+        options:
+          type: array
+          items:
+            type: string
+      required:
+        - type
+    AppDataType:
+      type: object
+      properties:
+        description:
+          type: string
+        storage:
+          $ref: "#/components/schemas/AppDataStorage"
+        visibility:
+          type: string
+          enum:
+            - public
+            - owner
+            - admin
+        anchors:
+          type: array
+          items:
+            type: string
+            enum:
+              - product
+              - variant
+              - batch
+              - proof
+              - contact
+        fields:
+          type: object
+          additionalProperties:
+            $ref: "#/components/schemas/AppDataField"
+        listing:
+          type: object
+          additionalProperties: true
+        examples:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+        read:
+          type: object
+          additionalProperties: true
+        since:
+          type: string
+      required:
+        - description
+        - storage
+        - fields
+    AppDataDeclaration:
+      type: object
+      properties:
+        schemaVersion:
+          type: string
+        types:
+          type: object
+          additionalProperties:
+            $ref: "#/components/schemas/AppDataType"
+      required:
+        - schemaVersion
+        - types
+    AppHeadlessDeclaration:
+      type: object
+      properties:
+        purpose:
+          type: string
+        categories:
+          type: array
+          items:
+            $ref: "#/components/schemas/HeadlessCategory"
+        primaryTypes:
+          type: array
+          items:
+            type: string
+        editedIn:
+          type: object
+          additionalProperties: true
+        render:
+          type: object
+          additionalProperties: true
+      required:
+        - purpose
+        - categories
+        - primaryTypes
+        - editedIn
+    AppDataFieldType:
+      type: string
+      enum:
+        - string
+        - text
+        - richtext
+        - markdown
+        - number
+        - boolean
+        - date
+        - datetime
+        - enum
+        - url
+        - image
+        - file
+        - ref
+        - "string[]"
+        - "ref[]"
+        - json
+    AppDataStorage:
+      type: object
+      additionalProperties: true
+    HeadlessCategory:
+      type: string
+      enum:
+        - faq
+        - media
+        - pages
+        - articles
+        - catalog
+        - events
+        - locations
+        - people
+        - reviews
+        - documents
+        - forms
+        - other
+    HeadlessSeoHelper:
+      type: string
+      enum:
+        - faqPage
+        - product
+        - article
+        - breadcrumbs
+        - organization
+        - localBusiness
     CachedData:
       type: object
       properties:

package/dist/seo.d.ts

@@ -0,0 +1,85 @@
+export interface SeoHead {
+    title?: string;
+    description?: string;
+    /** Absolute image URL for link previews (og:image / twitter:image). */
+    image?: string;
+    /** Absolute canonical URL. Usually leave unset: the platform sends the site's canonical address. */
+    canonical?: string;
+    /** Keep this page out of search engines. */
+    noindex?: boolean;
+    /** og:type — 'website' (default), 'article' or 'product'. */
+    type?: 'website' | 'article' | 'product';
+    /** The site's name (og:site_name). */
+    siteName?: string;
+}
+/** Set this route's head tags. Call on every route change; unset fields are removed (if we added them). */
+export declare function head(h: SeoHead): void;
+/**
+ * Place a JSON-LD structured-data block in <head>. `id` names the block, so calling again replaces it
+ * (e.g. per route); pass null to remove it. `<` is escaped so data can't close the script tag.
+ */
+export declare function jsonLd(id: string, data: object | object[] | null): void;
+type Obj = Record<string, any>;
+export interface ProductSchemaOptions {
+    /** The page's absolute URL. */
+    url?: string;
+    /** Brand name (defaults to none). */
+    brand?: string;
+    /** An offer, when the product is sold: price as a number or string, ISO currency, availability. */
+    offer?: {
+        price: number | string;
+        currency: string;
+        availability?: 'InStock' | 'OutOfStock' | 'PreOrder';
+        url?: string;
+    };
+    /** Aggregate rating, when the site shows one. */
+    rating?: {
+        value: number;
+        count: number;
+    };
+}
+export declare const schema: {
+    /** schema.org Product from a SmartLinks product. */
+    product(product: Obj, opts?: ProductSchemaOptions): Obj;
+    /** schema.org FAQPage — answer-shaped content AI search can cite, and FAQ rich results. */
+    faqPage(items: Array<{
+        question: string;
+        answer: string;
+    }>): Obj;
+    /** schema.org Organization from a collection (the brand behind the site). */
+    organization(collection: Obj, opts?: {
+        url?: string;
+        sameAs?: string[];
+    }): Obj;
+    /** schema.org LocalBusiness — for a business with a place (shop, restaurant, studio). */
+    localBusiness(collection: Obj, opts?: {
+        url?: string;
+        telephone?: string;
+        address?: {
+            street?: string;
+            locality?: string;
+            region?: string;
+            postalCode?: string;
+            country?: string;
+        };
+        openingHours?: string[];
+        type?: string;
+    }): Obj;
+    /** schema.org BreadcrumbList from a trail of { name, url } (home first). */
+    breadcrumbs(trail: Array<{
+        name: string;
+        url: string;
+    }>): Obj;
+    /** schema.org Article (a blog post, news item, guide). Dates as ISO strings. */
+    article(a: {
+        headline: string;
+        description?: string;
+        image?: string;
+        url?: string;
+        datePublished?: string;
+        dateModified?: string;
+        author?: string;
+        publisher?: string;
+    }): Obj;
+};
+export {};

package/dist/seo.js

@@ -0,0 +1,172 @@
+// =============================================================================
+// SEO + GEO helpers for apps served as websites (framework-agnostic).
+// =============================================================================
+// seo.head()       per-route <title>, description, Open Graph / Twitter tags, canonical, robots
+// seo.jsonLd()     place a structured-data block (replaces the previous one with the same id)
+// seo.schema.*     schema.org builders from platform data (Product, FAQPage, Organization, …)
+//
+// They write plain DOM, so whatever pre-renders the page (the platform's renderer, a crawler that runs
+// JavaScript) captures them. In SSR / no-document environments they're no-ops; the builders are pure.
+// =============================================================================
+const MARK = 'data-sl-seo';
+function doc() {
+    return typeof document !== 'undefined' && document && document.head ? document : null;
+}
+function setMeta(d, attr, key, content) {
+    let el = d.head.querySelector(`meta[${attr}="${key}"]`);
+    if (content === undefined || content === null || content === '') {
+        if (el && el.getAttribute(MARK) !== null)
+            el.remove();
+        return;
+    }
+    if (!el) {
+        el = d.createElement('meta');
+        el.setAttribute(attr, key);
+        el.setAttribute(MARK, '');
+        d.head.appendChild(el);
+    }
+    el.setAttribute('content', content);
+}
+/** Set this route's head tags. Call on every route change; unset fields are removed (if we added them). */
+export function head(h) {
+    const d = doc();
+    if (!d)
+        return;
+    if (h.title)
+        d.title = h.title;
+    setMeta(d, 'name', 'description', h.description);
+    setMeta(d, 'property', 'og:title', h.title);
+    setMeta(d, 'property', 'og:description', h.description);
+    setMeta(d, 'property', 'og:image', h.image);
+    setMeta(d, 'property', 'og:type', h.type || 'website');
+    setMeta(d, 'property', 'og:site_name', h.siteName);
+    setMeta(d, 'name', 'twitter:card', h.image ? 'summary_large_image' : 'summary');
+    setMeta(d, 'name', 'twitter:title', h.title);
+    setMeta(d, 'name', 'twitter:description', h.description);
+    setMeta(d, 'name', 'twitter:image', h.image);
+    setMeta(d, 'name', 'robots', h.noindex ? 'noindex, nofollow' : undefined);
+    let link = d.head.querySelector('link[rel="canonical"]');
+    if (h.canonical) {
+        if (!link) {
+            link = d.createElement('link');
+            link.setAttribute('rel', 'canonical');
+            link.setAttribute(MARK, '');
+            d.head.appendChild(link);
+        }
+        link.setAttribute('href', h.canonical);
+    }
+    else if (link && link.getAttribute(MARK) !== null) {
+        link.remove();
+    }
+}
+/**
+ * Place a JSON-LD structured-data block in <head>. `id` names the block, so calling again replaces it
+ * (e.g. per route); pass null to remove it. `<` is escaped so data can't close the script tag.
+ */
+export function jsonLd(id, data) {
+    const d = doc();
+    if (!d)
+        return;
+    const sel = `script[type="application/ld+json"][${MARK}="${id}"]`;
+    let el = d.head.querySelector(sel);
+    if (data === null) {
+        if (el)
+            el.remove();
+        return;
+    }
+    if (!el) {
+        el = d.createElement('script');
+        el.setAttribute('type', 'application/ld+json');
+        el.setAttribute(MARK, id);
+        d.head.appendChild(el);
+    }
+    el.textContent = JSON.stringify(data).replace(/</g, '\\u003c');
+}
+const CTX = 'https://schema.org';
+/** Drop undefined / null / empty values so the output stays valid and small. */
+function clean(o) {
+    for (const k of Object.keys(o)) {
+        const v = o[k];
+        if (v === undefined || v === null || v === '' || (Array.isArray(v) && v.length === 0))
+            delete o[k];
+    }
+    return o;
+}
+const imageOf = (x) => { var _a, _b, _c; return ((_a = x === null || x === void 0 ? void 0 : x.heroImage) === null || _a === void 0 ? void 0 : _a.url) || ((_b = x === null || x === void 0 ? void 0 : x.logoImage) === null || _b === void 0 ? void 0 : _b.url) || ((_c = x === null || x === void 0 ? void 0 : x.image) === null || _c === void 0 ? void 0 : _c.url) || (typeof (x === null || x === void 0 ? void 0 : x.image) === 'string' ? x.image : undefined); };
+export const schema = {
+    /** schema.org Product from a SmartLinks product. */
+    product(product, opts = {}) {
+        const images = [imageOf(product), ...(product.additionalImages || []).map((i) => i === null || i === void 0 ? void 0 : i.url)].filter(Boolean);
+        return clean({
+            '@context': CTX,
+            '@type': 'Product',
+            name: product.name,
+            description: product.description || undefined,
+            image: images.length > 1 ? images : images[0],
+            sku: product.sku || undefined,
+            gtin: product.gtin || product.ownGtin || undefined,
+            url: opts.url,
+            brand: opts.brand ? { '@type': 'Brand', name: opts.brand } : undefined,
+            offers: opts.offer ? clean({
+                '@type': 'Offer',
+                price: String(opts.offer.price),
+                priceCurrency: opts.offer.currency,
+                availability: opts.offer.availability ? `${CTX}/${opts.offer.availability}` : undefined,
+                url: opts.offer.url || opts.url,
+            }) : undefined,
+            aggregateRating: opts.rating ? { '@type': 'AggregateRating', ratingValue: opts.rating.value, reviewCount: opts.rating.count } : undefined,
+        });
+    },
+    /** schema.org FAQPage — answer-shaped content AI search can cite, and FAQ rich results. */
+    faqPage(items) {
+        return {
+            '@context': CTX,
+            '@type': 'FAQPage',
+            mainEntity: items.filter((i) => i && i.question && i.answer).map((i) => ({
+                '@type': 'Question',
+                name: i.question,
+                acceptedAnswer: { '@type': 'Answer', text: i.answer },
+            })),
+        };
+    },
+    /** schema.org Organization from a collection (the brand behind the site). */
+    organization(collection, opts = {}) {
+        return clean({
+            '@context': CTX,
+            '@type': 'Organization',
+            name: collection.title || collection.name,
+            description: collection.description || undefined,
+            logo: imageOf(collection),
+            url: opts.url || (collection.hubCustomDomain ? `https://${collection.hubCustomDomain}` : collection.siteHost ? `https://${collection.siteHost}` : undefined),
+            sameAs: opts.sameAs,
+        });
+    },
+    /** schema.org LocalBusiness — for a business with a place (shop, restaurant, studio). */
+    localBusiness(collection, opts = {}) {
+        const a = opts.address;
+        return clean(Object.assign(Object.assign({}, schema.organization(collection, { url: opts.url })), { '@type': opts.type || 'LocalBusiness', telephone: opts.telephone, address: a ? clean({ '@type': 'PostalAddress', streetAddress: a.street, addressLocality: a.locality, addressRegion: a.region, postalCode: a.postalCode, addressCountry: a.country }) : undefined, openingHours: opts.openingHours }));
+    },
+    /** schema.org BreadcrumbList from a trail of { name, url } (home first). */
+    breadcrumbs(trail) {
+        return {
+            '@context': CTX,
+            '@type': 'BreadcrumbList',
+            itemListElement: trail.map((t, i) => ({ '@type': 'ListItem', position: i + 1, name: t.name, item: t.url })),
+        };
+    },
+    /** schema.org Article (a blog post, news item, guide). Dates as ISO strings. */
+    article(a) {
+        return clean({
+            '@context': CTX,
+            '@type': 'Article',
+            headline: a.headline,
+            description: a.description,
+            image: a.image,
+            url: a.url,
+            datePublished: a.datePublished,
+            dateModified: a.dateModified || a.datePublished,
+            author: a.author ? { '@type': 'Person', name: a.author } : undefined,
+            publisher: a.publisher ? { '@type': 'Organization', name: a.publisher } : undefined,
+        });
+    },
+};

package/dist/site.d.ts

@@ -0,0 +1,10 @@
+declare global {
+    var __SL_READY__: boolean | undefined;
+}
+/**
+ * Tell the platform this page has finished rendering its content (data loaded, head tags set). The
+ * platform's page renderer takes its snapshot for search engines and AI crawlers at this point;
+ * without it, it waits for the network to go idle (capped). Call once per page, after your data
+ * renders. Harmless anywhere else.
+ */
+export declare function ready(): void;

package/dist/site.js

@@ -0,0 +1,18 @@
+// =============================================================================
+// site — for apps served as websites.
+// =============================================================================
+/**
+ * Tell the platform this page has finished rendering its content (data loaded, head tags set). The
+ * platform's page renderer takes its snapshot for search engines and AI crawlers at this point;
+ * without it, it waits for the network to go idle (capped). Call once per page, after your data
+ * renders. Harmless anywhere else.
+ */
+export function ready() {
+    if (typeof globalThis === 'undefined')
+        return;
+    globalThis.__SL_READY__ = true;
+    const w = typeof window !== 'undefined' ? window : null;
+    if (w && typeof w.dispatchEvent === 'function' && typeof w.CustomEvent === 'function') {
+        w.dispatchEvent(new w.CustomEvent('smartlinks:ready'));
+    }
+}

package/dist/types/appManifest.d.ts

@@ -1,5 +1,6 @@
 /// <reference types="node" />
 /// <reference types="node" />
+import type { AppDataDeclaration, AppHeadlessDeclaration } from './headless.js';
 /**
  * A bundle (widget or container) as returned by the collection widgets endpoint.
  *
@@ -662,6 +663,16 @@ export interface AppManifest {
      * @see AppManifestFunctions
      */
     functions?: AppManifestFunctions;
+    /**
+     * The app's public data model: its data types, how each is stored, fields, examples and read
+     * recipes. Required for `headless`. @see AppDataDeclaration · docs/headless-providers.md
+     */
+    data?: AppDataDeclaration;
+    /**
+     * Opt-in: other sites and apps may install this app and use its content (a headless content
+     * provider). Validated by `smartlinks-headless`. @see AppHeadlessDeclaration
+     */
+    headless?: AppHeadlessDeclaration;
     [key: string]: any;
 }
 /**

package/dist/types/appManifest.js

@@ -1,2 +1 @@
-// src/types/appManifest.ts
 export {};

package/dist/types/headless.d.ts

@@ -0,0 +1,96 @@
+/** Field value types. Keep this set small: generated editors, typed reads and sites rely on it. */
+export type AppDataFieldType = 'string' | 'text' | 'richtext' | 'markdown' | 'number' | 'boolean' | 'date' | 'datetime' | 'enum' | 'url' | 'image' | 'file' | 'ref' | 'string[]' | 'ref[]' | 'json';
+export interface AppDataField {
+    type: AppDataFieldType;
+    label?: string;
+    description?: string;
+    required?: boolean;
+    /** Translated per language (string / text / richtext / markdown only). */
+    localized?: boolean;
+    /**
+     * The JSONB zone it lives in (app objects): `data` (default), `owner`, or `admin`. Only `data`
+     * can be public; `admin` is never readable on public endpoints.
+     */
+    zone?: 'data' | 'owner' | 'admin';
+    /** Readable by anonymous visitors (when the item's visibility is public). */
+    public?: boolean;
+    /** For `ref` / `ref[]`: the declared type id, or 'product' | 'contact' | 'proof'. */
+    to?: string;
+    /** For `enum`: the allowed values. */
+    options?: string[];
+}
+/** How a type's items are stored. */
+export type AppDataStorage = 
+/** App records (`SL.app.records`), filtered by recordType. The usual home for content. */
+{
+    kind: 'record';
+    recordType: string;
+}
+/** App cases (`SL.app.cases`) — requests that get resolved. */
+ | {
+    kind: 'case';
+    category?: string;
+}
+/** App threads (`SL.app.threads`) — discussions, Q&A, reviews. */
+ | {
+    kind: 'thread';
+    slug?: string;
+}
+/** App configuration (`SL.appConfiguration.getConfig` / data items) — settings, small lists. */
+ | {
+    kind: 'config';
+    key?: string;
+};
+export interface AppDataType {
+    /** What one item is, in a sentence. */
+    description: string;
+    storage: AppDataStorage;
+    /** The visibility items normally have (app objects): public, owner or admin. Default public. */
+    visibility?: 'public' | 'owner' | 'admin';
+    /** What an item can be attached to (app objects' anchor columns). */
+    anchors?: Array<'product' | 'variant' | 'batch' | 'proof' | 'contact'>;
+    fields: Record<string, AppDataField>;
+    /** How a site normally lists them. */
+    listing?: {
+        sort?: string[];
+        filters?: string[];
+    };
+    /** Real-shaped sample items (the `data` zone's JSON). At least one for a headless type. */
+    examples?: Array<Record<string, unknown>>;
+    /** SDK recipes a site uses. If omitted, the checker prints the standard ones for the storage. */
+    read?: {
+        list?: string;
+        get?: string;
+        notes?: string;
+    };
+    /** The app version that introduced this type. */
+    since?: string;
+}
+export interface AppDataDeclaration {
+    /** Semver of the data contract itself (not the app's version). Major = breaking. */
+    schemaVersion: string;
+    types: Record<string, AppDataType>;
+}
+/** What kind of content a provider supplies — how site builders find it. */
+export type HeadlessCategory = 'faq' | 'media' | 'pages' | 'articles' | 'catalog' | 'events' | 'locations' | 'people' | 'reviews' | 'documents' | 'forms' | 'other';
+export declare const HEADLESS_CATEGORIES: readonly HeadlessCategory[];
+/** SEO structured-data helpers a site should use with this content (`SL.seo.schema.*`). */
+export type HeadlessSeoHelper = 'faqPage' | 'product' | 'article' | 'breadcrumbs' | 'organization' | 'localBusiness';
+export interface AppHeadlessDeclaration {
+    /** What content this app holds, and when a site should use it rather than build its own. */
+    purpose: string;
+    categories: HeadlessCategory[];
+    /** The `data` types a site renders (the rest are supporting types, e.g. categories). */
+    primaryTypes: string[];
+    /** Where the business edits the content — the app's admin inside SmartLinks. Sites never build an editor for it. */
+    editedIn: {
+        label: string;
+        adminPath?: string;
+        notes?: string;
+    };
+    /** How a site should present it. */
+    render?: {
+        guidance?: string;
+        seo?: HeadlessSeoHelper[];
+    };
+}

package/dist/types/headless.js

@@ -0,0 +1,16 @@
+// =============================================================================
+// Headless providers — an app's declared public data model, and its promise that other sites and
+// apps can install it and use its content (FAQ, media, content pages, articles…).
+//
+// Two manifest blocks:
+//   data      the app's data types: how each is stored, its fields (JSON types, zone, public or not),
+//             examples, and how to read it. Useful on its own (typed reads, generated editors).
+//   headless  the opt-in: purpose, categories, which types a site renders, where the owner edits the
+//             content, rendering + SEO guidance. Requires a complete `data` block.
+//
+// Validate with `smartlinks-headless` (scripts/headless-check.mjs) or validateHeadless() (SDK).
+// Docs: docs/headless-providers.md.
+// =============================================================================
+export const HEADLESS_CATEGORIES = [
+    'faq', 'media', 'pages', 'articles', 'catalog', 'events', 'locations', 'people', 'reviews', 'documents', 'forms', 'other',
+];

package/dist/types/index.d.ts

@@ -42,3 +42,4 @@ export * from "./integrations.js";
 export * from "./research.js";
 export * from "./config.js";
 export * from "./widgets.js";
+export * from "./headless.js";

package/dist/types/index.js

@@ -44,3 +44,4 @@ export * from "./integrations.js";
 export * from "./research.js";
 export * from "./config.js";
 export * from "./widgets.js";
+export * from "./headless.js";