From a45bcd5f84b2e7be982e170aa31f64afac61a337 Mon Sep 17 00:00:00 2001
From: Pawel Zelawski <pawel.zelawski@outlook.com>
Date: Wed, 9 Apr 2025 20:18:15 +0200
Subject: docs: Add README, usage examples, and example runner instructions

- Create comprehensive README.md including:
    - Features, Installation (from GitHub), Usage examples (URI generation, callback verification), API Reference, Dependency status note, Testing instructions.
- Review and confirm adequacy of TSDoc comments in source files.
- Update README intro sentence and add explicit notes on required URL format.
- Create `examples/` directory with runnable scripts:
    - `examples/generate-uri.ts`
    - `examples/verify-callback-example.ts`
- Update signature verification helper (`_internalVerifySignature`) to use `createRequire` for CJS dependency loading in ESM context (required for examples).
- Add "Running Examples" section to README with the correct `node --loader ts-node/esm` command.
---
 examples/generate-uri.ts | 72 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 72 insertions(+)
 create mode 100644 examples/generate-uri.ts

(limited to 'examples/generate-uri.ts')

diff --git a/examples/generate-uri.ts b/examples/generate-uri.ts
new file mode 100644
index 0000000..9aee864
--- /dev/null
+++ b/examples/generate-uri.ts
@@ -0,0 +1,72 @@
+// examples/generate-uri.ts
+
+// Import directly from src for running locally before publishing
+// In a real project, you'd import from 'digiid-ts' after installing
+// Revert extension, ts-node should handle this when configured
+import { generateDigiIDUri, DigiIDError } from '../src/index'; 
+
+console.log('--- DigiID URI Generation Example ---');
+
+// --- Example 1: Secure Callback (HTTPS) ---
+const secureOptions = {
+  callbackUrl: 'https://myapp.example.com/api/auth/digiid',
+};
+
+try {
+  const secureUri = generateDigiIDUri(secureOptions);
+  console.log('\nSecure URI (HTTPS):');
+  console.log(`  Callback: ${secureOptions.callbackUrl}`);
+  console.log(`  Generated: ${secureUri}`);
+  // Typically, you would now generate a QR code from secureUri
+} catch (error) {
+  console.error('Error generating secure URI:', (error as Error).message);
+}
+
+// --- Example 2: Unsecure Callback (HTTP) for Testing ---
+const unsecureOptions = {
+  callbackUrl: 'http://localhost:8080/dev/callback',
+  unsecure: true, // Must set this flag for http
+};
+
+try {
+  const unsecureUri = generateDigiIDUri(unsecureOptions);
+  console.log('\nUnsecure URI (HTTP) for testing:');
+  console.log(`  Callback: ${unsecureOptions.callbackUrl}`);
+  console.log(`  Generated: ${unsecureUri}`);
+} catch (error) {
+  console.error('Error generating unsecure URI:', (error as Error).message);
+}
+
+// --- Example 3: Providing a Custom Nonce ---
+const customNonceOptions = {
+  callbackUrl: 'https://anotherapp.com/verify',
+  nonce: 'my-unique-secret-nonce-per-request-12345'
+};
+
+try {
+  const customNonceUri = generateDigiIDUri(customNonceOptions);
+  console.log('\nURI with Custom Nonce:');
+  console.log(`  Callback: ${customNonceOptions.callbackUrl}`);
+  console.log(`  Nonce:    ${customNonceOptions.nonce}`);
+  console.log(`  Generated: ${customNonceUri}`);
+} catch (error) {
+  console.error('Error generating URI with custom nonce:', (error as Error).message);
+}
+
+// --- Example 4: Invalid URL (Missing Scheme) ---
+const invalidUrlOptions = {
+  callbackUrl: 'myapi.com/auth' // Missing https://
+};
+
+console.log('\nAttempting URI with Invalid URL (expecting error):');
+try {
+  generateDigiIDUri(invalidUrlOptions as any);
+} catch (error) {
+  if (error instanceof DigiIDError) {
+    console.log(`  Caught expected DigiIDError: ${error.message}`);
+  } else {
+    console.error('  Caught unexpected error:', error);
+  }
+}
+
+console.log('\n--- End of Generation Example ---');
-- 
cgit v1.2.3