@wemush/wols 0.1.0 → 1.3.0

package/dist/esm/crypto/shared.js

@@ -0,0 +1,222 @@
+/**
+ * Shared primitives for the WOLS encrypted format (v1.3.0).
+ *
+ * Uses only WebCrypto (`globalThis.crypto.subtle`), so it runs unchanged in
+ * Node.js 20+, browsers, Deno, Bun and workers.
+ *
+ * `base64UrlEncode`, `base64UrlDecode` and `derivePassphraseKey` are public
+ * (re-exported from the package root and `@wemush/wols/crypto`); everything
+ * else here is internal to the crypto module.
+ *
+ * @module crypto/shared
+ */
+import { WolsDecryptionError, WolsEncryptionError, WolsErrorCode } from '../errors.js';
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+/** Default PBKDF2 iteration count used when generating. */
+export const DEFAULT_PBKDF2_ITERATIONS = 600_000;
+/** Iteration count pre-1.3.0 payloads used when they recorded none. */
+export const LEGACY_PBKDF2_ITERATIONS = 100_000;
+/** Generators MUST use at least this many PBKDF2 iterations (WOLS v1.3.0). */
+export const MIN_GENERATE_ITERATIONS = 100_000;
+/** Decoders MUST reject fewer PBKDF2 iterations than this (WOLS v1.3.0). */
+export const MIN_DECODE_ITERATIONS = 10_000;
+/** Default largest PBKDF2 iteration count accepted from a label when decoding. */
+export const DEFAULT_MAX_DECODE_ITERATIONS = 10_000_000;
+/**
+ * WOLS 1.3.0 ceiling: decoders reject more than this many iterations (alone,
+ * or in total across a field-encrypted label), and generators never exceed it.
+ * A configured `maxIterations` may be lower, never higher.
+ */
+export const MAX_ITERATIONS = 10_000_000;
+/** WebCrypto's PBKDF2 `iterations` is an unsigned long; nothing above this is derivable. */
+export const MAX_PBKDF2_ITERATIONS = 0xffff_ffff;
+/** Per-label PBKDF2 salt length generated (spec minimum: 16 bytes). */
+export const SALT_LENGTH = 16;
+/** AES-GCM appends a 16-byte authentication tag, so no valid ciphertext is shorter. */
+export const GCM_TAG_LENGTH = 16;
+/** AES-GCM IV length in bytes. */
+export const IV_LENGTH = 12;
+/** Raw AES-256 key length in bytes. */
+export const RAW_KEY_LENGTH = 32;
+/** Prefix of every encrypted-format URL. */
+export const ENCRYPTED_URL_PREFIX = 'wemush://v1/encrypted/';
+/**
+ * Library-wide salt used by pre-1.3.0 releases. Only for decoding legacy
+ * payloads behind `allowLegacy`; never used when generating.
+ */
+export const LEGACY_PBKDF2_SALT = new TextEncoder().encode('@wemush/wols/crypto/v1');
+// =============================================================================
+// ERRORS
+// =============================================================================
+/**
+ * Create a decryption error carrying a stable `details.reason` category.
+ */
+export function decryptionError(reason, message, details = {}) {
+    return new WolsDecryptionError(reason, message, details);
+}
+/**
+ * Whether WebCrypto (`globalThis.crypto.subtle`) is available. It is global in
+ * browsers, workers, Deno, Bun and Node.js 19+ (Node 18 needs
+ * `--experimental-global-webcrypto`).
+ */
+export function hasWebCrypto() {
+    const c = globalThis.crypto;
+    return (typeof c?.subtle === 'object' && c.subtle !== null && typeof c.getRandomValues === 'function');
+}
+/** Message used when WebCrypto is missing. */
+export const NO_WEBCRYPTO_MESSAGE = 'WebCrypto (globalThis.crypto.subtle) is not available in this runtime. ' +
+    'Use Node.js 20+, a modern browser, Deno or Bun.';
+/** Throw a WolsEncryptionError when WebCrypto is missing (encryption paths). */
+export function assertWebCrypto() {
+    if (!hasWebCrypto()) {
+        throw new WolsEncryptionError(WolsErrorCode.ENCRYPTION_ERROR, NO_WEBCRYPTO_MESSAGE);
+    }
+}
+// =============================================================================
+// BASE64URL
+// =============================================================================
+/**
+ * Encode bytes as base64url (RFC 4648 §5) without padding.
+ *
+ * @since 1.3.0
+ */
+export function base64UrlEncode(bytes) {
+    const view = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+    let binary = '';
+    for (const byte of view) {
+        binary += String.fromCharCode(byte);
+    }
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+const BASE64URL_PATTERN = /^[A-Za-z0-9_-]*={0,2}$/;
+/**
+ * Decode base64url (RFC 4648 §5). Padded input is accepted.
+ *
+ * @throws Error if the input is not valid base64url
+ * @since 1.3.0
+ */
+export function base64UrlDecode(value) {
+    if (!BASE64URL_PATTERN.test(value)) {
+        throw new Error('Invalid base64url string');
+    }
+    const unpadded = value.replace(/=+$/, '');
+    if (unpadded.length % 4 === 1) {
+        throw new Error('Invalid base64url length');
+    }
+    const base64 = unpadded.replace(/-/g, '+').replace(/_/g, '/');
+    const binary = atob(base64.padEnd(base64.length + ((4 - (base64.length % 4)) % 4), '='));
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+// =============================================================================
+// RANDOMNESS
+// =============================================================================
+/** Cryptographically random bytes from WebCrypto. */
+export function randomBytes(length) {
+    const bytes = new Uint8Array(length);
+    crypto.getRandomValues(bytes);
+    return bytes;
+}
+// =============================================================================
+// KEYS
+// =============================================================================
+/** Copy a byte view into a fresh ArrayBuffer-backed Uint8Array (WebCrypto-safe). */
+function toOwnedBytes(bytes) {
+    const view = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+    const copy = new Uint8Array(view.length);
+    copy.set(view);
+    return copy;
+}
+/**
+ * Derive a 256-bit key from a passphrase with PBKDF2-HMAC-SHA256.
+ *
+ * Exposed for debugging and interoperability testing (it reproduces the
+ * conformance `derive` vectors). Returns the raw key bytes.
+ *
+ * @param passphrase - Passphrase; normalized to Unicode NFC, then UTF-8 encoded (WOLS 1.3.0)
+ * @param salt - Salt bytes (the label's decoded `salt` parameter)
+ * @param iterations - PBKDF2 iteration count (positive integer)
+ * @since 1.3.0
+ */
+export async function derivePassphraseKey(passphrase, salt, iterations) {
+    if (!Number.isInteger(iterations) || iterations < 1 || iterations > MAX_PBKDF2_ITERATIONS) {
+        throw new Error(`PBKDF2 iterations must be an integer from 1 to ${MAX_PBKDF2_ITERATIONS}, got ${iterations}`);
+    }
+    const material = await crypto.subtle.importKey('raw', 
+    // WOLS 1.3.0: NFC so composed and decomposed input derive the same key.
+    new TextEncoder().encode(passphrase.normalize('NFC')), 'PBKDF2', false, ['deriveBits']);
+    const bits = await crypto.subtle.deriveBits({ name: 'PBKDF2', hash: 'SHA-256', salt: toOwnedBytes(salt), iterations }, material, 256);
+    return new Uint8Array(bits);
+}
+/**
+ * Field-level AES-GCM additional data (WOLS 1.3.0): UTF-8 of the label's full
+ * `id`, a line feed, and the top-level field name, e.g. "wemush:clx1a2b3c4\nstrain".
+ * Binds each encrypted value to its label and field.
+ */
+export function fieldAad(id, field) {
+    return new TextEncoder().encode(`${id}\n${field}`);
+}
+/**
+ * Fields that identify or type a label. They are never encrypted, and a label
+ * in which any of them is an encrypted object is refused (WOLS 1.3.0).
+ */
+export const IDENTIFYING_FIELDS = [
+    '@context',
+    '@type',
+    'id',
+    'version',
+    'type',
+    'species',
+];
+/** Import 32 raw key bytes as an AES-GCM key. */
+export async function importAesKey(bytes, usage) {
+    return crypto.subtle.importKey('raw', toOwnedBytes(bytes), { name: 'AES-GCM' }, false, [usage]);
+}
+/**
+ * Check whether a value is a WebCrypto CryptoKey without relying on the
+ * global `CryptoKey` constructor (absent in some runtimes).
+ */
+export function isCryptoKey(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'algorithm' in value &&
+        'usages' in value &&
+        'type' in value &&
+        !(value instanceof Uint8Array) &&
+        !(value instanceof ArrayBuffer));
+}
+/**
+ * Resolve a raw key (bytes or CryptoKey) to an AES-256-GCM CryptoKey.
+ * Returns an error message string when the key is unusable.
+ */
+export async function resolveRawKey(key, usage) {
+    if (isCryptoKey(key)) {
+        const algorithm = key.algorithm;
+        if (algorithm.name !== 'AES-GCM' || algorithm.length !== 256) {
+            return `CryptoKey must be AES-GCM with length 256, got ${algorithm.name ?? 'unknown'}/${algorithm.length ?? '?'}`;
+        }
+        if (!key.usages.includes(usage)) {
+            return `CryptoKey does not allow '${usage}'`;
+        }
+        return key;
+    }
+    const length = key instanceof Uint8Array ? key.length : key.byteLength;
+    if (length !== RAW_KEY_LENGTH) {
+        return `Raw key must be exactly ${RAW_KEY_LENGTH} bytes, got ${length}`;
+    }
+    return importAesKey(key, usage);
+}
+/** Whether a key value is a passphrase (selects kdf=pbkdf2). */
+export function isPassphrase(key) {
+    return typeof key === 'string';
+}
+/** Whether a key value is raw key material (selects kdf=raw). */
+export function isRawKey(key) {
+    return key instanceof Uint8Array || key instanceof ArrayBuffer || isCryptoKey(key);
+}
+//# sourceMappingURL=shared.js.map

package/dist/esm/crypto/shared.js.map

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

package/dist/esm/errors.js

@@ -128,6 +128,43 @@ export class WolsEncryptionError extends WolsError {
         }
     }
 }
