nornweave 0.1.2__py3-none-any.whl

nornweave/yggdrasil/routes/webhooks/resend.py

@@ -0,0 +1,344 @@
+"""Resend webhook handler."""
+
+import logging
+import uuid
+from datetime import UTC, datetime
+from typing import Any
+
+import httpx
+from fastapi import APIRouter, Depends, HTTPException, Request, status
+
+from nornweave.adapters.resend import ResendAdapter, ResendWebhookError
+from nornweave.core.config import Settings, get_settings
+from nornweave.core.interfaces import (
+    StorageInterface,  # noqa: TC001 - needed at runtime for FastAPI
+)
+from nornweave.models.message import Message, MessageDirection
+from nornweave.models.thread import Thread
+from nornweave.verdandi.parser import html_to_markdown
+from nornweave.yggdrasil.dependencies import get_storage
+
+router = APIRouter()
+logger = logging.getLogger(__name__)
+
+
+# Event types for email delivery tracking
+DELIVERY_EVENT_TYPES = frozenset(
+    {
+        "email.sent",
+        "email.delivered",
+        "email.bounced",
+        "email.complained",
+        "email.failed",
+        "email.opened",
+        "email.clicked",
+        "email.delivery_delayed",
+        "email.scheduled",
+        "email.suppressed",
+    }
+)
+
+
+def _get_resend_adapter(settings: Settings) -> ResendAdapter:
+    """Create ResendAdapter with settings."""
+    return ResendAdapter(
+        api_key=settings.resend_api_key,
+        webhook_secret=settings.resend_webhook_secret,
+    )
+
+
+@router.post("/resend", status_code=status.HTTP_200_OK)
+async def resend_webhook(
+    request: Request,
+    storage: StorageInterface = Depends(get_storage),
+    settings: Settings = Depends(get_settings),
+) -> dict[str, str]:
+    """Handle webhook from Resend.
+
+    Resend sends webhooks as JSON with Svix signature headers.
+    This handler:
+    1. Verifies the webhook signature (if secret is configured)
+    2. Routes to appropriate handler based on event type
+    3. For email.received: fetches full content, creates/resolves thread, stores message
+    4. For delivery events: logs the event for tracking
+
+    Supported event types:
+    - email.received: Inbound email (primary for NornWeave)
+    - email.sent: Outbound email accepted
+    - email.delivered: Successfully delivered
+    - email.bounced: Permanently rejected
+    - email.complained: Marked as spam
+    - email.failed: Failed to send
+    - email.opened: Recipient opened email
+    - email.clicked: Recipient clicked link
+    - email.delivery_delayed: Temporary delivery issue
+    - email.scheduled: Email scheduled
+    - email.suppressed: Suppressed by Resend
+    """
+    # Get raw body for signature verification
+    raw_body = await request.body()
+
+    # Parse JSON payload
+    try:
+        payload: dict[str, Any] = await request.json()
+    except Exception as e:
+        logger.error("Failed to parse JSON payload: %s", e)
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Invalid JSON payload",
+        ) from e
+
+    # Create adapter
+    adapter = _get_resend_adapter(settings)
+
+    # Verify webhook signature if secret is configured
+    if settings.resend_webhook_secret:
+        try:
+            headers = {k.lower(): v for k, v in request.headers.items()}
+            adapter.verify_webhook_signature(raw_body, headers)
+            logger.debug("Webhook signature verified successfully")
+        except ResendWebhookError as e:
+            logger.warning("Webhook signature verification failed: %s", e)
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail=str(e),
+            ) from e
+    else:
+        logger.warning("Webhook secret not configured, skipping signature verification")
+
+    # Get event type
+    event_type = ResendAdapter.get_event_type(payload)
+    logger.info("Received Resend webhook: %s", event_type)
+
+    # Route based on event type
+    if event_type == "email.received":
+        return await _handle_inbound_email(adapter, payload, storage)
+    elif event_type in DELIVERY_EVENT_TYPES:
+        return _handle_delivery_event(event_type, payload)
+    else:
+        logger.warning("Unknown event type: %s", event_type)
+        return {"status": "unknown_event", "event_type": event_type}
+
+
+async def _handle_inbound_email(
+    adapter: ResendAdapter,
+    payload: dict[str, Any],
+    storage: StorageInterface,
+) -> dict[str, str]:
+    """Handle email.received event.
+
+    Fetches full email content from Resend API and stores the message.
+    """
+    data = payload.get("data", {})
+    email_id = data.get("email_id", "unknown")
+
+    logger.info(
+        "Processing inbound email %s from %s to %s",
+        email_id,
+        data.get("from"),
+        data.get("to"),
+    )
+
+    # Parse webhook and fetch full content
+    content_fetch_failed = False
+    try:
+        inbound = await adapter.parse_inbound_webhook_with_content(
+            payload,
+            fetch_attachments=True,
+        )
+    except httpx.HTTPStatusError as e:
+        # If content fetch fails (e.g., API key lacks read permission),
+        # fall back to webhook metadata only and continue processing.
+        # This ensures the message is still created, but with limited content.
+        if e.response.status_code == 401:
+            logger.warning(
+                "Could not fetch full email content (API key restricted). "
+                "Processing with webhook metadata only. "
+                "To get full email content, use an API key with 'Full access' permission."
+            )
+            content_fetch_failed = True
+            inbound = adapter.parse_inbound_webhook(payload)
+        elif e.response.status_code == 404:
+            logger.warning(
+                "Email %s not found in Resend API. Processing with webhook metadata only.",
+                email_id,
+            )
+            content_fetch_failed = True
+            inbound = adapter.parse_inbound_webhook(payload)
+        else:
+            logger.error("Failed to fetch email content: %s", e)
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=f"Failed to process email: {e}",
+            ) from e
+    except ValueError as e:
+        logger.error("Failed to parse webhook payload: %s", e)
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Failed to parse webhook: {e}",
+        ) from e
+
+    # Find inbox by recipient email address
+    inbox = await storage.get_inbox_by_email(inbound.to_address)
+    if inbox is None:
+        logger.warning("No inbox found for recipient: %s", inbound.to_address)
+        # Return 200 to prevent Resend from retrying, but log the issue
+        return {"status": "no_inbox", "recipient": inbound.to_address}
+
+    logger.info("Found inbox %s for recipient %s", inbox.id, inbound.to_address)
+
+    # Try to find existing thread by Message-ID references (for replies)
+    thread_id: str | None = None
+
+    # Check In-Reply-To header first
+    if inbound.in_reply_to:
+        existing_msg = await storage.get_message_by_provider_id(inbox.id, inbound.in_reply_to)
+        if existing_msg:
+            thread_id = existing_msg.thread_id
+            logger.debug("Found thread via In-Reply-To: %s", thread_id)
+
+    # Check References header
+    if not thread_id and inbound.references:
+        for ref in inbound.references:
+            existing_msg = await storage.get_message_by_provider_id(inbox.id, ref)
+            if existing_msg:
+                thread_id = existing_msg.thread_id
+                logger.debug("Found thread via References: %s", thread_id)
+                break
+
+    # If no thread found, create a new one
+    if thread_id:
+        thread = await storage.get_thread(thread_id)
+    else:
+        # Create new thread
+        new_thread = Thread(
+            thread_id=str(uuid.uuid4()),
+            inbox_id=inbox.id,
+            subject=inbound.subject,
+            timestamp=inbound.timestamp,
+            senders=[inbound.from_address],
+            recipients=[inbound.to_address],
+        )
+        thread = await storage.create_thread(new_thread)
+        thread_id = thread.id
+        logger.info("Created new thread %s for subject: %s", thread_id, inbound.subject)
+
+    # Convert HTML to Markdown for clean content
+    # Use stripped versions if available (Mailgun), fall back to full body (Resend)
+    content_clean = inbound.stripped_text or inbound.body_plain
+    extracted_html = inbound.stripped_html or inbound.body_html
+    if inbound.stripped_html:
+        content_clean = html_to_markdown(inbound.stripped_html)
+    elif inbound.body_html:
+        content_clean = html_to_markdown(inbound.body_html)
+
+    # Create the message
+    message = Message(
+        message_id=str(uuid.uuid4()),
+        thread_id=thread_id,
+        inbox_id=inbox.id,
+        provider_message_id=inbound.message_id,
+        direction=MessageDirection.INBOUND,
+        from_address=inbound.from_address,
+        to=[inbound.to_address, *inbound.cc_addresses],
+        subject=inbound.subject,
+        text=inbound.body_plain,
+        html=inbound.body_html,
+        extracted_text=content_clean,
+        extracted_html=extracted_html,
+        in_reply_to=inbound.in_reply_to,
+        references=inbound.references if inbound.references else None,
+        headers=inbound.headers,
+        timestamp=inbound.timestamp,
+        created_at=datetime.now(UTC),
+    )
+
+    created_message = await storage.create_message(message)
+    logger.info("Created message %s in thread %s", created_message.id, thread_id)
+
+    # Store attachments if present
+    for att in inbound.attachments:
+        if att.content and att.size_bytes > 0:
+            try:
+                await storage.create_attachment(
+                    message_id=created_message.id,
+                    filename=att.filename,
+                    content_type=att.content_type,
+                    size_bytes=att.size_bytes,
+                    disposition=att.disposition.value,
+                    content_id=att.content_id,
+                )
+                logger.debug("Created attachment record for %s", att.filename)
+            except (ValueError, RuntimeError) as e:
+                logger.warning("Failed to create attachment record: %s", e)
+
+    # Update thread's last_message_at
+    if thread:
+        thread.last_message_at = created_message.created_at
+        thread.received_timestamp = created_message.created_at
+        await storage.update_thread(thread)
+
+    result = {
+        "status": "received",
+        "message_id": created_message.id,
+        "thread_id": thread_id or "",
+        "email_id": email_id,
+    }
+
+    if content_fetch_failed:
+        result["warning"] = (
+            "Email content could not be fetched from Resend API. "
+            "Message was created with metadata only (no body content). "
+            "Ensure your API key has 'Full access' permission."
+        )
+
+    return result
+
+
+def _handle_delivery_event(event_type: str, payload: dict[str, Any]) -> dict[str, str]:
+    """Handle delivery-related events (sent, delivered, bounced, etc.).
+
+    These events are useful for tracking outbound email delivery status.
+    For now, we just log them. In the future, these could update message status.
+    """
+    data = payload.get("data", {})
+    email_id = data.get("email_id", "unknown")
+    created_at = payload.get("created_at", "")
+
+    # Log event details
+    logger.info(
+        "Resend delivery event: %s for email %s at %s",
+        event_type,
+        email_id,
+        created_at,
+    )
+
+    # For bounced/complained events, log additional details
+    if event_type == "email.bounced":
+        bounce_info = data.get("bounce", {})
+        logger.warning(
+            "Email %s bounced: type=%s, subType=%s, message=%s",
+            email_id,
+            bounce_info.get("type"),
+            bounce_info.get("subType"),
+            bounce_info.get("message"),
+        )
+    elif event_type == "email.complained":
+        logger.warning(
+            "Email %s marked as spam by recipient: %s",
+            email_id,
+            data.get("to", []),
+        )
+    elif event_type == "email.failed":
+        logger.error(
+            "Email %s failed to send: subject=%s, to=%s",
+            email_id,
+            data.get("subject"),
+            data.get("to", []),
+        )
+
+    return {
+        "status": "acknowledged",
+        "event_type": event_type,
+        "email_id": email_id,
+    }

