@memizy/oqse 0.1.1 → 0.1.3

package/dist/src/progress.d.ts

@@ -2,7 +2,7 @@
  * OQSEP v0.1 Type Definitions
  * (Open Quiz & Study Exchange - Progress)
  *
- * @see /SPECIFICATION.md#25-user-progress-portability-oqsep
+ * @see ../oqse-progress.md#data-model
  */
 /** Aggregate performance statistics for a single item. */
 export interface StatsObject {
@@ -16,7 +16,7 @@ export interface LastAnswerObject {
     confidence?: 1 | 2 | 3 | 4;
     answeredAt: string;
     timeSpent?: number;
-    hintsUsed?: number;
+    hintsUsed: number;
     isSkipped?: boolean;
 }
 /** Progress state for one item from the linked OQSE set. */

package/dist/src/richTextProcessor.d.ts

@@ -0,0 +1,46 @@
+import { FeatureProfile } from './oqse';
+export interface TokenMap {
+    [tokenId: string]: {
+        type: 'asset' | 'blank';
+        key: string;
+        originalTag: string;
+    };
+}
+export interface RichTextProcessingOptions {
+    /** * Function to parse Markdown to HTML (e.g., `marked.parse`).
+     * For Tier 1, this should ideally be configured to escape raw HTML.
+     */
+    markdownParser: (markdown: string) => string;
+    /** * Function to sanitize HTML (e.g., `DOMPurify.sanitize`).
+     * REQUIRED if the set declares the 'html' feature (Tier 2).
+     */
+    htmlSanitizer?: (html: string) => string;
+    /** Callback to render an <asset:key /> tag into HTML (e.g., <img src="...">) */
+    assetReplacer?: (key: string) => string;
+    /** Callback to render a <blank:key /> tag into HTML (e.g., <input type="text">) */
+    blankReplacer?: (key: string) => string;
+}
+/**
+ * Step 1: Tokenization.
+ * Temporarily replaces <asset:key /> and <blank:key /> with cryptographically safe
+ * text tokens so they survive Markdown parsing and HTML sanitization.
+ */
+export declare function tokenizeOqseTags(rawText: string): {
+    text: string;
+    tokens: TokenMap;
+};
+/**
+ * Step 2 (Tier 1): Strict HTML Validation.
+ * If 'html' is not allowed, any raw HTML tags written by the user must cause a validation error.
+ */
+export declare function validateTier1Markdown(textWithoutOqseTags: string): void;
+/**
+ * Step 4: Detokenization.
+ * Replaces the safe tokens back with the final interactive HTML elements.
+ */
+export declare function detokenizeOqseTags(safeHtml: string, tokens: TokenMap, options: Pick<RichTextProcessingOptions, 'assetReplacer' | 'blankReplacer'>): string;
+/**
+ * Main Facade for rendering OQSE Rich Content securely.
+ * Executes the complete Tokenization -> Validation -> Parsing -> Sanitization -> Detokenization pipeline.
+ */
+export declare function prepareRichTextForDisplay(rawContent: string, requirements: FeatureProfile | undefined, options: RichTextProcessingOptions): string;

package/dist/src/richTextProcessor.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/utils.d.ts

@@ -1,3 +1,17 @@
 export type UUID = string;
+/**
+ * Validates if the given string is a syntactically valid UUID (any version).
+ * Uses the robust validator from the 'uuid' package.
+ */
 export declare function isValidUUID(id: string): boolean;
+/**
+ * Generates a new UUIDv7.
+ * UUIDv7 is required by the OQSE specification for new items
+ * because it is time-sortable and optimized for database indexing.
+ */
 export declare function generateUUID(): UUID;
+/**
+ * Checks if an object exceeds the maximum allowed nesting depth.
+ * OQSE specification requires a limit of 10 levels for customData and appSpecific.
+ */
+export declare function validateJsonDepth(data: unknown, maxDepth?: number, currentDepth?: number): void;

package/dist/src/utils.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memizy/oqse",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "TypeScript SDK and Zod validators for the OQSE specification.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -29,6 +29,7 @@
     "prepublishOnly": "npm run build"
   },
   "devDependencies": {
+    "@types/uuid": "^10.0.0",
     "tsx": "^4.21.0",
     "typescript": "~6.0.2",
     "vite": "^8.0.4",
@@ -36,6 +37,7 @@
     "vitest": "^4.1.4"
   },
   "dependencies": {
+    "uuid": "^13.0.0",
     "zod": "^4.3.6"
   }
 }

package/schemas/oqse-header-v0.1.json

