add createEncryptedLink for e2e encrypted short links

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: gugu

README.md

@@ -17,6 +17,7 @@ Official Node.js SDK for the [Short.io](https://short.io) URL shortening and lin
   - [Folders](#folders)
   - [OpenGraph](#opengraph)
   - [Permissions](#permissions)
+  - [Encrypted Links](#encrypted-links)
 - [API Reference](#api-reference)
 - [Advanced Configuration](#advanced-configuration)
 - [TypeScript Support](#typescript-support)
@@ -39,6 +40,7 @@ Official Node.js SDK for the [Short.io](https://short.io) URL shortening and lin
 - **Permissions Management** - Control user access to links
 - **Full TypeScript Support** - Comprehensive type definitions included
 - **Modern ESM** - Built with ES modules
+- **Encrypted Links** - End-to-end encrypted links with client-side AES-GCM encryption
 - **Automatic Rate Limit Handling** - Built-in retry logic for 429 responses with exponential backoff
 
 ## Requirements
@@ -527,6 +529,33 @@ await deleteLinkPermission({
 });
 ```
 
+### Encrypted Links
+
+Create end-to-end encrypted links where the destination URL is encrypted client-side before being sent to the API. The decryption key is embedded in the URL hash fragment (`#key`), which browsers never send to servers, ensuring true e2e encryption.
+
+```javascript
+import { setApiKey, createEncryptedLink } from "@short.io/client-node";
+
+setApiKey("YOUR_API_KEY");
+
+const result = await createEncryptedLink({
+  body: {
+    originalURL: "https://secret-destination.com/private-page",
+    domain: "your-domain.com",
+    path: "secure-link",   // Optional
+    title: "Secret Link"   // Optional
+  }
+});
+
+console.log("Encrypted short URL:", result.data.shortURL);
+// => https://your-domain.com/secure-link#<base64-encryption-key>
+
+console.log("Encryption key:", result.data.encryptionKey);
+// => base64-encoded AES-GCM key (included in the URL hash fragment)
+```
+
+The original URL is encrypted with AES-128-GCM before being sent to the Short.io API. The API only ever sees the encrypted payload (`shortsecure://...`), never the actual destination URL. The decryption key is appended as a hash fragment to the short URL, so it is only available to the end user's browser.
+
 ## API Reference
 
 ### Link Operations
@@ -547,6 +576,7 @@ await deleteLinkPermission({
 | `createLinkPublic` | Create link using public API key | 50/s |
 | `createLinkSimple` | Create link (GET method) | 50/s |
 | `createExampleLinks` | Generate example links | 5/10s |
+| `createEncryptedLink` | Create an e2e encrypted link | 50/s |
 
 ### Bulk Operations
 

src/index.ts

@@ -189,3 +189,58 @@ export const setApiKey = (apiKey: string) => {
         }
     })
 }
+
+// ─── Encrypted Links ─────────────────────────────────────────────────────────
+
+import type { Options } from "./generated/sdk.gen"
+import type { CreateLinkData } from "./generated/types.gen"
+import { createLink } from "./generated/sdk.gen"
+import { webcrypto } from "node:crypto"
+
+function arrayBufferToBase64(buffer: ArrayBuffer): string {
+    return Buffer.from(buffer).toString('base64');
+}
+
+async function encryptURL(originalURL: string): Promise<{ encryptedURL: string; key: string }> {
+    const subtle = webcrypto.subtle;
+    const cryptoKey = await subtle.generateKey({ name: "AES-GCM", length: 128 }, true, [
+        "encrypt",
+        "decrypt",
+    ]);
+    const iv = webcrypto.getRandomValues(new Uint8Array(12));
+    const urlData = new TextEncoder().encode(originalURL);
+    const encryptedUrl = await subtle.encrypt({ name: "AES-GCM", iv }, cryptoKey, urlData);
+    const encryptedUrlBase64 = arrayBufferToBase64(encryptedUrl);
+    const encryptedIvBase64 = arrayBufferToBase64(iv.buffer);
+    const encryptedURL = `shortsecure://${encryptedUrlBase64}?${encryptedIvBase64}`;
+    const exportedKey = await subtle.exportKey("raw", cryptoKey);
+    const key = arrayBufferToBase64(exportedKey);
+    return { encryptedURL, key };
+}
+
+export async function createEncryptedLink(
+    options: Options<CreateLinkData, false> & { body: { originalURL: string } }
+) {
+    const { encryptedURL, key } = await encryptURL(options.body.originalURL);
+
+    const result = await createLink({
+        ...options,
+        body: {
+            ...options.body,
+            originalURL: encryptedURL,
+        },
+    });
+
+    if (result.data) {
+        const data = result.data as Record<string, unknown>;
+        if (typeof data.shortURL === 'string') {
+            data.shortURL = `${data.shortURL}#${key}`;
+        }
+        if (typeof data.secureShortURL === 'string') {
+            data.secureShortURL = `${data.secureShortURL}#${key}`;
+        }
+        return { ...result, data: { ...data, encryptionKey: key } };
+    }
+
+    return result;
+}

tests/sdk.test.ts

@@ -15,6 +15,7 @@ import {
   enableRateLimiting,
   disableRateLimiting,
   getRateLimitConfig,
+  createEncryptedLink,
   type RateLimitInfo,
   type SleepFunction,
 } from '../src/index';
@@ -620,3 +621,107 @@ describe('Rate limiting', () => {
     expect(mockSleep).toHaveBeenCalledWith(5000); // Capped at maxDelayMs
   });
 });
+
+// ── 5. Encrypted link creation ──────────────────────────────────────────
+
+describe('Encrypted link creation', () => {
+  it('encrypts URL and creates link with key in shortURL', async () => {
+    let capturedBody: Record<string, unknown> | null = null;
+
+    server.use(
+      http.post(`${BASE_URL}/links`, async ({ request }) => {
+        capturedBody = await request.json() as Record<string, unknown>;
+        return HttpResponse.json({
+          originalURL: capturedBody.originalURL,
+          path: 'enc123',
+          shortURL: 'https://short.io/enc123',
+          secureShortURL: 'https://short.io/enc123',
+          idString: 'lnk_enc_123',
+        });
+      }),
+    );
+
+    const result = await createEncryptedLink({
+      client: makeClient(),
+      body: {
+        originalURL: 'https://example.com/secret',
+        domain: 'short.io',
+      },
+    });
+
+    // API should receive shortsecure:// URL, not the original
+    expect(capturedBody).not.toBeNull();
+    expect((capturedBody as Record<string, unknown>).originalURL).toMatch(/^shortsecure:\/\//);
+
+    // Response should have key appended as hash fragment
+    expect(result.data).toBeDefined();
+    const data = result.data as Record<string, unknown>;
+    expect(data.shortURL).toMatch(/#.+$/);
+    expect(data.secureShortURL).toMatch(/#.+$/);
+    expect(data.encryptionKey).toBeDefined();
+    expect(typeof data.encryptionKey).toBe('string');
+  });
+
+  it('preserves other body options (title, path)', async () => {
+    let capturedBody: Record<string, unknown> | null = null;
+
+    server.use(
+      http.post(`${BASE_URL}/links`, async ({ request }) => {
+        capturedBody = await request.json() as Record<string, unknown>;
+        return HttpResponse.json({
+          originalURL: capturedBody.originalURL,
+          path: 'custom-path',
+          title: 'My Title',
+          shortURL: 'https://short.io/custom-path',
+          secureShortURL: 'https://short.io/custom-path',
+          idString: 'lnk_custom_123',
+        });
+      }),
+    );
+
+    await createEncryptedLink({
+      client: makeClient(),
+      body: {
+        originalURL: 'https://example.com/secret',
+        domain: 'short.io',
+        path: 'custom-path',
+        title: 'My Title',
+      },
+    });
+
+    expect(capturedBody).not.toBeNull();
+    expect((capturedBody as Record<string, unknown>).path).toBe('custom-path');
+    expect((capturedBody as Record<string, unknown>).title).toBe('My Title');
+    expect((capturedBody as Record<string, unknown>).domain).toBe('short.io');
+  });
+
+  it('returned encryptionKey is a valid base64 string', async () => {
+    server.use(
+      http.post(`${BASE_URL}/links`, () => {
+        return HttpResponse.json({
+          originalURL: 'shortsecure://test',
+          path: 'b64test',
+          shortURL: 'https://short.io/b64test',
+          secureShortURL: 'https://short.io/b64test',
+          idString: 'lnk_b64_123',
+        });
+      }),
+    );
+
+    const result = await createEncryptedLink({
+      client: makeClient(),
+      body: {
+        originalURL: 'https://example.com',
+        domain: 'short.io',
+      },
+    });
+
+    const data = result.data as Record<string, unknown>;
+    const key = data.encryptionKey as string;
+
+    // Valid base64: decode and re-encode should round-trip
+    const decoded = Buffer.from(key, 'base64');
+    expect(decoded.length).toBe(16); // 128-bit AES key = 16 bytes
+    expect(decoded.toString('base64')).toBe(key);
+  });
+});