+/**
+ * Decryption failure with a stable, typed {@link DecryptionFailureReason}.
+ *
+ * It extends `WolsEncryptionError` on purpose: 1.2.x returned a
+ * `WolsEncryptionError` for decryption failures, so existing
+ * `instanceof WolsEncryptionError` checks keep matching. Encryption misuse is
+ * thrown as a plain `WolsEncryptionError`; decryption failures are returned as
+ * this subclass, so check `instanceof WolsDecryptionError` to tell them apart.
+ * Malformed encrypted URLs are reported here too (`invalid-url`), not as
+ * `WolsParseError`, so every decryption input problem has one error type.
+ *
+ * Returned (never thrown) by `decryptSpecimen`, `decryptPlaintext`,
+ * `decryptField` and `decryptFields`. `reason` is also copied into
+ * `details.reason` for code that reads the generic error shape.
+ *
+ * @example
+ * ```typescript
+ * const r = await decryptSpecimen(url, { key });
+ * if (!r.success && r.error.reason === 'legacy-format') {
+ *   // a pre-1.3.0 label: retry with { allowLegacy: true } during migration
+ * }
+ * ```
+ *
+ * @since 1.3.0
+ */
+export class WolsDecryptionError extends WolsEncryptionError {
+    /** Stable failure category */
+    reason;
+    constructor(reason, message, details) {
+        super(reason === 'invalid-key' ? WolsErrorCode.INVALID_KEY : WolsErrorCode.DECRYPTION_ERROR, message, { ...details, reason });
+        this.name = 'WolsDecryptionError';
+        this.reason = reason;
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, WolsDecryptionError);
+        }
+    }
+}
 // =============================================================================
 // ERROR FACTORY FUNCTIONS
 // =============================================================================

