@txwallet/graz-connector 0.1.0

package/README.md

@@ -0,0 +1,205 @@
+# @txwallet/graz-connector
+
+Thin-slice TX Wallet compatibility connector for Graz-oriented Cosmos integrations.
+
+Ownership note: this package is an adapter layer. The TX Wallet Auth protocol remains the source of truth for request IDs, payload verification, callback policy, and approval outcomes.
+
+This package is the first implementation rail only:
+
+- connect
+- account and chain context
+- ADR-36 sign-in result path
+- typed transaction-request launch path for approved payment lanes
+
+It does not claim full Keplr or Leap parity.
+
+Partner rollout checklist: see `TX_WALLET_GRAZ_PARTNER_QUICKSTART.md` in the repo root for the end-to-end thin-slice handoff flow.
+
+## Install
+
+```bash
+npm install @txwallet/graz-connector
+```
+
+## Minimal usage
+
+```js
+import { createTxWalletGrazConnector } from '@txwallet/graz-connector';
+
+const connector = createTxWalletGrazConnector({
+  handlers: {
+    connect: async ({ chainId, appId, callbackUrl }) => {
+      // map into existing TX Wallet connect/request rails
+      return {
+        accountAddress: 'core1example...',
+        chainId,
+      };
+    },
+    signAdr36: async ({ appId, requestId, callbackUrl, challenge }) => {
+      // map into existing TX Wallet sign-in approval flow
+      return {
+        status: 'approved',
+        requestId,
+        signature: {
+          pubKey: 'A1B2...',
+          signature: 'MEQC...',
+          signed: challenge,
+        },
+      };
+    },
+    disconnect: async () => {
+      // clear session state only
+    },
+  },
+});
+
+await connector.connect({
+  chainId: 'coreum-mainnet-1',
+  appId: 'txapp_01JZ8S3J9M3N7Q2K5R9V6X4H1A',
+  callbackUrl: 'https://partner.example.com/tx-wallet/callback',
+});
+
+const account = await connector.getAccount();
+```
+
+## Live TX Wallet Auth-backed usage
+
+Use the built-in handlers when you want this connector to call your existing TX Wallet Auth endpoints directly.
+
+```js
+import {
+  createTxWalletGrazAuthConnector,
+} from '@txwallet/graz-connector';
+
+const connector = createTxWalletGrazAuthConnector({
+  requestOrigin: window.location.origin,
+  walletBaseUrl: 'https://txwallet.tesbert.com',
+  supportedChains: ['coreum-mainnet-1', 'coreum-testnet-1'],
+});
+
+await connector.connect({
+  chainId: 'coreum-mainnet-1',
+  appId: 'txapp_01JZ8S3J9M3N7Q2K5R9V6X4H1A',
+  callbackUrl: 'https://partner.example.com/tx-wallet/callback',
+  statement: 'Connect with TX Wallet',
+});
+
+const signResult = await connector.signAdr36({
+  appId: 'txapp_01JZ8S3J9M3N7Q2K5R9V6X4H1A',
+  callbackUrl: 'https://partner.example.com/tx-wallet/callback',
+  challenge: {
+    statement: 'Sign in with TX Wallet.',
+  },
+});
+
+console.log(signResult.status, signResult.requestId);
+```
+
+Notes:
+
+- `connect()` creates and polls a standard sign-in request and returns normalized account context.
+- `signAdr36()` uses the same approval rail and returns approved/rejected/failed terminal status.
+- If your backend already created a sign-in request, pass `requestId` to `signAdr36()`.
+- Unknown `chainId` values now fail fast with `UNSUPPORTED_CHAIN` before network calls. Override allowed chains with `supportedChains` when needed.
+- Callback and status URL origins are enforced against `requestOrigin`; mismatches fail fast with `CALLBACK_ORIGIN_MISMATCH` before network calls.
+- Fallback handoff URLs are enforced against the configured `walletBaseUrl` origin; mismatches fail fast with `CALLBACK_ORIGIN_MISMATCH` before opening a wallet window.
+- Status payload `request_id` values are integrity-checked against the expected request id; mismatches fail with `REQUEST_FAILED` to prevent cross-request result confusion.
+
+## React / Graz hook usage
+
+Graz is hooks-first, so `@txwallet/graz-connector/react` ships a `useTxWalletGrazConnector` hook with graz-style ergonomics. Pass auth-handler options (a connector is built once on mount) or an existing connector instance. `react` is an optional peer dependency.
+
+```tsx
+import { useTxWalletGrazConnector } from '@txwallet/graz-connector/react';
+
+function ConnectTxWallet() {
+  const { connect, signAdr36, disconnect, account, error, isConnecting, isConnected } =
+    useTxWalletGrazConnector({
+      requestOrigin: window.location.origin,
+      walletBaseUrl: 'https://txwallet.tesbert.com',
+    });
+
+  if (isConnected) {
+    return (
+      <div>
+        <p>Connected: {account?.accountAddress}</p>
+        <button onClick={() => signAdr36({
+          appId: 'txapp_01JZ8S3J9M3N7Q2K5R9V6X4H1A',
+          callbackUrl: 'https://partner.example.com/tx-wallet/callback',
+          challenge: { statement: 'Sign in with TX Wallet.' },
+        })}>Sign in</button>
+        <button onClick={() => disconnect()}>Disconnect</button>
+      </div>
+    );
+  }
+
+  return (
+    <button
+      disabled={isConnecting}
+      onClick={() => connect({
+        chainId: 'coreum-mainnet-1',
+        appId: 'txapp_01JZ8S3J9M3N7Q2K5R9V6X4H1A',
+        callbackUrl: 'https://partner.example.com/tx-wallet/callback',
+      })}
+    >
+      {isConnecting ? 'Connecting…' : 'Connect TX Wallet'}{error ? ` — ${error.code}` : ''}
+    </button>
+  );
+}
+```
+
+Hook actions are fire-and-forget safe (failures surface through `error`/`status`, no unhandled rejections); use the returned `connector` directly when you need the raw awaitable/throwing calls.
+
+## Transaction Requests
+
+Use the transaction-request handlers when Graz-oriented integrations need to launch a typed TX Wallet Request instead of an ADR-36 sign-in.
+
+```js
+import { createTxWalletGrazTransactionConnector } from '@txwallet/graz-connector';
+
+const connector = createTxWalletGrazTransactionConnector({
+  requestOrigin: window.location.origin,
+  walletBaseUrl: 'https://txwallet.tesbert.com',
+});
+
+const result = await connector.requestTransaction({
+  appId: 'txapp_01JZ8S3J9M3N7Q2K5R9V6X4H1A',
+  callbackUrl: 'https://partner.example.com/tx-wallet/callback',
+  chainId: 'coreum-mainnet-1',
+  body: {
+    category: 'token_payment',
+    payer: 'core1payer...',
+    recipient: 'core1recipient...',
+    amount: '1',
+  },
+});
+
+console.log(result.status, result.txHash);
+```
+
+For partners that already assemble the request envelope themselves, `requestTransaction()` also accepts prebuilt `requestId`, `statusUrl`, and `fallbackUrl` values.
+
+Transaction support in this adapter is intentionally focused on the approved payment lanes. Keep checkout/payment mainnet lanes behind the existing app and rollout switches, and do not use the connector as a blind-signing surface.
+- `requestTransaction()` launches and polls a typed TX Wallet Request and returns the final request status.
+- The connector emits a request result through the same connector state machine, but the request rail is still separate from ADR-36 sign-in.
+- Review-only categories are blocked by default in the transaction handlers to prevent accidental production onboarding mistakes; use `allowReviewOnly: true` only for explicit review-fixture workflows.
+
+## Error behavior
+
+Expected stable error code buckets include:
+
+- `WALLET_LOCKED`
+- `NO_ACTIVE_ACCOUNT`
+- `UNSUPPORTED_CHAIN`
+- `REQUEST_EXPIRED`
+- `CALLBACK_ORIGIN_MISMATCH`
+- `USER_REJECTED`
+- `REQUEST_FAILED`
+- `NETWORK_ERROR`
+- `INTERNAL_ERROR`
+
+## Boundary
+
+Use this adapter as a compatibility bridge into existing TX Wallet Auth rails.
+Treat TX Wallet protocol docs and server/client rails as authoritative behavior.
+Do not bypass approval UI, policy checks, or request validation.

