@wemush/wols 0.1.0

package/dist/cjs/qr/generate.js

@@ -0,0 +1,275 @@
+"use strict";
+/**
+ * QR Code Generation Module
+ *
+ * This module provides QR code generation functionality for WOLS specimens.
+ * Requires the 'qrcode' package as an optional peer dependency.
+ *
+ * @module qr/generate
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isQRAvailable = isQRAvailable;
+exports.isQRAvailableSync = isQRAvailableSync;
+exports.toQRCode = toQRCode;
+exports.toQRCodeDataURL = toQRCodeDataURL;
+exports.toQRCodeSVG = toQRCodeSVG;
+const errors_js_1 = require("../errors.js");
+const specimen_js_1 = require("../specimen.js");
+// Cached reference to the qrcode library
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let qrLib = null;
+let qrLibLoadAttempted = false;
+/**
+ * Dynamically load the qrcode library.
+ * Returns null if the library is not installed.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+async function loadQRLib() {
+    if (qrLibLoadAttempted) {
+        return qrLib;
+    }
+    qrLibLoadAttempted = true;
+    try {
+        // Dynamic import of optional peer dependency
+        const module = await Promise.resolve().then(() => __importStar(require('qrcode')));
+        qrLib = module.default ?? module;
+        return qrLib;
+    }
+    catch {
+        // qrcode package not installed
+        qrLib = null;
+        return null;
+    }
+}
+/**
+ * Ensure qrcode library is available.
+ * Throws an error if not installed.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+async function requireQRLib() {
+    const lib = await loadQRLib();
+    if (!lib) {
+        throw new errors_js_1.WolsError(errors_js_1.WolsErrorCode.UNKNOWN_ERROR, 'QR code generation requires the "qrcode" package. Install it with: npm install qrcode', { missingDependency: 'qrcode' });
+    }
+    return lib;
+}
+// =============================================================================
+// COMPACT URL FORMAT
+// =============================================================================
+/**
+ * Species code mapping for compact URLs.
+ */
+const SPECIES_CODES = {
+    'Pleurotus ostreatus': 'POSTR',
+    'Pleurotus citrinopileatus': 'PCITRI',
+    'Pleurotus djamor': 'PDJAR',
+    'Pleurotus eryngii': 'PERYN',
+    'Hericium erinaceus': 'HERIN',
+    'Ganoderma lucidum': 'GLUCI',
+    'Laetiporus pudens': 'LPUDE',
+    'Lentinula edodes': 'LLENC',
+    'Agrocybe polyphylla': 'APOLY',
+    'Stropharia rugosoannulata': 'STRUG',
+};
+/**
+ * Growth stage to short code mapping.
+ */
+const STAGE_CODES = {
+    INOCULATION: 'IN',
+    COLONIZATION: 'CO',
+    FRUITING: 'FR',
+    HARVEST: 'HA',
+};
+/**
+ * Convert specimen to compact URL format.
+ * Format: wemush://v1/{id}?s={species}&st={stage}&t={timestamp}
+ */
+function toCompactUrl(specimen) {
+    // Extract the CUID part from the full ID
+    const cuidPart = specimen.id.replace('wemush:', '');
+    // Build query params
+    const params = new URLSearchParams();
+    // Add species code
+    const speciesCode = SPECIES_CODES[specimen.species];
+    if (speciesCode) {
+        params.set('s', speciesCode);
+    }
+    // Add stage if present
+    if (specimen.stage) {
+        const stageCode = STAGE_CODES[specimen.stage];
+        if (stageCode) {
+            params.set('st', stageCode);
+        }
+    }
+    // Add timestamp if created is present
+    if (specimen.created) {
+        const timestamp = Math.floor(new Date(specimen.created).getTime() / 1000);
+        params.set('t', String(timestamp));
+    }
+    const queryString = params.toString();
+    return `wemush://v1/${cuidPart}${queryString ? '?' + queryString : ''}`;
+}
+// =============================================================================
+// QR CODE GENERATION
+// =============================================================================
+/**
+ * Generate QR code content based on format option.
+ */
+function getQRContent(specimen, format) {
+    if (format === 'compact') {
+        return toCompactUrl(specimen);
+    }
+    return (0, specimen_js_1.serializeSpecimen)(specimen);
+}
+/**
+ * Map QRCodeOptions to library options.
+ */
+function mapOptions(options = {}) {
+    const result = {
+        errorCorrectionLevel: options.errorCorrection ?? 'M',
+        width: options.size ?? 300,
+        margin: options.margin ?? 1,
+    };
+    if (options.color) {
+        result.color = options.color;
+    }
+    return result;
+}
+// =============================================================================
+// PUBLIC API
+// =============================================================================
+/**
+ * Check if QR code generation is available.
+ * Returns true if the qrcode library is installed.
+ */
+async function isQRAvailable() {
+    const lib = await loadQRLib();
+    return lib !== null;
+}
+/**
+ * Synchronous check if QR code generation is available.
+ * Note: Only accurate after first async call to any QR function.
+ */
+function isQRAvailableSync() {
+    return qrLib !== null;
+}
+/**
+ * Generate QR code as PNG buffer.
+ *
+ * @param specimen - The specimen to encode
+ * @param options - QR code generation options
+ * @returns PNG buffer containing the QR code
+ *
+ * @example
+ * ```typescript
+ * const buffer = await toQRCode(specimen, { size: 400 });
+ * fs.writeFileSync('specimen-qr.png', buffer);
+ * ```
+ */
+async function toQRCode(specimen, options = {}) {
+    const lib = await requireQRLib();
+    const content = getQRContent(specimen, options.format ?? 'embedded');
+    const qrOptions = mapOptions(options);
+    try {
+        return await lib.toBuffer(content, { ...qrOptions, type: 'png' });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new errors_js_1.WolsError(errors_js_1.WolsErrorCode.SIZE_EXCEEDED, `Failed to generate QR code: ${message}`, {
+            originalError: message,
+        });
+    }
+}
+/**
+ * Generate QR code as data URL (base64 encoded PNG).
+ *
+ * @param specimen - The specimen to encode
+ * @param options - QR code generation options
+ * @returns Data URL string (data:image/png;base64,...)
+ *
+ * @example
+ * ```typescript
+ * const dataUrl = await toQRCodeDataURL(specimen);
+ * // Use in HTML: <img src={dataUrl} />
+ * ```
+ */
+async function toQRCodeDataURL(specimen, options = {}) {
+    const lib = await requireQRLib();
+    const content = getQRContent(specimen, options.format ?? 'embedded');
+    const qrOptions = mapOptions(options);
+    try {
+        return await lib.toDataURL(content, qrOptions);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new errors_js_1.WolsError(errors_js_1.WolsErrorCode.SIZE_EXCEEDED, `Failed to generate QR code: ${message}`, {
+            originalError: message,
+        });
+    }
+}
+/**
+ * Generate QR code as SVG string.
+ *
+ * @param specimen - The specimen to encode
+ * @param options - QR code generation options
+ * @returns SVG string
+ *
+ * @example
+ * ```typescript
+ * const svg = await toQRCodeSVG(specimen, { color: { dark: '#000', light: '#fff' } });
+ * fs.writeFileSync('specimen-qr.svg', svg);
+ * ```
+ */
+async function toQRCodeSVG(specimen, options = {}) {
+    const lib = await requireQRLib();
+    const content = getQRContent(specimen, options.format ?? 'embedded');
+    const qrOptions = mapOptions(options);
+    try {
+        const svg = await lib.toString(content, { ...qrOptions, type: 'svg' });
+        // Ensure the SVG has proper dimensions based on size option
+        const size = options.size ?? 300;
+        return svg
+            .replace(/width="[^"]*"/, `width="${size}"`)
+            .replace(/height="[^"]*"/, `height="${size}"`);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new errors_js_1.WolsError(errors_js_1.WolsErrorCode.SIZE_EXCEEDED, `Failed to generate QR code: ${message}`, {
+            originalError: message,
+        });
+    }
+}
+//# sourceMappingURL=generate.js.map

