@learncard/helpers 1.3.5 → 1.3.7

package/src/images/filestack.helpers.ts

@@ -0,0 +1,179 @@
+import { getUrlsFromSrcSet } from './images.helpers';
+
+/**
+ * Creates an array of Filestack URL Parameters
+ *
+ * @param url Filestack URL
+ *
+ * @return Filestack URL Parameters
+ */
+export const getUrlParams = (url: string): string[] => url.split('.com/')[1].split('/');
+
+/**
+ * Converts an array of Filestack URL Parameters to a valid Filestack URL
+ *
+ * @param urlParams Filestack URL Parameters
+ *
+ * @return Filestack URL
+ */
+export const getUrlFromUrlParams = (urlParams: string[]): string =>
+    `https://cdn.filestackcontent.com/${urlParams.join('/')}`;
+
+/**
+ * Gets the handle from a Filestack URL
+ *
+ * @param url Filestack URL
+ *
+ * @return Filestack handle
+ */
+export const getFilestackHandle = (url: string): string => {
+    const urlParams = getUrlParams(url);
+
+    return urlParams[urlParams.length - 1];
+};
+
+export const getFileType = async (url: string): Promise<string> => {
+    const handle = getFilestackHandle(url);
+
+    try {
+        const data = (await (
+            await fetch(`https://www.filestackapi.com/api/file/${handle}/metadata`)
+        ).json()) as { mimetype?: string };
+
+        return data.mimetype ?? '';
+    } catch (error) {
+        console.error(error);
+
+        return '';
+    }
+};
+
+export const fileTypeSupportsPreview = (fileType: string): boolean => {
+    const unsupportedFileTypes = [
+        'application/vnd.apple.pages', // .pages
+        'application/vnd.apple.numbers', // .numbers
+        'application/x-iwork-keynote-sffkey', // .key
+    ];
+
+    return !unsupportedFileTypes.includes(fileType);
+};
+
+/**
+ * Fixes image rotation based on EXIF data and uses auto_image on a given URL
+ *
+ * @param url URL to fix
+ * @param mimetype MIME type (e.g. image/gif)
+ * @param webp flag to indicate whether we should manually specify conversion to webp
+ *
+ * @return fixed URL
+ */
+export const fixUrl = (url: string, mimetype?: string, webp = false): string => {
+    // eslint-disable-next-line @typescript-eslint/no-use-before-define
+    if (url.split(' ').length > 1) return fixSrcSetString(url, mimetype, webp);
+
+    const urlParams = getUrlParams(url).filter(param => param !== 'rotate=deg:exif');
+
+    urlParams.splice(0, 0, 'rotate=deg:exif');
+
+    if (mimetype !== 'image/gif') urlParams.splice(-1, 0, 'auto_image');
+    if (webp) urlParams.splice(-1, 0, 'output=format:webp');
+
+    return getUrlFromUrlParams(urlParams);
+};
+
+/**
+ * Fixes image rotation based on EXIF data and uses auto_image on a given srcset string
+ *
+ * @param srcSetString srcset string to fix
+ * @param mimetype MIME type (e.g. image/gif)
+ * @param webp flag to indicate whether we should manually specify conversion to webp
+ *
+ * @return fixed srcset string
+ */
+export const fixSrcSetString = (srcSetString: string, mimetype?: string, webp = false): string => {
+    const urls = getUrlsFromSrcSet(srcSetString);
+
+    return urls.map(url => `${fixUrl(url[0], mimetype, webp)} ${url[1]}`).join(', ');
+};
+
+/**
+ * Resizes a filestack image to the given size
+ *
+ * @param url Filestack URL to resize
+ * @param size Target output width
+ *
+ * @return Filestack URL
+ */
+export const resizeUrl = (url: string, size: number): string => {
+    const urlParams = getUrlParams(url).filter(param => !param.match(/resize.*/));
+
+    if (urlParams.includes('rotate=deg:exif')) urlParams.splice(1, 0, `resize=width:${size}`);
+    else urlParams.splice(0, 0, `resize=width:${size}`);
+
+    return getUrlFromUrlParams(urlParams);
+};
+
+/**
+ * Changes a filestack image's quality to the given value
+ *
+ * @param url Filestack URL to change
+ * @param quality quality value (1-100)
+ *
+ * @return Filestack URL
+ */
+export const changeQuality = (url: string, quality: number): string => {
+    const urlParams = getUrlParams(url).filter(param => !param.match(/quality.*/));
+
+    if (urlParams.includes('rotate=deg:exif')) urlParams.splice(1, 0, `quality=value:${quality}`);
+    else urlParams.splice(0, 0, `quality=value:${quality}`);
+
+    return getUrlFromUrlParams(urlParams);
+};
+
+/**
+ * Resizes and changes a filestack image's quality
+ *
+ * @param url Filestack URL to change
+ * @param size Target output width
+ * @param quality quality value (1-100)
+ *
+ * @return Filestack URL
+ */
+export const resizeAndChangeQuality = (
+    url: string,
+    size: number,
+    quality: number,
+    {
+        mimetype,
+        fix = false,
+        webp = false,
+    }: { mimetype?: string; fix?: boolean; webp?: boolean } = {}
+) => {
+    const updatedUrl = changeQuality(resizeUrl(url, size), quality);
+
+    return fix ? fixUrl(updatedUrl, mimetype, webp) : updatedUrl;
+};
+
+/**
+ * Generates a responsive srcset string from a Filestack URL and array of resolutions
+ *
+ * @param url Filestack URL
+ * @param resolutions list of resolutions
+ *
+ * @return srcset string
+ */
+export const generateSrcSet = (
+    url: string,
+    resolutions: number[],
+    {
+        mimetype,
+        fix = false,
+        webp = false,
+    }: { mimetype?: string; fix?: boolean; webp?: boolean } = {}
+) => {
+    const srcSet = resolutions
+        .map(resolution => `${resizeUrl(url, resolution)} ${resolution}w`)
+        .join(', ');
+
+    return fix ? fixSrcSetString(srcSet, mimetype, webp) : srcSet;
+};

