@longdotxyz/shared 0.0.11 → 0.0.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@longdotxyz/shared",
-  "version": "0.0.11",
+  "version": "0.0.12",
   "description": "Shared types and utilities for Long.xyz API",
   "files": [
     "dist"

package/readme.md

@@ -1 +1,291 @@
-# Long.xyz Platform Shared Library
+# @longdotxyz/shared
+
+Shared TypeScript library for Long.xyz API containing GraphQL types, REST API contracts, and utilities.
+
+## Installation
+
+```bash
+npm install @longdotxyz/shared
+# or
+pnpm add @longdotxyz/shared
+```
+
+## Features
+
+- **GraphQL Types & SDK**: Auto-generated types and SDK client from GraphQL schema
+- **REST API Contracts**: Type-safe API contracts built with [ts-rest](https://ts-rest.com)
+- **Type Utilities**: Common types for blockchain addresses, pool keys, and more
+- **Utilities**: Helper functions for native token handling
+
+## GraphQL Types and SDK
+
+The library includes auto-generated GraphQL types and a ready-to-use SDK client.
+
+### Basic Setup
+
+```typescript
+import { GraphQLClient } from 'graphql-request';
+import { getSdk } from '@longdotxyz/shared';
+
+// Initialize GraphQL client
+const client = new GraphQLClient('https://graphql.long.xyz');
+
+// Create SDK instance
+const sdk = getSdk(client);
+```
+
+### Example: Fetch Auction by Address
+
+```typescript
+import { getSdk, GetAuctionByAddressQuery } from '@longdotxyz/shared';
+
+// Query an auction
+const { auction_pool } = await sdk.GetAuctionByAddress({
+  address: '0x123...'
+});
+
+// Type-safe access to auction data
+if (auction_pool) {
+  console.log(auction_pool.auction_pool_address);
+  console.log(auction_pool.asset_address);
+  console.log(auction_pool.numeraire_address);
+}
+```
+
+### Available GraphQL Types
+
+```typescript
+import type {
+  Asset,
+  AuctionPool,
+  GraduationPool,
+  Asset_Bool_Exp,
+  Asset_Order_By
+} from '@longdotxyz/shared';
+
+// Use types for type-safe queries
+const assetFilter: Asset_Bool_Exp = {
+  chain_id: { _eq: 1 },
+  asset_address: { _ilike: '0x%' }
+};
+```
+
+## REST API Client (ts-rest)
+
+The library provides type-safe REST API contracts using [ts-rest](https://ts-rest.com/client/fetch).
+
+### Initialize API Client
+
+```typescript
+import { initClient } from '@ts-rest/core';
+import { rootContract } from '@longdotxyz/shared';
+
+// Create typed API client
+const apiClient = initClient(rootContract, {
+  baseUrl: 'https://api.long.xyz',
+  baseHeaders: {
+    'Content-Type': 'application/json'
+  }
+});
+```
+
+### Auction Endpoints
+
+```typescript
+// Get dynamic auction details
+const auctionResponse = await apiClient.auctions.getDynamicAuction({
+  params: {
+    address: '0x123...'
+  }
+});
+
+if (auctionResponse.status === 200) {
+  const { auction_pool_address, auction_base_token_symbol } = auctionResponse.body.result;
+  console.log(`Pool: ${auction_pool_address}, Symbol: ${auction_base_token_symbol}`);
+}
+
+// Create dynamic auction
+const createResponse = await apiClient.auctions.createDynamicAuction({
+  body: {
+    chainId: 8453, // Base
+    integrator: '0xabc...',
+    initial_supply: '1000000000000000000000000',
+    num_tokens_to_sell: '500000000000000000000000',
+    numeraire: '0xdef...'
+    // ... other params
+  }
+});
+```
+
+### Quote Endpoints (Uniswap V3/V4)
+
+```typescript
+// V4 Exact Input Quote
+const v4Quote = await apiClient.quotes.v4ExactInputSingle({
+  body: {
+    chainId: 8453,
+    poolKey: {
+      currency0: '0x0000000000000000000000000000000000000000', // ETH
+      currency1: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // USDC
+      fee: 500,
+      tickSpacing: 10,
+      hooks: '0x0000000000000000000000000000000000000000'
+    },
+    zeroForOne: true,
+    exactAmount: '1000000000000000000' // 1 ETH
+  }
+});
+
+if (v4Quote.status === 200) {
+  console.log(`Output amount: ${v4Quote.body.result.amountOut}`);
+  console.log(`Gas estimate: ${v4Quote.body.result.gasEstimate}`);
+}
+
+// V3 Exact Output Quote
+const v3Quote = await apiClient.quotes.v3ExactOutputSingle({
+  body: {
+    chainId: 1,
+    tokenIn: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', // WETH
+    tokenOut: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC
+    amountOut: '1000000000', // 1000 USDC
+    fee: 500 // 0.05%
+  }
+});
+
+if (v3Quote.status === 200) {
+  console.log(`Input required: ${v3Quote.body.result.amountIn}`);
+}
+```
+
+### Community Endpoints
+
+```typescript
+// Fetch all communities
+const communities = await apiClient.communities.fetchCommunities();
+
+if (communities.status === 200) {
+  communities.body.result.forEach(community => {
+    console.log(`${community.label}: ${community.description}`);
+    console.log(`Funding: ${community.funding_amount}`);
+  });
+}
+
+// Get specific community
+const community = await apiClient.communities.getCommunity({
+  params: { id: 1 }
+});
+```
+
+### IPFS Endpoints
+
+```typescript
+// Create IPFS content
+const ipfsResult = await apiClient.ipfs.createFile({
+  body: {
+    name: 'Token Metadata',
+    description: 'My awesome token',
+    image: 'https://example.com/image.png',
+    animation_url: 'https://example.com/animation.mp4',
+    content: {
+      customField: 'value'
+    }
+  }
+});
+
+if (ipfsResult.status === 200) {
+  console.log(`IPFS hash: ${ipfsResult.body.ipfsHash}`);
+  console.log(`Gateway URL: ${ipfsResult.body.url}`);
+}
+```
+
+## Type Utilities
+
+### Pool Key Type (Uniswap V4)
+
+```typescript
+import { PoolKey } from '@longdotxyz/shared';
+
+const poolKey: PoolKey = {
+  currency0: '0x0000000000000000000000000000000000000000',
+  currency1: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+  fee: 500,
+  tickSpacing: 10,
+  hooks: '0x0000000000000000000000000000000000000000'
+};
+```
+
+### Hex Address Validation
+
+```typescript
+import { hex } from '@longdotxyz/shared';
+import { z } from 'zod';
+
+// Validate and normalize hex addresses
+const addressSchema = z.string().pipe(hex);
+const validAddress = addressSchema.parse('0xabc...'); // Returns lowercase hex
+```
+
+### BigInt Coercion
+
+```typescript
+import { coerceBigInt } from '@longdotxyz/shared';
+
+const amount = coerceBigInt.parse('1000000000000000000'); // Returns bigint
+const amount2 = coerceBigInt.parse(1000n); // Also accepts bigint
+```
+
+## Native Token Utilities
+
+```typescript
+import { isNativeToken, isNativeTokenAddress } from '@longdotxyz/shared';
+
+// Check if address is native token (ETH)
+isNativeTokenAddress('0x0000000000000000000000000000000000000000'); // true
+isNativeTokenAddress('0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE'); // true
+
+// Check token object
+isNativeToken({
+  address: '0x0000000000000000000000000000000000000000',
+  symbol: 'ETH'
+}); // true
+```
+
+## Development
+
+### Building the Library
+
+```bash
+# Generate GraphQL types
+pnpm codegen
+
+# Build TypeScript
+pnpm build
+
+# Run tests
+pnpm test
+
+# Format and lint
+pnpm format
+pnpm lint
+```
+
+### GraphQL Code Generation
+
+The GraphQL types are generated from a schema using `@graphql-codegen`. Configuration is in `codegen.ts`.
+
+```bash
+pnpm codegen
+```
+
+## API Contract Structure
+
+All API contracts are defined using ts-rest and exported from `@longdotxyz/shared/contracts`:
+
+- **Auctions**: `/auctions/*` - Dynamic auction creation and management
+- **Quotes**: `/quotes/*` - Uniswap V3/V4 swap quotes
+- **Communities**: `/communities/*` - Community data management
+- **IPFS**: `/ipfs/*` - IPFS content creation
+
+## License
+
+UNLICENSED