crinkl-agent 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Crinkl Protocol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,161 @@
+<div align="center">
+
+# crinkl-agent
+
+Scan Gmail for SaaS billing emails. Submit them to [Crinkl](https://crinkl.xyz). Get sats over Lightning.
+
+[Quick start](#quick-start) · [API](#api-reference) · [Privacy](#privacy)
+
+</div>
+
+---
+
+[Crinkl](https://crinkl.xyz) verifies real-world spend and mints **identity-free spend tokens** — cryptographic proofs with no personal data. This agent is a reference implementation for the [email receipt API](#api-reference). Humans scan physical receipts in the [PWA](https://app.crinkl.xyz). Agents submit DKIM-signed emails via REST. Both produce the same protocol artifact.
+
+> Building your own agent? You may only need the [API endpoints](#api-reference).
+
+## How it works
+
+```
+Gmail (readonly) → crinkl-agent (your machine) → api.crinkl.xyz (DKIM verify + attest) → spend token → ₿ sats
+```
+
+1. **Fetch** allowed vendors from the Crinkl API
+2. **Search** Gmail for billing emails from those vendors (last 14 days, read-only)
+3. **Download** each email as raw `.eml` — in memory, never written to disk
+4. **Submit** to Crinkl — server verifies the DKIM signature, extracts invoice data, mints a spend token
+5. **Dedup** locally so the same email is never submitted twice
+
+The server does all verification and data extraction. The agent is just a pipe from your inbox to the API.
+
+## Quick start
+
+### 1. Get a Crinkl API key
+
+Sign up at [app.crinkl.xyz](https://app.crinkl.xyz) — it's a PWA, works in any browser. Once you have a wallet:
+
+**Settings → Agent API Keys → Generate**
+
+This gives you a `crk_...` key tied to your wallet. Spend tokens minted by the agent are credited to this wallet.
+
+### 2. Set up Gmail OAuth
+
+1. [Create an OAuth 2.0 Client ID](https://console.cloud.google.com/apis/credentials) (type: Desktop app)
+2. [Enable the Gmail API](https://console.cloud.google.com/apis/library/gmail.googleapis.com)
+
+### 3. Run
+
+```bash
+git clone https://github.com/crinkl-protocol/crinkl-agent.git
+cd crinkl-agent
+npm install
+cp .env.example .env    # add your API key + OAuth credentials
+npm run auth            # one-time Gmail authorization
+npm run dev             # scan + submit
+```
+
+### Usage
+
+```
+npm run dev              # scan Gmail + submit receipts
+npm run dev -- --scan    # dry run (preview only)
+npm run dev -- --auth    # set up Gmail auth only
+```
+
+### Run on a schedule
+
+```bash
+# Every 6 hours
+0 */6 * * * cd /path/to/crinkl-agent && npm run dev >> ~/.crinkl/agent.log 2>&1
+```
+
+## Supported vendors
+
+The server maintains the allowlist. The agent fetches it on every run.
+
+```bash
+curl https://api.crinkl.xyz/api/agent/allowed-vendors
+```
+
+Vendors must send DKIM-signed billing emails. Web-only invoices (download from dashboard) have no DKIM signature and can't be verified.
+
+If you submit an email from an unknown vendor, it's **queued for review** (not rejected). Once approved, the vendor is added to the allowlist and your spend is created retroactively.
+
+> **Want to add a vendor?** Just submit an email from them. If the domain has valid DKIM, we'll review and approve it.
+
+## API reference
+
+### Public (no auth)
+
+```
+GET https://api.crinkl.xyz/api/agent/allowed-vendors
+```
+
+### Authenticated (`x-api-key` header)
+
+```
+POST https://api.crinkl.xyz/api/agent/submit-email-receipt
+Body: { "eml": "<base64-encoded .eml>" }
+Returns: 201 (created) | 202 (queued for vendor review) | 409 (duplicate) | 422 (validation error)
+
+POST https://api.crinkl.xyz/api/agent/verify-email-receipt
+Body: { "eml": "<base64-encoded .eml>" }
+Returns: 200 (preview without submitting)
+
+GET https://api.crinkl.xyz/api/agent/spends/:spendId/token/latest
+Returns: the signed spend attestation token
+```
+
+### For MCP-capable agents
+
+If you're running Claude Desktop, Cursor, OpenClaw, or any MCP client — you can use the public MCP server for read-only commerce intelligence:
+
+```json
+{
+  "mcpServers": {
+    "crinkl": {
+      "url": "https://mcp.crinkl.xyz/mcp"
+    }
+  }
+}
+```
+
+Email receipt submission uses the REST API above (requires an API key).
+
+## Privacy
+
+This agent runs on your machine. Here's what leaves it:
+
+| Data | Destination | Purpose |
+|------|-------------|---------|
+| Individual `.eml` files | `api.crinkl.xyz` | DKIM verification + spend token minting |
+| Nothing else | — | — |
+
+- **Read-only Gmail access** — `gmail.readonly` scope. Cannot send, delete, or modify.
+- **No inbox access shared** — Crinkl receives individual emails, not credentials or tokens.
+- **OAuth token stays local** — stored at `~/.crinkl/gmail-credentials.json`.
+- **Spend tokens are identity-free** — no email, no name, no account ID in the signed payload.
+
+## Architecture
+
+```
+src/
+├── index.ts       # CLI entry — Gmail scan loop, submit/dedup logic
+├── config.ts      # .env loader
+├── gmail.ts       # Gmail OAuth + search + download
+└── crinkl.ts      # Crinkl API client (verify, submit, vendors)
+```
+
+~200 lines of core logic. The server does the hard part.
+
+## License
+
+[MIT](LICENSE)
+
+---
+
+<div align="center">
+
+**[crinkl.xyz](https://crinkl.xyz)** · verified spend, identity detached
+
+</div>

package/dist/config.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Configuration — loads from environment variables or .env file.
+ * All secrets stay local on the user's machine.
+ */
+export interface Config {
+    crinklApiKey: string;
+    crinklApiUrl: string;
+    gmailClientId: string;
+    gmailClientSecret: string;
+    maxEmailAgeDays: number;
+    credentialsPath: string;
+}
+export declare function loadConfig(): Config;

package/dist/config.js

@@ -0,0 +1,49 @@
+/**
+ * Configuration — loads from environment variables or .env file.
+ * All secrets stay local on the user's machine.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+/** Load .env file (simple key=value parser, no npm dep) */
+function loadDotEnv() {
+    const envPath = resolve(process.cwd(), ".env");
+    if (!existsSync(envPath))
+        return;
+    const lines = readFileSync(envPath, "utf-8").split("\n");
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const eq = trimmed.indexOf("=");
+        if (eq === -1)
+            continue;
+        const key = trimmed.slice(0, eq).trim();
+        const value = trimmed.slice(eq + 1).trim();
+        if (!process.env[key]) {
+            process.env[key] = value;
+        }
+    }
+}
+export function loadConfig() {
+    loadDotEnv();
+    const crinklApiKey = process.env.CRINKL_API_KEY;
+    if (!crinklApiKey) {
+        console.error("CRINKL_API_KEY is required. Get one from https://app.crinkl.xyz");
+        process.exit(1);
+    }
+    const gmailClientId = process.env.GMAIL_CLIENT_ID;
+    const gmailClientSecret = process.env.GMAIL_CLIENT_SECRET;
+    if (!gmailClientId || !gmailClientSecret) {
+        console.error("GMAIL_CLIENT_ID and GMAIL_CLIENT_SECRET are required.");
+        console.error("Create an OAuth app at https://console.cloud.google.com/apis/credentials");
+        process.exit(1);
+    }
+    return {
+        crinklApiKey,
+        crinklApiUrl: process.env.CRINKL_API_URL || "https://api.crinkl.xyz",
+        gmailClientId,
+        gmailClientSecret,
+        maxEmailAgeDays: parseInt(process.env.MAX_EMAIL_AGE_DAYS || "14", 10),
+        credentialsPath: resolve(process.env.HOME || "~", ".crinkl", "gmail-credentials.json"),
+    };
+}

package/dist/crinkl.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Crinkl API client — wrappers for the DKIM email receipt endpoints.
+ *
+ * All communication goes through the public REST API.
+ * Only the .eml content is sent — no inbox access is shared.
+ */
+import type { Config } from "./config.js";
+interface Vendor {
+    domain: string;
+    displayName: string;
+}
+interface VerifyResult {
+    success: boolean;
+    data?: {
+        dkimVerified: boolean;
+        dkimDomain: string;
+        provider: string;
+        totalCents: number;
+        date: string;
+        invoiceId: string | null;
+        subject: string;
+        currency: string;
+        lineItems: Array<{
+            description: string;
+            amountCents: number;
+        }>;
+    };
+    error?: string;
+    domain?: string;
+    date?: string;
+    maxAgeDays?: number;
+}
+interface SubmitResult {
+    success: boolean;
+    /** Present when spend was created (201) */
+    data?: {
+        submissionId: string;
+        spendId: string;
+        provider: string;
+        store: string;
+        storeId: string;
+        totalCents: number;
+        date: string;
+        currency: string;
+        invoiceId: string | null;
+        dkimDomain: string;
+        status: string;
+        verificationMethod: string;
+    };
+    /** Present when vendor is unknown and queued for admin review (202) */
+    status?: "QUEUED_FOR_REVIEW";
+    message?: string;
+    error?: string;
+    domain?: string;
+}
+export declare class CrinklClient {
+    private apiUrl;
+    private apiKey;
+    constructor(config: Config);
+    /** Fetch allowed vendors from the server */
+    getAllowedVendors(): Promise<Vendor[]>;
+    /** Preview DKIM verification without submitting */
+    verifyEmailReceipt(rawEml: string): Promise<VerifyResult>;
+    /** Submit a DKIM-verified email receipt for rewards */
+    submitEmailReceipt(rawEml: string): Promise<SubmitResult>;
+}
+export {};

package/dist/crinkl.js

@@ -0,0 +1,49 @@
+/**
+ * Crinkl API client — wrappers for the DKIM email receipt endpoints.
+ *
+ * All communication goes through the public REST API.
+ * Only the .eml content is sent — no inbox access is shared.
+ */
+export class CrinklClient {
+    apiUrl;
+    apiKey;
+    constructor(config) {
+        this.apiUrl = config.crinklApiUrl;
+        this.apiKey = config.crinklApiKey;
+    }
+    /** Fetch allowed vendors from the server */
+    async getAllowedVendors() {
+        const response = await fetch(`${this.apiUrl}/api/agent/allowed-vendors`);
+        if (!response.ok) {
+            throw new Error(`Failed to fetch vendors: ${response.status} ${response.statusText}`);
+        }
+        const body = (await response.json());
+        return body.data.vendors;
+    }
+    /** Preview DKIM verification without submitting */
+    async verifyEmailReceipt(rawEml) {
+        const eml = Buffer.from(rawEml).toString("base64");
+        const response = await fetch(`${this.apiUrl}/api/agent/verify-email-receipt`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "x-api-key": this.apiKey,
+            },
+            body: JSON.stringify({ eml }),
+        });
+        return response.json();
+    }
+    /** Submit a DKIM-verified email receipt for rewards */
+    async submitEmailReceipt(rawEml) {
+        const eml = Buffer.from(rawEml).toString("base64");
+        const response = await fetch(`${this.apiUrl}/api/agent/submit-email-receipt`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "x-api-key": this.apiKey,
+            },
+            body: JSON.stringify({ eml }),
+        });
+        return response.json();
+    }
+}

package/dist/gmail.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Gmail OAuth + email search/download.
+ *
+ * Privacy: OAuth tokens are stored locally only (~/.crinkl/gmail-credentials.json).
+ * Only gmail.readonly scope is requested — no send/delete/modify access.
+ * Emails are downloaded to memory (never written to disk).
+ */
+import { google } from "googleapis";
+import type { Config } from "./config.js";
+/** Get authenticated Gmail client. Runs OAuth flow on first use. */
+export declare function getGmailClient(config: Config): Promise<import("googleapis").gmail_v1.Gmail>;
+/** Search Gmail for receipt emails from allowed vendors */
+export declare function searchReceiptEmails(gmail: ReturnType<typeof google.gmail>, vendors: Array<{
+    domain: string;
+}>, maxAgeDays: number): Promise<Array<{
+    messageId: string;
+    snippet: string;
+}>>;
+/** Download raw .eml content for a message (in memory only — never written to disk) */
+export declare function downloadRawEml(gmail: ReturnType<typeof google.gmail>, messageId: string): Promise<string>;
+/** Get email subject for display */
+export declare function getMessageSubject(gmail: ReturnType<typeof google.gmail>, messageId: string): Promise<string>;

package/dist/gmail.js

@@ -0,0 +1,111 @@
+/**
+ * Gmail OAuth + email search/download.
+ *
+ * Privacy: OAuth tokens are stored locally only (~/.crinkl/gmail-credentials.json).
+ * Only gmail.readonly scope is requested — no send/delete/modify access.
+ * Emails are downloaded to memory (never written to disk).
+ */
+import { google } from "googleapis";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { createInterface } from "node:readline";
+const SCOPES = ["https://www.googleapis.com/auth/gmail.readonly"];
+const REDIRECT_URI = "http://localhost";
+/** Get authenticated Gmail client. Runs OAuth flow on first use. */
+export async function getGmailClient(config) {
+    const oauth2 = new google.auth.OAuth2(config.gmailClientId, config.gmailClientSecret, REDIRECT_URI);
+    // Try loading saved credentials
+    if (existsSync(config.credentialsPath)) {
+        const saved = JSON.parse(readFileSync(config.credentialsPath, "utf-8"));
+        oauth2.setCredentials(saved);
+        return google.gmail({ version: "v1", auth: oauth2 });
+    }
+    // First-time OAuth flow
+    const authUrl = oauth2.generateAuthUrl({
+        access_type: "offline",
+        scope: SCOPES,
+        prompt: "consent",
+    });
+    console.log("\n--- Gmail Authorization ---");
+    console.log("1. Open this URL in your browser:\n");
+    console.log(`   ${authUrl}\n`);
+    console.log("2. Authorize the app. You'll be redirected to a page that won't load.");
+    console.log("3. Copy the FULL URL from your browser's address bar and paste it below.\n");
+    console.log("   It will look like: http://localhost?code=4/0AQ...\n");
+    const rawUrl = await prompt("Paste the full redirect URL: ");
+    // Extract code from the pasted URL
+    let code;
+    if (rawUrl.startsWith("http")) {
+        const url = new URL(rawUrl);
+        code = url.searchParams.get("code") || rawUrl;
+    }
+    else {
+        code = rawUrl;
+    }
+    const { tokens } = await oauth2.getToken(code);
+    oauth2.setCredentials(tokens);
+    // Save credentials locally
+    mkdirSync(dirname(config.credentialsPath), { recursive: true });
+    writeFileSync(config.credentialsPath, JSON.stringify(tokens, null, 2), { mode: 0o600 });
+    console.log(`Credentials saved to ${config.credentialsPath}\n`);
+    return google.gmail({ version: "v1", auth: oauth2 });
+}
+/** Search Gmail for receipt emails from allowed vendors */
+export async function searchReceiptEmails(gmail, vendors, maxAgeDays) {
+    if (vendors.length === 0) {
+        console.log("No allowed vendors found.");
+        return [];
+    }
+    // Build search query: from:@vendor1 OR from:@vendor2 ... newer_than:14d
+    const fromClauses = vendors.map((v) => `from:@${v.domain}`).join(" OR ");
+    const query = `(${fromClauses}) newer_than:${maxAgeDays}d`;
+    console.log(`Searching Gmail: ${query}`);
+    const response = await gmail.users.messages.list({
+        userId: "me",
+        q: query,
+        maxResults: 50,
+    });
+    const messages = response.data.messages || [];
+    console.log(`Found ${messages.length} matching emails.`);
+    return messages.map((m) => ({
+        messageId: m.id,
+        snippet: m.snippet || "",
+    }));
+}
+/** Download raw .eml content for a message (in memory only — never written to disk) */
+export async function downloadRawEml(gmail, messageId) {
+    const response = await gmail.users.messages.get({
+        userId: "me",
+        id: messageId,
+        format: "raw",
+    });
+    // Gmail returns URL-safe base64
+    const raw = response.data.raw;
+    return Buffer.from(raw, "base64url").toString("utf-8");
+}
+/** Get email subject for display */
+export async function getMessageSubject(gmail, messageId) {
+    const response = await gmail.users.messages.get({
+        userId: "me",
+        id: messageId,
+        format: "metadata",
+        metadataHeaders: ["Subject", "From", "Date"],
+    });
+    const headers = response.data.payload?.headers || [];
+    const subject = headers.find((h) => h.name === "Subject")?.value || "(no subject)";
+    const from = headers.find((h) => h.name === "From")?.value || "";
+    const date = headers.find((h) => h.name === "Date")?.value || "";
+    return `${date} | ${from} | ${subject}`;
+}
+function prompt(question) {
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * Crinkl Email Receipt Agent
+ *
+ * Scans your Gmail for billing receipts from approved vendors,
+ * verifies DKIM signatures, and submits them to earn BTC rewards.
+ *
+ * Privacy: Gmail OAuth runs locally. Emails are processed in memory.
+ * Only individual .eml files are sent to Crinkl for verification.
+ *
+ * Usage:
+ *   crinkl-agent            # scan + submit (default)
+ *   crinkl-agent --auth     # just set up Gmail auth
+ *   crinkl-agent --scan     # scan only (dry run, no submit)
+ *   crinkl-agent --help     # show help
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+/**
+ * Crinkl Email Receipt Agent
+ *
+ * Scans your Gmail for billing receipts from approved vendors,
+ * verifies DKIM signatures, and submits them to earn BTC rewards.
+ *
+ * Privacy: Gmail OAuth runs locally. Emails are processed in memory.
+ * Only individual .eml files are sent to Crinkl for verification.
+ *
+ * Usage:
+ *   crinkl-agent            # scan + submit (default)
+ *   crinkl-agent --auth     # just set up Gmail auth
+ *   crinkl-agent --scan     # scan only (dry run, no submit)
+ *   crinkl-agent --help     # show help
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { loadConfig } from "./config.js";
+import { getGmailClient, searchReceiptEmails, downloadRawEml, getMessageSubject, } from "./gmail.js";
+import { CrinklClient } from "./crinkl.js";
+const SUBMITTED_IDS_FILE = resolve(process.env.HOME || "~", ".crinkl", "submitted-emails.json");
+const HELP = `
+Crinkl Email Receipt Agent
+
+Scans your Gmail for billing receipts from approved vendors,
+verifies DKIM signatures, and submits them to Crinkl for BTC rewards.
+
+Usage:
+  crinkl-agent            Scan + submit (default)
+  crinkl-agent --auth     Set up Gmail authorization only
+  crinkl-agent --scan     Dry run — preview without submitting
+  crinkl-agent --help     Show this help
+
+Environment variables (or .env file):
+  CRINKL_API_KEY          Your Crinkl agent API key (required)
+  GMAIL_CLIENT_ID         Google OAuth client ID (required)
+  GMAIL_CLIENT_SECRET     Google OAuth client secret (required)
+  CRINKL_API_URL          API base URL (default: https://api.crinkl.xyz)
+  MAX_EMAIL_AGE_DAYS      How far back to search (default: 14)
+
+Get started:
+  1. Get an API key at https://app.crinkl.xyz
+  2. Create a Google OAuth app at https://console.cloud.google.com/apis/credentials
+  3. Copy .env.example to .env and fill in your credentials
+  4. Run: crinkl-agent
+`.trim();
+/** Load set of already-submitted Gmail message IDs */
+function loadSubmittedIds() {
+    if (!existsSync(SUBMITTED_IDS_FILE))
+        return new Set();
+    try {
+        const data = JSON.parse(readFileSync(SUBMITTED_IDS_FILE, "utf-8"));
+        return new Set(Array.isArray(data) ? data : []);
+    }
+    catch {
+        return new Set();
+    }
+}
+/** Save submitted IDs to disk */
+function saveSubmittedIds(ids) {
+    mkdirSync(dirname(SUBMITTED_IDS_FILE), { recursive: true });
+    writeFileSync(SUBMITTED_IDS_FILE, JSON.stringify([...ids], null, 2));
+}
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.includes("--help") || args.includes("-h")) {
+        console.log(HELP);
+        return;
+    }
+    const authOnly = args.includes("--auth");
+    const scanOnly = args.includes("--scan");
+    console.log("Crinkl Email Receipt Agent v0.1.0\n");
+    // 1. Load config
+    const config = loadConfig();
+    const crinkl = new CrinklClient(config);
+    // 2. Authenticate with Gmail
+    console.log("Connecting to Gmail...");
+    const gmail = await getGmailClient(config);
+    console.log("Gmail connected.\n");
+    if (authOnly) {
+        console.log("Auth setup complete. Run without --auth to scan emails.");
+        return;
+    }
+    // 3. Fetch allowed vendors from Crinkl
+    console.log("Fetching allowed vendors...");
+    const vendors = await crinkl.getAllowedVendors();
+    console.log(`Allowed vendors: ${vendors.map((v) => v.displayName).join(", ")}\n`);
+    if (vendors.length === 0) {
+        console.log("No vendors are currently approved. Check back later.");
+        return;
+    }
+    // 4. Search Gmail for receipt emails
+    const emails = await searchReceiptEmails(gmail, vendors, config.maxEmailAgeDays);
+    if (emails.length === 0) {
+        console.log("No receipt emails found in the last " +
+            config.maxEmailAgeDays +
+            " days.");
+        return;
+    }
+    // 5. Process each email
+    const submittedIds = loadSubmittedIds();
+    let submitted = 0;
+    let skipped = 0;
+    let errors = 0;
+    for (const email of emails) {
+        // Dedup: skip already-submitted emails
+        if (submittedIds.has(email.messageId)) {
+            skipped++;
+            continue;
+        }
+        const subject = await getMessageSubject(gmail, email.messageId);
+        console.log(`\n--- Processing: ${subject}`);
+        try {
+            // Download raw .eml (in memory only)
+            const rawEml = await downloadRawEml(gmail, email.messageId);
+            // Preview: verify DKIM first
+            const preview = await crinkl.verifyEmailReceipt(rawEml);
+            if (!preview.success) {
+                console.log(`  SKIP: ${preview.error}`);
+                // Mark as "seen" to avoid retrying non-DKIM emails
+                submittedIds.add(email.messageId);
+                skipped++;
+                continue;
+            }
+            const data = preview.data;
+            const amount = (data.totalCents / 100).toFixed(2);
+            console.log(`  DKIM: ${data.dkimVerified ? "PASS" : "FAIL"} (${data.dkimDomain})`);
+            console.log(`  Amount: $${amount} ${data.currency}`);
+            console.log(`  Date: ${data.date}`);
+            if (data.invoiceId)
+                console.log(`  Invoice: ${data.invoiceId}`);
+            if (!data.dkimVerified) {
+                console.log("  SKIP: DKIM verification failed");
+                submittedIds.add(email.messageId);
+                skipped++;
+                continue;
+            }
+            if (scanOnly) {
+                console.log("  DRY RUN: would submit (run without --scan to submit)");
+                continue;
+            }
+            // Submit for rewards
+            const result = await crinkl.submitEmailReceipt(rawEml);
+            if (result.status === "QUEUED_FOR_REVIEW") {
+                console.log(`  QUEUED: vendor ${result.domain || "unknown"} not yet approved — queued for admin review`);
+                submittedIds.add(email.messageId);
+                skipped++;
+            }
+            else if (result.success && result.data) {
+                console.log(`  SUBMITTED: ${result.data.store} — $${amount} — status: ${result.data.status}`);
+                submittedIds.add(email.messageId);
+                submitted++;
+            }
+            else {
+                console.log(`  ERROR: ${result.error}`);
+                if (result.error?.includes("already been submitted")) {
+                    submittedIds.add(email.messageId);
+                    skipped++;
+                }
+                else {
+                    errors++;
+                }
+            }
+        }
+        catch (err) {
+            console.error(`  ERROR: ${err instanceof Error ? err.message : String(err)}`);
+            errors++;
+        }
+    }
+    // Save dedup state
+    saveSubmittedIds(submittedIds);
+    // Summary
+    console.log("\n--- Summary ---");
+    console.log(`Submitted: ${submitted}`);
+    console.log(`Skipped: ${skipped} (already submitted or non-receipt)`);
+    if (errors > 0)
+        console.log(`Errors: ${errors}`);
+    console.log("");
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "crinkl-agent",
+  "version": "0.1.0",
+  "description": "Earn BTC from email receipts. Scans Gmail for billing emails, verifies DKIM signatures, and submits to Crinkl.",
+  "type": "module",
+  "bin": {
+    "crinkl-agent": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "scan": "tsx src/index.ts --scan",
+    "auth": "tsx src/index.ts --auth",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "crinkl",
+    "bitcoin",
+    "receipt",
+    "dkim",
+    "email",
+    "agent"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/crinkl-protocol/crinkl-agent.git"
+  },
+  "homepage": "https://crinkl.xyz",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "googleapis": "^144.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.0.18"
+  }
+}