package/src/images/images.helpers.ts

@@ -0,0 +1,75 @@
+import * as filestack from './filestack.helpers';
+import * as unsplash from './unsplash.helpers';
+import * as discord from './discord.helpers';
+
+const Providers = { filestack, unsplash, discord };
+
+export const getProvider = (url?: string): keyof typeof Providers | null => {
+    if (url?.includes('cdn.filestackcontent.com')) return 'filestack';
+
+    if (url?.includes('images.unsplash.com')) return 'unsplash';
+
+    if (url?.includes('cdn.discordapp.com')) return 'discord';
+
+    return null;
+};
+
+export const changeQuality = (url: string, quality: number): string => {
+    const provider = getProvider(url);
+
+    if (!provider) return url;
+
+    return Providers[provider].changeQuality(url, quality);
+};
+
+export const fixUrl = (url: string, mimetype?: string, webp = false): string => {
+    const provider = getProvider(url);
+
+    if (!provider) return url;
+
+    return Providers[provider].fixUrl(url, mimetype, webp);
+};
+
+export const generateSrcSet = (
+    url: string,
+    resolutions: number[],
+    options: { mimetype?: string; fix?: boolean; webp?: boolean } = {}
+): string => {
+    const provider = getProvider(url);
+
+    if (!provider) return url;
+
+    return Providers[provider].generateSrcSet(url, resolutions, options);
+};
+
+export const resizeAndChangeQuality = (
+    url: string,
+    size: number,
+    quality: number,
+    options: { mimetype?: string; fix?: boolean; webp?: boolean } = {}
+): string => {
+    const provider = getProvider(url);
+
+    if (!provider) return url;
+
+    return Providers[provider].resizeAndChangeQuality(url, size, quality, options);
+};
+
+export const DEFAULT_RESOLUTIONS = [200, 400, 600];
+
+/**
+ * Gets an array of URLs from a srcSet string
+ *
+ * @param srcSet HTML srcSet string (e.g. 'test.com/img 100w, test.com/img2 200w')
+ *
+ * @return URLs
+ */
+export const getUrlsFromSrcSet = (srcSet: string): [string, string][] => {
+    return srcSet.split(/,? /).reduce<[string, string][]>((accumulator, current, index, array) => {
+        if (index % 2 === 0) return accumulator;
+
+        accumulator.push([array[index - 1], current]);
+
+        return accumulator;
+    }, []);
+};

package/src/images/index.ts

@@ -0,0 +1 @@
+export * from './images.helpers';

package/src/images/unsplash.helpers.ts

