@0xslots/sdk 0.5.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +44 -167
  2. package/dist/index.d.ts +530 -27
  3. package/dist/index.js +375 -9
  4. package/dist/index.js.map +1 -1
  5. package/package.json +7 -3
package/README.md CHANGED
@@ -1,199 +1,76 @@
1
1
  # @0xslots/sdk
2
2
 
3
- Type-safe SDK for querying 0xSlots subgraph data with full TypeScript support.
3
+ Unified SDK for the 0xSlots protocol — subgraph reads + on-chain writes with ERC-20 approval handling and EIP-5792 atomic batch support.
4
4
 
5
- ## Features
6
-
7
- - 🔒 **Fully typed** - Generated from GraphQL schema with complete type safety
8
- - 🚀 **Chain support** - Easy chain selection (Base Sepolia, more coming)
9
- - 📦 **Tree-shakeable** - ESM exports with optimized bundle size
10
- - 🎯 **Easy to use** - Simple, intuitive API
11
-
12
- ## Installation
5
+ ## Install
13
6
 
14
7
  ```bash
15
- npm install @0xslots/sdk
16
- # or
17
- pnpm add @0xslots/sdk
18
- # or
19
- yarn add @0xslots/sdk
20
- ```
21
-
22
- ## Quick Start
23
-
24
- ```typescript
25
- import { createSlotsClient, SlotsChain } from '@0xslots/sdk';
26
-
27
- // Create a client for Base Sepolia
28
- const client = createSlotsClient({
29
- chainId: SlotsChain.BASE_SEPOLIA,
30
- });
31
-
32
- // Query the hub
33
- const hub = await client.getHub({
34
- id: '0x268cfaB9ddDdF6A326458Ae79d55592516f382eF',
35
- });
36
-
37
- console.log('Hub slot price:', hub.hub?.slotPrice);
8
+ pnpm add @0xslots/sdk viem
38
9
  ```
39
10
 
40
- ## Usage Examples
11
+ ## Usage
41
12
 
42
- ### Query Lands
13
+ ### Read-only (subgraph)
43
14
 
44
- ```typescript
45
- // Get all lands
46
- const { lands } = await client.getLands({
47
- first: 10,
48
- orderBy: 'createdAt',
49
- orderDirection: 'desc',
50
- });
15
+ ```ts
16
+ import { createSlotsClient, SlotsChain } from "@0xslots/sdk";
51
17
 
52
- // Get lands by owner
53
- const { lands: myLands } = await client.getLandsByOwner({
54
- owner: '0x...',
55
- first: 100,
56
- });
18
+ const client = createSlotsClient({ chainId: SlotsChain.BASE_SEPOLIA });
57
19
 
58
- // Get a specific land with slots
59
- const { land } = await client.getLand({
60
- id: '0x...',
61
- });
20
+ const { slots } = await client.getSlots({ first: 10 });
21
+ const { slot } = await client.getSlot({ id: "0x..." });
62
22
  ```
63
23
 
64
- ### Query Slots
65
-
66
- ```typescript
67
- // Get all active slots
68
- const { slots } = await client.getSlots({
69
- where: { active: true },
70
- first: 50,
71
- orderBy: 'price',
72
- orderDirection: 'asc',
73
- });
74
-
75
- // Get available (vacant) slots
76
- const { slots: available } = await client.getAvailableSlots({
77
- first: 20,
78
- });
79
-
80
- // Get slots owned by an address
81
- const { slots: mySlots } = await client.getSlotsByOccupant({
82
- occupant: '0x...',
83
- });
24
+ ### Read + Write
84
25
 
85
- // Get slot details with history
86
- const { slot } = await client.getSlot({
87
- id: '0x...-0',
88
- });
89
-
90
- console.log('Price history:', slot?.priceHistory);
91
- console.log('Tax updates:', slot?.taxUpdates);
92
- ```
26
+ ```ts
27
+ import { createSlotsClient, SlotsChain } from "@0xslots/sdk";
93
28
 
94
- ### Query Events
95
-
96
- ```typescript
97
- // Get recent slot purchases
98
- const { slotPurchases } = await client.getSlotPurchases({
99
- first: 50,
100
- orderBy: 'timestamp',
101
- orderDirection: 'desc',
102
- });
103
-
104
- // Get land creation events
105
- const { landOpenedEvents } = await client.getLandOpenedEvents({
106
- first: 10,
107
- orderBy: 'timestamp',
108
- orderDirection: 'desc',
109
- });
110
-
111
- // Get flow changes (Superfluid streams)
112
- const { flowChanges } = await client.getFlowChanges({
113
- where: { from: '0x...' },
114
- first: 100,
115
- });
116
- ```
117
-
118
- ### Advanced Usage
119
-
120
- ```typescript
121
- // Use custom subgraph URL
122
29
  const client = createSlotsClient({
123
30
  chainId: SlotsChain.BASE_SEPOLIA,
124
- subgraphUrl: 'https://your-custom-endpoint.com/graphql',
31
+ factoryAddress: "0x...",
32
+ publicClient, // viem PublicClient
33
+ walletClient, // viem WalletClient
125
34
  });
126
35
 
127
- // Access the underlying SDK for more control
128
- const sdk = client.getSdk();
36
+ // Buy handles ERC-20 approval automatically
37
+ await client.buy({ slot: "0x...", depositAmount: 1000000n, selfAssessedPrice: 5000000n });
129
38
 
130
- // Access the GraphQL client directly
131
- const graphqlClient = client.getClient();
39
+ await client.topUp("0x...", 500000n);
40
+ await client.release("0x...");
41
+ await client.collect("0x...");
132
42
  ```
