@odvi/create-dtt-framework 0.1.13 → 0.1.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@odvi/create-dtt-framework",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "description": "CLI tool to scaffold new projects with DTT Framework",
   "type": "module",
   "bin": {

package/template/docs/framework/integrations.md

@@ -0,0 +1,78 @@
+# Reusable Integrations
+
+The DTT Framework provides a unified interface to access all configured integrations through a single `framework` instance. This allows you to easily use third-party services in your application logic without manually managing connections or clients.
+
+## Usage
+
+You can import the `framework` instance from `@/lib/framework`.
+
+```typescript
+import { framework } from '@/lib/framework'
+
+async function myFunction() {
+  // 1. Clerk Authentication
+  const user = await framework.clerk.users.getUser('user_id')
+
+  // 2. Supabase (Admin Access)
+  const { data } = await framework.supabase
+    .from('my_table')
+    .select('*')
+
+  // 3. Snowflake Query
+  const rows = await framework.snowflake.query('SELECT * FROM PUBLIC.USERS LIMIT 10')
+
+  // 4. NextBank API
+  const account = await framework.nextbank.get('/accounts/123')
+  await framework.nextbank.post('/transfers', { amount: 100 })
+
+  // 5. Synology File Operations
+  const files = await framework.synology.listFiles('/home/user')
+  const fileContent = await framework.synology.getFile('/home/user/doc.pdf')
+
+  // 6. AWS S3
+  await framework.s3.uploadFile('my-bucket', 'uploads/hello.txt', 'Hello World')
+}
+```
+
+## Integration Details
+
+### Clerk (`framework.clerk`)
+Exposes the `@clerk/nextjs/server` client. Use this for server-side user management, organization handling, and session verification.
+
+### Supabase (`framework.supabase`)
+Exposes the Supabase Admin client (using `SUPABASE_SERVICE_ROLE_KEY`).
+**Note:** This client has full admin privileges. Be careful when using it in client-facing code (it should only be used server-side).
+
+### Snowflake (`framework.snowflake`)
+Provides a simplified `query` method that handles connection pooling, execution, and cleanup automatically.
+- `query(sqlText, binds?)`: Executes a SQL query.
+
+### NextBank (`framework.nextbank`)
+A wrapper around the NextBank API that automatically handles:
+- Base URL injection
+- Authentication headers
+- JSON parsing
+- Error handling
+
+Methods:
+- `get(endpoint)`
+- `post(endpoint, body)`
+- `put(endpoint, body)`
+- `delete(endpoint)`
+
+### Synology (`framework.synology`)
+Provides methods to interact with Synology File Station.
+- `listFiles(folderPath)`
+- `getFile(filePath)`
+- `deleteFile(filePath)`
+
+### AWS S3 (`framework.s3`)
+Wraps the AWS SDK S3 Client.
+- `listBuckets()`
+- `listFiles(bucket, prefix?)`
+- `uploadFile(bucket, key, body, contentType?)`
+- `getFile(bucket, key)`
+- `deleteFile(bucket, key)`
+- `getPresignedUrl(bucket, key, expiresIn?)`
+- `getClient()`: Returns the raw AWS S3 Client for advanced operations.
+

package/template/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@odvi/dtt-framework",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "private": false,
   "type": "module",
   "bin": {
@@ -64,6 +64,7 @@
   },
   "dependencies": {
     "@aws-sdk/client-s3": "^3.958.0",
+    "@aws-sdk/s3-request-presigner": "^3.958.0",
     "@clerk/nextjs": "^6.36.5",
     "@radix-ui/react-collapsible": "^1.1.12",
     "@radix-ui/react-dialog": "^1.1.15",

package/template/src/lib/aws-s3/client.ts

@@ -0,0 +1,103 @@
+import { 
+  S3Client, 
+  ListBucketsCommand, 
+  PutObjectCommand, 
+  GetObjectCommand, 
+  DeleteObjectCommand,
+  ListObjectsV2Command
+} from '@aws-sdk/client-s3'
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner'
+import { env } from '@/config/env'
+
+export class S3IntegrationClient {
+  private client: S3Client
+  private region: string
+
+  constructor() {
+    this.region = env.AWS_REGION ?? 'us-east-1'
+    
+    // Initialize with credentials from env
+    this.client = new S3Client({
+      region: this.region,
+      credentials: {
+        accessKeyId: env.AWS_ACCESS_KEY_ID ?? '',
+        secretAccessKey: env.AWS_ACCESS_SECRET_KEY ?? '',
+      },
+    })
+  }
+
+  /**
+   * Get the underlying S3 Client
+   */
+  getClient(): S3Client {
+    return this.client
+  }
+
+  /**
+   * List all buckets
+   */
+  async listBuckets() {
+    const command = new ListBucketsCommand({})
+    return this.client.send(command)
+  }
+
+  /**
+   * List files in a bucket
+   */
+  async listFiles(bucket: string, prefix?: string) {
+    const command = new ListObjectsV2Command({
+      Bucket: bucket,
+      Prefix: prefix,
+    })
+    return this.client.send(command)
+  }
+
+  /**
+   * Upload a file to S3
+   */
+  async uploadFile(bucket: string, key: string, body: Buffer | Uint8Array | Blob | string, contentType?: string) {
+    const command = new PutObjectCommand({
+      Bucket: bucket,
+      Key: key,
+      Body: body,
+      ContentType: contentType,
+    })
+    return this.client.send(command)
+  }
+
+  /**
+   * Get a file from S3 (returns the raw output)
+   */
+  async getFile(bucket: string, key: string) {
+    const command = new GetObjectCommand({
+      Bucket: bucket,
+      Key: key,
+    })
+    return this.client.send(command)
+  }
+
+  /**
+   * Generate a presigned URL for a file
+   */
+  async getPresignedUrl(bucket: string, key: string, expiresIn = 3600) {
+    const command = new GetObjectCommand({
+      Bucket: bucket,
+      Key: key,
+    })
+    return getSignedUrl(this.client, command, { expiresIn })
+  }
+
+  /**
+   * Delete a file from S3
+   */
+  async deleteFile(bucket: string, key: string) {
+    const command = new DeleteObjectCommand({
+      Bucket: bucket,
+      Key: key,
+    })
+    return this.client.send(command)
+  }
+}
+
+export const s3Client = new S3IntegrationClient()
+

package/template/src/lib/framework.ts

@@ -0,0 +1,47 @@
+import { clerkClient } from '@clerk/nextjs/server'
+import { supabaseAdmin } from './supabase/admin'
+import { nextbankClient } from './nextbank/client'
+import { synologyClient } from './synology/client'
+import { snowflakeClient } from './snowflake/client'
+import { s3Client } from './aws-s3/client'
+
+export class Framework {
+  /**
+   * Clerk Authentication SDK
+   * Use this to manage users, sessions, and organizations.
+   */
+  public clerk = clerkClient
+
+  /**
+   * Supabase Admin Client (Service Role)
+   * Use this for database and storage operations with full privileges.
+   */
+  public supabase = supabaseAdmin
+
+  /**
+   * Snowflake Client
+   * Use this to execute SQL queries against your Snowflake data warehouse.
+   */
+  public snowflake = snowflakeClient
+
+  /**
+   * AWS S3 Client
+   * Use this to manage files in AWS S3 buckets.
+   */
+  public s3 = s3Client
+
+  /**
+   * NextBank Integration
+   * Use this to interact with the NextBank API.
+   */
+  public nextbank = nextbankClient
+
+  /**
+   * Synology Integration
+   * Use this to manage files on a Synology NAS.
+   */
+  public synology = synologyClient
+}
+
+export const framework = new Framework()
+

package/template/src/lib/nextbank/client.ts

@@ -17,22 +17,21 @@ class NextBankClient {
     return { Authorization: `Basic ${token}` }
   }
 
-  async ping(fingerprint: string): Promise<{ status: string; timestamp: string }> {
-    const url = `${this.apiUrl}/management/status`
-    console.log(`[NextBank] Pinging ${url}`)
+  private async request<T = any>(endpoint: string, options: RequestInit = {}): Promise<T> {
+    const url = `${this.apiUrl}${endpoint.startsWith('/') ? endpoint : `/${endpoint}`}`
     
+    const headers = {
+      ...this.getAuthHeader(),
+      'Content-Type': 'application/json',
+      'Accept': 'application/json',
+      'User-Agent': 'dtt-framework-client',
+      ...options.headers,
+    }
+
     try {
       const response = await fetch(url, {
-        method: 'POST',
-        headers: {
-          ...this.getAuthHeader(),
-          'Content-Type': 'application/json',
-          'Accept': 'application/json',
-          'User-Agent': 'dtt-framework-health-check',
-        },
-        body: JSON.stringify({
-          fingerprint: fingerprint,
-        }),
+        ...options,
+        headers,
       })
 
       const contentType = response.headers.get('content-type')
@@ -40,28 +39,54 @@ class NextBankClient {
       if (!response.ok) {
         if (contentType && contentType.includes('text/html')) {
            const text = await response.text()
-           console.error('[NextBank] Received HTML error response. Possible causes:')
-           console.error('1. NEXTBANK_API is pointing to the wrong server (e.g. Next.js app instead of NextBank API)')
-           console.error('2. The endpoint /management/status does not exist or does not support POST')
-           console.error(`[NextBank] Response preview: ${text.substring(0, 150)}...`)
-           throw new Error(`NextBank API error: ${response.status} (HTML response)`)
+           throw new Error(`NextBank API error: ${response.status} (HTML response): ${text.substring(0, 100)}...`)
         }
         throw new Error(`NextBank API error: ${response.status} ${response.statusText}`)
       }
 
       if (contentType && contentType.includes('application/json')) {
         return await response.json()
-      } else {
-        const text = await response.text()
-        console.error('[NextBank] Invalid response content type:', contentType)
-        console.error('[NextBank] Response preview:', text.substring(0, 200))
-        throw new Error(`Invalid response format. Expected JSON, got ${contentType}`)
+      }
+      
+      // If not JSON, return text if generic T is string, or try to return as is?
+      // For now, assume JSON or void.
+      const text = await response.text()
+      try {
+          return JSON.parse(text)
+      } catch {
+          return text as unknown as T
       }
     } catch (error) {
-      console.error('[NextBank] Ping failed:', error)
+      console.error(`[NextBank] Request to ${endpoint} failed:`, error)
       throw error
     }
   }
+
+  async get<T = any>(endpoint: string): Promise<T> {
+    return this.request<T>(endpoint, { method: 'GET' })
+  }
+
+  async post<T = any>(endpoint: string, body: any): Promise<T> {
+    return this.request<T>(endpoint, { 
+      method: 'POST',
+      body: JSON.stringify(body)
+    })
+  }
+
+  async put<T = any>(endpoint: string, body: any): Promise<T> {
+    return this.request<T>(endpoint, { 
+      method: 'PUT',
+      body: JSON.stringify(body)
+    })
+  }
+
+  async delete<T = any>(endpoint: string): Promise<T> {
+    return this.request<T>(endpoint, { method: 'DELETE' })
+  }
+
+  async ping(fingerprint: string): Promise<{ status: string; timestamp: string }> {
+    return this.post('/management/status', { fingerprint })
+  }
 }
 
 export const nextbankClient = new NextBankClient()

package/template/src/lib/snowflake/client.ts

@@ -100,3 +100,40 @@ export async function destroyConnection(connection: Connection): Promise<void> {
     })
   })
 }
