@powerhousedao/contributor-billing 0.1.31 → 0.1.33

package/dist/editors/snapshot-report-editor/utils/flowTypeCalculations.js

@@ -0,0 +1,63 @@
+/**
+ * Calculate the flow type for a transaction based on account types
+ * @param direction - Transaction direction (INFLOW or OUTFLOW)
+ * @param accountType - Type of the account the transaction belongs to
+ * @param counterPartyType - Type of the counter-party account (if found)
+ * @returns The calculated flow type
+ */
+export function calculateFlowType(direction, accountType, counterPartyType) {
+    if (!counterPartyType) {
+        return "External";
+    }
+    // Determine sender and receiver types based on transaction direction
+    const fromType = direction === "OUTFLOW" ? accountType : counterPartyType;
+    const toType = direction === "OUTFLOW" ? counterPartyType : accountType;
+    // Flow categorization rules
+    if (fromType === "Source") {
+        return "TopUp";
+    }
+    else if (toType === "Source") {
+        return "Return";
+    }
+    else if (toType === "Destination") {
+        return "TopUp";
+    }
+    else if (fromType === "External") {
+        return "External";
+    }
+    else if (fromType === "Internal" && toType === "Internal") {
+        return "Internal";
+    }
+    else if (fromType === "Internal" && toType === "External") {
+        return "External";
+    }
+    return "External";
+}
+/**
+ * Find a counter-party account by address in the snapshot accounts
+ * @param counterPartyAddress - The ethereum address of the counter-party
+ * @param snapshotAccounts - Array of snapshot accounts to search
+ * @returns The matching account or undefined
+ */
+export function findCounterPartyAccount(counterPartyAddress, snapshotAccounts) {
+    if (!counterPartyAddress) {
+        return undefined;
+    }
+    return snapshotAccounts.find((acc) => acc.accountAddress.toLowerCase() === counterPartyAddress.toLowerCase());
+}
+/**
+ * Calculate flow type and counter-party account ID for a transaction
+ * @param direction - Transaction direction
+ * @param accountType - Type of the account
+ * @param counterPartyAddress - Counter-party ethereum address
+ * @param snapshotAccounts - All snapshot accounts for lookup
+ * @returns Object with flowType and counterPartyAccountId
+ */
+export function calculateTransactionFlowInfo(direction, accountType, counterPartyAddress, snapshotAccounts) {
+    const counterPartyAccount = findCounterPartyAccount(counterPartyAddress, snapshotAccounts);
+    const flowType = calculateFlowType(direction, accountType, counterPartyAccount?.type ?? null);
+    return {
+        flowType,
+        counterPartyAccountId: counterPartyAccount?.id ?? null,
+    };
+}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import type { Manifest } from "document-model";
 export declare const manifest: Manifest;
-export declare const documentModels: (import("document-model").DocumentModelModule<import("./document-models/invoice/index.js").InvoicePHState> | import("document-model").DocumentModelModule<import("./document-models/billing-statement/index.js").BillingStatementPHState> | import("document-model").DocumentModelModule<import("./document-models/integrations/index.js").IntegrationsPHState> | import("document-model").DocumentModelModule<import("./document-models/expense-report/index.js").ExpenseReportPHState>)[];
+export declare const documentModels: (import("document-model").DocumentModelModule<import("./document-models/account-transactions/index.js").AccountTransactionsPHState> | import("document-model").DocumentModelModule<import("./document-models/accounts/index.js").AccountsPHState> | import("document-model").DocumentModelModule<import("./document-models/billing-statement/index.js").BillingStatementPHState> | import("document-model").DocumentModelModule<import("./document-models/expense-report/index.js").ExpenseReportPHState> | import("document-model").DocumentModelModule<import("./document-models/invoice/index.js").InvoicePHState> | import("document-model").DocumentModelModule<import("./document-models/snapshot-report/index.js").SnapshotReportPHState> | import("document-model").DocumentModelModule<import("./document-models/service-subscriptions/index.js").ServiceSubscriptionsPHState> | import("document-model").DocumentModelModule<import("./document-models/service-offering/index.js").ServiceOfferingPHState>)[];
 export declare const editors: import("document-model").EditorModule[];
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAK/C,eAAO,MAAM,QAAQ,EAAE,QAAuB,CAAC;AAC/C,eAAO,MAAM,cAAc,6dAAuC,CAAC;AACnE,eAAO,MAAM,OAAO,yCAAgC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAK/C,eAAO,MAAM,QAAQ,EAAE,QAAuB,CAAC;AAC/C,eAAO,MAAM,cAAc,y9BAAuC,CAAC;AACnE,eAAO,MAAM,OAAO,yCAAgC,CAAC"}

