sui.ski 0.1.0 → 0.1.2

package/.github/workflows/deploy.yml

@@ -0,0 +1,21 @@
+name: Deploy
+
+on:
+  push:
+    branches: ['*']
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - run: npm install
+
+      - run: npx wrangler deploy
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}

package/.github/workflows/publish-npm.yml

@@ -0,0 +1,48 @@
+name: Publish npm Package
+
+on:
+  push:
+    branches: [master]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    if: github.actor != 'github-actions[bot]' && github.ref == 'refs/heads/master'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org
+
+      - name: Configure git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Bump package version
+        run: npm version patch --no-git-tag-version
+
+      - name: Read version
+        id: version
+        run: |
+          echo "value=$(npm pkg get version | tr -d '"')" >> "$GITHUB_OUTPUT"
+
+      - name: Publish to npm
+        run: npm publish --access public --provenance
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}
+
+      - name: Commit version bump and tag
+        run: |
+          git add package.json
+          git commit -m "chore(release): v${{ steps.version.outputs.value }} [skip ci]"
+          git tag "v${{ steps.version.outputs.value }}"
+          git push origin HEAD:master --follow-tags

package/.obsidian/app.json

@@ -0,0 +1,7 @@
+{
+	"alwaysUpdateLinks": true,
+	"newFileLocation": "folder",
+	"newFileFolderPath": ".vault",
+	"attachmentFolderPath": ".vault/assets",
+	"promptDelete": false
+}

package/.obsidian/appearance.json

@@ -0,0 +1,9 @@
+{
+	"accentColor": "#7c3aed",
+	"cssTheme": "",
+	"interfaceFontFamily": "",
+	"textFontFamily": "",
+	"monospaceFontFamily": "",
+	"enabledCssSnippets": [],
+	"baseFontSize": 16
+}

package/.obsidian/core-plugins-migration.json

@@ -0,0 +1,14 @@
+{
+	"trashOption": "system",
+	"alwaysUpdateLinks": true,
+	"newFileLocation": "folder",
+	"newFileFolderPath": ".vault",
+	"attachmentFolderPath": ".vault/assets",
+	"promptDelete": false,
+	"pdfExportSettings": {
+		"pageSize": "Letter",
+		"landscape": false,
+		"margin": "0",
+		"downscalePercent": 100
+	}
+}

package/.obsidian/core-plugins.json

@@ -0,0 +1,13 @@
+[
+	"graph",
+	"backlink",
+	"page-preview",
+	"note-composer",
+	"command-palette",
+	"editor-status",
+	"starred",
+	"outline",
+	"word-count",
+	"daily-notes",
+	"templates"
+]

package/.obsidian/daily-notes.json

@@ -0,0 +1,5 @@
+{
+	"folder": ".vault/daily-notes",
+	"format": "YYYY-MM-DD",
+	"template": ".vault/templates/Daily Note Template.md"
+}

package/.obsidian/editor.json

@@ -0,0 +1,10 @@
+{
+	"tabSize": 4,
+	"useTab": false,
+	"lineWrap": true,
+	"readableLineLength": true,
+	"foldHeading": true,
+	"foldIndent": true,
+	"showLineNumber": false,
+	"rightToLeft": false
+}

package/.obsidian/templates.json

@@ -0,0 +1,5 @@
+{
+	"templatesFolder": ".vault/templates",
+	"dateFormat": "YYYY-MM-DD",
+	"timeFormat": "HH:mm"
+}

package/.vault/Index.md

@@ -0,0 +1,51 @@
+# Development Index
+
+## Quick Links
+
+- [[README|Project Overview]]
+- [[.vault/README|Vault Guide]]
+- [[CODEBASE_GUIDE|Codebase Guide]]
+- [[AGENTS|Agent Guidelines]]
+
+## SDK Documentation
+
+### Sui TypeScript SDK
+- [[sdk-docs/DApp-Kit-State|DApp Kit State Management]] - Wallet connection state
+- [[sdk-docs/Transaction-Executors|Transaction Executors]] - Serial & Parallel execution
+- [[sdk-docs/Transaction-Plugins|Transaction Plugins]] - Plugin system & Intents
+- [[sdk-docs/Building-SDKs|Building SDKs]] - Best practices for SDK development
+
+## Daily Notes
+
+```dataview
+TABLE file.ctime as Created
+FROM ".vault/daily-notes"
+SORT file.name DESC
+LIMIT 10
+```
+
+## Recent Progress
+
+```dataview
+TABLE status as Status, priority as Priority, file.mtime as Modified
+FROM ".vault/progress"
+SORT file.mtime DESC
+LIMIT 10
+```
+
+## Recent Git Observations
+
+```dataview
+TABLE file.ctime as Created
+FROM ".vault/git-observations"
+SORT file.name DESC
+LIMIT 10
+```
+
+## Active Tags
+
+#development #git #progress #daily #observation
+
+---
+
+*Use this note as your dashboard. Click any link above to navigate.*