package/dist/esm/errors.js.map

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

package/dist/esm/index.js

@@ -1,12 +1,12 @@
 /**
  * @wemush/wols - Official WOLS TypeScript Library
  *
- * WeMush Open Labeling Standard (WOLS) v1.1.0 implementation
+ * WeMush Open Labeling Standard (WOLS) v1.3.0 implementation
  * for biological specimen labeling and traceability.
  *
  * @packageDocumentation
  * @module @wemush/wols
- * @version 1.1.0
+ * @version 1.3.0
  */
 // =============================================================================
 // Constants
@@ -17,13 +17,25 @@ export { WOLS_VERSION, WOLS_CONTEXT } from './types.js';
 // =============================================================================
 export { asSpecimenId, isSpecimenType, isGrowthStage, isStrain, SPECIMEN_TYPES, GROWTH_STAGES, } from './types.js';
 // =============================================================================
+// Type Alias System (v1.2.0)
+// =============================================================================
+export { registerTypeAlias, resolveTypeAlias, getTypeAliases, resolveTypeAndStage, PRIMORDIA_TYPE_ALIAS, } from './types.js';
+// =============================================================================
+// Type Mapping System (v1.2.0)
+// =============================================================================
+export { WOLS_TO_PLATFORM_MAP, mapToWolsType, mapFromWolsType, registerPlatformType, } from './types.js';
+// =============================================================================
+// Generation Format System (v1.2.0)
+// =============================================================================
+export { normalizeGeneration, isValidGeneration } from './types.js';
+// =============================================================================
 // Errors
 // =============================================================================