@@ -0,0 +1,110 @@
+import { getUrlsFromSrcSet } from './images.helpers';
+import { parseUrl, stringifyUrl } from './url.helpers';
+
+/**
+ * Fixes image rotation based on EXIF data and uses auto_image on a given srcset string
+ *
+ * @param srcSetString srcset string to fix
+ * @param mimetype MIME type (e.g. image/gif)
+ * @param webp flag to indicate whether we should manually specify conversion to webp
+ *
+ * @return fixed srcset string
+ */
+export const fixSrcSetString = (
+    srcSetString: string,
+    _mimetype?: string,
+    _webp = false
+): string => {
+    const urls = getUrlsFromSrcSet(srcSetString);
+
+    return urls.map(([url, width]) => `${fixUrl(url)} ${width}`).join(', ');
+};
+
+/**
+ * Returns the best format on a given URL
+ *
+ * @param url URL to fix
+ *
+ * @return fixed URL
+ */
+export const fixUrl = (url: string, _mimetype?: string, _webp = false): string => {
+    if (url.split(' ').length > 1) return fixSrcSetString(url);
+
+    const parsedUrl = parseUrl(url);
+
+    parsedUrl.query.auto = 'format';
+
+    return stringifyUrl(parsedUrl);
+};
+
+/**
+ * Resizes an unsplash image to the given size
+ *
+ * @param url Unsplash URL to resize
+ * @param size Target output width
+ *
+ * @return Unsplash URL
+ */
+export const resizeUrl = (url: string, size: number): string => {
+    const parsedUrl = parseUrl(url);
+
+    parsedUrl.query.w = size.toString();
+
+    return stringifyUrl(parsedUrl);
+};
+
+/**
+ * Changes an unsplash image's quality to the given value
+ *
+ * @param url Unsplash URL to change
+ * @param quality quality value (1-100)
+ *
+ * @return Unsplash URL
+ */
+export const changeQuality = (url: string, quality: number): string => {
+    const parsedUrl = parseUrl(url);
+
+    parsedUrl.query.q = quality.toString();
+
+    return stringifyUrl(parsedUrl);
+};
+
+/**
+ * Resizes and changes an unsplash image's quality
+ *
+ * @param url Unsplash URL to change
+ * @param size Target output width
+ * @param quality quality value (1-100)
+ *
+ * @return Unsplash URL
+ */
+export const resizeAndChangeQuality = (
+    url: string,
+    size: number,
+    quality: number,
+    { fix = false }: { mimetype?: string; fix?: boolean; webp?: boolean } = {}
+): string => {
+    const updatedUrl = changeQuality(resizeUrl(url, size), quality);
+
+    return fix ? fixUrl(updatedUrl) : updatedUrl;
+};
+
+/**
+ * Generates a responsive srcset string from an Unsplash URL and array of resolutions
+ *
+ * @param url Unsplash URL
+ * @param resolutions list of resolutions
+ *
+ * @return srcset string
+ */
+export const generateSrcSet = (
+    url: string,
+    resolutions: number[],
+    { fix = false }: { mimetype?: string; fix?: boolean; webp?: boolean } = {}
+): string => {
+    const srcSet = resolutions
+        .map(resolution => `${resizeUrl(url, resolution)} ${resolution}w`)
+        .join(', ');
+
+    return fix ? fixSrcSetString(srcSet) : srcSet;
+};

package/src/images/url.helpers.ts

@@ -0,0 +1,46 @@
+/**
+ * Minimal URL query helpers backed by `URLSearchParams`, replacing the two
+ * `query-string` call sites in the image helpers. `query-string@9` is ESM-only
+ * and pulls in ESM-only transitive deps, which broke the CommonJS build of
+ * `@learncard/helpers` for external consumers on Node 18.
+ */
+
+export type ParsedUrl = {
+    url: string;
+    query: Record<string, string>;
+    fragmentIdentifier?: string;
+};
+
+export const parseUrl = (input: string): ParsedUrl => {
+    const hashIndex = input.indexOf('#');
+    const fragmentIdentifier = hashIndex === -1 ? undefined : input.slice(hashIndex + 1);
+    const withoutFragment = hashIndex === -1 ? input : input.slice(0, hashIndex);
+
+    const queryIndex = withoutFragment.indexOf('?');
+    const url = queryIndex === -1 ? withoutFragment : withoutFragment.slice(0, queryIndex);
+    const search = queryIndex === -1 ? '' : withoutFragment.slice(queryIndex + 1);
+
+    const query: Record<string, string> = {};
+    for (const [key, value] of new URLSearchParams(search)) query[key] = value;
+
+    return {
+        url,
+        query,
+        ...(fragmentIdentifier !== undefined ? { fragmentIdentifier } : {}),
+    };
+};
+
+export const stringifyUrl = (parsed: ParsedUrl): string => {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(parsed.query)) {
+        if (value === undefined || value === null) continue;
+        params.append(key, String(value));
+    }
+
+    // URLSearchParams encodes spaces as `+`; normalize to `%20` so output stays
+    // byte-stable for consumers that use the URL as a cache key.
+    const search = params.toString().replace(/\+/g, '%20');
+    const fragment = parsed.fragmentIdentifier ? `#${parsed.fragmentIdentifier}` : '';
+
+    return `${parsed.url}${search ? `?${search}` : ''}${fragment}`;
+};