+
+export class SnowflakeClient {
+  async query<T = unknown>(sqlText: string, binds?: Bind[]): Promise<T[]> {
+    let connection: Connection | undefined
+    try {
+      connection = await createSnowflakeConnection()
+      
+      // Connect
+      await new Promise<void>((resolve, reject) => {
+        connection!.connect((err) => {
+          if (err) reject(err)
+          else resolve()
+        })
+      })
+
+      // Execute
+      return await new Promise<T[]>((resolve, reject) => {
+        connection!.execute({
+          sqlText,
+          binds: binds as any,
+          complete: (err, stmt, rows) => {
+            if (err) reject(err)
+            else resolve((rows || []) as T[])
+          },
+        })
+      })
+    } finally {
+      if (connection) {
+        connection.destroy((err) => {
+          if (err) console.error('Error destroying Snowflake connection:', err)
+        })
+      }
+    }
+  }
+}
+
+export const snowflakeClient = new SnowflakeClient()

package/template/src/lib/synology/client.ts

@@ -74,6 +74,79 @@ class SynologyClient {
     }
   }
 
+  async listFiles(folderPath: string) {
+    if (!this.sessionID) await this.login()
+    
+    const params = new URLSearchParams({
+      api: 'SYNO.FileStation.List',
+      version: '2',
+      method: 'list',
+      folder_path: folderPath,
+      _sid: this.sessionID!
+    })
+
+    const url = `${this.host}/webapi/entry.cgi?${params.toString()}`
+    const response = await this.fetchWithAgent(url)
+    
+    if (!response.ok) {
+      throw new Error(`Synology ListFiles error: ${response.status}`)
+    }
+
+    const data = await response.json()
+    if (!data.success) {
+       throw new Error(`Synology ListFiles failed: ${JSON.stringify(data)}`)
+    }
+    return data.data.files
+  }
+
+  async getFile(filePath: string) {
+    if (!this.sessionID) await this.login()
+    
+    const params = new URLSearchParams({
+      api: 'SYNO.FileStation.Download',
+      version: '2',
+      method: 'download',
+      path: filePath,
+      mode: 'open',
+      _sid: this.sessionID!
+    })
+
+    const url = `${this.host}/webapi/entry.cgi?${params.toString()}`
+    const response = await this.fetchWithAgent(url)
+
+    if (!response.ok) {
+      throw new Error(`Synology GetFile error: ${response.status}`)
+    }
+    
+    // Return array buffer or blob?
+    return response.arrayBuffer()
+  }
+
+  async deleteFile(filePath: string) {
+    if (!this.sessionID) await this.login()
+      
+    const params = new URLSearchParams({
+      api: 'SYNO.FileStation.Delete',
+      version: '2',
+      method: 'delete',
+      path: filePath,
+      _sid: this.sessionID!
+    })
+
+    const url = `${this.host}/webapi/entry.cgi?${params.toString()}`
+    const response = await this.fetchWithAgent(url)
+    
+    if (!response.ok) {
+      throw new Error(`Synology DeleteFile error: ${response.status}`)
+    }
+
+    const data = await response.json()
+    if (!data.success) {
+       throw new Error(`Synology DeleteFile failed: ${JSON.stringify(data)}`)
+    }
+    return data
+  }
+
   async ping(): Promise<{ status: string; timestamp: string; version?: string; sid?: string }> {
     if (!this.host) {
       throw new Error('Synology host not configured')