package/dist/powerhouse.manifest.json

@@ -7,6 +7,14 @@
         "url": "https://powerhouse.inc/"
     },
     "documentModels": [
+        {
+            "id": "powerhouse/accounts",
+            "name": "Accounts"
+        },
+        {
+            "id": "powerhouse/account-transactions",
+            "name": "AccountTransactions"
+        },
         {
             "id": "powerhouse/invoice",
             "name": "Invoice"
@@ -15,17 +23,81 @@
             "id": "powerhouse/billing-statement",
             "name": "Billing Statement"
         },
-        {
-            "id": "powerhouse/integrations",
-            "name": "Integrations"
-        },
         {
             "id": "powerhouse/expense-report",
             "name": "ExpenseReport"
+        },
+        {
+            "id": "powerhouse/snapshot-report",
+            "name": "Snapshot Report"
+        },
+        {
+            "id": "powerhouse/service-subscriptions",
+            "name": "ServiceSubscriptions"
+        },
+        {
+            "id": "powerhouse/service-offering",
+            "name": "ServiceOffering"
+        }
+    ],
+    "editors": [
+        {
+            "id": "powerhouse-accounts-editor",
+            "name": "Accounts",
+            "documentTypes": [
+                "powerhouse/accounts"
+            ]
+        },
+        {
+            "id": "powerhouse-account-transactions-editor",
+            "name": "Account Transactions",
+            "documentTypes": [
+                "powerhouse/account-transactions"
+            ]
+        },
+        {
+            "id": "powerhouse-invoice-editor",
+            "name": "Invoice",
+            "documentTypes": [
+                "powerhouse/invoice"
+            ]
+        },
+        {
+            "id": "powerhouse-billing-statement-editor",
+            "name": "Billing Statement",
+            "documentTypes": [
+                "powerhouse/billing-statement"
+            ]
+        },
+        {
+            "id": "powerhouse-expense-report-editor",
+            "name": "Expense Report",
+            "documentTypes": [
+                "powerhouse/expense-report"
+            ]
+        },
+        {
+            "id": "powerhouse-snapshot-report-editor",
+            "name": "Snapshot Report",
+            "documentTypes": [
+                "powerhouse/snapshot-report"
+            ]
+        }
+    ],
+    "apps": [
+        {
+            "id": "contributor-billing",
+            "name": "Contributor Billing",
+            "driveEditor": "contributor-billing"
+        },
+        {
+            "id": "builder-team-admin",
+            "name": "Builder Team Admin",
+            "documentTypes": [
+                "powerhouse/document-drive"
+            ]
         }
     ],
-    "editors": [],
-    "apps": [],
     "subgraphs": [],
     "importScripts": []
 }

