@takuhon/core 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 var $schema = "https://json-schema.org/draft/2020-12/schema";
-var $id = "https://takuhon.example/schemas/0.2.0/takuhon.schema.json";
+var $id = "https://takuhon.example/schemas/0.4.0/takuhon.schema.json";
 var title = "Takuhon Profile";
 var description = "Portable profile data format consumed by @takuhon/core. The canonical contract for profile content authored as takuhon.json.";
 var type = "object";
@@ -115,6 +115,20 @@ var properties = {
 			$ref: "#/$defs/Patent"
 		}
 	},
+	testScores: {
+		type: "array",
+		maxItems: 30,
+		items: {
+			$ref: "#/$defs/TestScore"
+		}
+	},
+	recommendations: {
+		type: "array",
+		maxItems: 50,
+		items: {
+			$ref: "#/$defs/Recommendation"
+		}
+	},
 	contact: {
 		$ref: "#/$defs/Contact"
 	},
@@ -599,7 +613,7 @@ var $defs = {
 	MetaPrivacy: {
 		type: "object",
 		additionalProperties: true,
-		description: "Opt-out flags that strip personally identifying fields from public API output (GET /api/profile, /api/jsonld, /takuhon.json). Admin endpoints (PUT /api/admin/*, GET /api/export) ignore these flags. Privacy-by-default: omitting the object or individual flags is equivalent to true.",
+		description: "Opt-out flags that strip personally identifying fields from public API output (GET /api/profile, /api/jsonld, /takuhon.json). Admin endpoints (PUT /api/admin/*, GET /api/admin/export) ignore these flags. Privacy-by-default: omitting the object or individual flags is equivalent to true.",
 		properties: {
 			hideCredentialIds: {
 				type: "boolean",
@@ -1034,6 +1048,109 @@ var $defs = {
 				minimum: 0
 			}
 		}
+	},
+	TestScore: {
+		type: "object",
+		additionalProperties: true,
+		required: [
+			"id",
+			"title",
+			"score",
+			"date"
+		],
+		properties: {
+			id: {
+				$ref: "#/$defs/Slug"
+			},
+			title: {
+				$ref: "#/$defs/LocalizedTitle"
+			},
+			score: {
+				type: "string",
+				minLength: 1,
+				maxLength: 50,
+				description: "Free-form score string (e.g. '112 / 120', '330', 'N1 Pass', or a percentile). The validator does not interpret its contents."
+			},
+			date: {
+				$ref: "#/$defs/YearMonth"
+			},
+			relatedEducationId: {
+				$ref: "#/$defs/Slug",
+				description: "Optional reference to an education[].id (e.g. for a university course exam)."
+			},
+			description: {
+				$ref: "#/$defs/LocalizedBody"
+			},
+			url: {
+				$ref: "#/$defs/Url"
+			},
+			order: {
+				type: "integer",
+				minimum: 0
+			}
+		}
+	},
+	Recommendation: {
+		type: "object",
+		additionalProperties: true,
+		required: [
+			"id",
+			"body",
+			"author"
+		],
+		properties: {
+			id: {
+				$ref: "#/$defs/Slug"
+			},
+			body: {
+				$ref: "#/$defs/LocalizedBody"
+			},
+			author: {
+				$ref: "#/$defs/RecommendationAuthor"
+			},
+			relationship: {
+				$ref: "#/$defs/LocalizedTitle",
+				description: "How the recommender relates to the profile owner (e.g. 'managed directly', 'worked together')."
+			},
+			date: {
+				$ref: "#/$defs/YearMonth"
+			},
+			relatedCareerId: {
+				$ref: "#/$defs/Slug",
+				description: "Optional reference to a careers[].id (the position the recommendation pertains to)."
+			},
+			relatedEducationId: {
+				$ref: "#/$defs/Slug",
+				description: "Optional reference to an education[].id (e.g. a recommendation from a professor)."
+			},
+			order: {
+				type: "integer",
+				minimum: 0
+			}
+		}
+	},
+	RecommendationAuthor: {
+		type: "object",
+		additionalProperties: true,
+		required: [
+			"name"
+		],
+		properties: {
+			name: {
+				type: "string",
+				minLength: 1,
+				maxLength: 100,
+				description: "Recommender's name, in its original script. Owner-curated; takuhon does not verify it."
+			},
+			headline: {
+				$ref: "#/$defs/LocalizedTitle",
+				description: "Recommender's title / role / organization at the time of the recommendation."
+			},
+			url: {
+				$ref: "#/$defs/Url",
+				description: "Link to the recommender's profile, for external verification by the reader."
+			}
+		}
 	}
 };
 var schemaJson = {
@@ -1165,6 +1282,20 @@ declare const schema: {
                 $ref: string;
             };
         };
+        testScores: {
+            type: string;
+            maxItems: number;
+            items: {
+                $ref: string;
+            };
+        };
+        recommendations: {
+            type: string;
+            maxItems: number;
+            items: {
+                $ref: string;
+            };
+        };
         contact: {
             $ref: string;
         };
@@ -1981,6 +2112,98 @@ declare const schema: {
                 };
             };
         };
