feat: add custom post metadata type

Author: kualta

jsonschemas/schema.json

@@ -27,6 +27,9 @@
     {
       "$ref": "#/$defs/MintMetadata"
     },
+    {
+      "$ref": "#/$defs/CustomMetadata"
+    },
     {
       "$ref": "#/$defs/SpaceMetadata"
     },
@@ -78,7 +81,8 @@
         "SHORT_VIDEO",
         "3D",
         "STORY",
-        "SPACE"
+        "SPACE",
+        "CUSTOM"
       ]
     },
     "AnyMedia": {
@@ -2306,6 +2310,9 @@
       ],
       "additionalProperties": true
     },
+    "CustomMetadata": {
+      "$ref": "posts/custom/3.0.0.json"
+    },
     "SpaceMetadata": {
       "type": "object",
       "properties": {

scripts/build.ts

@@ -39,6 +39,7 @@ import {
   MetadataIdSchema,
   MetadataLicenseTypeSchema,
   MintSchema,
+  CustomSchema,
   NamespaceMetadataSchema,
   NamespaceRuleMetadataSchema,
   Nft721MetadataAttributeSchema,
@@ -77,6 +78,7 @@ const schemas = new Map<string, z.ZodSchema<unknown>>([
   ['posts/link/3.0.0.json', LinkSchema],
   ['posts/livestream/3.0.0.json', LiveStreamSchema],
   ['posts/mint/3.0.0.json', MintSchema],
+  ['posts/custom/3.0.0.json', CustomSchema],
   ['posts/space/3.0.0.json', SpaceSchema],
   ['posts/story/3.0.0.json', StorySchema],
   ['posts/text-only/3.0.0.json', TextOnlySchema],
@@ -216,6 +218,7 @@ async function generateUmbrellaSchema() {
       LinkMetadata: LinkSchema,
       LiveStreamMetadata: LiveStreamSchema,
       MintMetadata: MintSchema,
+      CustomMetadata: CustomSchema,
       SpaceMetadata: SpaceSchema,
       TextOnlyMetadata: TextOnlySchema,
       StoryMetadata: StorySchema,

src/builders/posts.ts

@@ -28,6 +28,9 @@ import {
   type MintMetadata,
   type MintMetadataDetails,
   MintSchema,
+  type CustomMetadata,
+  type CustomMetadataDetails,
+  CustomSchema,
   PostMainFocus,
   PostMetadataSchemaId,
   type SpaceMetadata,
@@ -652,6 +655,46 @@ export function mint({
   );
 }
 
+/**
+ * @private
+ * @privateRemarks MUST stay very @private to produce usable docs
+ */
+type CustomDetails = InputForPostMetadataDetails<CustomMetadataDetails>;
+/**
+ * All {@link CustomMetadataDetails} fields with:
+ * - `id` defaults to a UUID
+ * - `locale` defaults to `en`
+ * - `mainContentFocus` automatically set to `PostSchemaId.CUSTOM_LATEST`
+ */
+export type CustomOptions = CustomDetails & {
+  /**
+   * All the {@link NftMetadata} fields.
+   */
+  nft?: NftDetails;
+};
+/**
+ * Creates a valid CustomMetadata.
+ */
+export function custom({
+  nft,
+  locale = DEFAULT_LOCALE,
+  id = v4(),
+  ...others
+}: CustomOptions): CustomMetadata {
+  return evaluate(
+    CustomSchema.safeParse({
+      $schema: PostMetadataSchemaId.CUSTOM_LATEST,
+      ...nft,
+      lens: {
+        id,
+        locale,
+        mainContentFocus: PostMainFocus.CUSTOM,
+        ...others,
+      },
+    }),
+  );
+}
+
 /**
  * @private
  * @privateRemarks MUST stay very @private to produce usable docs

src/post/CustomSchema.ts

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+
+import { NonEmptyStringSchema, type Signature } from '../primitives.js';
+import type { NftMetadata } from '../tokens/eip721.js';
+import { PostMainFocus } from './PostMainFocus.js';
+import { PostMetadataSchemaId } from './PostMetadataSchemaId.js';
+import {
+  mainContentFocus,
+  metadataDetailsWith,
+  postWith,
+  type PostMetadataCommon,
+} from './common';
+
+export type CustomMetadataDetails = PostMetadataCommon & {
+  /**
+   * The main focus of the post.
+   */
+  mainContentFocus: PostMainFocus.CUSTOM;
+  /**
+   * A JSON string containing any custom data.
+   */
+  value: string;
+};
+
+const CustomMetadataDetailsSchema: z.ZodType<CustomMetadataDetails, z.ZodTypeDef, object> =
+  metadataDetailsWith({
+    mainContentFocus: mainContentFocus(PostMainFocus.CUSTOM),
+
+    value: NonEmptyStringSchema.describe('A JSON string containing any custom data.'),
+  });
+
+export type CustomMetadata = NftMetadata & {
+  /**
+   * The schema id.
+   */
+  $schema: PostMetadataSchemaId.CUSTOM_LATEST;
+  /**
+   * The metadata details.
+   */
+  lens: CustomMetadataDetails;
+  /**
+   * A cryptographic signature of the `lens` data.
+   */
+  signature?: Signature;
+};
+
+export const CustomSchema = postWith({
+  $schema: z.literal(PostMetadataSchemaId.CUSTOM_LATEST),
+  lens: CustomMetadataDetailsSchema,
+});

src/post/PostMainFocus.ts

@@ -20,6 +20,7 @@ export enum PostMainFocus {
   THREE_D = '3D',
   STORY = 'STORY',
   SPACE = 'SPACE',
+  CUSTOM = 'CUSTOM',
 }
 
 export const PostMainFocusSchema = z.nativeEnum(PostMainFocus);

src/post/PostMetadataSchemaId.ts

@@ -21,4 +21,5 @@ export enum PostMetadataSchemaId {
   TRANSACTION_LATEST = `${location}/transaction/3.0.0.json`,
   TEXT_ONLY_LATEST = `${location}/text-only/3.0.0.json`,
   VIDEO_LATEST = `${location}/video/3.0.0.json`,
+  CUSTOM_LATEST = `${location}/custom/3.0.0.json`,
 }

src/post/index.ts

@@ -11,6 +11,7 @@ export * from './ImageSchema.js';
 export * from './LinkSchema.js';
 export * from './LiveStreamSchema.js';
 export * from './MintSchema.js';
+export * from './CustomSchema.js';
 export * from './PostMainFocus.js';
 export * from './PostMetadataSchemaId.js';
 export * from './SpaceSchema.js';
@@ -30,6 +31,7 @@ import { type ImageMetadata, ImageSchema } from './ImageSchema.js';
 import { type LinkMetadata, LinkSchema } from './LinkSchema.js';
 import { type LiveStreamMetadata, LiveStreamSchema } from './LiveStreamSchema.js';
 import { type MintMetadata, MintSchema } from './MintSchema.js';
+import { type CustomMetadata, CustomSchema } from './CustomSchema.js';
 import { type SpaceMetadata, SpaceSchema } from './SpaceSchema.js';
 import { type StoryMetadata, StorySchema } from './StorySchema.js';
 import { type TextOnlyMetadata, TextOnlySchema } from './TextOnlySchema.js';
@@ -82,6 +84,7 @@ export type PostMetadata = ShapeCheck<
   | LinkMetadata
   | LiveStreamMetadata
   | MintMetadata
+  | CustomMetadata
   | SpaceMetadata
   | TextOnlyMetadata
   | StoryMetadata
@@ -124,6 +127,7 @@ export const PostMetadataSchema: z.ZodType<PostMetadata, z.ZodTypeDef, object> =
     LinkSchema,
     LiveStreamSchema,
     MintSchema,
+    CustomSchema,
     SpaceSchema,
     TextOnlySchema,
     StorySchema,