package/dist/scripts/alchemy/alchemyClient.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Main Alchemy API client following repository patterns
+ */
+import type { AlchemyResponse, GetAssetTransfersParams, TransactionEntry } from "./alchemyTypes.js";
+export declare class AlchemyClient {
+    private apiKey;
+    private network;
+    private baseURL;
+    constructor(apiKey?: string);
+    /**
+     * Fetch asset transfers using Alchemy's getAssetTransfers method
+     */
+    getAssetTransfers(params: GetAssetTransfersParams): Promise<AlchemyResponse>;
+    /**
+     * Get block timestamp using eth_getBlockByNumber
+     */
+    getBlockTimestamp(blockNumber: string): Promise<number>;
+    /**
+     * Get timestamps for multiple blocks efficiently (batch unique blocks)
+     */
+    getBlockTimestamps(blockNumbers: string[]): Promise<Map<string, number>>;
+    /**
+     * Get formatted transactions ready for document model creation
+     */
+    getFormattedTransactions(address: string, options?: {
+        fromBlock?: string;
+        includeERC20?: boolean;
+        includeExternal?: boolean;
+        includeInternal?: boolean;
+        maxCount?: number;
+    }): Promise<TransactionEntry[]>;
+    /**
+     * Get transactions where the address is the receiver (toAddress)
+     */
+    getTransactionsToAddress(address: string, options?: {
+        fromBlock?: string;
+        includeERC20?: boolean;
+        includeExternal?: boolean;
+        includeInternal?: boolean;
+        maxCount?: number;
+    }): Promise<TransactionEntry[]>;
+    /**
+     * Fetch both outgoing and incoming transactions for an address
+     */
+    getAllTransactionsForAddress(address: string, options?: {
+        fromBlock?: string;
+        includeERC20?: boolean;
+        includeExternal?: boolean;
+        includeInternal?: boolean;
+        maxCount?: number;
+    }): Promise<{
+        transactions: TransactionEntry[];
+        summary: {
+            outgoing: number;
+            incoming: number;
+            unique: number;
+        };
+    }>;
+}
+export declare const alchemyClient: {
+    readonly instance: AlchemyClient;
+};
+//# sourceMappingURL=alchemyClient.d.ts.map

package/dist/scripts/alchemy/alchemyClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alchemyClient.d.ts","sourceRoot":"","sources":["../../../scripts/alchemy/alchemyClient.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACV,eAAe,EAEf,uBAAuB,EAEvB,gBAAgB,EACjB,MAAM,mBAAmB,CAAC;AAS3B,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAAS;gBAEZ,MAAM,CAAC,EAAE,MAAM;IAS3B;;OAEG;IACG,iBAAiB,CACrB,MAAM,EAAE,uBAAuB,GAC9B,OAAO,CAAC,eAAe,CAAC;IAwC3B;;OAEG;IACG,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA2C7D;;OAEG;IACG,kBAAkB,CACtB,YAAY,EAAE,MAAM,EAAE,GACrB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IA4B/B;;OAEG;IACG,wBAAwB,CAC5B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QACP,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;KACd,GACL,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAgE9B;;OAEG;IACG,wBAAwB,CAC5B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QACP,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;KACd,GACL,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAgE9B;;OAEG;IACG,4BAA4B,CAChC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QACP,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;KACd,GACL,OAAO,CAAC;QACT,YAAY,EAAE,gBAAgB,EAAE,CAAC;QACjC,OAAO,EAAE;YAAE,QAAQ,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC;KACjE,CAAC;CAuCH;AAID,eAAO,MAAM,aAAa;uBACR,aAAa;CAM9B,CAAC"}

package/dist/scripts/alchemy/alchemyClient.js