+        TestScore: {
+            type: string;
+            additionalProperties: boolean;
+            required: string[];
+            properties: {
+                id: {
+                    $ref: string;
+                };
+                title: {
+                    $ref: string;
+                };
+                score: {
+                    type: string;
+                    minLength: number;
+                    maxLength: number;
+                    description: string;
+                };
+                date: {
+                    $ref: string;
+                };
+                relatedEducationId: {
+                    $ref: string;
+                    description: string;
+                };
+                description: {
+                    $ref: string;
+                };
+                url: {
+                    $ref: string;
+                };
+                order: {
+                    type: string;
+                    minimum: number;
+                };
+            };
+        };
+        Recommendation: {
+            type: string;
+            additionalProperties: boolean;
+            required: string[];
+            properties: {
+                id: {
+                    $ref: string;
+                };
+                body: {
+                    $ref: string;
+                };
+                author: {
+                    $ref: string;
+                };
+                relationship: {
+                    $ref: string;
+                    description: string;
+                };
+                date: {
+                    $ref: string;
+                };
+                relatedCareerId: {
+                    $ref: string;
+                    description: string;
+                };
+                relatedEducationId: {
+                    $ref: string;
+                    description: string;
+                };
+                order: {
+                    type: string;
+                    minimum: number;
+                };
+            };
+        };
+        RecommendationAuthor: {
+            type: string;
+            additionalProperties: boolean;
+            required: string[];
+            properties: {
+                name: {
+                    type: string;
+                    minLength: number;
+                    maxLength: number;
+                    description: string;
+                };
+                headline: {
+                    $ref: string;
+                    description: string;
+                };
+                url: {
+                    $ref: string;
+                    description: string;
+                };
+            };
+        };
     };
 };
 type Schema = typeof schemaJson;
@@ -2234,6 +2457,45 @@ interface Patent {
     coInventors?: string[];
     order?: number;
 }