package/.vault/README.md

@@ -0,0 +1,129 @@
+# Sui-ski Gateway Documentation Vault
+
+This is an Obsidian vault for tracking development progress, git observations, and project documentation for the Sui-ski Gateway project.
+
+## Structure
+
+```
+.vault/
+├── daily-notes/       # Daily progress logs
+├── git-observations/  # Git state snapshots
+├── progress/          # Feature/task progress entries
+├── templates/         # Note templates
+├── sdk-docs/          # SDK documentation (Sui SDK)
+└── assets/           # Images and attachments
+```
+
+## Quick Start
+
+### Using npm scripts
+
+```bash
+# Create today's daily note
+bun run obsidian:daily
+
+# Generate git observation
+bun run obsidian:git
+
+# Create progress entry
+bun run obsidian:progress "Feature Name"
+
+# Create both daily note and git observation
+bun run obsidian:all
+
+# Open vault in Obsidian
+bun run obsidian:open
+```
+
+### Manual CLI
+
+```bash
+# Run the script directly
+bun run scripts/obsidian.ts <command> [args]
+
+# Examples:
+bun run scripts/obsidian.ts daily
+bun run scripts/obsidian.ts git
+bun run scripts/obsidian.ts progress "My Feature"
+bun run scripts/obsidian.ts open
+```
+
+## Templates
+
+### Daily Note Template
+Located at: `.vault/templates/Daily Note Template.md`
+
+Includes:
+- Day at a Glance
+- Tasks checklist
+- Progress Log (Morning/Afternoon/Evening)
+- Notes & Ideas
+- Blockers
+- Git Activity tracking
+- Links to previous/next days
+
+### Progress Entry Template
+Located at: `.vault/templates/Progress Entry Template.md`
+
+Includes:
+- Status, Priority, Timeline
+- Objectives checklist
+- Implementation Details
+- Code Changes tracking
+- Testing checklist
+- Issues and Related links
+
+### Git Observation Template
+Located at: `.vault/templates/Git Observation Template.md`
+
+Includes:
+- Repository state (branch, commit)
+- Recent commits log
+- Files changed (modified/added/deleted)
+- Code quality status
+- Observations and patterns
+
+## Obsidian Features Enabled
+
+- **Daily Notes**: Automatic daily note creation
+- **Templates**: Pre-configured note templates
+- **Graph View**: Visualize note connections
+- **Backlinks**: See which notes link to the current one
+- **Outline**: Navigate document headers
+- **Word Count**: Track document length
+
+## Git Integration
+
+The vault automatically captures:
+- Current branch and commit
+- Recent commit history
+- Modified, added, and deleted files
+- Can be extended to capture lint/test status
+
+## SDK Documentation
+
+The `sdk-docs/` directory contains imported documentation from the Mysten Labs SDK:
+
+- **[[sdk-docs/DApp-Kit-State|DApp Kit State Management]]** - Reactive stores for wallet connections
+- **[[sdk-docs/Transaction-Executors|Transaction Executors]]** - Serial and Parallel executor patterns
+- **[[sdk-docs/Transaction-Plugins|Transaction Plugins]]** - Plugin system for extending transactions
+- **[[sdk-docs/Building-SDKs|Building SDKs]]** - Best practices for SDK development
+
+These are linked in the [[Index]] for easy navigation.
+
+## Tips
+
+1. **Linking**: Use `[[Note Name]]` to link between notes
+2. **Tags**: Use `#tag` to categorize notes
+3. **Search**: Press `Ctrl/Cmd + O` for quick file search
+4. **Command Palette**: Press `Ctrl/Cmd + P` for all commands
+5. **Graph View**: Press `Ctrl/Cmd + G` to see note connections
+
+## Customization
+
+Edit templates in `.vault/templates/` to customize your note structure. Templates support these variables:
+
+- `{{date:YYYY-MM-DD}}` - Current date
+- `{{date:YYYY-MM-DD HH:mm}}` - Current timestamp
+- `{{yesterday}}` - Yesterday's date
+- `{{tomorrow}}` - Tomorrow's date

package/.vault/sdk-docs/Building-SDKs.md