@@ -0,0 +1,232 @@
+/**
+ * Main Alchemy API client following repository patterns
+ */
+import { SUPPORTED_TOKEN_CONTRACTS } from "./alchemyTypes.js";
+import { withRetry, isValidEthereumAddress, convertToTransactionEntry, validateEnvironment, } from "./alchemyHelpers.js";
+export class AlchemyClient {
+    apiKey;
+    network;
+    baseURL;
+    constructor(apiKey) {
+        const env = validateEnvironment();
+        this.apiKey = apiKey || env.apiKey;
+        this.network = env.network;
+        this.baseURL = `https://eth-${this.network}.g.alchemy.com/v2/${this.apiKey}`;
+        console.log(`[AlchemyClient] Initialized for network: ${this.network}`);
+    }
+    /**
+     * Fetch asset transfers using Alchemy's getAssetTransfers method
+     */
+    async getAssetTransfers(params) {
+        return withRetry(async () => {
+            const data = {
+                jsonrpc: "2.0",
+                id: 0,
+                method: "alchemy_getAssetTransfers",
+                params: [params],
+            };
+            const response = await fetch(this.baseURL, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify(data),
+            });
+            if (!response.ok) {
+                throw new Error(`Alchemy API error: ${response.status} - ${response.statusText}`);
+            }
+            const result = (await response.json());
+            if ("error" in result) {
+                throw new Error(`Alchemy RPC error: ${result.error.message}`);
+            }
+            return result;
+        }, 3, 1000, "getAssetTransfers");
+    }
+    /**
+     * Get block timestamp using eth_getBlockByNumber
+     */
+    async getBlockTimestamp(blockNumber) {
+        return withRetry(async () => {
+            const data = {
+                jsonrpc: "2.0",
+                id: 0,
+                method: "eth_getBlockByNumber",
+                params: [blockNumber, false], // false = don't include full transaction objects
+            };
+            const response = await fetch(this.baseURL, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify(data),
+            });
+            if (!response.ok) {
+                throw new Error(`Alchemy API error: ${response.status} - ${response.statusText}`);
+            }
+            const result = (await response.json());
+            if ("error" in result) {
+                throw new Error(`Alchemy RPC error: ${result.error.message}`);
+            }
+            // Convert hex timestamp to number (seconds) then to milliseconds
+            const timestampHex = result.result.timestamp;
+            const timestampSeconds = parseInt(timestampHex, 16);
+            return timestampSeconds * 1000; // Convert to milliseconds
+        }, 3, 1000, `getBlockTimestamp(${blockNumber})`);
+    }
+    /**
+     * Get timestamps for multiple blocks efficiently (batch unique blocks)
+     */
+    async getBlockTimestamps(blockNumbers) {
+        const uniqueBlocks = [...new Set(blockNumbers)];
+        const timestampMap = new Map();
+        // Fetch timestamps for unique blocks in parallel (but limit concurrency)
+        const BATCH_SIZE = 5; // Limit concurrent requests to avoid rate limiting
+        for (let i = 0; i < uniqueBlocks.length; i += BATCH_SIZE) {
+            const batch = uniqueBlocks.slice(i, i + BATCH_SIZE);
+            const promises = batch.map(async (blockNum) => {
+                try {
+                    const timestamp = await this.getBlockTimestamp(blockNum);
+                    timestampMap.set(blockNum, timestamp);
+                }
+                catch (error) {
+                    console.warn(`[AlchemyClient] Failed to fetch timestamp for block ${blockNum}, using current time:`, error.message);
+                    timestampMap.set(blockNum, Date.now());
+                }
+            });
+            await Promise.all(promises);
+        }
+        return timestampMap;
+    }
+    /**
+     * Get formatted transactions ready for document model creation
+     */
+    async getFormattedTransactions(address, options = {}) {
+        if (!isValidEthereumAddress(address)) {
+            throw new Error(`Invalid Ethereum address format: ${address}`);
+        }
+        const { fromBlock = "0x0", includeERC20 = true, includeExternal = true, includeInternal = false, maxCount = 100, } = options;
+        const categories = [];
+        if (includeExternal)
+            categories.push("external");
+        if (includeInternal)
+            categories.push("internal");
+        if (includeERC20)
+            categories.push("erc20");
+        if (categories.length === 0) {
+            throw new Error("At least one transaction category must be included");
+        }
+        const params = {
+            fromBlock,
+            fromAddress: address,
+            category: categories,
+            excludeZeroValue: true,
+            maxCount: `0x${maxCount.toString(16)}`,
+            // Filter to only supported tokens for ERC20 transactions
+            ...(includeERC20 && {
+                contractAddresses: Object.values(SUPPORTED_TOKEN_CONTRACTS),
+            }),
+        };
+        try {
+            const response = await this.getAssetTransfers(params);
+            const transfers = response.result.transfers;
+            // Get block numbers for timestamp fetching
+            const blockNumbers = transfers.map((t) => t.blockNum);
+            const timestampMap = await this.getBlockTimestamps(blockNumbers);
+            // Convert transfers with actual timestamps
+            return transfers.map((transfer) => {
+                const blockTimestamp = timestampMap.get(transfer.blockNum);
+                return convertToTransactionEntry(transfer, address, blockTimestamp);
+            });
+        }
+        catch (error) {
+            console.error(`[AlchemyClient] Failed to fetch transactions for address ${address}:`, error.message);
+            throw new Error(`Failed to fetch transactions: ${error.message}`);
+        }
+    }
+    /**
+     * Get transactions where the address is the receiver (toAddress)
+     */
+    async getTransactionsToAddress(address, options = {}) {
+        if (!isValidEthereumAddress(address)) {
+            throw new Error(`Invalid Ethereum address format: ${address}`);
+        }
+        const { fromBlock = "0x0", includeERC20 = true, includeExternal = true, includeInternal = false, maxCount = 100, } = options;
+        const categories = [];
+        if (includeExternal)
+            categories.push("external");
+        if (includeInternal)
+            categories.push("internal");
+        if (includeERC20)
+            categories.push("erc20");
+        if (categories.length === 0) {
+            throw new Error("At least one transaction category must be included");
+        }
+        const params = {
+            fromBlock,
+            toAddress: address, // Use toAddress instead of fromAddress
+            category: categories,
+            excludeZeroValue: true,
+            maxCount: `0x${maxCount.toString(16)}`,
+            // Filter to only supported tokens for ERC20 transactions
+            ...(includeERC20 && {
+                contractAddresses: Object.values(SUPPORTED_TOKEN_CONTRACTS),
+            }),
+        };
+        try {
+            const response = await this.getAssetTransfers(params);
+            const transfers = response.result.transfers;
+            // Get block numbers for timestamp fetching
+            const blockNumbers = transfers.map((t) => t.blockNum);
+            const timestampMap = await this.getBlockTimestamps(blockNumbers);
+            // Convert transfers with actual timestamps
+            return transfers.map((transfer) => {
+                const blockTimestamp = timestampMap.get(transfer.blockNum);
+                return convertToTransactionEntry(transfer, address, blockTimestamp);
+            });
+        }
+        catch (error) {
+            console.error(`[AlchemyClient] Failed to fetch transactions to address ${address}:`, error.message);
+            throw new Error(`Failed to fetch transactions: ${error.message}`);
+        }
+    }
+    /**
+     * Fetch both outgoing and incoming transactions for an address
+     */
+    async getAllTransactionsForAddress(address, options = {}) {
+        try {
+            // Fetch both outgoing and incoming transactions in parallel
+            const [outgoingTxs, incomingTxs] = await Promise.all([
+                this.getFormattedTransactions(address, options),
+                this.getTransactionsToAddress(address, options),
+            ]);
+            // Combine and deduplicate transactions by uniqueId
+            // Note: uniqueId includes log index, so multiple ERC20 transfers in same txHash are preserved
+            const allTransactions = [...outgoingTxs, ...incomingTxs];
+            const uniqueTransactions = allTransactions.filter((tx, index, self) => index === self.findIndex((t) => t.uniqueId === tx.uniqueId));
+            const summary = {
+                outgoing: outgoingTxs.length,
+                incoming: incomingTxs.length,
+                unique: uniqueTransactions.length,
+            };
+            console.log(`[AlchemyClient] Fetched ${summary.outgoing} outgoing + ${summary.incoming} incoming = ${summary.unique} unique transactions (${allTransactions.length - summary.unique} duplicates removed)`);
+            return {
+                transactions: uniqueTransactions,
+                summary,
+            };
+        }
+        catch (error) {
+            console.error(`[AlchemyClient] Failed to fetch all transactions for address ${address}:`, error.message);
+            throw error;
+        }
+    }
+}
+// Export singleton instance (lazy-loaded to avoid environment variable issues)
+let _alchemyClient = null;
+export const alchemyClient = {
+    get instance() {
+        if (!_alchemyClient) {
+            _alchemyClient = new AlchemyClient();
+        }
+        return _alchemyClient;
+    },
+};