+interface TestScore {
+    id: Slug;
+    title: LocalizedTitle;
+    /**
+     * Free-form score string (e.g. '112 / 120', '330', 'N1 Pass', a percentile).
+     * Stored verbatim; the validator does not interpret its contents.
+     */
+    score: string;
+    /** Test date (year-month). */
+    date: YearMonth;
+    /** Optional reference to an `education[].id` (e.g. for a university course exam). */
+    relatedEducationId?: Slug;
+    description?: LocalizedBody;
+    url?: string;
+    order?: number;
+}
+interface RecommendationAuthor {
+    /** Recommender's name in its original script. Owner-curated; not verified by takuhon. */
+    name: string;
+    /** Recommender's title / role / organization at the time of the recommendation. */
+    headline?: LocalizedTitle;
+    /** Link to the recommender's profile, for external verification by the reader. */
+    url?: string;
+}
+interface Recommendation {
+    id: Slug;
+    /** The recommendation text (testimonial body). */
+    body: LocalizedBody;
+    author: RecommendationAuthor;
+    /** How the recommender relates to the profile owner (e.g. 'managed directly'). */
+    relationship?: LocalizedTitle;
+    /** When the recommendation was given (year-month). */
+    date?: YearMonth;
+    /** Optional reference to a `careers[].id` the recommendation pertains to. */
+    relatedCareerId?: Slug;
+    /** Optional reference to an `education[].id` the recommendation pertains to. */
+    relatedEducationId?: Slug;
+    order?: number;
+}
 interface Contact {
     email?: string;
     showEmail?: boolean;
@@ -2268,7 +2530,7 @@ interface ContentLicense {
 /**
  * Privacy opt-out flags that strip personally identifying fields from public
  * API output (`GET /api/profile`, `/api/jsonld`, `/takuhon.json`). Admin
- * endpoints (`PUT /api/admin/*`, `GET /api/export`) ignore these flags.
+ * endpoints (`PUT /api/admin/*`, `GET /api/admin/export`) ignore these flags.
  * Privacy-by-default: omitting the object or individual flags is equivalent
  * to `true`.
  */
@@ -2289,10 +2551,11 @@ interface Meta {
 /**
  * A complete takuhon profile document.
  *
- * Schema-level, the nine new arrays from 0.2.0 (`certifications` through
- * `patents`) are optional for 0.1.x back-compat. At the TypeScript layer they
- * are typed as required because `validate()` and `normalize()` defensively
- * coerce missing arrays to `[]` so downstream consumers never see `undefined`.
+ * Schema-level, the nine arrays added in 0.2.0 (`certifications` through
+ * `patents`), `testScores` (0.3.0), and `recommendations` (0.4.0) are optional
+ * for back-compat with older documents. At the TypeScript layer they are typed
+ * as required because `validate()` and `normalize()` defensively coerce missing
+ * arrays to `[]` so downstream consumers never see `undefined`.
  */
 interface Takuhon {
     schemaVersion: string;
@@ -2310,6 +2573,8 @@ interface Takuhon {
     languages: Language[];
     courses: Course[];
     patents: Patent[];
+    testScores: TestScore[];
+    recommendations: Recommendation[];
     contact: Contact;
     settings: Settings;
     meta: Meta;
@@ -2496,6 +2761,34 @@ interface LocalizedPatent {
     coInventors?: string[];
     order?: number;
 }
+/** Test score with localized fields collapsed to single strings. */
+interface LocalizedTestScore {
+    id: Slug;
+    title: string;
+    score: string;
+    date: YearMonth;
+    relatedEducationId?: Slug;
+    description?: string;
+    url?: string;
+    order?: number;
+}
+/** Recommendation author with `headline` collapsed to a single string. */
+interface LocalizedRecommendationAuthor {
+    name: string;
+    headline?: string;
+    url?: string;
+}
+/** Recommendation with localized fields collapsed to single strings. */
+interface LocalizedRecommendation {
+    id: Slug;
+    body: string;
+    author: LocalizedRecommendationAuthor;
+    relationship?: string;
+    date?: YearMonth;
+    relatedCareerId?: Slug;
+    relatedEducationId?: Slug;
+    order?: number;
+}
 /**
  * A takuhon document with every localized map flattened to a single string,
  * plus a `resolvedLocale` field recording which tag was actually used as the
@@ -2520,6 +2813,8 @@ interface LocalizedTakuhon {
     languages: LocalizedLanguage[];
     courses: LocalizedCourse[];
     patents: LocalizedPatent[];
+    testScores: LocalizedTestScore[];
+    recommendations: LocalizedRecommendation[];
     contact: Contact;
     settings: Settings;
     meta: Meta;
@@ -2561,7 +2856,7 @@ interface LocalizedTakuhon {
  * versions whose JSON Schema this package literally bundles, not the full
  * support window seen by end users.
  */
-declare const SUPPORTED_SCHEMA_VERSIONS: readonly ["0.1.0", "0.2.0"];
+declare const SUPPORTED_SCHEMA_VERSIONS: readonly ["0.1.0", "0.2.0", "0.3.0", "0.4.0"];
 /**
  * A single validation failure.
  *
@@ -2760,7 +3055,7 @@ declare function generateJsonLd(data: LocalizedTakuhon): object[];
  * Structural alias of {@link Takuhon}: the transport form is the document
  * itself. A wrapping envelope (e.g. `{ format, version, data, hash }`) is
  * intentionally avoided in Phase 1 — adding one later would be a breaking
- * change to the `GET /api/export` response shape and would require a major
+ * change to the `GET /api/admin/export` response shape and would require a major
  * version bump of `@takuhon/core`.
  */
 type ExportedTakuhon = Takuhon;
@@ -2812,10 +3107,10 @@ declare function importTakuhon(data: ExportedTakuhon): Takuhon;
  * Forward migration entry point for takuhon documents.
  *
  * {@link migrateTakuhon} composes a chain of {@link Migration} entries from
- * the registry (`./migrations`) and applies them in order. Phase 1 ships
- * with an empty registry, so any non-identity migration currently throws
- * {@link MigrationError}; the first concrete entry will land alongside
- * the v0.2.0 schema bump.
+ * the registry (`./migrations`) and applies them in order. The registry
+ * currently ships the `0.1.0 → 0.2.0`, `0.2.0 → 0.3.0`, and `0.3.0 → 0.4.0`
+ * forward migrations; a request whose source has no chain to the target
+ * throws {@link MigrationError}.
  *
  * Scope (deliberately narrow, mirroring `export.ts`):
  * - Pure data transform — no I/O, no backup creation, no storage write.
@@ -3047,8 +3342,8 @@ declare class ConflictError extends StorageError {
  *   {@link ExportedTakuhon} / {@link ImportError}: roundtrip-stable
  *   serialisation for transport (file, API response, …).
  * - {@link migrateTakuhon} / {@link Migration} / {@link migrations} /
- *   {@link MigrationError}: forward-only migration registry. Empty in
- *   Phase 1; first entry lands with the v0.2.0 schema bump.
+ *   {@link MigrationError}: forward-only migration registry, chaining
+ *   `0.1.0 → 0.2.0 → 0.3.0 → 0.4.0`.
  * - Domain types: {@link Takuhon} and its constituent shapes (`Profile`,
  *   `Settings`, `Career`, `Project`, `Link` discriminated union, etc.).
  */
@@ -3058,6 +3353,6 @@ declare class ConflictError extends StorageError {
  * A takuhon profile document's `schemaVersion` field must be migrate-compatible
  * with this version. See operational-lifecycle docs for the migration policy.
  */
-declare const SCHEMA_VERSION = "0.2.0";
+declare const SCHEMA_VERSION = "0.4.0";
 
-export { type Address, type AssetOptions, type AssetRecord, type Avatar, type Career, type Certification, ConflictError, type Contact, type ContentLicense, type ContentLicenseAttribution, type Course, type Education, type ExportOptions, type ExportedTakuhon, type Honor, ImportError, type Iso3166Alpha2, type IsoDateTime, type Language, type LanguageProficiency, type Link, type LinkBuiltin, type LinkCustom, type LinkType, type LocaleTag, type LocalizedAddress, type LocalizedAvatar, type LocalizedBody, type LocalizedCareer, type LocalizedCertification, type LocalizedCourse, type LocalizedEducation, type LocalizedHonor, type LocalizedLanguage, type LocalizedLink, type LocalizedLinkBuiltin, type LocalizedLinkCustom, type LocalizedMembership, type LocalizedPatent, type LocalizedProfile, type LocalizedProject, type LocalizedPublication, type LocalizedTakuhon, type LocalizedTitle, type LocalizedVolunteering, type Membership, type Meta, type MetaPrivacy, type Migration, MigrationError, type NormalizedTakuhon, NotFoundError, type Patent, type PatentStatus, type Profile, type Project, type Publication, SCHEMA_VERSION, SUPPORTED_SCHEMA_VERSIONS, type Schema, type Settings, type Skill, type Slug, StorageError, type Takuhon, type TakuhonAssetStorage, type TakuhonStorage, type ValidationError, type ValidationResult, type Volunteering, type YearMonth, exportTakuhon, generateJsonLd, generatePersonJsonLd, generateProfilePageJsonLd, importTakuhon, migrateTakuhon, migrations, normalize, resolveLocale, schema, validate };
+export { type Address, type AssetOptions, type AssetRecord, type Avatar, type Career, type Certification, ConflictError, type Contact, type ContentLicense, type ContentLicenseAttribution, type Course, type Education, type ExportOptions, type ExportedTakuhon, type Honor, ImportError, type Iso3166Alpha2, type IsoDateTime, type Language, type LanguageProficiency, type Link, type LinkBuiltin, type LinkCustom, type LinkType, type LocaleTag, type LocalizedAddress, type LocalizedAvatar, type LocalizedBody, type LocalizedCareer, type LocalizedCertification, type LocalizedCourse, type LocalizedEducation, type LocalizedHonor, type LocalizedLanguage, type LocalizedLink, type LocalizedLinkBuiltin, type LocalizedLinkCustom, type LocalizedMembership, type LocalizedPatent, type LocalizedProfile, type LocalizedProject, type LocalizedPublication, type LocalizedRecommendation, type LocalizedRecommendationAuthor, type LocalizedTakuhon, type LocalizedTestScore, type LocalizedTitle, type LocalizedVolunteering, type Membership, type Meta, type MetaPrivacy, type Migration, MigrationError, type NormalizedTakuhon, NotFoundError, type Patent, type PatentStatus, type Profile, type Project, type Publication, type Recommendation, type RecommendationAuthor, SCHEMA_VERSION, SUPPORTED_SCHEMA_VERSIONS, type Schema, type Settings, type Skill, type Slug, StorageError, type Takuhon, type TakuhonAssetStorage, type TakuhonStorage, type TestScore, type ValidationError, type ValidationResult, type Volunteering, type YearMonth, exportTakuhon, generateJsonLd, generatePersonJsonLd, generateProfilePageJsonLd, importTakuhon, migrateTakuhon, migrations, normalize, resolveLocale, schema, validate };