nornweave/yggdrasil/routes/webhooks/sendgrid.py

@@ -0,0 +1,15 @@
+"""SendGrid webhook handler."""
+
+from fastapi import APIRouter, Request, status
+
+router = APIRouter()
+
+
+@router.post("/sendgrid", status_code=status.HTTP_200_OK)
+async def sendgrid_webhook(_request: Request) -> dict[str, str]:
+    """Handle inbound email webhook from SendGrid.
+
+    TODO: Parse webhook payload, create/resolve thread, store message.
+    """
+    # Placeholder - will be implemented with Verdandi (ingestion engine)
+    return {"status": "received"}

nornweave/yggdrasil/routes/webhooks/ses.py

@@ -0,0 +1,15 @@
+"""AWS SES webhook handler."""
+
+from fastapi import APIRouter, Request, status
+
+router = APIRouter()
+
+
+@router.post("/ses", status_code=status.HTTP_200_OK)
+async def ses_webhook(_request: Request) -> dict[str, str]:
+    """Handle inbound email webhook from AWS SES.
+
+    TODO: Parse webhook payload (SNS notification), create/resolve thread, store message.
+    """
+    # Placeholder - will be implemented with Verdandi (ingestion engine)
+    return {"status": "received"}

nornweave-0.1.2.dist-info/METADATA