package/dist/scripts/alchemy/alchemyEnvironment.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Environment-aware configuration for Alchemy API integration
+ * Follows the contributor-billing pattern for local/remote compatibility
+ */
+export declare const AlchemyEnvironmentConfig: {
+    endpoint: string;
+    isLocal: boolean;
+    apiKey: string | undefined;
+    network: string;
+    readonly debugInfo: {
+        mode: string;
+        endpoint: string;
+        network: string;
+        hasApiKey: boolean;
+    };
+};
+/**
+ * Get the appropriate GraphQL endpoint based on environment
+ */
+export declare function getAlchemyGraphQLEndpoint(): string;
+/**
+ * Check if we're running in local development mode
+ */
+export declare function isLocalEnvironment(): boolean;
+/**
+ * Log environment information for debugging
+ */
+export declare function logEnvironmentInfo(): void;
+//# sourceMappingURL=alchemyEnvironment.d.ts.map

package/dist/scripts/alchemy/alchemyEnvironment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alchemyEnvironment.d.ts","sourceRoot":"","sources":["../../../scripts/alchemy/alchemyEnvironment.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAeH,eAAO,MAAM,wBAAwB;;;;;;;;;;;CAoBpC,CAAC;AAEF;;GAEG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,CAElD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CAE5C;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}

