@nixxie-cms/fields-oembed 1.0.1

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2026 Nixxie International DMCC
+Portions Copyright (c) 2023 Thinkmill Labs Pty Ltd and contributors
+(this software is derived from the KeystoneJS project, https://keystonejs.com)
+
+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.md

@@ -0,0 +1,16 @@
+# @nixxie-cms/fields-oembed
+
+An oEmbed field for Nixxie CMS, for embeddable media URLs (YouTube, Vimeo, tweets, etc.). By
+default it stores a validated URL string; set `resolve: true` to fetch and store the full oEmbed
+payload as JSON on save.
+
+```ts
+import { oembed } from '@nixxie-cms/fields-oembed'
+
+fields: {
+  video: oembed(),                 // stores the validated URL
+  embed: oembed({ resolve: true }) // stores { url, html, title, thumbnailUrl, ... }
+}
+```
+
+Also exports `fetchOembed(url, endpoint?)` for ad-hoc lookups.

package/dist/declarations/src/index.d.ts

@@ -0,0 +1,31 @@
+import type { TextFieldConfig } from '@nixxie-cms/core/fields';
+import type { BaseListTypeInfo, FieldTypeFunc } from '@nixxie-cms/core/types';
+export type OembedData = {
+    url: string;
+    type?: string;
+    title?: string;
+    html?: string;
+    thumbnailUrl?: string;
+    providerName?: string;
+    raw?: any;
+};
+export type OembedFieldConfig<ListTypeInfo extends BaseListTypeInfo> = Omit<TextFieldConfig<ListTypeInfo>, 'validation'> & {
+    validation?: {
+        isRequired?: boolean;
+    };
+    /**
+     * When set, the field stores the full resolved oEmbed payload (as JSON) instead of just the URL,
+     * fetching it on save from this oEmbed endpoint. Default endpoint: https://noembed.com/embed
+     */
+    resolve?: boolean | {
+        endpoint: string;
+    };
+};
+/** Fetch oEmbed data for a URL via an oEmbed proxy endpoint (defaults to noembed.com). */
+export declare function fetchOembed(url: string, endpoint?: string, timeoutMs?: number): Promise<OembedData>;
+/**
+ * An oEmbed field for embeddable media URLs (YouTube, Vimeo, tweets, etc.). By default it stores a
+ * validated URL string. Set `resolve: true` to fetch and store the full oEmbed payload as JSON.
+ */
+export declare function oembed<ListTypeInfo extends BaseListTypeInfo>(config?: OembedFieldConfig<ListTypeInfo>): FieldTypeFunc<ListTypeInfo>;
+//# sourceMappingURL=index.d.ts.map

package/dist/declarations/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"../../../src","sources":["index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAmB,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAC/E,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAE7E,MAAM,MAAM,UAAU,GAAG;IACvB,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,GAAG,CAAC,EAAE,GAAG,CAAA;CACV,CAAA;AAED,MAAM,MAAM,iBAAiB,CAAC,YAAY,SAAS,gBAAgB,IAAI,IAAI,CACzE,eAAe,CAAC,YAAY,CAAC,EAC7B,YAAY,CACb,GAAG;IACF,UAAU,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,OAAO,CAAA;KAAE,CAAA;IACrC;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,GAAG;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAA;CACzC,CAAA;AAWD,0FAA0F;AAC1F,wBAAsB,WAAW,CAC/B,GAAG,EAAE,MAAM,EACX,QAAQ,SAA8B,EACtC,SAAS,SAAO,GACf,OAAO,CAAC,UAAU,CAAC,CAqBrB;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,YAAY,SAAS,gBAAgB,EAC1D,MAAM,GAAE,iBAAiB,CAAC,YAAY,CAAM,GAC3C,aAAa,CAAC,YAAY,CAAC,CA2C7B"}

package/dist/nixxie-cms-fields-oembed.cjs.d.ts

@@ -0,0 +1,2 @@
+export * from "./declarations/src/index.js";
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibml4eGllLWNtcy1maWVsZHMtb2VtYmVkLmNqcy5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi9kZWNsYXJhdGlvbnMvc3JjL2luZGV4LmQudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEifQ==

package/dist/nixxie-cms-fields-oembed.cjs.js

@@ -0,0 +1,106 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var fields = require('@nixxie-cms/core/fields');
+
+function isUrl(value) {
+  try {
+    const u = new URL(value);
+    return u.protocol === 'http:' || u.protocol === 'https:';
+  } catch {
+    return false;
+  }
+}
+
+/** Fetch oEmbed data for a URL via an oEmbed proxy endpoint (defaults to noembed.com). */
+async function fetchOembed(url, endpoint = 'https://noembed.com/embed', timeoutMs = 5000) {
+  // Bound the request so a slow/hanging oEmbed provider can't stall the create/update mutation.
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  let res;
+  try {
+    res = await fetch(`${endpoint}?url=${encodeURIComponent(url)}`, {
+      signal: controller.signal
+    });
+  } finally {
+    clearTimeout(timer);
+  }
+  if (!res.ok) throw new Error(`oEmbed lookup failed (${res.status})`);
+  const raw = await res.json();
+  return {
+    url,
+    type: raw.type,
+    title: raw.title,
+    html: raw.html,
+    thumbnailUrl: raw.thumbnail_url,
+    providerName: raw.provider_name,
+    raw
+  };
+}
+
+/**
+ * An oEmbed field for embeddable media URLs (YouTube, Vimeo, tweets, etc.). By default it stores a
+ * validated URL string. Set `resolve: true` to fetch and store the full oEmbed payload as JSON.
+ */
+function oembed(config = {}) {
+  const {
+    validation,
+    resolve,
+    hooks,
+    ...rest
+  } = config;
+  const endpoint = resolve && typeof resolve === 'object' ? resolve.endpoint : 'https://noembed.com/embed';
+  if (resolve) {
+    return fields.json({
+      ...rest,
+      defaultValue: null,
+      hooks: {
+        ...hooks,
+        resolveInput: async args => {
+          const value = args.resolvedData[args.fieldKey];
+          if (value === undefined) return undefined;
+          if (value === null) return null;
+          const urlString = typeof value === 'string' ? value : value === null || value === void 0 ? void 0 : value.url;
+          if (!urlString || !isUrl(urlString)) return value;
+          try {
+            return await fetchOembed(urlString, endpoint);
+          } catch {
+            return {
+              url: urlString
+            };
+          }
+        }
+      }
+    });
+  }
+  return fields.text({
+    ...rest,
+    validation: {
+      isRequired: validation === null || validation === void 0 ? void 0 : validation.isRequired
+    },
+    ui: {
+      description: 'An embeddable media URL',
+      ...rest.ui
+    },
+    hooks: {
+      ...hooks,
+      validate: args => {
+        const {
+          resolvedData,
+          fieldKey,
+          addValidationError,
+          operation
+        } = args;
+        if (operation === 'delete') return;
+        const value = resolvedData[fieldKey];
+        if (typeof value === 'string' && value.length > 0 && !isUrl(value)) {
+          addValidationError(`${fieldKey} must be a valid http(s) URL`);
+        }
+      }
+    }
+  });
+}
+
+exports.fetchOembed = fetchOembed;
+exports.oembed = oembed;

package/dist/nixxie-cms-fields-oembed.esm.js

@@ -0,0 +1,101 @@
+import { json, text } from '@nixxie-cms/core/fields';
+
+function isUrl(value) {
+  try {
+    const u = new URL(value);
+    return u.protocol === 'http:' || u.protocol === 'https:';
+  } catch {
+    return false;
+  }
+}
+
+/** Fetch oEmbed data for a URL via an oEmbed proxy endpoint (defaults to noembed.com). */
+async function fetchOembed(url, endpoint = 'https://noembed.com/embed', timeoutMs = 5000) {
+  // Bound the request so a slow/hanging oEmbed provider can't stall the create/update mutation.
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  let res;
+  try {
+    res = await fetch(`${endpoint}?url=${encodeURIComponent(url)}`, {
+      signal: controller.signal
+    });
+  } finally {
+    clearTimeout(timer);
+  }
+  if (!res.ok) throw new Error(`oEmbed lookup failed (${res.status})`);
+  const raw = await res.json();
+  return {
+    url,
+    type: raw.type,
+    title: raw.title,
+    html: raw.html,
+    thumbnailUrl: raw.thumbnail_url,
+    providerName: raw.provider_name,
+    raw
+  };
+}
+
+/**
+ * An oEmbed field for embeddable media URLs (YouTube, Vimeo, tweets, etc.). By default it stores a
+ * validated URL string. Set `resolve: true` to fetch and store the full oEmbed payload as JSON.
+ */
+function oembed(config = {}) {
+  const {
+    validation,
+    resolve,
+    hooks,
+    ...rest
+  } = config;
+  const endpoint = resolve && typeof resolve === 'object' ? resolve.endpoint : 'https://noembed.com/embed';
+  if (resolve) {
+    return json({
+      ...rest,
+      defaultValue: null,
+      hooks: {
+        ...hooks,
+        resolveInput: async args => {
+          const value = args.resolvedData[args.fieldKey];
+          if (value === undefined) return undefined;
+          if (value === null) return null;
+          const urlString = typeof value === 'string' ? value : value === null || value === void 0 ? void 0 : value.url;
+          if (!urlString || !isUrl(urlString)) return value;
+          try {
+            return await fetchOembed(urlString, endpoint);
+          } catch {
+            return {
+              url: urlString
+            };
+          }
+        }
+      }
+    });
+  }
+  return text({
+    ...rest,
+    validation: {
+      isRequired: validation === null || validation === void 0 ? void 0 : validation.isRequired
+    },
+    ui: {
+      description: 'An embeddable media URL',
+      ...rest.ui
+    },
+    hooks: {
+      ...hooks,
+      validate: args => {
+        const {
+          resolvedData,
+          fieldKey,
+          addValidationError,
+          operation
+        } = args;
+        if (operation === 'delete') return;
+        const value = resolvedData[fieldKey];
+        if (typeof value === 'string' && value.length > 0 && !isUrl(value)) {
+          addValidationError(`${fieldKey} must be a valid http(s) URL`);
+        }
+      }
+    }
+  });
+}
+
+export { fetchOembed, oembed };

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@nixxie-cms/fields-oembed",
+  "version": "1.0.1",
+  "license": "MIT",
+  "main": "dist/nixxie-cms-fields-oembed.cjs.js",
+  "module": "dist/nixxie-cms-fields-oembed.esm.js",
+  "exports": {
+    ".": {
+      "types": "./dist/nixxie-cms-fields-oembed.cjs.js",
+      "module": "./dist/nixxie-cms-fields-oembed.esm.js",
+      "default": "./dist/nixxie-cms-fields-oembed.cjs.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@babel/runtime": "^7.24.7"
+  },
+  "devDependencies": {
+    "@nixxie-cms/core": "^1.0.1"
+  },
+  "peerDependencies": {
+    "@nixxie-cms/core": "^1.0.1"
+  },
+  "preconstruct": {
+    "entrypoints": [
+      "index.ts"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nixxiecms/nixxie/tree/main/packages/fields-oembed"
+  }
+}

package/src/index.ts

@@ -0,0 +1,113 @@
+import { json, text } from '@nixxie-cms/core/fields'
+import type { JsonFieldConfig, TextFieldConfig } from '@nixxie-cms/core/fields'
+import type { BaseListTypeInfo, FieldTypeFunc } from '@nixxie-cms/core/types'
+
+export type OembedData = {
+  url: string
+  type?: string
+  title?: string
+  html?: string
+  thumbnailUrl?: string
+  providerName?: string
+  raw?: any
+}
+
+export type OembedFieldConfig<ListTypeInfo extends BaseListTypeInfo> = Omit<
+  TextFieldConfig<ListTypeInfo>,
+  'validation'
+> & {
+  validation?: { isRequired?: boolean }
+  /**
+   * When set, the field stores the full resolved oEmbed payload (as JSON) instead of just the URL,
+   * fetching it on save from this oEmbed endpoint. Default endpoint: https://noembed.com/embed
+   */
+  resolve?: boolean | { endpoint: string }
+}
+
+function isUrl(value: string): boolean {
+  try {
+    const u = new URL(value)
+    return u.protocol === 'http:' || u.protocol === 'https:'
+  } catch {
+    return false
+  }
+}
+
+/** Fetch oEmbed data for a URL via an oEmbed proxy endpoint (defaults to noembed.com). */
+export async function fetchOembed(
+  url: string,
+  endpoint = 'https://noembed.com/embed',
+  timeoutMs = 5000
+): Promise<OembedData> {
+  // Bound the request so a slow/hanging oEmbed provider can't stall the create/update mutation.
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+  let res: Response
+  try {
+    res = await fetch(`${endpoint}?url=${encodeURIComponent(url)}`, { signal: controller.signal })
+  } finally {
+    clearTimeout(timer)
+  }
+  if (!res.ok) throw new Error(`oEmbed lookup failed (${res.status})`)
+  const raw: any = await res.json()
+  return {
+    url,
+    type: raw.type,
+    title: raw.title,
+    html: raw.html,
+    thumbnailUrl: raw.thumbnail_url,
+    providerName: raw.provider_name,
+    raw,
+  }
+}
+
+/**
+ * An oEmbed field for embeddable media URLs (YouTube, Vimeo, tweets, etc.). By default it stores a
+ * validated URL string. Set `resolve: true` to fetch and store the full oEmbed payload as JSON.
+ */
+export function oembed<ListTypeInfo extends BaseListTypeInfo>(
+  config: OembedFieldConfig<ListTypeInfo> = {}
+): FieldTypeFunc<ListTypeInfo> {
+  const { validation, resolve, hooks, ...rest } = config
+  const endpoint =
+    resolve && typeof resolve === 'object' ? resolve.endpoint : 'https://noembed.com/embed'
+
+  if (resolve) {
+    return json<ListTypeInfo>({
+      ...(rest as unknown as JsonFieldConfig<ListTypeInfo>),
+      defaultValue: null,
+      hooks: {
+        ...hooks,
+        resolveInput: async (args: any) => {
+          const value = args.resolvedData[args.fieldKey]
+          if (value === undefined) return undefined
+          if (value === null) return null
+          const urlString = typeof value === 'string' ? value : value?.url
+          if (!urlString || !isUrl(urlString)) return value
+          try {
+            return await fetchOembed(urlString, endpoint)
+          } catch {
+            return { url: urlString }
+          }
+        },
+      },
+    })
+  }
+
+  return text<ListTypeInfo>({
+    ...(rest as TextFieldConfig<ListTypeInfo>),
+    validation: { isRequired: validation?.isRequired },
+    ui: { description: 'An embeddable media URL', ...rest.ui },
+    hooks: {
+      ...hooks,
+      validate: (args: any) => {
+        const { resolvedData, fieldKey, addValidationError, operation } = args
+        if (operation === 'delete') return
+        const value = resolvedData[fieldKey]
+        if (typeof value === 'string' && value.length > 0 && !isUrl(value)) {
+          addValidationError(`${fieldKey} must be a valid http(s) URL`)
+        }
+      },
+    },
+  })
+}