package/dist/cjs/qr/generate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.js","sourceRoot":"","sources":["../../../src/qr/generate.ts"],"names":[],"mappings":"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"}

package/dist/cjs/qr/index.js

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * QR Code Submodule
+ *
+ * This module provides QR code generation functionality for WOLS specimens.
+ *
+ * @packageDocumentation
+ * @module @wemush/wols/qr
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isQRAvailableSync = exports.isQRAvailable = exports.toQRCodeSVG = exports.toQRCodeDataURL = exports.toQRCode = void 0;
+var generate_js_1 = require("./generate.js");
+Object.defineProperty(exports, "toQRCode", { enumerable: true, get: function () { return generate_js_1.toQRCode; } });
+Object.defineProperty(exports, "toQRCodeDataURL", { enumerable: true, get: function () { return generate_js_1.toQRCodeDataURL; } });
+Object.defineProperty(exports, "toQRCodeSVG", { enumerable: true, get: function () { return generate_js_1.toQRCodeSVG; } });
+Object.defineProperty(exports, "isQRAvailable", { enumerable: true, get: function () { return generate_js_1.isQRAvailable; } });
+Object.defineProperty(exports, "isQRAvailableSync", { enumerable: true, get: function () { return generate_js_1.isQRAvailableSync; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/qr/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/qr/index.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAEH,6CAMuB;AALrB,uGAAA,QAAQ,OAAA;AACR,8GAAA,eAAe,OAAA;AACf,0GAAA,WAAW,OAAA;AACX,4GAAA,aAAa,OAAA;AACb,gHAAA,iBAAiB,OAAA"}

package/dist/cjs/specimen.js

@@ -0,0 +1,163 @@
+"use strict";
+/**
+ * Specimen Creation and Serialization
+ *
+ * This module provides functions to create and serialize
+ * WOLS v1.1.0 compliant specimen objects.
+ *
+ * @module specimen
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSpecimen = createSpecimen;
+exports.serializeSpecimen = serializeSpecimen;
+const types_js_1 = require("./types.js");
+const cuid_js_1 = require("./utils/cuid.js");
+/**
+ * Expand a strain input to a full Strain object.
+ * String inputs are expanded to { name: string }.
+ *
+ * @param strain - String or Strain object input
+ * @returns Strain object or undefined
+ */
+function expandStrain(strain) {
+    if (strain === undefined) {
+        return undefined;
+    }
+    if (typeof strain === 'string') {
+        return { name: strain };
+    }
+    if ((0, types_js_1.isStrain)(strain)) {
+        return strain;
+    }
+    return undefined;
+}
+/**
+ * Create a new specimen with auto-generated ID and JSON-LD fields.
+ *
+ * This function creates a fully-formed WOLS v1.1.0 compliant Specimen
+ * with automatic ID generation, version assignment, and JSON-LD context.
+ *
+ * @param input - Specimen creation parameters
+ * @returns Fully-formed Specimen with JSON-LD fields
+ *
+ * @example
+ * ```typescript
+ * // Minimal specimen
+ * const culture = createSpecimen({
+ *   type: 'CULTURE',
+ *   species: 'Pleurotus ostreatus',
+ * });
+ *
+ * // Full specimen with strain info
+ * const substrate = createSpecimen({
+ *   type: 'SUBSTRATE',
+ *   species: 'Hericium erinaceus',
+ *   strain: {
+ *     name: "Lion's Mane Premium",
+ *     generation: 'F2',
+ *     clonalGeneration: 3,
+ *   },
+ *   stage: 'COLONIZATION',
+ *   batch: 'batch_2025_12_001',
+ *   organization: 'org_mushoh',
+ * });
+ *
+ * // String strain shorthand
+ * const spawn = createSpecimen({
+ *   type: 'SPAWN',
+ *   species: 'Ganoderma lucidum',
+ *   strain: 'Reishi Red',  // Auto-expands to { name: 'Reishi Red' }
+ * });
+ * ```
+ */
+function createSpecimen(input) {
+    const id = (0, types_js_1.asSpecimenId)((0, cuid_js_1.createSpecimenId)());
+    const strain = expandStrain(input.strain);
+    // Build specimen with required fields
+    const specimen = {
+        '@context': types_js_1.WOLS_CONTEXT,
+        '@type': 'Specimen',
+        id,
+        version: types_js_1.WOLS_VERSION,
+        type: input.type,
+        species: input.species,
+    };
+    // Add optional fields only if defined
+    if (strain !== undefined) {
+        specimen.strain = strain;
+    }
+    if (input.stage !== undefined) {
+        specimen.stage = input.stage;
+    }
+    if (input.batch !== undefined) {
+        specimen.batch = input.batch;
+    }
+    if (input.organization !== undefined) {
+        specimen.organization = input.organization;
+    }
+    if (input.creator !== undefined) {
+        specimen.creator = input.creator;
+    }
+    if (input.custom !== undefined) {
+        specimen.custom = input.custom;
+    }
+    return specimen;
+}
+/**
+ * Serialize a specimen to JSON-LD string.
+ *
+ * The output is formatted with JSON-LD fields (@context, @type) first,
+ * followed by id, version, and remaining fields. Undefined fields are omitted.
+ *
+ * @param specimen - Specimen to serialize
+ * @returns JSON string suitable for QR encoding
+ *
+ * @example
+ * ```typescript
+ * const specimen = createSpecimen({
+ *   type: 'CULTURE',
+ *   species: 'Pleurotus ostreatus',
+ * });
+ *
+ * const json = serializeSpecimen(specimen);
+ * // Returns: '{"@context":"https://wemush.com/wols/v1","@type":"Specimen",...}'
+ * ```
+ */
+function serializeSpecimen(specimen) {
+    // Build ordered object with JSON-LD fields first
+    const ordered = {
+        '@context': specimen['@context'],
+        '@type': specimen['@type'],
+        id: specimen.id,
+        version: specimen.version,
+        type: specimen.type,
+        species: specimen.species,
+    };
+    // Add optional fields in order, only if defined
+    if (specimen.strain !== undefined) {
+        ordered['strain'] = specimen.strain;
+    }
+    if (specimen.stage !== undefined) {
+        ordered['stage'] = specimen.stage;
+    }
+    if (specimen.created !== undefined) {
+        ordered['created'] = specimen.created;
+    }
+    if (specimen.batch !== undefined) {
+        ordered['batch'] = specimen.batch;
+    }
+    if (specimen.organization !== undefined) {
+        ordered['organization'] = specimen.organization;
+    }
+    if (specimen.creator !== undefined) {
+        ordered['creator'] = specimen.creator;
+    }
+    if (specimen.custom !== undefined) {
+        ordered['custom'] = specimen.custom;
+    }
+    if (specimen.signature !== undefined) {
+        ordered['signature'] = specimen.signature;
+    }
+    return JSON.stringify(ordered);
+}
+//# sourceMappingURL=specimen.js.map

package/dist/cjs/specimen.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"specimen.js","sourceRoot":"","sources":["../../src/specimen.ts"],"names":[],"mappings":"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"}

package/dist/cjs/types.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * WOLS TypeScript Library - Core Types
+ *
+ * This module defines all the core types, interfaces, and enums
+ * for the WeMush Open Labeling Standard (WOLS) v1.1.0.
+ *
+ * @packageDocumentation
+ * @module @wemush/wols
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GROWTH_STAGES = exports.SPECIMEN_TYPES = exports.WOLS_CONTEXT = exports.WOLS_VERSION = void 0;
+exports.asSpecimenId = asSpecimenId;
+exports.isSpecimenType = isSpecimenType;
+exports.isGrowthStage = isGrowthStage;
+exports.isStrain = isStrain;
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+/**
+ * WOLS specification version implemented by this library.
+ */
+exports.WOLS_VERSION = '1.1.0';
+/**
+ * JSON-LD context URL for WOLS specimens.
+ */
+exports.WOLS_CONTEXT = 'https://wemush.com/wols/v1';
+/**
+ * Create a SpecimenId from a string.
+ * Does not validate the format - use isValidSpecimenId for validation.
+ */
+function asSpecimenId(id) {
+    return id;
+}
+/**
+ * Array of valid specimen types for validation.
+ */
+exports.SPECIMEN_TYPES = [
+    'CULTURE',
+    'SPAWN',
+    'SUBSTRATE',
+    'FRUITING',
+    'HARVEST',
+];
+/**
+ * Array of valid growth stages for validation.
+ */
+exports.GROWTH_STAGES = [
+    'INOCULATION',
+    'COLONIZATION',
+    'FRUITING',
+    'HARVEST',
+];
+// =============================================================================
+// TYPE GUARDS
+// =============================================================================
+/**
+ * Type guard to check if a value is a valid SpecimenType.
+ */
+function isSpecimenType(value) {
+    return typeof value === 'string' && exports.SPECIMEN_TYPES.includes(value);
+}
+/**
+ * Type guard to check if a value is a valid GrowthStage.
+ */
+function isGrowthStage(value) {
+    return typeof value === 'string' && exports.GROWTH_STAGES.includes(value);
+}
+/**
+ * Type guard to check if a value is a Strain object.
+ */
+function isStrain(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'name' in value &&
+        typeof value.name === 'string');
+}
+//# sourceMappingURL=types.js.map

package/dist/cjs/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AAoCH,oCAEC;AA0RD,wCAEC;AAKD,sCAEC;AAKD,4BAOC;AAnVD,gFAAgF;AAChF,YAAY;AACZ,gFAAgF;AAEhF;;GAEG;AACU,QAAA,YAAY,GAAG,OAAO,CAAC;AAEpC;;GAEG;AACU,QAAA,YAAY,GAAG,4BAA4B,CAAC;AAkBzD;;;GAGG;AACH,SAAgB,YAAY,CAAC,EAAU;IACrC,OAAO,EAAgB,CAAC;AAC1B,CAAC;AAWD;;GAEG;AACU,QAAA,cAAc,GAA4B;IACrD,SAAS;IACT,OAAO;IACP,WAAW;IACX,UAAU;IACV,SAAS;CACD,CAAC;AAOX;;GAEG;AACU,QAAA,aAAa,GAA2B;IACnD,aAAa;IACb,cAAc;IACd,UAAU;IACV,SAAS;CACD,CAAC;AAgPX,gFAAgF;AAChF,cAAc;AACd,gFAAgF;AAEhF;;GAEG;AACH,SAAgB,cAAc,CAAC,KAAc;IAC3C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,sBAAc,CAAC,QAAQ,CAAC,KAAqB,CAAC,CAAC;AACrF,CAAC;AAED;;GAEG;AACH,SAAgB,aAAa,CAAC,KAAc;IAC1C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,qBAAa,CAAC,QAAQ,CAAC,KAAoB,CAAC,CAAC;AACnF,CAAC;AAED;;GAEG;AACH,SAAgB,QAAQ,CAAC,KAAc;IACrC,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,MAAM,IAAI,KAAK;QACf,OAAQ,KAAgB,CAAC,IAAI,KAAK,QAAQ,CAC3C,CAAC;AACJ,CAAC"}