@@ -0,0 +1,324 @@
+Metadata-Version: 2.4
+Name: nornweave
+Version: 0.1.2
+Summary: Open-source, self-hosted Inbox-as-a-Service API for AI Agents
+Project-URL: Homepage, https://github.com/DataCovey/nornweave
+Project-URL: Documentation, https://nornweave.datacovey.com/docs/
+Project-URL: Repository, https://github.com/DataCovey/nornweave
+Project-URL: Issues, https://github.com/DataCovey/nornweave/issues
+Project-URL: Changelog, https://github.com/DataCovey/nornweave/blob/main/CHANGELOG.md
+Author: NornWeave Contributors
+Maintainer: NornWeave Contributors
+License: Apache-2.0
+License-File: LICENSE
+Keywords: agents,ai,api,email,inbox,llm,mcp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Requires-Dist: aiosqlite>=0.20.0
+Requires-Dist: alembic>=1.14.0
+Requires-Dist: click>=8.1.0
+Requires-Dist: cryptography>=44.0.0
+Requires-Dist: email-validator>=2.2.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: html2text>=2024.2.26
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: markdown>=3.7
+Requires-Dist: pydantic-settings>=2.6.0
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: python-multipart>=0.0.18
+Requires-Dist: sqlalchemy[asyncio]>=2.0.36
+Requires-Dist: svix>=1.24.0
+Requires-Dist: uvicorn[standard]>=0.32.0
+Provides-Extra: all
+Requires-Dist: asyncpg>=0.30.0; extra == 'all'
+Requires-Dist: fastmcp>=2.0.0; extra == 'all'
+Requires-Dist: mcp>=1.0.0; extra == 'all'
+Requires-Dist: openai>=1.57.0; extra == 'all'
+Requires-Dist: pgvector>=0.3.6; extra == 'all'
+Requires-Dist: psycopg2-binary>=2.9.0; extra == 'all'
+Requires-Dist: pypdf>=5.1.0; extra == 'all'
+Requires-Dist: python-magic>=0.4.27; extra == 'all'
+Requires-Dist: redis>=5.2.0; extra == 'all'
+Provides-Extra: attachments
+Requires-Dist: pypdf>=5.1.0; extra == 'attachments'
+Requires-Dist: python-magic>=0.4.27; extra == 'attachments'
+Provides-Extra: dev
+Requires-Dist: aiosqlite>=0.20.0; extra == 'dev'
+Requires-Dist: httpx>=0.28.0; extra == 'dev'
+Requires-Dist: mypy>=1.13.0; extra == 'dev'
+Requires-Dist: pre-commit>=4.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: fastmcp>=2.0.0; extra == 'mcp'
+Requires-Dist: mcp>=1.0.0; extra == 'mcp'
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.30.0; extra == 'postgres'
+Requires-Dist: psycopg2-binary>=2.9.0; extra == 'postgres'
+Provides-Extra: ratelimit
+Requires-Dist: redis>=5.2.0; extra == 'ratelimit'
+Provides-Extra: search
+Requires-Dist: openai>=1.57.0; extra == 'search'
+Requires-Dist: pgvector>=0.3.6; extra == 'search'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="web/static/images/Nornorna_spinner.jpg" alt="The Norns weaving fate at Yggdrasil" width="400">
+</p>
+
+<h1 align="center">NornWeave</h1>
+
+<p align="center">
+  <em>"Laws they made there, and life allotted / To the sons of men, and set their fates."</em><br>
+  - Voluspa (The Prophecy of the Seeress), Poetic Edda, Stanza 20
+</p>
+
+<p align="center">
+  <strong>Open-source, self-hosted Inbox-as-a-Service API for AI Agents</strong>
+</p>
+
+<p align="center">
+  <a href="https://github.com/DataCovey/nornweave/actions"><img src="https://github.com/DataCovey/nornweave/workflows/CI/badge.svg" alt="CI Status"></a>
+  <a href="https://github.com/DataCovey/nornweave/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="License"></a>
+</p>
+
+---
+
+## What is NornWeave?
+
+Standard email APIs are stateless and built for transactional sending. **NornWeave** adds a **stateful layer** (Inboxes, Threads, History) and an **intelligent layer** (Markdown parsing, Semantic Search) to make email consumable by LLMs via REST or MCP.
+
+In Norse mythology, the Norns (Urdr, Verdandi, and Skuld) dwell at the base of Yggdrasil, the World Tree. They weave the tapestry of fate for all beings. Similarly, NornWeave:
+
+- Takes raw "water" (incoming email data streams)
+- Weaves disconnected messages into coherent **Threads** (the Tapestry)
+- Nourishes AI Agents with clean, structured context
+
+## Features
+
+### Foundation (The Mail Proxy)
+- **Virtual Inboxes**: Create email addresses for your AI agents
+- **Webhook Ingestion**: Receive emails from Mailgun, SES, SendGrid, Resend
+- **Persistent Storage**: PostgreSQL with abstracted storage adapters
+- **Email Sending**: Send replies through your configured provider
+
+### Intelligence (The Agent Layer)
+- **Content Parsing**: HTML to clean Markdown, cruft removal
+- **Threading**: Automatic conversation grouping via email headers
+- **MCP Server**: Connect directly to Claude, Cursor, and other MCP clients
+- **Attachment Processing**: Extract text from PDFs and documents
+
+### Enterprise (The Platform Layer)
+- **Semantic Search**: Vector embeddings with pgvector
+- **Real-time Webhooks**: Get notified of new messages
+- **Rate Limiting**: Protect against runaway agents
+- **Multi-Tenancy**: Organizations and projects
+
+## Quick Start
+
+### Install from PyPI
+
+```bash
+# Base installation (SQLite, all email providers)
+pip install nornweave
+
+# With PostgreSQL support
+pip install nornweave[postgres]
+
+# With MCP server for AI agents
+pip install nornweave[mcp]
+
+# Full installation
+pip install nornweave[all]
+```
+
+### Using Docker (Recommended for Production)
+
+```bash
+# Clone the repository
+git clone https://github.com/DataCovey/nornweave.git
+cd nornweave
+
+# Copy environment configuration
+cp .env.example .env
+# Edit .env with your API keys
+
+# Start the stack
+docker compose up -d
+
+# Run migrations
+docker compose exec api alembic upgrade head
+```
+
+### Using uv (Development)
+
+```bash
+# Clone the repository
+git clone https://github.com/DataCovey/nornweave.git
+cd nornweave
+
+# Install dependencies
+make install-dev
+
+# Copy environment configuration
+cp .env.example .env
+
+# Start PostgreSQL (or use your own)
+docker compose up -d postgres
+
+# Run migrations
+make migrate
+
+# Start the development server
+make dev
+```
+
+### Configure Your Email Provider
+
+1. Set `EMAIL_PROVIDER` in `.env` (e.g., `mailgun`)
+2. Add your provider's API key
+3. Configure the webhook URL in your provider's dashboard:
+   ```
+   https://your-server.com/webhooks/mailgun
+   ```
+
+## API Overview
+
+### Create an Inbox
+
+```bash
+curl -X POST http://localhost:8000/v1/inboxes \
+  -H "Authorization: Bearer YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Support Agent", "email_username": "support"}'
+```
+
+### Read a Thread
+
+```bash
+curl http://localhost:8000/v1/threads/th_123 \
+  -H "Authorization: Bearer YOUR_API_KEY"
+```
+
+Response (LLM-optimized):
+```json
+{
+  "id": "th_123",
+  "subject": "Re: Pricing Question",
+  "messages": [
+    { "role": "user", "author": "bob@gmail.com", "content": "How much is it?", "timestamp": "..." },
+    { "role": "assistant", "author": "agent@myco.com", "content": "$20/mo", "timestamp": "..." }
+  ]
+}
+```
+
+### Send a Reply
+
+```bash
+curl -X POST http://localhost:8000/v1/messages \
+  -H "Authorization: Bearer YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "inbox_id": "ibx_555",
+    "reply_to_thread_id": "th_123",
+    "to": ["client@gmail.com"],
+    "subject": "Re: Pricing Question",
+    "body": "Thanks for your interest! Our pricing starts at $20/mo."
+  }'
+```
+
+## MCP Integration
+
+NornWeave exposes an MCP server for direct integration with Claude, Cursor, and other MCP-compatible clients.
+
+### Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `create_inbox` | Provision a new email address |
+| `send_email` | Send an email (auto-converts Markdown to HTML) |
+| `search_email` | Find relevant messages in your inbox |
+| `wait_for_reply` | Block until a reply arrives (experimental) |
+
+### Configure in Cursor/Claude
+
+```bash
+pip install nornweave[mcp]
+```
+
+```json
+{
+  "mcpServers": {
+    "nornweave": {
+      "command": "nornweave",
+      "args": ["mcp"],
+      "env": {
+        "NORNWEAVE_API_URL": "http://localhost:8000"
+      }
+    }
+  }
+}
+```
+
+## Architecture
+
+NornWeave uses a thematic architecture inspired by Norse mythology:
+
+| Component | Name | Purpose |
+|-----------|------|---------|
+| Storage Layer | **Urdr** (The Well) | Database adapters (PostgreSQL, SQLite) |
+| Ingestion Engine | **Verdandi** (The Loom) | Webhook processing, HTML to Markdown |
+| API & Outbound | **Skuld** (The Prophecy) | REST API, email sending, rate limiting |
+| Gateway | **Yggdrasil** | API router connecting all providers |
+| MCP Tools | **Huginn & Muninn** | Read/write tools for AI agents |
+
+## Supported Providers
+
+| Provider | Sending | Receiving | Auto-Route Setup |
+|----------|---------|-----------|------------------|
+| Mailgun | yes | yes | yes |
+| AWS SES | yes | yes | manual |
+| SendGrid | yes | yes | yes |
+| Resend | yes | yes | yes |
+
+## Documentation
+
+- [Getting Started Guide](https://nornweave.datacovey.com/docs/getting-started/)
+- [API Reference](https://nornweave.datacovey.com/docs/api/)
+- [Architecture Overview](https://nornweave.datacovey.com/docs/concepts/architecture/)
+- [Provider Setup Guides](https://nornweave.datacovey.com/docs/guides/)
+
+## Repository Structure
+
+This is a monorepo:
+
+- **`src/nornweave/`** – Main NornWeave server components
+- **`clients/python/`** – Python client SDK (`nornweave-client`)
+- **`packages/n8n-nodes-nornweave/`** – n8n community node (`@nornweave/n8n-nodes-nornweave`)
+
+The root **`credentials`** symlink points to `packages/n8n-nodes-nornweave/credentials` so n8n’s package verification can find the credential file when checking the repo.
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+## License
+
+NornWeave is open-source software licensed under the [Apache 2.0 License](LICENSE).
+
+---
+
+<p align="center">
+  <sub>Image: "Nornorna spinner odet tradar vid Yggdrasil" by L. B. Hansen</sub><br>
+  <sub><a href="https://commons.wikimedia.org/w/index.php?curid=164065">Public Domain</a></sub>
+</p>