@oxyhq/core 3.11.0 → 3.13.0

package/src/mixins/index.ts

@@ -30,6 +30,7 @@ import { OxyServicesTopicsMixin } from './OxyServices.topics';
 import { OxyServicesManagedAccountsMixin } from './OxyServices.managedAccounts';
 import { OxyServicesContactsMixin } from './OxyServices.contacts';
 import { OxyServicesAppDataMixin } from './OxyServices.appData';
+import { OxyServicesCivicMixin } from './OxyServices.civic';
 
 /**
  * Instance shape of every mixin in the pipeline, intersected. The runtime
@@ -64,6 +65,7 @@ type AllMixinInstances =
   & InstanceType<ReturnType<typeof OxyServicesManagedAccountsMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesCivicMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
 
 /**
@@ -130,6 +132,8 @@ const MIXIN_PIPELINE: MixinFunction[] = [
     OxyServicesManagedAccountsMixin,
     OxyServicesContactsMixin,
     OxyServicesAppDataMixin,
+    // Civic / Commons "Oxy ID" (public signed cards, Oxy ID QR payload)
+    OxyServicesCivicMixin,
 
     // Utility (last, can use all above)
     OxyServicesUtilityMixin,

package/src/utils/__tests__/profileLinks.test.ts

@@ -0,0 +1,180 @@
+import { normalizeProfileLinks, type ProfileLink } from '../profileLinks';
+
+describe('normalizeProfileLinks', () => {
+  describe('linksMetadata path (preferred)', () => {
+    it('maps title + url and uses the entry id when present', () => {
+      const result = normalizeProfileLinks([
+        { url: 'https://oxy.so', title: 'Oxy', id: 'abc' },
+      ]);
+      expect(result).toEqual<ProfileLink[]>([
+        { id: 'abc', title: 'Oxy', url: 'https://oxy.so' },
+      ]);
+    });
+
+    it('falls back to the index when an entry has no id', () => {
+      const result = normalizeProfileLinks([
+        { url: 'https://a.example', title: 'A' },
+        { url: 'https://b.example', title: 'B' },
+      ]);
+      expect(result).toEqual<ProfileLink[]>([
+        { id: '0', title: 'A', url: 'https://a.example' },
+        { id: '1', title: 'B', url: 'https://b.example' },
+      ]);
+    });
+
+    it('omits title when absent', () => {
+      const result = normalizeProfileLinks([{ url: 'https://no-title.example' }]);
+      expect(result).toEqual<ProfileLink[]>([
+        { id: '0', url: 'https://no-title.example' },
+      ]);
+      expect(result[0]).not.toHaveProperty('title');
+    });
+
+    it('carries through description and image when present', () => {
+      const result = normalizeProfileLinks([
+        {
+          url: 'https://oxy.so',
+          title: 'Oxy',
+          description: 'The Oxy ecosystem',
+          image: 'https://cdn.example/oxy.png',
+          id: 'abc',
+        },
+      ]);
+      expect(result).toEqual<ProfileLink[]>([
+        {
+          id: 'abc',
+          title: 'Oxy',
+          url: 'https://oxy.so',
+          description: 'The Oxy ecosystem',
+          image: 'https://cdn.example/oxy.png',
+        },
+      ]);
+    });
+
+    it('omits description and image when absent', () => {
+      const result = normalizeProfileLinks([
+        { url: 'https://min.example', title: 'Min' },
+      ]);
+      expect(result).toEqual<ProfileLink[]>([
+        { id: '0', title: 'Min', url: 'https://min.example' },
+      ]);
+      expect(result[0]).not.toHaveProperty('description');
+      expect(result[0]).not.toHaveProperty('image');
+    });
+
+    it('carries description and image independently of title', () => {
+      const result = normalizeProfileLinks([
+        { url: 'https://only-image.example', image: 'https://cdn.example/i.png' },
+        { url: 'https://only-desc.example', description: 'Just a description' },
+      ]);
+      expect(result).toEqual<ProfileLink[]>([
+        { id: '0', url: 'https://only-image.example', image: 'https://cdn.example/i.png' },
+        { id: '1', url: 'https://only-desc.example', description: 'Just a description' },
+      ]);
+      expect(result[0]).not.toHaveProperty('title');
+      expect(result[0]).not.toHaveProperty('description');
+      expect(result[1]).not.toHaveProperty('title');
+      expect(result[1]).not.toHaveProperty('image');
+    });
+
+    it('drops entries with missing or empty url and keeps stable index ids', () => {
+      const result = normalizeProfileLinks([
+        { url: 'https://keep.example', title: 'Keep', id: 'keep' },
+        { url: '', title: 'Empty' },
+        { url: '   ', title: 'Whitespace' },
+        { url: 'https://second.example', title: 'Second' },
+      ]);
+      expect(result).toEqual<ProfileLink[]>([
+        { id: 'keep', title: 'Keep', url: 'https://keep.example' },
+        // index is preserved from the source array position (3), not re-numbered
+        { id: '3', title: 'Second', url: 'https://second.example' },
+      ]);
+    });
+
+    it('trims surrounding whitespace from urls', () => {
+      const result = normalizeProfileLinks([{ url: '  https://trim.example  ' }]);
+      expect(result).toEqual<ProfileLink[]>([
+        { id: '0', url: 'https://trim.example' },
+      ]);
+    });
+
+    it('does NOT add a scheme to bare urls', () => {
+      const result = normalizeProfileLinks([{ url: 'oxy.so', title: 'Bare' }]);
+      expect(result).toEqual<ProfileLink[]>([
+        { id: '0', title: 'Bare', url: 'oxy.so' },
+      ]);
+    });
+  });
+
+  describe('legacy links path (no linksMetadata)', () => {
+    it('maps strings to { id, url } without title/description/image', () => {
+      const result = normalizeProfileLinks(undefined, [
+        'https://a.example',
+        'https://b.example',
+      ]);
+      expect(result).toEqual<ProfileLink[]>([
+        { id: '0', url: 'https://a.example' },
+        { id: '1', url: 'https://b.example' },
+      ]);
+      expect(
+        result.every(
+          (link) =>
+            !('title' in link) &&
+            !('description' in link) &&
+            !('image' in link),
+        ),
+      ).toBe(true);
+    });
+
+    it('drops empty and whitespace-only strings, preserving source index ids', () => {
+      const result = normalizeProfileLinks(undefined, [
+        'https://keep.example',
+        '',
+        '   ',
+        'https://second.example',
+      ]);
+      expect(result).toEqual<ProfileLink[]>([
+        { id: '0', url: 'https://keep.example' },
+        { id: '3', url: 'https://second.example' },
+      ]);
+    });
+  });
+
+  describe('fall-through and empty inputs', () => {
+    it('returns [] when both inputs are absent', () => {
+      expect(normalizeProfileLinks()).toEqual([]);
+      expect(normalizeProfileLinks(undefined, undefined)).toEqual([]);
+    });
+
+    it('returns [] when both inputs are empty arrays', () => {
+      expect(normalizeProfileLinks([], [])).toEqual([]);
+    });
+
+    it('falls through to legacy links when linksMetadata is empty', () => {
+      const result = normalizeProfileLinks([], ['https://legacy.example']);
+      expect(result).toEqual<ProfileLink[]>([
+        { id: '0', url: 'https://legacy.example' },
+      ]);
+    });
+
+    it('returns [] (does NOT fall back to links) when linksMetadata is non-empty but every entry is dropped', () => {
+      const result = normalizeProfileLinks(
+        [{ url: '' }, { url: '   ' }],
+        ['https://legacy.example'],
+      );
+      expect(result).toEqual([]);
+    });
+  });
+
+  it('is pure — does not mutate its inputs', () => {
+    const linksMetadata = [{ url: 'https://oxy.so', title: 'Oxy', id: 'abc' }];
+    const links = ['https://legacy.example'];
+    const metadataSnapshot = JSON.stringify(linksMetadata);
+    const linksSnapshot = JSON.stringify(links);
+
+    normalizeProfileLinks(linksMetadata, links);
+
+    expect(JSON.stringify(linksMetadata)).toBe(metadataSnapshot);
+    expect(JSON.stringify(links)).toBe(linksSnapshot);
+  });
+});

package/src/utils/profileLinks.ts

@@ -0,0 +1,91 @@
+/**
+ * Normalized profile link shape for display.
+ *
+ * `id` is a stable key for list rendering (the source entry's id when present,
+ * otherwise the source index as a string). `url` is always a non-empty string.
+ * `title`, `description`, and `image` are carried through from `linksMetadata`
+ * only when present; the legacy `links: string[]` path produces just
+ * `{ id, url }`.
+ */
+export interface ProfileLink {
+  id: string;
+  title?: string;
+  url: string;
+  description?: string;
+  image?: string;
+}
+
+/** Source shape of a single `User.linksMetadata` entry. */
+export interface ProfileLinkMetadata {
+  url: string;
+  title?: string;
+  description?: string;
+  image?: string;
+  id?: string;
+}
+
+function cleanUrl(value: unknown): string | null {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+/**
+ * Normalizes a user's profile links into a clean display shape.
+ *
+ * Pure, no side effects, no I/O.
+ *
+ * - Prefers `linksMetadata` when it is a non-empty array: maps each entry to
+ *   `{ id, title, url, description, image }`, using `entry.id` when present and
+ *   falling back to the entry index. `title`, `description`, and `image` are
+ *   carried through only when they are present strings. Entries without a
+ *   non-empty string `url` are dropped.
+ * - Otherwise falls back to the legacy `links` string array: maps each string to
+ *   `{ id: <index>, url }` (no title/description/image). Empty/non-string values
+ *   are dropped.
+ * - Returns `[]` when both are absent or empty (including when `linksMetadata`
+ *   is present but every entry is dropped — it does NOT fall back to `links`).
+ *
+ * URLs are trimmed and blanks are filtered out. This does NOT add a scheme such
+ * as `https://`; prefixing is a display concern left to the caller.
+ */
+export function normalizeProfileLinks(
+  linksMetadata?: ProfileLinkMetadata[],
+  links?: string[],
+): ProfileLink[] {
+  if (Array.isArray(linksMetadata) && linksMetadata.length > 0) {
+    const result: ProfileLink[] = [];
+    linksMetadata.forEach((entry, index) => {
+      const url = cleanUrl(entry?.url);
+      if (!url) return;
+      const id =
+        typeof entry?.id === 'string' && entry.id.trim().length > 0
+          ? entry.id
+          : String(index);
+      const title = typeof entry?.title === 'string' ? entry.title : undefined;
+      const description =
+        typeof entry?.description === 'string' ? entry.description : undefined;
+      const image = typeof entry?.image === 'string' ? entry.image : undefined;
+      result.push({
+        id,
+        url,
+        ...(title !== undefined ? { title } : {}),
+        ...(description !== undefined ? { description } : {}),
+        ...(image !== undefined ? { image } : {}),
+      });
+    });
+    return result;
+  }
+
+  if (Array.isArray(links) && links.length > 0) {
+    const result: ProfileLink[] = [];
+    links.forEach((value, index) => {
+      const url = cleanUrl(value);
+      if (!url) return;
+      result.push({ id: String(index), url });
+    });
+    return result;
+  }
+
+  return [];
+}