-export { WolsErrorCode, WolsError, WolsParseError, WolsValidationError, WolsEncryptionError, } from './errors.js';
+export { WolsErrorCode, WolsError, WolsParseError, WolsValidationError, WolsEncryptionError, WolsDecryptionError, } from './errors.js';
 // =============================================================================
 // Core Functions - Specimen
 // =============================================================================
-export { createSpecimen, serializeSpecimen } from './specimen.js';
+export { createSpecimen, serializeSpecimen, PRIMORDIA_AS_TYPE_WARNING } from './specimen.js';
 // =============================================================================
 // Core Functions - Validation
 // =============================================================================
@@ -35,13 +47,21 @@ export { parseSpecimen } from './parser.js';
 // =============================================================================
 // Core Functions - Compact URL
 // =============================================================================
-export { toCompactUrl, parseCompactUrl, SPECIES_CODES, getSpeciesFromCode, getCodeFromSpecies, registerSpeciesCode, } from './compact-url.js';
+export { toCompactUrl, parseCompactUrl, parseCompactUrlOrThrow, parseCompactUrlOrNull, SPECIES_CODES, getSpeciesFromCode, getCodeFromSpecies, registerSpeciesCode, } from './compact-url.js';
 // =============================================================================
 // Core Functions - Encryption
 // =============================================================================
-export { encryptSpecimen, isEncrypted, decryptSpecimen } from './crypto/index.js';
+export { encryptSpecimen, encryptFields, isEncrypted, isEncryptedSpecimen, isEncryptedField, toEncryptedUrl, decryptSpecimen, decryptPlaintext, decryptField, decryptFields, parseEncryptedUrl, base64UrlEncode, base64UrlDecode, derivePassphraseKey, } from './crypto/index.js';
 // =============================================================================
 // Core Functions - QR Code Generation
 // =============================================================================
 export { toQRCode, toQRCodeDataURL, toQRCodeSVG, isQRAvailable, isQRAvailableSync, } from './qr/index.js';