package/src/index.ts

@@ -0,0 +1,105 @@
+import { JWE, JWEValidator, UnsignedVC, VC } from '@learncard/types';
+import type { DataTransformer } from '@trpc/server';
+
+/**
+ * Determines whether or not a string is a valid hexadecimal string
+ *
+ * E.g. 'abc123' is valid hex, 'zzz' is not
+ */
+export const isHex = (str: string) => /^[0-9a-f]+$/i.test(str);
+
+/** Determines whether or not an object is an encrypted JWE */
+export const isEncrypted = (item: Record<string, any>): item is JWE => {
+    return JWEValidator.safeParse(item).success;
+};
+
+/**
+ * tRPC data transformer that handles RegExp serialization/deserialization
+ */
+export const RegExpTransformer: DataTransformer = {
+    serialize(object: any): any {
+        return JSON.stringify(object, (_key, value) => {
+            if (value instanceof RegExp) return value.toString(); // Converts to format /pattern/flags
+
+            return value;
+        });
+    },
+
+    deserialize(object: any): any {
+        // Old clients will for some reason already be deserialized, so this checks for that to retain
+        // backwards compat
+        if (typeof object !== 'string') return object;
+
+        return JSON.parse(object, (_key, value) => {
+            if (typeof value === 'string') {
+                const match = value.match(/^\/(.*)\/([gimsuy]*)$/);
+
+                if (match) {
+                    try {
+                        return new RegExp(match[1], match[2]);
+                    } catch (error) {
+                        console.warn(`Failed to parse RegExp: ${error}`);
+                        return value;
+                    }
+                }
+            }
+            return value;
+        });
+    },
+};
+
+/**
+ * Determines if a credential uses VC 2.0 format by checking the context array
+ */
+export const isVC2Format = (credential: UnsignedVC | VC): boolean => {
+    if (!credential['@context'] || !Array.isArray(credential['@context'])) {
+        return false;
+    }
+
+    return credential['@context'].some(
+        context => context === 'https://www.w3.org/ns/credentials/v2'
+    );
+};
+
+/** Unwraps a boost credential from a CertifiedBoostCredential, if it is one */
+export const unwrapBoostCredential = (vc?: VC | UnsignedVC) => {
+    if (vc?.type?.includes('CertifiedBoostCredential') && vc?.boostCredential) {
+        return vc.boostCredential;
+    } else {
+        return vc;
+    }
+};
+
+// Export helpers from shared-helpers migration
+export * from './images';
+export * from './arrays';
+export * from './types';
+export * from './strings';
+export * from './numbers';
+export * from './state';
+export * from './bitstring-status-list';
+
+// Export utilities from shared-types migration
+export * from './Utilities';
+
+// Export app install helpers
+export * from './app-install';
+export * from './credential-format';
+
+// ADR-0001 Phase 1: format-tagged credential storage projector
+export * from './credential-format';
+
+/**
+ * Checks if a DID is an app-specific did:web
+ *
+ * App did:webs follow the pattern: `did:web:learncard.app:app:&lt;slug&gt;`
+ *
+ * @param did - The DID to check
+ * @returns true if the DID is an app did:web, false otherwise
+ */
+export const isAppDidWeb = (did?: string): boolean => {
+    if (!did) return false;
+    // Matches did:web:<slug>:app:<slug> pattern
+    const LCN_APP_DID_WEB_REGEX = /^did:web:.*:app:([^:]+)$/;
+    return LCN_APP_DID_WEB_REGEX.test(did);
+};

package/src/numbers/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Formats a number into a friendlier string i.e. 1,234 becomes 1.2K
+ */
+export const formatNumber = (num: number): string => {
+    const abbreviations = [
+        { value: 1e9, symbol: 'B' },
+        { value: 1e6, symbol: 'M' },
+        { value: 1e3, symbol: 'K' }
+    ];
+
+    for (const { value, symbol } of abbreviations) {
+        if (num >= value) {
+            // Round to 1 decimal place and remove trailing zero
+            const result = (Math.floor(num / (value / 10)) / 10).toFixed(1);
+            return result.replace(/\.0$/, '') + symbol;
+        }
+    }
+
+    // For numbers less than 1000, return as is, but without decimal places
+    return Math.floor(num).toString();
+}