@@ -0,0 +1,361 @@
+# Building SDKs
+
+**Source**: [Mysten Labs SDK Docs](https://sdk.mystenlabs.com/sui/sdk-building)
+
+## Overview
+
+Recommended patterns for building TypeScript SDKs that integrate with the Sui SDK. Following these patterns ensures:
+
+- Seamless ecosystem integration
+- Works across transports (JSON-RPC, GraphQL, gRPC)
+- Composes well with other SDKs
+
+**Key Requirement**: All SDKs should depend on `ClientWithCoreApi`, the transport-agnostic interface implemented by all Sui clients.
+
+---
+
+## Package Setup
+
+### Use Mysten Packages as Peer Dependencies
+
+```json
+{
+	"name": "@your-org/your-sdk",
+	"peerDependencies": {
+		"@mysten/sui": "^2.0.0",
+		"@mysten/bcs": "^2.0.0"
+	},
+	"devDependencies": {
+		"@mysten/sui": "^2.0.0",
+		"@mysten/bcs": "^2.0.0"
+	}
+}
+```
+
+**Benefits:**
+- Prevents multiple versions from being bundled
+- Ensures compatibility with user versions
+- Reduces bundle size
+- Avoids bugs from mismatched package instances
+
+---
+
+## Client Extensions
+
+The recommended way to build SDKs using the **client extension pattern** via the `$extend` method.
+
+### Extension Pattern
+
+```typescript
+import type { ClientWithCoreApi } from '@mysten/sui/client';
+
+export interface MySDKOptions<Name = 'mySDK'> {
+	name?: Name;
+	apiKey?: string;
+}
+
+export function mySDK<const Name = 'mySDK'>({
+	name = 'mySDK' as Name,
+	...options
+}: MySDKOptions<Name> = {}) {
+	return {
+		name,
+		register: (client: ClientWithCoreApi) => {
+			return new MySDKClient({ client, ...options });
+		},
+	};
+}
+
+export class MySDKClient {
+	#client: ClientWithCoreApi;
+	#apiKey?: string;
+
+	constructor({ client, apiKey }: { client: ClientWithCoreApi; apiKey?: string }) {
+		this.#client = client;
+		this.#apiKey = apiKey;
+	}
+
+	async getResource(id: string) {
+		const result = await this.#client.core.getObject({ objectId: id });
+		return result;
+	}
+}
+```
+
+### Usage
+
+```typescript
+import { SuiGrpcClient } from '@mysten/sui/grpc';
+import { mySDK } from '@your-org/your-sdk';
+
+const client = new SuiGrpcClient({
+	network: 'testnet',
+	baseUrl: 'https://fullnode.testnet.sui.io:443',
+}).$extend(mySDK());
+
+// Access extension
+await client.mySDK.getResource('0x...');
+```
+
+### Real-World Examples
+
+- **[@mysten/walrus](https://www.npmjs.com/package/@mysten/walrus)** - Decentralized storage
+- **[@mysten/seal](https://www.npmjs.com/package/@mysten/seal)** - Encryption and key management
+
+---
+
+## SDK Organization
+
+Recommended structure for client extension methods:
+
+| Property | Purpose | Example |
+|----------|---------|---------|
+| `methods` | Top-level operations | `sdk.readBlob()`, `sdk.getConfig()` |
+| `tx` | Transaction builders (non-executing) | `sdk.tx.registerBlob()` |
+| `bcs` | BCS type definitions | `sdk.bcs.MyStruct` |
+| `call` | Move calls for `tx.add` | `sdk.call.myFunction()` |
+| `view` | Simulate API for reading state | `sdk.view.getState()` |
+
+### Example Organization
+
+```typescript
+import { Transaction } from '@mysten/sui/transactions';
+import * as myModule from './contracts/my-package/my-module';
+
+export class MySDKClient {
+	#client: ClientWithCoreApi;
+
+	constructor({ client }: { client: ClientWithCoreApi }) {
+		this.#client = client;
+	}
+
+	// Top-level methods - execute/read
+	async executeAction(options: ActionOptions) {
+		const transaction = this.tx.createAction(options);
+		// Execute and return
+	}
+
+	async getResource(objectId: string) {
+		const { object } = await this.#client.core.getObject({
+			objectId,
+			include: { content: true },
+		});
+		return myModule.MyStruct.parse(object.content);
+	}
+
+	// Transaction builders
+	tx = {
+		createAction: (options: ActionOptions) => {
+			const transaction = new Transaction();
+			transaction.add(this.call.action(options));
+			return transaction;
+		},
+	};
+
+	// Move call helpers
+	call = {
+		action: (options: ActionOptions) => {
+			return myModule.action({
+				arguments: {
+					obj: options.objectId,
+					amount: options.amount,
+				},
+			});
+		},
+	};
+
+	// View methods - simulate to read state
+	view = {
+		getBalance: async (managerId: string) => {
+			const tx = new Transaction();
+			tx.add(myModule.getBalance({ arguments: { manager: managerId } }));
+
+			const res = await this.#client.core.simulateTransaction({
+				transaction: tx,
+				include: { commandResults: true },
+			});
+
+			return bcs.U64.parse(res.commandResults![0].returnValues[0].bcs);
+		},
+	};
+}
+```
+
+---
+
+## Transaction Building Patterns
+
+### Transaction Thunks
+
+Functions that accept a `Transaction` and mutate it, enabling composition:
+
+```typescript
+import type { Transaction, TransactionObjectArgument } from '@mysten/sui/transactions';
+
+// Synchronous thunk
+function createResource(options: { name: string }) {
+	return (tx: Transaction): TransactionObjectArgument => {
+		const [resource] = tx.moveCall({
+			target: `${PACKAGE_ID}::module::create`,
+			arguments: [tx.pure.string(options.name)],
+		});
+		return resource;
+	};
+}
+
+// Usage
+const tx = new Transaction();
+const resource = tx.add(createResource({ name: 'my-resource' }));
+tx.transferObjects([resource], recipient);
+```
+
+### Async Thunks
+
+For operations requiring async work (like fetching package IDs):
+
+```typescript
+function createResourceAsync(options: { name: string }) {
+	return async (tx: Transaction): Promise<TransactionObjectArgument> => {
+		// Async work happens before signing
+		const packageId = await getLatestPackageId();
+
+		const [resource] = tx.moveCall({
+			target: `${packageId}::module::create`,
+			arguments: [tx.pure.string(options.name)],
+		});
+		return resource;
+	};
+}
+
+// Usage - identical to synchronous
+const tx = new Transaction();
+const resource = tx.add(createResourceAsync({ name: 'my-resource' }));
+tx.transferObjects([resource], recipient);
+
+// Async resolves automatically when building/signing
+await signer.signAndExecuteTransaction({ transaction: tx, client });
+```
+
+**Critical for web wallet compatibility** - async work during construction won't block user-triggered popups.
+
+---
+
+## Transaction Execution
+
+### Accept a Signer Parameter
+
+```typescript
+import type { Signer } from '@mysten/sui/cryptography';
+
+export class MySDKClient {
+	#client: ClientWithCoreApi;
+
+	async createAndExecute({
+		signer,
+		...options
+	}: CreateOptions & { signer: Signer }) {
+		const transaction = this.tx.create(options);
+
+		const result = await signer.signAndExecuteTransaction({
+			transaction,
+			client: this.#client,
+		});
+
+		return result;
+	}
+}
+```
+
+**Benefits:**
+- Wallet integration via dApp Kit
+- Transaction sponsorship support
+- Custom signing flows
+
+---
+
+## Code Generation
+
+Use **[@mysten/codegen](/codegen)** to generate type-safe TypeScript bindings from Move packages.
+
+### Benefits
+
+- Type safety
+- BCS parsing
+- IDE support
+- MoveRegistry support for human-readable names
+
+### Using Generated Code
+
+```typescript
+import * as myContract from './contracts/my-package/my-module';
+
+// Move call functions return thunks with typed options
+const tx = new Transaction();
+tx.add(
+	myContract.doSomething({
+		arguments: {
+			obj: '0x123...',
+			amount: 100n,
+		},
+	}),
+);
+
+// BCS types parse on-chain data
+const { object } = await client.core.getObject({
+	objectId: '0x123...',
+	include: { content: true },
+});
+const parsed = myContract.MyStruct.parse(object.content);
+```
+
+---
+
+## Reading Object Contents
+
+### Single Object
+
+```typescript
+import { MyStruct } from './contracts/my-package/my-module';
+
+async function getResource(objectId: string) {
+	const { object } = await this.#client.core.getObject({
+		objectId,
+		include: { content: true },
+	});
+
+	if (!object) {
+		throw new Error(`Object ${objectId} not found`);
+	}
+
+	return MyStruct.parse(object.content);
+}
+```
+
+### Batch Fetch
+
+```typescript
+async function getResources(objectIds: string[]) {
+	const { objects } = await this.#client.core.getObjects({
+		objectIds,
+		include: { content: true },
+	});
+
+	return objects.map((obj) => {
+		if (obj instanceof Error) {
+			throw obj;
+		}
+		return MyStruct.parse(obj.content);
+	});
+}
+```
+
+---
+
+## Related
+
+- [[Transaction-Executors|Transaction Executors]]
+- [[Transaction-Plugins|Transaction Plugins]]
+- [[DApp-Kit-State|DApp Kit State Management]]
+
+---
+*Documentation from Mysten Labs SDK - @mysten/sui v2.0*