@@ -0,0 +1,120 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "format": "uuid",
+      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 500
+    },
+    "language": {
+      "type": "string",
+      "minLength": 2,
+      "pattern": "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-[A-Z]{2})?$"
+    },
+    "updatedAt": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?(Z|[+-]\\d{2}:\\d{2})?)?$"
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 5000
+    },
+    "author": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "role": {
+          "type": "string"
+        },
+        "email": {
+          "type": "string",
+          "format": "email",
+          "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
+        },
+        "url": {
+          "type": "string",
+          "format": "uri"
+        }
+      },
+      "required": [
+        "name"
+      ],
+      "additionalProperties": false
+    },
+    "subject": {
+      "type": "string"
+    },
+    "tags": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "createdAt": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?(Z|[+-]\\d{2}:\\d{2})?)?$"
+    },
+    "estimatedTime": {
+      "type": "number",
+      "exclusiveMinimum": 0
+    },
+    "requirements": {
+      "type": "object",
+      "properties": {
+        "features": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "latexPackages": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "itemProperties": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "metaProperties": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "url": {
+      "type": "string",
+      "format": "uri"
+    },
+    "$schema": {
+      "type": "string",
+      "format": "uri"
+    }
+  },
+  "required": [
+    "id",
+    "title",
+    "language",
+    "updatedAt",
+    "url"
+  ],
+  "additionalProperties": false
+}

package/schemas/oqse-manifest-v0.1.json

@@ -7,22 +7,28 @@
       "format": "uri"
     },
     "id": {
-      "type": "string",
-      "minLength": 1,
-      "pattern": "^[a-z0-9-]+(\\.[a-z0-9-]+)*$"
+      "anyOf": [
+        {
+          "type": "string",
+          "format": "uri"
+        },
+        {
+          "type": "string",
+          "pattern": "^urn:uuid:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
+        }
+      ]
     },
     "appName": {
       "type": "string",
       "minLength": 1,
-      "maxLength": 100
+      "maxLength": 200
     },
     "version": {
       "type": "string",
       "pattern": "^\\d+\\.\\d+$"
     },
     "pluginVersion": {
-      "type": "string",
-      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+      "type": "string"
     },
     "minOqseVersion": {
       "type": "string",
@@ -38,8 +44,7 @@
         "features": {
           "type": "array",
           "items": {
-            "type": "string",
-            "minLength": 1
+            "type": "string"
           }
         },
         "latexPackages": {
@@ -52,15 +57,13 @@
         "itemProperties": {
           "type": "array",
           "items": {
-            "type": "string",
-            "minLength": 1
+            "type": "string"
           }
         },
         "metaProperties": {
           "type": "array",
           "items": {
-            "type": "string",
-            "minLength": 1
+            "type": "string"
           }
         },
         "actions": {
@@ -194,10 +197,63 @@
       "additionalProperties": false
     },
     "author": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "role": {
+          "type": "string"
+        },
+        "email": {
+          "type": "string",
+          "format": "email",
+          "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
+        },
+        "url": {
+          "type": "string",
+          "format": "uri"
+        }
+      },
+      "required": [
+        "name"
+      ],
+      "additionalProperties": false
+    },
+    "contributors": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "minLength": 1
+          },
+          "role": {
+            "type": "string"
+          },
+          "email": {
+            "type": "string",
+            "format": "email",
+            "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
+          },
+          "url": {
+            "type": "string",
+            "format": "uri"
+          }
+        },
+        "required": [
+          "name"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "license": {
       "type": "string",
       "maxLength": 100
     },
-    "authorUrl": {
+    "licenseUrl": {
       "type": "string",
       "format": "uri"
     },
@@ -205,12 +261,12 @@
       "type": "array",
       "items": {
         "type": "string",
-        "minLength": 1
+        "pattern": "^[a-zA-Z]{2,8}(-[a-zA-Z0-9\\-]+)*$"
       }
     },
     "description": {
       "type": "string",
-      "maxLength": 500
+      "maxLength": 5000
     },
     "emoji": {
       "type": "string"

package/schemas/{oqsep-v0.1.json → oqse-progress-v0.1.json}

@@ -133,6 +133,7 @@
                 "maximum": 9007199254740991
               },
               "hintsUsed": {
+                "default": 0,
                 "type": "integer",
                 "minimum": 0,
                 "maximum": 9007199254740991
@@ -143,7 +144,8 @@
             },
             "required": [
               "isCorrect",
-              "answeredAt"
+              "answeredAt",
+              "hintsUsed"
             ],
             "additionalProperties": false
           },