package/dist/scripts/alchemy/alchemyEnvironment.js

@@ -0,0 +1,49 @@
+/**
+ * Environment-aware configuration for Alchemy API integration
+ * Follows the contributor-billing pattern for local/remote compatibility
+ */
+// Environment detection following the invoice module pattern
+let ALCHEMY_GRAPHQL_URL = "http://localhost:4001/graphql";
+let LOCAL_MODE = true;
+// Check if we're running in a remote environment
+if (typeof window !== "undefined" &&
+    !window.document.baseURI.includes("localhost")) {
+    ALCHEMY_GRAPHQL_URL = "https://switchboard-dev.powerhouse.xyz/graphql";
+    LOCAL_MODE = false;
+}
+export const AlchemyEnvironmentConfig = {
+    endpoint: ALCHEMY_GRAPHQL_URL,
+    isLocal: LOCAL_MODE,
+    // API calls work regardless of document location
+    apiKey: typeof process !== "undefined" ? process.env.ALCHEMY_API_KEY : undefined,
+    network: typeof process !== "undefined"
+        ? process.env.ALCHEMY_NETWORK || "mainnet"
+        : "mainnet",
+    // Debug info
+    get debugInfo() {
+        return {
+            mode: this.isLocal ? "Local Connect" : "Remote Switchboard",
+            endpoint: this.endpoint,
+            network: this.network,
+            hasApiKey: !!this.apiKey,
+        };
+    },
+};
+/**
+ * Get the appropriate GraphQL endpoint based on environment
+ */
+export function getAlchemyGraphQLEndpoint() {
+    return AlchemyEnvironmentConfig.endpoint;
+}
+/**
+ * Check if we're running in local development mode
+ */
+export function isLocalEnvironment() {
+    return AlchemyEnvironmentConfig.isLocal;
+}
+/**
+ * Log environment information for debugging
+ */
+export function logEnvironmentInfo() {
+    console.log("[AlchemyEnvironment]", AlchemyEnvironmentConfig.debugInfo);
+}

package/dist/scripts/alchemy/alchemyHelpers.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Utility functions for Alchemy API integration
+ */
+import type { AlchemyAssetTransfer, TransactionEntry } from "./alchemyTypes.js";
+/**
+ * Retry mechanism with exponential backoff (following gnosis pattern)
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, maxRetries?: number, initialDelay?: number, operationName?: string): Promise<T>;
+/**
+ * Validate Ethereum address format
+ */
+export declare function isValidEthereumAddress(address: string): boolean;
+/**
+ * Convert Alchemy transaction to document model format
+ */
+export declare function convertToTransactionEntry(transfer: AlchemyAssetTransfer, userAddress: string, blockTimestamp?: number): TransactionEntry;
+/**
+ * Validate environment variables
+ */
+export declare function validateEnvironment(): {
+    apiKey: string;
+    network: string;
+};
+//# sourceMappingURL=alchemyHelpers.d.ts.map

package/dist/scripts/alchemy/alchemyHelpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alchemyHelpers.d.ts","sourceRoot":"","sources":["../../../scripts/alchemy/alchemyHelpers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAEhF;;GAEG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,UAAU,SAAI,EACd,YAAY,SAAO,EACnB,aAAa,SAAqB,GACjC,OAAO,CAAC,CAAC,CAAC,CA8BZ;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAE/D;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,oBAAoB,EAC9B,WAAW,EAAE,MAAM,EACnB,cAAc,CAAC,EAAE,MAAM,GACtB,gBAAgB,CA0ElB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CASzE"}