package/index.d.ts

@@ -0,0 +1,152 @@
+export const TX_WALLET_GRAZ_CONNECTOR_VERSION: '0.1.0';
+export const TX_WALLET_GRAZ_DEFAULT_SIGNIN_CREATE_ENDPOINT: '/api/tx-wallet/signin/requests';
+export const TX_WALLET_GRAZ_DEFAULT_TRANSACTION_CREATE_ENDPOINT: '/api/tx-wallet/requests';
+
+export interface TxWalletGrazConnectedAccount {
+  accountAddress: string;
+  chainId: string;
+  walletName: 'TX Wallet';
+}
+
+export interface TxWalletGrazAccount {
+  accountAddress: string;
+  chainId: string;
+}
+
+export interface TxWalletGrazSignResult {
+  status: 'approved' | 'rejected' | 'failed';
+  requestId: string;
+  txWalletResultUrl?: string;
+  signature?: {
+    pubKey: string;
+    signature: string;
+    signed: Record<string, unknown>;
+  };
+  error?: {
+    code: string;
+    message: string;
+  };
+}
+
+export interface TxWalletGrazTransactionResult {
+  status: 'broadcasted' | 'confirmed' | 'rejected' | 'failed' | 'expired' | 'unsupported' | 'invalid' | 'error';
+  requestId: string;
+  txWalletResultUrl?: string;
+  receiptUrl?: string;
+  txHash?: string;
+  receipt?: Record<string, unknown>;
+  error?: unknown;
+}
+
+export interface TxWalletGrazHandlers {
+  connect?: (input: {
+    chainId: string;
+    appId: string;
+    callbackUrl: string;
+    statement?: string;
+  }) => Promise<TxWalletGrazConnectedAccount | { accountAddress: string; chainId: string }>;
+  signAdr36?: (input: {
+    appId: string;
+    requestId?: string;
+    callbackUrl: string;
+    challenge?: Record<string, unknown>;
+  }) => Promise<TxWalletGrazSignResult>;
+  requestTransaction?: (input: {
+    appId: string;
+    requestId?: string;
+    callbackUrl: string;
+    chainId?: string;
+    body?: Record<string, unknown>;
+    statusUrl?: string;
+    fallbackUrl?: string;
+  }) => Promise<TxWalletGrazTransactionResult>;
+  disconnect?: () => Promise<void>;
+}
+
+export interface TxWalletGrazAuthHandlerOptions {
+  fetchImpl?: typeof fetch;
+  requestOrigin?: string;
+  createEndpoint?: string;
+  walletBaseUrl?: string;
+  credentials?: RequestCredentials;
+  pollIntervalMs?: number;
+  pollTimeoutMs?: number;
+  openWallet?: (fallbackUrl: string) => unknown;
+  supportedChains?: string[];
+}
+
+export interface TxWalletGrazConnectorOptions {
+  handlers?: TxWalletGrazHandlers;
+  initialChainId?: string;
+}
+
+export class TxWalletGrazConnectorError extends Error {
+  code: string;
+  details?: unknown;
+  cause?: unknown;
+  constructor(message: string, options?: { code?: string; details?: unknown; cause?: unknown });
+}
+
+export class TxWalletGrazConnector {
+  state: 'idle' | 'connecting' | 'connected' | 'signing' | 'requesting' | 'error' | 'disconnected';
+  chainId: string;
+  accountAddress: string;
+  constructor(options?: TxWalletGrazConnectorOptions);
+  on(eventName: string, listener: (detail: unknown) => void): () => void;
+  off(eventName: string, listener: (detail: unknown) => void): void;
+  emit(eventName: string, detail: unknown): void;
+  setState(nextState: TxWalletGrazConnector['state']): void;
+  getState(): TxWalletGrazConnector['state'];
+  getSupportedSignStatuses(): Array<'approved' | 'rejected' | 'failed'>;
+  connect(input: { chainId: string; appId: string; callbackUrl: string; statement?: string }): Promise<TxWalletGrazConnectedAccount>;
+  getAccount(): Promise<TxWalletGrazAccount>;
+  signAdr36(input: {
+    appId: string;
+    requestId?: string;
+    callbackUrl: string;
+    challenge?: Record<string, unknown>;
+  }): Promise<TxWalletGrazSignResult>;
+  disconnect(): Promise<void>;
+  getSupportedRequestStatuses(): Array<'broadcasted' | 'confirmed' | 'rejected' | 'failed' | 'expired' | 'unsupported' | 'invalid' | 'error'>;
+  requestTransaction(input: {
+    appId: string;
+    requestId?: string;
+    callbackUrl: string;
+    chainId?: string;
+    body?: Record<string, unknown>;
+    statusUrl?: string;
+    fallbackUrl?: string;
+  }): Promise<TxWalletGrazTransactionResult>;
+  launchRequest(input: {
+    appId: string;
+    requestId?: string;
+    callbackUrl: string;
+    chainId?: string;
+    body?: Record<string, unknown>;
+    statusUrl?: string;
+    fallbackUrl?: string;
+  }): Promise<TxWalletGrazTransactionResult>;
+}
+
+export function createTxWalletGrazConnector(options?: TxWalletGrazConnectorOptions): TxWalletGrazConnector;
+export function createTxWalletGrazAuthHandlers(options?: TxWalletGrazAuthHandlerOptions): TxWalletGrazHandlers;
+export function createTxWalletGrazAuthConnector(
+  options?: TxWalletGrazAuthHandlerOptions & { initialChainId?: string }
+): TxWalletGrazConnector;
+export function createTxWalletGrazTransactionHandlers(options?: TxWalletGrazTransactionHandlerOptions): TxWalletGrazHandlers;
+export function createTxWalletGrazTransactionConnector(
+  options?: TxWalletGrazTransactionHandlerOptions & { initialChainId?: string }
+): TxWalletGrazConnector;
+
+export interface TxWalletGrazTransactionHandlerOptions {
+  fetchImpl?: typeof fetch;
+  requestOrigin?: string;
+  createEndpoint?: string;
+  walletBaseUrl?: string;
+  credentials?: RequestCredentials;
+  pollIntervalMs?: number;
+  pollTimeoutMs?: number;
+  openWallet?: (fallbackUrl: string) => unknown;
+  allowReviewOnly?: boolean;
+  supportedChains?: string[];
+}