+// =============================================================================
+// Environment Detection (v1.2.0)
+// =============================================================================
+export { isServer, isBrowser, isWebWorker, isDeno, isBun, getRuntimeEnvironment, supportsWebCrypto, supportsNodeCrypto, isCryptoSupported, supportsTextEncoding, supportsURLAPIs, } from './utils/environment.js';
+// =============================================================================
+// Migration Utilities (v1.2.0)
+// =============================================================================
+export { compareVersions, isOutdated, isNewer, getCurrentVersion, registerMigration, canMigrate, migrate, getMigrations, clearMigrations, } from './utils/migration.js';
 //# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,gFAAgF;AAChF,YAAY;AACZ,gFAAgF;AAChF,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAoCxD,gFAAgF;AAChF,iBAAiB;AACjB,gFAAgF;AAChF,OAAO,EACL,YAAY,EACZ,cAAc,EACd,aAAa,EACb,QAAQ,EACR,cAAc,EACd,aAAa,GACd,MAAM,YAAY,CAAC;AAEpB,gFAAgF;AAChF,SAAS;AACT,gFAAgF;AAChF,OAAO,EACL,aAAa,EACb,SAAS,EACT,cAAc,EACd,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,aAAa,CAAC;AAErB,gFAAgF;AAChF,4BAA4B;AAC5B,gFAAgF;AAChF,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAElE,gFAAgF;AAChF,8BAA8B;AAC9B,gFAAgF;AAChF,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAElD,gFAAgF;AAChF,0BAA0B;AAC1B,gFAAgF;AAChF,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,gFAAgF;AAChF,+BAA+B;AAC/B,gFAAgF;AAChF,OAAO,EACL,YAAY,EACZ,eAAe,EACf,aAAa,EACb,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,kBAAkB,CAAC;AAE1B,gFAAgF;AAChF,8BAA8B;AAC9B,gFAAgF;AAChF,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAElF,gFAAgF;AAChF,sCAAsC;AACtC,gFAAgF;AAChF,OAAO,EACL,QAAQ,EACR,eAAe,EACf,WAAW,EACX,aAAa,EACb,iBAAiB,GAClB,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,gFAAgF;AAChF,YAAY;AACZ,gFAAgF;AAChF,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAiDxD,gFAAgF;AAChF,iBAAiB;AACjB,gFAAgF;AAChF,OAAO,EACL,YAAY,EACZ,cAAc,EACd,aAAa,EACb,QAAQ,EACR,cAAc,EACd,aAAa,GACd,MAAM,YAAY,CAAC;AAEpB,gFAAgF;AAChF,6BAA6B;AAC7B,gFAAgF;AAChF,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,EACd,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,YAAY,CAAC;AAEpB,gFAAgF;AAChF,+BAA+B;AAC/B,gFAAgF;AAChF,OAAO,EACL,oBAAoB,EACpB,aAAa,EACb,eAAe,EACf,oBAAoB,GACrB,MAAM,YAAY,CAAC;AAEpB,gFAAgF;AAChF,oCAAoC;AACpC,gFAAgF;AAChF,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAGpE,gFAAgF;AAChF,SAAS;AACT,gFAAgF;AAChF,OAAO,EACL,aAAa,EACb,SAAS,EACT,cAAc,EACd,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,aAAa,CAAC;AAErB,gFAAgF;AAChF,4BAA4B;AAC5B,gFAAgF;AAChF,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAE7F,gFAAgF;AAChF,8BAA8B;AAC9B,gFAAgF;AAChF,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAElD,gFAAgF;AAChF,0BAA0B;AAC1B,gFAAgF;AAChF,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,gFAAgF;AAChF,+BAA+B;AAC/B,gFAAgF;AAChF,OAAO,EACL,YAAY,EACZ,eAAe,EACf,sBAAsB,EACtB,qBAAqB,EACrB,aAAa,EACb,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,kBAAkB,CAAC;AAE1B,gFAAgF;AAChF,8BAA8B;AAC9B,gFAAgF;AAChF,OAAO,EACL,eAAe,EACf,aAAa,EACb,WAAW,EACX,mBAAmB,EACnB,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,iBAAiB,EAEjB,eAAe,EACf,eAAe,EACf,mBAAmB,GACpB,MAAM,mBAAmB,CAAC;AAE3B,gFAAgF;AAChF,sCAAsC;AACtC,gFAAgF;AAChF,OAAO,EACL,QAAQ,EACR,eAAe,EACf,WAAW,EACX,aAAa,EACb,iBAAiB,GAClB,MAAM,eAAe,CAAC;AAEvB,gFAAgF;AAChF,iCAAiC;AACjC,gFAAgF;AAChF,OAAO,EACL,QAAQ,EACR,SAAS,EACT,WAAW,EACX,MAAM,EACN,KAAK,EACL,qBAAqB,EACrB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,oBAAoB,EACpB,eAAe,GAChB,MAAM,wBAAwB,CAAC;AAGhC,gFAAgF;AAChF,+BAA+B;AAC/B,gFAAgF;AAChF,OAAO,EACL,eAAe,EACf,UAAU,EACV,OAAO,EACP,iBAAiB,EACjB,iBAAiB,EACjB,UAAU,EACV,OAAO,EACP,aAAa,EACb,eAAe,GAChB,MAAM,sBAAsB,CAAC"}

