@fastxyz/fast-connector 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fast.xyz
+
+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,115 @@
+# `@fastxyz/fast-connector`
+
+Dapp-facing connector for injected Fast wallets.
+
+## Positioning
+
+- `@fastxyz/sdk` is the low-level Fast client layer, parallel to `viem` or `ethers`
+- `window.fastset` is the injected wallet surface, parallel to `window.ethereum`
+- `@fastxyz/fast-connector` is the app-facing wallet adapter layer, parallel to a wagmi injected connector or an app wrapper around `ethers.BrowserProvider(window.ethereum)`
+
+This package is for browser apps such as InfoFi. It is not for extension-internal wallet logic.
+
+The extension still owns:
+
+- key management
+- permissions and approval UI
+- signing
+- transaction submission
+
+This package owns:
+
+- injected wallet detection
+- adapter typing
+- dapp-facing connection state
+- a reusable app connector over `window.fastset`
+- optional provider-backed reads through `@fastxyz/sdk/browser`
+- high-level transaction helpers over injected wallet methods
+
+## Status
+
+This repo includes:
+
+- injected wallet detection and waiting for `fastset#initialized`
+- connection/account state
+- message signing
+- provider-backed read helpers for balances, tokens, certificates, and explorer URLs
+- high-level `transfer()` and `submitClaim()` wrappers
+- a `@fastxyz/fast-connector/testing` entrypoint for reusable wallet mocks
+
+It intentionally does not own onramp/vendor logic. Swapper, AllSet, and fiat adapters should live in `fast-onramp`.
+
+## Planned Usage
+
+```ts
+import { FastConnector } from '@fastxyz/fast-connector';
+
+const connector = FastConnector.fromInjected(window.fastset);
+await connector.connect();
+
+const account = await connector.exportKeys();
+const signed = await connector.sign({ message: 'hello fast' });
+const balance = await connector.getBalance('FAST');
+const payment = await connector.transfer({
+  recipient: 'fast1...',
+  amount: '0x32',
+});
+const explorerUrl = await connector.getExplorerUrl(payment.txHash);
+```
+
+You can also inject a custom read provider, or let the connector build one from the installed SDK:
+
+```ts
+import { FastConnector } from '@fastxyz/fast-connector';
+
+const connector = FastConnector.fromInjected(window.fastset, {
+  providerOptions: {
+    network: 'mainnet',
+  },
+});
+
+await connector.connect();
+const tokens = await connector.getTokens();
+const network = await connector.getNetwork();
+```
+
+## Testing
+
+`@fastxyz/fast-connector/testing` provides reusable mocks for app and integration tests:
+
+```ts
+import { FastConnector } from '@fastxyz/fast-connector';
+import {
+  createMockAccount,
+  createMockInjectedFastConnector,
+  dispatchFastsetInitialized,
+} from '@fastxyz/fast-connector/testing';
+
+const wallet = createMockInjectedFastConnector();
+window.fastset = wallet;
+dispatchFastsetInitialized(window);
+
+const connector = FastConnector.fromInjected(wallet);
+await connector.connect();
+
+wallet.mock.emitAccountChanged(createMockAccount({
+  publicKey: 'bb'.repeat(32),
+  injected: true,
+}));
+```
+
+The testing entrypoint includes:
+
+- mock injected wallet factory
+- canonical and injected mock accounts
+- mock transfer and claim certificates
+- helpers for `fastset#initialized`
+- helpers for account-change events
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+```

package/dist/client.d.ts

@@ -0,0 +1,48 @@
+import type { FastConnectorAccount, FastConnectorAdapter, FastConnectorConnectOptions, FastConnectorOptions, FastConnectorSubmitClaimParams, FastConnectorSubmitClaimResult, FastConnectorTransferParams, FastConnectorTransferResult } from './types.js';
+export declare function getInjectedFastConnector(): FastConnectorAdapter | undefined;
+export declare function waitForInjectedFastConnector(timeoutMs?: number): Promise<FastConnectorAdapter | undefined>;
+export declare class FastConnector {
+    private readonly adapter;
+    private readonly customProvider?;
+    private provider?;
+    private providerNetworkKey?;
+    private readonly providerOptions?;
+    private accounts;
+    private locallyDisconnected;
+    private constructor();
+    static fromInjected(injected?: FastConnectorAdapter | undefined, options?: FastConnectorOptions): FastConnector;
+    getNetwork(): Promise<string>;
+    get address(): string | null;
+    connect(options?: FastConnectorConnectOptions): Promise<boolean>;
+    disconnect(): Promise<boolean>;
+    isConnected(): boolean;
+    getAccounts(): Promise<FastConnectorAccount[]>;
+    getActiveNetwork(): Promise<string>;
+    onAccountChanged(callback: (account: FastConnectorAccount) => void): () => void;
+    exportKeys(): Promise<FastConnectorAccount>;
+    sign(params: {
+        message: string | Uint8Array;
+    }): Promise<{
+        signature: string;
+        address: string;
+        messageBytes: string;
+    }>;
+    transfer(params: FastConnectorTransferParams): Promise<FastConnectorTransferResult>;
+    submitClaim(params: FastConnectorSubmitClaimParams): Promise<FastConnectorSubmitClaimResult>;
+    getBalance(token?: string): Promise<{
+        amount: string;
+        token: string;
+    }>;
+    getTokens(): Promise<import("@fastxyz/sdk/core").TokenBalance[]>;
+    getTokenInfo(token: string): Promise<import("@fastxyz/sdk/core").TokenInfo | null>;
+    getCertificateByNonce(nonce: number): Promise<import("@fastxyz/sdk/core").FastTransactionCertificate | null>;
+    getExplorerUrl(txHash?: string): Promise<string | null>;
+    private captureTransactionFreshness;
+    private assertFreshTransaction;
+    private getExplorerUrlSafe;
+    private requireAccount;
+    private resolveTransferTokenId;
+    private resolveProviderNetwork;
+    private requireProvider;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EACV,oBAAoB,EACpB,oBAAoB,EACpB,2BAA2B,EAE3B,oBAAoB,EAGpB,8BAA8B,EAC9B,8BAA8B,EAE9B,2BAA2B,EAC3B,2BAA2B,EAC5B,MAAM,YAAY,CAAC;AAgTpB,wBAAgB,wBAAwB,IAAI,oBAAoB,GAAG,SAAS,CAE3E;AAED,wBAAsB,4BAA4B,CAAC,SAAS,SAAO,GAAG,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CAyB9G;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;IAC/C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAA4B;IAC5D,OAAO,CAAC,QAAQ,CAAC,CAA4B;IAC7C,OAAO,CAAC,kBAAkB,CAAC,CAAgB;IAC3C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAA+B;IAChE,OAAO,CAAC,QAAQ,CAA8B;IAC9C,OAAO,CAAC,mBAAmB,CAAS;IAEpC,OAAO;IAOP,MAAM,CAAC,YAAY,CACjB,QAAQ,GAAE,oBAAoB,GAAG,SAAsC,EACvE,OAAO,CAAC,EAAE,oBAAoB,GAC7B,aAAa;IAQV,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;IAInC,IAAI,OAAO,IAAI,MAAM,GAAG,IAAI,CAM3B;IAEK,OAAO,CAAC,OAAO,CAAC,EAAE,2BAA2B,GAAG,OAAO,CAAC,OAAO,CAAC;IAchE,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC;IASpC,WAAW,IAAI,OAAO;IAWhB,WAAW,IAAI,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAgB9C,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC;IAQzC,gBAAgB,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,IAAI,GAAG,MAAM,IAAI;IA2BzE,UAAU,IAAI,OAAO,CAAC,oBAAoB,CAAC;IAQ3C,IAAI,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,GAAG,UAAU,CAAA;KAAE,GAAG,OAAO,CAAC;QAC5D,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;QAChB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IAmBI,QAAQ,CAAC,MAAM,EAAE,2BAA2B,GAAG,OAAO,CAAC,2BAA2B,CAAC;IAsDnF,WAAW,CAAC,MAAM,EAAE,8BAA8B,GAAG,OAAO,CAAC,8BAA8B,CAAC;IAoE5F,UAAU,CAAC,KAAK,SAAS,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAKtE,SAAS;IAKT,YAAY,CAAC,KAAK,EAAE,MAAM;IAI1B,qBAAqB,CAAC,KAAK,EAAE,MAAM;IAKnC,cAAc,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;YAI/C,2BAA2B;IAsBzC,OAAO,CAAC,sBAAsB;YAgBhB,kBAAkB;YAQlB,cAAc;YAiBd,sBAAsB;YAyCtB,sBAAsB;YAqCtB,eAAe;CAmB9B"}