133
43
 
134
- ## Supported Chains
44
+ ## API
135
45
 
136
- | Chain | Chain ID | Status |
137
- |-------|----------|--------|
138
- | Base Sepolia | 84532 | ✅ Live |
46
+ ### Subgraph Queries
139
47
 
140
- More chains coming soon!
48
+ `getSlots`, `getSlot`, `getSlotsByRecipient`, `getSlotsByOccupant`, `getFactory`, `getModules`, `getAccounts`, `getAccount`, `getSlotActivity`, `getRecentEvents`, `getBoughtEvents`, `getReleasedEvents`, `getLiquidatedEvents`, `getSettledEvents`, `getTaxCollectedEvents`, `getDepositedEvents`, `getWithdrawnEvents`, `getPriceUpdatedEvents`, `getMeta`
141
49
 
142
- ## Type Safety
50
+ ### On-chain Reads
143
51
 
144
- All queries return fully typed responses:
52
+ `getSlotInfo(slot)` — full slot state via RPC
145
53
 
146
- ```typescript
147
- import type { GetSlotQuery, Slot } from '@0xslots/sdk';
148
-
149
- // Response types are automatically inferred
150
- const response: GetSlotQuery = await client.getSlot({ id: '0x...' });
151
-
152
- // Extract specific types
153
- const slot: Slot | null = response.slot;
154
- ```
54
+ ### Writes (require `walletClient` + `publicClient`)
155
55
 
156
- ## API Reference
56
+ | Method | Description |
57
+ |--------|-------------|
58
+ | `createSlot(params)` | Deploy a new slot via factory |
59
+ | `createSlots(params)` | Deploy multiple slots |
60
+ | `buy(params)` | Buy or force-buy a slot (auto-approves ERC-20) |
61
+ | `topUp(slot, amount)` | Add to deposit (auto-approves ERC-20) |
62
+ | `withdraw(slot, amount)` | Withdraw from deposit |
63
+ | `selfAssess(slot, price)` | Set self-assessed price |
64
+ | `release(slot)` | Release slot, reclaim deposit |
65
+ | `collect(slot)` | Flush accumulated tax to recipient |
66
+ | `liquidate(slot)` | Liquidate insolvent slot |
67
+ | `proposeTaxUpdate(slot, pct)` | Propose new tax rate (manager) |
68
+ | `proposeModuleUpdate(slot, module)` | Propose new module (manager) |
69
+ | `cancelPendingUpdates(slot)` | Cancel pending proposals (manager) |
70
+ | `setLiquidationBounty(slot, bps)` | Set liquidation bounty (manager) |
71
+ | `multicall(slot, calls)` | Batch multiple slot calls |
157
72
 
158
- ### SlotsClient
159
-
160
- #### Hub Queries
161
- - `getHub(params)` - Get hub configuration
162
- - `getAllowedModules(params)` - Get allowed modules
163
- - `getAllowedCurrencies(params)` - Get allowed currencies
164
-
165
- #### Land Queries
166
- - `getLands(params)` - Get all lands with pagination
167
- - `getLand(params)` - Get a specific land by ID
168
- - `getLandsByOwner(params)` - Get lands owned by an address
169
-
170
- #### Slot Queries
171
- - `getSlots(params)` - Get all slots with filters
172
- - `getSlot(params)` - Get a specific slot with history
173
- - `getSlotsByOccupant(params)` - Get slots held by an address
174
- - `getAvailableSlots(params)` - Get vacant slots
175
-
176
- #### Event Queries
177
- - `getSlotPurchases(params)` - Get slot purchase events
178
- - `getLandOpenedEvents(params)` - Get land creation events
179
- - `getSlotCreatedEvents(params)` - Get slot creation events
180
- - `getFlowChanges(params)` - Get Superfluid flow changes
181
-
182
- ## Development
183
-
184
- ```bash
185
- # Install dependencies
186
- pnpm install
187
-
188
- # Generate types from GraphQL schema
189
- pnpm codegen
190
-
191
- # Build the SDK
192
- pnpm build
193
-
194
- # Watch mode for development
195
- pnpm dev
196
- ```
73
+ ERC-20 approvals are handled automatically for `buy` and `topUp`. If the wallet supports EIP-5792 atomic batching, approve + action are sent as a single atomic call.
197
74
 
198
75
  ## License
199
76