package/dist/esm/parser.js

@@ -137,6 +137,9 @@ export function parseSpecimen(json) {
     if (data['signature'] !== undefined) {
         specimen.signature = data['signature'];
     }
+    if (data['_meta'] !== undefined) {
+        specimen._meta = data['_meta'];
+    }
     return {
         success: true,
         data: specimen,

package/dist/esm/parser.js.map

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

package/dist/esm/specimen.js

@@ -2,12 +2,27 @@
  * Specimen Creation and Serialization
  *
  * This module provides functions to create and serialize
- * WOLS v1.1.0 compliant specimen objects.
+ * WOLS v1.3.0 compliant specimen objects.
  *
  * @module specimen
  */
-import { WOLS_CONTEXT, WOLS_VERSION, asSpecimenId, isStrain } from './types.js';
+import { WOLS_CONTEXT, WOLS_VERSION, asSpecimenId, isStrain, resolveTypeAndStage, } from './types.js';
 import { createSpecimenId } from './utils/cuid.js';
+import { isValidISO8601 } from './utils/iso8601.js';
+/**
+ * Warning code emitted when `PRIMORDIA` is supplied as a specimen type.
+ *
+ * @since 1.3.0
+ */
+export const PRIMORDIA_AS_TYPE_WARNING = 'PRIMORDIA_AS_TYPE';
+function primordiaWarning() {
+    return {
+        path: 'type',
+        code: PRIMORDIA_AS_TYPE_WARNING,
+        message: `'PRIMORDIA' is a growth stage, not a specimen type; resolved to type 'FRUITING'`,
+        suggestion: `Use type: 'FRUITING', stage: 'PRIMORDIA'`,
+    };
+}
 /**
  * Expand a strain input to a full Strain object.
  * String inputs are expanded to { name: string }.
@@ -30,11 +45,17 @@ function expandStrain(strain) {
 /**
  * Create a new specimen with auto-generated ID and JSON-LD fields.
  *
- * This function creates a fully-formed WOLS v1.1.0 compliant Specimen
+ * This function creates a fully-formed WOLS v1.3.0 compliant Specimen
  * with automatic ID generation, version assignment, and JSON-LD context.
  *
+ * Type aliases resolve case-insensitively. `PRIMORDIA` supplied as a type
+ * resolves to `FRUITING`, sets `stage: 'PRIMORDIA'` when no stage was given
+ * (a supplied stage is never overridden), and emits a warning.
+ *
  * @param input - Specimen creation parameters
+ * @param options - `onWarning` receives non-fatal warnings (default: console.warn)
  * @returns Fully-formed Specimen with JSON-LD fields
+ * @throws Error if the type is unknown or `created` is not ISO 8601
  *
  * @example
  * ```typescript
@@ -64,26 +85,74 @@ function expandStrain(strain) {
  *   species: 'Ganoderma lucidum',
  *   strain: 'Reishi Red',  // Auto-expands to { name: 'Reishi Red' }
  * });
+ *
+ * // PRIMORDIA as a type (v1.3.0) -> type FRUITING, stage PRIMORDIA, plus a warning
+ * const pinning = createSpecimen(
+ *   { type: 'PRIMORDIA', species: 'Pleurotus ostreatus' },
+ *   { onWarning: w => console.info(w.message) }
+ * );
+ *
+ * // Explicit creation timestamp (v1.3.0)
+ * const dated = createSpecimen({
+ *   type: 'CULTURE',
+ *   species: 'Pleurotus ostreatus',
+ *   created: '2025-12-16T10:30:00Z',
+ * });
  * ```
  */
-export function createSpecimen(input) {
+export function createSpecimen(input, options = {}) {
     const id = asSpecimenId(createSpecimenId());
     const strain = expandStrain(input.strain);
+    // Resolve type alias to canonical WOLS type (e.g., 'LIQUID_CULTURE' -> 'CULTURE')
+    const resolved = resolveTypeAndStage(input.type, input.stage);
+    if (resolved === null) {
+        throw new Error(`Invalid specimen type: '${input.type}'. ` +
+            `Must be one of: CULTURE, SPAWN, SUBSTRATE, FRUITING, HARVEST ` +
+            `(or a registered alias).`);
+    }
+    let created;
+    if (input.created !== undefined) {
+        if (input.created instanceof Date) {
+            if (Number.isNaN(input.created.getTime())) {
+                throw new Error('Invalid created timestamp: Date is invalid. Must be ISO 8601.');
+            }
+            created = input.created.toISOString();
+        }
+        else {
+            created = input.created;
+        }
+        if (typeof created !== 'string' || !isValidISO8601(created)) {
+            throw new Error(`Invalid created timestamp: '${String(input.created)}'. Must be ISO 8601.`);
+        }
+    }
+    if (resolved.primordia) {
+        const warning = primordiaWarning();
+        if (options.onWarning) {
+            options.onWarning(warning);
+        }
+        else {
+            // eslint-disable-next-line no-console
+            console.warn(`[@wemush/wols] ${warning.message}. ${warning.suggestion ?? ''}`.trim());
+        }
+    }
     // Build specimen with required fields
     const specimen = {
         '@context': WOLS_CONTEXT,
         '@type': 'Specimen',
         id,
         version: WOLS_VERSION,
-        type: input.type,
+        type: resolved.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 (resolved.stage !== undefined) {
+        specimen.stage = resolved.stage;
+    }
+    if (created !== undefined) {
+        specimen.created = created;
     }
     if (input.batch !== undefined) {
         specimen.batch = input.batch;
@@ -97,6 +166,9 @@ export function createSpecimen(input) {
     if (input.custom !== undefined) {
         specimen.custom = input.custom;
     }
+    if (input._meta !== undefined) {
+        specimen._meta = input._meta;
+    }
     return specimen;
 }
 /**
@@ -120,21 +192,31 @@ export function createSpecimen(input) {
  * ```
  */
 export function serializeSpecimen(specimen) {
+    // WOLS v1.3.0: PRIMORDIA is never emitted as a type. A specimen object built
+    // by hand with type PRIMORDIA gets the same resolution as createSpecimen()
+    // (shared resolveTypeAndStage). Any other type is emitted as given.
+    let type = specimen.type;
+    let stage = specimen.stage;
+    const resolved = resolveTypeAndStage(type, stage);
+    if (resolved?.primordia) {
+        type = resolved.type;
+        stage = resolved.stage;
+    }
     // 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,
+        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 (stage !== undefined) {
+        ordered['stage'] = stage;
     }
     if (specimen.created !== undefined) {
         ordered['created'] = specimen.created;
@@ -154,6 +236,9 @@ export function serializeSpecimen(specimen) {
     if (specimen.signature !== undefined) {
         ordered['signature'] = specimen.signature;
     }
+    if (specimen._meta !== undefined) {
+        ordered['_meta'] = specimen._meta;
+    }
     return JSON.stringify(ordered);
 }
 //# sourceMappingURL=specimen.js.map

package/dist/esm/specimen.js.map

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