@ampless/plugin-schema-jsonld 0.1.1-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ampless contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS 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.

package/README.ja.md

@@ -0,0 +1,90 @@
+> English: [README.md](./README.md)
+>
+
+# @ampless/plugin-schema-jsonld
+
+[ampless](https://github.com/heavymoons/ampless) 向け JSON-LD 構造化データ (Article スキーマ) プラグイン。
+
+> **プレリリース / アルファ版。** v1.0 まではマイナーバージョンでも破壊的変更が入る可能性があります。
+
+`publicBodyForPost` フック (Phase 4) を使って、投稿ページの body 内に `<script type="application/ld+json">` 要素を出力します。スクリプトには、投稿フィールドと 4 つの管理設定から組み立てた [schema.org](https://schema.org/) Article 系オブジェクトが格納されます。
+
+AWS のデータ権限は不要です。プラグインは公開 Next.js プロセス内でリクエスト時に動くだけの純粋関数です。`trust_level` は `untrusted`。
+
+## インストール
+
+```bash
+npm install @ampless/plugin-schema-jsonld@alpha
+```
+
+## 設定
+
+`cms.config.ts` に記述します:
+
+```ts
+import { defineConfig } from 'ampless'
+import schemaJsonLdPlugin from '@ampless/plugin-schema-jsonld'
+
+export default defineConfig({
+  // ...
+  plugins: [
+    schemaJsonLdPlugin(),
+  ],
+})
+```
+
+オプションはすべて省略可能です。著者名・発行者名は空のとき `site.name` にフォールバックします:
+
+```ts
+schemaJsonLdPlugin({
+  articleType:    'BlogPosting',   // デフォルト: 'Article'
+  authorName:     'Jane Smith',    // デフォルト: site.name
+  publisherName:  'Acme Blog',     // デフォルト: site.name
+  publisherLogo:  'https://example.com/logo.png',  // デフォルト: 省略
+})
+```
+
+| オプション | デフォルト | 備考 |
+|---|---|---|
+| `articleType` | `'Article'` | schema.org の `@type`。`Article`、`NewsArticle`、`BlogPosting`、`TechArticle` から選択。`/admin/plugins` から上書き可能。 |
+| `authorName` | `site.name` | スキーマ内の著者 `Person` の名前。空文字または未指定 → `site.name`。 |
+| `publisherName` | `site.name` | 発行者 `Organization` の名前。空文字または未指定 → `site.name`。 |
+| `publisherLogo` | _(省略)_ | 発行者ロゴ画像の絶対 URL。空文字または未指定 → スキーマからロゴを省略。 |
+| `instanceId` | `'schema-jsonld'` | script 要素 id の namespace。2 つのインスタンスを登録する場合にのみ必要。 |
+
+## 管理画面からの設定
+
+上記 4 つのオプションは `/admin/plugins` から編集できる管理設定としても公開されています。管理画面で保存した値はコンストラクタオプションより優先されるため、サイトを再デプロイせずに変更できます。
+
+## アーティクル種別の選び方
+
+| `@type` | 適した用途 |
+|---|---|
+| `Article` | 汎用のデフォルト。一般的なブログや企業ニュースに最適。 |
+| `BlogPosting` | 個人ブログや非公式な記事。Google はリッチリザルトの扱いを `Article` と同等にしています。 |
+| `NewsArticle` | ニュース・ジャーナリズムサイト。Google ニュースのリッチリザルト対象。 |
+| `TechArticle` | 技術ドキュメントやハウツーガイド。 |
+
+適格性ガイドラインは [Google の構造化データドキュメント](https://developers.google.com/search/docs/appearance/structured-data/article) を参照してください。
+
+## Google リッチリザルトテストで確認
+
+デプロイ後、以下で出力を確認できます:
+
+**<https://search.google.com/test/rich-results>**
+
+1. サイト上の任意の投稿 URL を入力します。
+2. ツールが `<script type="application/ld+json">` ブロックを解析し、検出したエンティティ種別を表示します。
+3. 「有効なアイテムが検出されました」と表示されれば、スキーマが正しく認識されています。
+
+## トラストレベル
+
+`untrusted`。プラグインは `@ampless/runtime` が検証・描画する body descriptor を返すだけです。DynamoDB、S3、Lambda プロセッサーには一切触れません。
+
+## 既知の制約
+
+- **著者・発行者が `site.name` にフォールバック** — プラグインは投稿単位の著者レコードにアクセスしません。`authorName` と `publisherName` が空（デフォルト）のとき、どちらも `site.name` を使います。管理設定またはコンストラクタオプションで実名を設定してください。
+- **tags → `keywords` へのマッピング** — `post.tags`（存在する場合）は `, ` で結合されて `keywords` フィールドに書き込まれます。`ItemList` ではなくカンマ区切り文字列です。
+- **ホームページ・一覧ページでは出力されない** — `publicBodyForPost` は投稿個別ページにのみ呼ばれます。インデックスページやタグ一覧などの非投稿ページにはディスクリプタが出力されません。
+- **`BlogPosting` vs `Article`（Google の扱い）** — Google はリッチリザルトにおいてどちらも同等に扱います。非公式な記事には `BlogPosting`、編集コンテンツには `Article`、ニュース媒体を運営している場合のみ `NewsArticle` を選んでください。
+- **image フィールド** — 投稿にカバー画像 URL がある場合でも、現時点では `image` フィールドをスキーマに含めません。将来のリリースで対応予定です。

package/README.md

@@ -0,0 +1,90 @@
+> 日本語版: [README.ja.md](./README.ja.md)
+>
+
+# @ampless/plugin-schema-jsonld
+
+JSON-LD structured data (Article schema) plugin for [ampless](https://github.com/heavymoons/ampless).
+
+> **Pre-release / alpha.** Breaking changes possible in any minor version until v1.0.
+
+Emits a `<script type="application/ld+json">` element inside the post body via the `publicBodyForPost` hook (Phase 4). The script carries an Article-family [schema.org](https://schema.org/) object built from the post's fields and four admin-managed settings.
+
+No AWS data permissions are required — the plugin is a pure function that runs at request time inside the public Next.js process. The plugin's `trust_level` is `untrusted`.
+
+## Install
+
+```bash
+npm install @ampless/plugin-schema-jsonld@alpha
+```
+
+## Configure
+
+In `cms.config.ts`:
+
+```ts
+import { defineConfig } from 'ampless'
+import schemaJsonLdPlugin from '@ampless/plugin-schema-jsonld'
+
+export default defineConfig({
+  // ...
+  plugins: [
+    schemaJsonLdPlugin(),
+  ],
+})
+```
+
+All options are optional. The plugin works out of the box and falls back to `site.name` for author / publisher:
+
+```ts
+schemaJsonLdPlugin({
+  articleType:    'BlogPosting',   // default: 'Article'
+  authorName:     'Jane Smith',    // default: site.name
+  publisherName:  'Acme Blog',     // default: site.name
+  publisherLogo:  'https://example.com/logo.png',  // default: omitted
+})
+```
+
+| Option | Default | Notes |
+|---|---|---|
+| `articleType` | `'Article'` | schema.org `@type`. One of `Article`, `NewsArticle`, `BlogPosting`, `TechArticle`. Can be overridden per-site from `/admin/plugins`. |
+| `authorName` | `site.name` | Author `Person` name in the schema. Empty string or absent → `site.name`. |
+| `publisherName` | `site.name` | Publisher `Organization` name. Empty string or absent → `site.name`. |
+| `publisherLogo` | _(omitted)_ | Absolute URL of the publisher logo image. Empty string or absent → logo omitted from the schema. |
+| `instanceId` | `'schema-jsonld'` | Namespace for the script element id. Needed only when registering two instances. |
+
+## Admin-managed settings
+
+The four options above are also exposed as admin-editable fields at `/admin/plugins`. Values stored there take precedence over the constructor options, so teams can update them without redeploying the site.
+
+## Choosing an Article type
+
+| `@type` | Use when |
+|---|---|
+| `Article` | General-purpose default. Works for most blogs and company news. |
+| `BlogPosting` | Personal blog or informal writing. Google treats it like `Article` for rich results. |
+| `NewsArticle` | News and journalism sites. Eligible for Google News rich results. |
+| `TechArticle` | Technical documentation or how-to guides. |
+
+See [Google's structured data documentation](https://developers.google.com/search/docs/appearance/structured-data/article) for eligibility guidelines.
+
+## Verify with Google Rich Results Test
+
+After deploying, verify the output at:
+
+**<https://search.google.com/test/rich-results>**
+
+1. Enter the URL of any post on your site.
+2. The tool parses the `<script type="application/ld+json">` block and shows detected entity types.
+3. A green "Valid items detected" result means the schema is well-formed.
+
+## Trust level
+
+`untrusted`. The plugin only contributes body descriptors that are validated and rendered by `@ampless/runtime`. It does not touch DynamoDB, S3, or any Lambda processor.
+
+## Known limitations
+
+- **author/publisher fallback to `site.name`** — the plugin does not have access to per-post author records. When `authorName` and `publisherName` are empty (default), both use `site.name`. Set a real author name via the admin settings or the constructor option.
+- **tags → `keywords`** — `post.tags` (when present) are joined with `, ` and written to the `keywords` field. This is a flat comma-separated string, which matches common structured-data consumers; it is not an `ItemList`.
+- **home page / listing routes** — `publicBodyForPost` is only called for individual post pages. Index, tag-listing, and other non-post routes do not receive the descriptor.
+- **`BlogPosting` vs `Article` for Google** — Google treats both types identically for Article rich results. Prefer `BlogPosting` for informal writing, `Article` for editorial content, and `NewsArticle` only if you operate a news publication.
+- **image field** — the schema does not include an `image` field. If your posts have a cover image URL, consider extending the plugin in a future release.

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+import { AmplessPlugin } from 'ampless';
+
+interface SchemaJsonLdOptions {
+    /**
+     * Default schema.org `@type` for this plugin instance — used as the
+     * manifest default for the `articleType` admin field. The admin
+     * value always wins at runtime; this option only seeds the initial
+     * default and acts as a fallback when an admin save somehow ends up
+     * with a value outside `ARTICLE_TYPES` (defence against a future
+     * manifest change).
+     */
+    articleType?: 'Article' | 'NewsArticle' | 'BlogPosting' | 'TechArticle';
+    /**
+     * Default author name — used as the manifest default for the
+     * `authorName` admin field. The admin value (including an explicit
+     * empty string, which means "fall back to site.name") always wins
+     * at runtime; this option only seeds the initial default.
+     */
+    authorName?: string;
+    /**
+     * Default publisher name — used as the manifest default for the
+     * `publisherName` admin field. Same precedence as `authorName`.
+     */
+    publisherName?: string;
+    /**
+     * Default publisher logo URL — used as the manifest default for the
+     * `publisherLogo` admin field. Same precedence as `authorName`. An
+     * empty stored value (admin save or default) omits the logo from
+     * the schema.
+     */
+    publisherLogo?: string;
+    /**
+     * Optional namespace when registering multiple instances (rare for
+     * schema). Defaults to `'schema-jsonld'`.
+     */
+    instanceId?: string;
+}
+/**
+ * Factory for the JSON-LD schema plugin. Returns a plugin manifest that
+ * emits a single `<script type="application/ld+json">` per post via
+ * `publicBodyForPost`. The plugin is `untrusted` — it only builds a pure
+ * in-memory object from post fields and site config; it does not touch
+ * DynamoDB, S3, or any Lambda processor.
+ */
+declare function schemaJsonLdPlugin(options?: SchemaJsonLdOptions): AmplessPlugin;
+
+export { type SchemaJsonLdOptions, schemaJsonLdPlugin as default };

package/dist/index.js

@@ -0,0 +1,126 @@
+// src/index.ts
+import {
+  definePlugin
+} from "ampless";
+var ARTICLE_TYPES = [
+  "Article",
+  "NewsArticle",
+  "BlogPosting",
+  "TechArticle"
+];
+function normalizeBaseUrl(u) {
+  return u.endsWith("/") ? u : u + "/";
+}
+function buildSchema(post, site, opts) {
+  const url = new URL(
+    encodeURIComponent(post.slug),
+    normalizeBaseUrl(site.url)
+  ).toString();
+  return {
+    "@context": "https://schema.org",
+    "@type": opts.articleType,
+    headline: post.title,
+    ...post.excerpt ? { description: post.excerpt } : {},
+    ...post.publishedAt ? { datePublished: post.publishedAt } : {},
+    ...post.updatedAt ? { dateModified: post.updatedAt } : {},
+    mainEntityOfPage: { "@type": "WebPage", "@id": url },
+    url,
+    author: { "@type": "Person", name: opts.authorName },
+    publisher: {
+      "@type": "Organization",
+      name: opts.publisherName,
+      ...opts.publisherLogo ? { logo: { "@type": "ImageObject", url: opts.publisherLogo } } : {}
+    },
+    ...post.tags?.length ? { keywords: post.tags.join(", ") } : {}
+  };
+}
+function schemaJsonLdPlugin(options = {}) {
+  const instanceId = options.instanceId ?? "schema-jsonld";
+  return definePlugin({
+    name: "schema-jsonld",
+    instanceId,
+    apiVersion: 1,
+    trust_level: "untrusted",
+    displayName: { en: "JSON-LD Schema", ja: "JSON-LD \u30B9\u30AD\u30FC\u30DE" },
+    capabilities: ["schema", "adminSettings"],
+    settings: {
+      public: [
+        {
+          type: "select",
+          key: "articleType",
+          label: { en: "Article type", ja: "\u30A2\u30FC\u30C6\u30A3\u30AF\u30EB\u7A2E\u5225" },
+          description: {
+            en: "schema.org @type used for posts.",
+            ja: "\u6295\u7A3F\u306B\u4F7F\u3046 schema.org \u306E @type\u3002"
+          },
+          default: options.articleType ?? "Article",
+          options: ARTICLE_TYPES.map((v) => ({
+            value: v,
+            label: { en: v, ja: v }
+          }))
+        },
+        {
+          type: "text",
+          key: "authorName",
+          label: { en: "Author name", ja: "\u8457\u8005\u540D" },
+          description: {
+            en: "Displayed as the article author. Leave empty to use site.name.",
+            ja: "\u8A18\u4E8B\u306E\u8457\u8005\u3068\u3057\u3066\u8868\u793A\u3055\u308C\u307E\u3059\u3002\u7A7A\u6B04\u3067 site.name \u3092\u4F7F\u7528\u3002"
+          },
+          default: options.authorName ?? ""
+        },
+        {
+          type: "text",
+          key: "publisherName",
+          label: { en: "Publisher name", ja: "\u767A\u884C\u8005\u540D" },
+          description: {
+            en: "Displayed as the publisher organization. Leave empty to use site.name.",
+            ja: "\u767A\u884C\u7D44\u7E54\u3068\u3057\u3066\u8868\u793A\u3055\u308C\u307E\u3059\u3002\u7A7A\u6B04\u3067 site.name \u3092\u4F7F\u7528\u3002"
+          },
+          default: options.publisherName ?? ""
+        },
+        {
+          type: "url",
+          key: "publisherLogo",
+          label: { en: "Publisher logo URL", ja: "\u767A\u884C\u8005\u30ED\u30B4 URL" },
+          description: {
+            en: "Absolute URL of the publisher logo image. Leave empty to omit the logo from the schema.",
+            ja: "\u767A\u884C\u8005\u30ED\u30B4\u753B\u50CF\u306E\u7D76\u5BFE URL\u3002\u7A7A\u6B04\u3067\u30B9\u30AD\u30FC\u30DE\u304B\u3089\u30ED\u30B4\u3092\u7701\u7565\u3057\u307E\u3059\u3002"
+          },
+          default: options.publisherLogo ?? "",
+          // Google Rich Results expects an absolute URL for
+          // publisher.logo (ImageObject.url); a relative path would
+          // be interpreted against whatever page the crawler is on.
+          allowRelative: false
+        }
+      ]
+    },
+    publicBodyForPost(post, ctx) {
+      const site = ctx.site;
+      const rawType = (ctx.setting("articleType") ?? "").trim();
+      const articleType = ARTICLE_TYPES.includes(rawType) ? rawType : "Article";
+      const authorName = (ctx.setting("authorName") ?? "").trim() || site.name;
+      const publisherName = (ctx.setting("publisherName") ?? "").trim() || site.name;
+      const publisherLogo = (ctx.setting("publisherLogo") ?? "").trim();
+      const schema = buildSchema(post, site, {
+        articleType,
+        authorName,
+        publisherName,
+        publisherLogo
+      });
+      return [
+        {
+          type: "inlineScript",
+          id: `schema-jsonld-${instanceId}`,
+          scriptType: "application/ld+json",
+          // JSON.stringify produces valid JSON; the runtime auto-escapes
+          // </script>-breaking chars so we must NOT escape them here.
+          body: JSON.stringify(schema)
+        }
+      ];
+    }
+  });
+}
+export {
+  schemaJsonLdPlugin as default
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@ampless/plugin-schema-jsonld",
+  "version": "0.1.1-alpha.0",
+  "description": "JSON-LD structured data (Article schema) for ampless posts.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/heavymoons/ampless.git",
+    "directory": "packages/plugin-schema-jsonld"
+  },
+  "homepage": "https://github.com/heavymoons/ampless/tree/main/packages/plugin-schema-jsonld#readme",
+  "bugs": "https://github.com/heavymoons/ampless/issues",
+  "dependencies": {
+    "ampless": "1.0.0-alpha.21"
+  },
+  "keywords": [
+    "ampless",
+    "plugin",
+    "schema",
+    "json-ld",
+    "structured-data",
+    "seo",
+    "article"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  }
+}