yoto-nodejs-client 0.0.1

package/bin/icons.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+
+/**
+ * @import {ArgscloptsParseArgsOptionsConfig} from 'argsclopts'
+ */
+
+import { printHelpText } from 'argsclopts'
+import { parseArgs } from 'node:util'
+import { pkg } from '../lib/pkg.cjs'
+import {
+  getCommonOptions,
+  loadTokensFromEnv,
+  createYotoClient,
+  handleCliError,
+  printHeader
+} from './lib/cli-helpers.js'
+
+/** @type {ArgscloptsParseArgsOptionsConfig} */
+const options = {
+  ...getCommonOptions(),
+  public: {
+    type: 'boolean',
+    short: 'p',
+    help: 'Show only public Yoto icons'
+  },
+  user: {
+    type: 'boolean',
+    short: 'u',
+    help: 'Show only user custom icons'
+  }
+}
+
+const args = parseArgs({ options, strict: false })
+
+if (args.values['help']) {
+  await printHelpText({
+    options,
+    name: 'yoto-icons',
+    version: pkg.version,
+    exampleFn: ({ name }) => `    Yoto icons information helper\n\n    Examples:\n      ${name}                # List both public and user icons\n      ${name} --public       # List only public Yoto icons\n      ${name} --user         # List only user custom icons\n`
+  })
+  process.exit(0)
+}
+
+// Load tokens from environment
+const { clientId, refreshToken, accessToken, envFile } = loadTokensFromEnv(args)
+
+const showPublic = Boolean(args.values['public'])
+const showUser = Boolean(args.values['user'])
+
+// If neither flag is set, show both
+const showBoth = !showPublic && !showUser
+
+async function main () {
+  printHeader('Yoto Icons')
+
+  try {
+    // Create client
+    const client = createYotoClient({
+      clientId,
+      refreshToken,
+      accessToken,
+      outputFile: envFile
+    })
+
+    if (showPublic || showBoth) {
+      console.log('\nFetching public Yoto icons...\n')
+      const publicIcons = await client.getPublicIcons()
+
+      if (showBoth) {
+        console.log('Public Icons:')
+      }
+      console.dir(publicIcons, { depth: null, colors: true })
+    }
+
+    if (showUser || showBoth) {
+      if (showBoth) {
+        console.log('\n' + '='.repeat(60) + '\n')
+      }
+      console.log('\nFetching user custom icons...\n')
+      const userIcons = await client.getUserIcons()
+
+      if (showBoth) {
+        console.log('User Icons:')
+      }
+      console.dir(userIcons, { depth: null, colors: true })
+    }
+
+    process.exit(0)
+  } catch (error) {
+    handleCliError(error)
+  }
+}
+
+// Run the main function
+await main().catch(err => {
+  console.error('\n❌ Unexpected error:')
+  console.error(err)
+  process.exit(1)
+})

package/bin/lib/cli-helpers.d.ts

@@ -0,0 +1,21 @@
+export function getCommonOptions(): ArgscloptsParseArgsOptionsConfig;
+export function loadEnvFile(envFile?: string): string;
+export function loadTokensFromEnv(args: {
+    values: Record<string, string | boolean | undefined>;
+}): {
+    clientId: string;
+    refreshToken: string;
+    accessToken: string;
+    envFile: string;
+};
+export function createYotoClient({ clientId, refreshToken, accessToken, outputFile }: {
+    clientId: string;
+    refreshToken: string;
+    accessToken: string;
+    outputFile?: string | undefined;
+}): YotoClient;
+export function handleCliError(error: any): void;
+export function printHeader(title: string): void;
+import type { ArgscloptsParseArgsOptionsConfig } from 'argsclopts';
+import { YotoClient } from '../../index.js';
+//# sourceMappingURL=cli-helpers.d.ts.map

package/bin/lib/cli-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-helpers.d.ts","sourceRoot":"","sources":["cli-helpers.js"],"names":[],"mappings":"AAYA,oCAFa,gCAAgC,CAoB5C;AAOD,sCAHW,MAAM,GACJ,MAAM,CAUlB;AAQD,wCAJW;IAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAA;CAAE,GACtD;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAoB5F;AAWD,sFANG;IAAwB,QAAQ,EAAxB,MAAM;IACU,YAAY,EAA5B,MAAM;IACU,WAAW,EAA3B,MAAM;IACW,UAAU;CACnC,GAAU,UAAU,CAsBtB;AAMD,sCAFW,GAAG,QAyBb;AAMD,mCAFW,MAAM,QAKhB;sDA1IoD,YAAY;2BAGtC,gBAAgB"}

package/bin/lib/cli-helpers.js

@@ -0,0 +1,140 @@
+/**
+ * @import { ArgscloptsParseArgsOptionsConfig } from 'argsclopts'
+ */
+
+import { YotoClient } from '../../index.js'
+import { DEFAULT_CLIENT_ID } from '../../lib/api-endpoints/constants.js'
+import { saveTokensToEnv } from './token-helpers.js'
+
+/**
+ * Get common CLI option definitions shared across all tools
+ * @returns {ArgscloptsParseArgsOptionsConfig}
+ */
+export function getCommonOptions () {
+  return {
+    help: {
+      type: 'boolean',
+      short: 'h',
+      help: 'Print help text'
+    },
+    'client-id': {
+      type: 'string',
+      short: 'c',
+      help: 'Yoto OAuth client ID (or set YOTO_CLIENT_ID env var)'
+    },
+    'env-file': {
+      type: 'string',
+      short: 'e',
+      help: 'Path to .env file to load (default: .env in current directory)'
+    }
+  }
+}
+
+/**
+ * Load .env file from specified path or default to .env in cwd
+ * @param {string} [envFile] - Optional path to .env file
+ * @returns {string} The path that was loaded (or attempted)
+ */
+export function loadEnvFile (envFile) {
+  const envPath = envFile || '.env'
+  try {
+    process.loadEnvFile(envPath)
+  } catch (err) {
+    // File doesn't exist or can't be loaded, that's okay
+  }
+  return envPath
+}
+
+/**
+ * Load and validate tokens from environment
+ * @param {{ values: Record<string, string | boolean | undefined> }} args - Parsed arguments from parseArgs
+ * @returns {{ clientId: string, refreshToken: string, accessToken: string, envFile: string }}
+ * @throws Exits process if tokens are missing
+ */
+export function loadTokensFromEnv (args) {
+  const envFile = loadEnvFile(args.values['env-file'] ? String(args.values['env-file']) : undefined)
+
+  const clientId = String(args.values['client-id'] || process.env['YOTO_CLIENT_ID'] || DEFAULT_CLIENT_ID)
+  const refreshToken = String(process.env['YOTO_REFRESH_TOKEN'] || '')
+  const accessToken = String(process.env['YOTO_ACCESS_TOKEN'] || '')
+
+  if (!accessToken || !refreshToken) {
+    console.error('❌ Both access token and refresh token are required')
+    console.error('Provide tokens via:')
+    console.error('  - Environment variables: YOTO_ACCESS_TOKEN and YOTO_REFRESH_TOKEN')
+    console.error('  - .env file (default or specify with --env-file)')
+    console.error('\n💡 Tip: Run yoto-auth to get both tokens')
+    process.exit(1)
+  }
+
+  return { clientId, refreshToken, accessToken, envFile }
+}
+
+/**
+ * Create YotoClient with standard token persistence callbacks
+ * @param {object} options
+ * @param {string} options.clientId - OAuth client ID
+ * @param {string} options.refreshToken - OAuth refresh token
+ * @param {string} options.accessToken - OAuth access token
+ * @param {string} [options.outputFile='.env'] - File to save refreshed tokens to
+ * @returns {YotoClient}
+ */
+export function createYotoClient ({ clientId, refreshToken, accessToken, outputFile = '.env' }) {
+  return new YotoClient({
+    clientId,
+    refreshToken,
+    accessToken,
+    onTokenRefresh: async (tokens) => {
+      // Save tokens if they refresh during operation
+      await saveTokensToEnv(outputFile, {
+        access_token: tokens.accessToken,
+        refresh_token: tokens.refreshToken,
+        token_type: 'Bearer',
+        expires_in: tokens.expiresAt - Math.floor(Date.now() / 1000)
+      }, tokens.clientId)
+    },
+    onRefreshStart: () => {
+      console.log('\n🔄 Token refresh triggered...')
+    },
+    onRefreshError: () => {},
+    onInvalid: () => {}
+  })
+}
+
+/**
+ * Standard error handler for CLI tools
+ * @param {any} error
+ */
+export function handleCliError (error) {
+  console.error('\n❌ Error:')
+  console.error(`Message: ${error.message}`)
+
+  // Show detailed error information if available
+  if (error.statusCode) {
+    console.error(`Status Code: ${error.statusCode}`)
+  }
+
+  if (error.body?.error) {
+    console.error(`Error: ${error.body.error}`)
+  }
+
+  if (error.body?.error_description) {
+    console.error(`Description: ${error.body.error_description}`)
+  }
+
+  if (error.body && typeof error.body === 'object') {
+    console.error('\nFull error response:')
+    console.error(JSON.stringify(error.body, null, 2))
+  }
+
+  process.exit(1)
+}
+
+/**
+ * Print CLI tool header with title
+ * @param {string} title - The title to display
+ */
+export function printHeader (title) {
+  console.log(`🎵 ${title}`)
+  console.log('='.repeat(60))
+}

package/bin/lib/token-helpers.d.ts

@@ -0,0 +1,14 @@
+export function formatTimestamp(timestamp: number): string;
+export function checkExpiration(exp: number, bufferSeconds?: number): {
+    expired: boolean;
+    message: string;
+};
+export function checkTokenExpiration(token: string, bufferSeconds?: number): {
+    expired: boolean;
+    message: string;
+};
+export function decodeJwt(token: string): any;
+export function saveTokensToEnv(filename: string, tokens: YotoTokenResponse, clientId: string): Promise<void>;
+export function sleep(ms: number): Promise<any>;
+import type { YotoTokenResponse } from '../../lib/api-endpoints/auth.js';
+//# sourceMappingURL=token-helpers.d.ts.map

package/bin/lib/token-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-helpers.d.ts","sourceRoot":"","sources":["token-helpers.js"],"names":[],"mappings":"AAaA,2CAHW,MAAM,GACJ,MAAM,CAKlB;AAQD,qCAJW,MAAM,kBACN,MAAM,GACJ;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,CAmB/C;AAQD,4CAJW,MAAM,kBACN,MAAM,GACJ;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,CAa/C;AAOD,iCAHW,MAAM,GACJ,GAAG,CASf;AAQD,0CAJW,MAAM,UACN,iBAAiB,YACjB,MAAM,iBA8DhB;AAMD,0BAFW,MAAM,gBAIhB;uCArJmC,iCAAiC"}

package/bin/lib/token-helpers.js

@@ -0,0 +1,151 @@
+/**
+ * @import {YotoTokenResponse} from '../../lib/api-endpoints/auth.js'
+ */
+
+import { promises as fs } from 'node:fs'
+import { join } from 'node:path'
+import { jwtDecode } from 'jwt-decode'
+
+/**
+ * Format timestamp
+ * @param {number} timestamp
+ * @returns {string}
+ */
+export function formatTimestamp (timestamp) {
+  const date = new Date(timestamp * 1000)
+  return date.toISOString()
+}
+
+/**
+ * Check if token is expired
+ * @param {number} exp
+ * @param {number} bufferSeconds
+ * @returns {{expired: boolean, message: string}}
+ */
+export function checkExpiration (exp, bufferSeconds = 30) {
+  const now = Math.floor(Date.now() / 1000)
+  const timeUntilExpiry = exp - now
+
+  if (timeUntilExpiry < 0) {
+    return { expired: true, message: `Expired ${Math.abs(timeUntilExpiry)} seconds ago` }
+  } else if (timeUntilExpiry < bufferSeconds) {
+    return { expired: true, message: `Expires in ${timeUntilExpiry} seconds (within buffer)` }
+  } else {
+    const minutes = Math.floor(timeUntilExpiry / 60)
+    const hours = Math.floor(minutes / 60)
+    if (hours > 0) {
+      return { expired: false, message: `Valid for ${hours} hour(s) ${minutes % 60} minute(s)` }
+    } else {
+      return { expired: false, message: `Valid for ${minutes} minute(s)` }
+    }
+  }
+}
+
+/**
+ * Check if a JWT token is expired or about to expire
+ * @param {string} token - JWT token to check
+ * @param {number} bufferSeconds - Seconds before expiration to consider expired
+ * @returns {{expired: boolean, message: string}}
+ */
+export function checkTokenExpiration (token, bufferSeconds = 30) {
+  try {
+    const decoded = jwtDecode(token)
+    if (!decoded.exp) {
+      return { expired: true, message: 'Token has no expiration claim' }
+    }
+
+    return checkExpiration(decoded.exp, bufferSeconds)
+  } catch (err) {
+    return { expired: true, message: 'Unable to decode token' }
+  }
+}
+
+/**
+ * Decode a JWT token without verification
+ * @param {string} token
+ * @returns {any}
+ */
+export function decodeJwt (token) {
+  try {
+    return jwtDecode(token)
+  } catch (err) {
+    const error = /** @type {any} */ (err)
+    throw new Error(`Failed to decode JWT: ${error.message}`)
+  }
+}
+
+/**
+ * Save tokens to .env file
+ * @param {string} filename
+ * @param {YotoTokenResponse} tokens
+ * @param {string} clientId
+ */
+export async function saveTokensToEnv (filename, tokens, clientId) {
+  const cwd = process.cwd()
+  const filePath = join(cwd, filename)
+
+  let existingContent = ''
+
+  // Read existing .env file if it exists
+  try {
+    existingContent = await fs.readFile(filePath, 'utf8')
+  } catch (err) {
+    // File doesn't exist, that's okay
+  }
+
+  // Parse existing content and remove old Yoto tokens (including comment lines)
+  const lines = existingContent.split('\n').filter(line => {
+    const trimmed = line.trim()
+    return !trimmed.startsWith('YOTO_ACCESS_TOKEN=') &&
+           !trimmed.startsWith('YOTO_REFRESH_TOKEN=') &&
+           !trimmed.startsWith('YOTO_CLIENT_ID=') &&
+           !trimmed.startsWith('# Yoto API tokens') &&
+           !trimmed.startsWith('# Saved at:') &&
+           !trimmed.startsWith('# Access token expires:')
+  })
+
+  // Remove trailing empty lines
+  while (lines.length > 0) {
+    const lastLine = lines[lines.length - 1]
+    if (lastLine && lastLine.trim() === '') {
+      lines.pop()
+    } else {
+      break
+    }
+  }
+
+  // Get token expiration for comment
+  let expirationComment = ''
+  try {
+    const decoded = decodeJwt(tokens.access_token)
+    if (decoded.exp) {
+      expirationComment = `# Access token expires: ${formatTimestamp(decoded.exp)}\n`
+    }
+  } catch (err) {
+    // If we can't decode, just skip the expiration comment
+  }
+
+  const now = new Date().toISOString()
+
+  // Add new tokens (only add leading blank line if file has content)
+  if (lines.length > 0 && lines[lines.length - 1] !== '') {
+    lines.push('')
+  }
+  lines.push('# Yoto API tokens')
+  lines.push(`# Saved at: ${now}`)
+  if (expirationComment) lines.push(expirationComment.trim())
+  lines.push(`YOTO_ACCESS_TOKEN=${tokens.access_token}`)
+  lines.push(`YOTO_REFRESH_TOKEN=${tokens.refresh_token}`)
+  lines.push(`YOTO_CLIENT_ID=${clientId}`)
+
+  // Write back to file
+  await fs.writeFile(filePath, lines.join('\n'), 'utf8')
+}
+
+/**
+ * Sleep for a specified number of milliseconds
+ * @param {number} ms
+ */
+export async function sleep (ms) {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}

package/bin/refresh-token.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=refresh-token.d.ts.map

package/bin/refresh-token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refresh-token.d.ts","sourceRoot":"","sources":["refresh-token.js"],"names":[],"mappings":""}

package/bin/refresh-token.js

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+
+/**
+ * @import { ArgscloptsParseArgsOptionsConfig } from 'argsclopts'
+ */
+
+import { printHelpText } from 'argsclopts'
+import { parseArgs } from 'node:util'
+import { YotoClient } from '../index.js'
+import { pkg } from '../lib/pkg.cjs'
+import { saveTokensToEnv } from './lib/token-helpers.js'
+import {
+  getCommonOptions,
+  loadEnvFile,
+  printHeader,
+  handleCliError
+} from './lib/cli-helpers.js'
+import { DEFAULT_CLIENT_ID } from '../lib/api-endpoints/constants.js'
+
+/** @type {ArgscloptsParseArgsOptionsConfig} */
+const options = {
+  ...getCommonOptions(),
+  'refresh-token': {
+    type: 'string',
+    short: 'r',
+    help: 'Refresh token to use (or set YOTO_REFRESH_TOKEN env var)'
+  },
+  output: {
+    type: 'string',
+    short: 'o',
+    default: '.env',
+    help: 'Output file for tokens (default: .env)'
+  },
+  force: {
+    type: 'boolean',
+    short: 'f',
+    help: 'Force refresh even if token is not expired'
+  }
+}
+
+const args = parseArgs({ options, strict: false })
+
+if (args.values['help']) {
+  await printHelpText({
+    options,
+    name: 'yoto-refresh-token',
+    version: pkg.version,
+    exampleFn: ({ name }) => `    Yoto token refresh helper\n\n    Examples:\n      ${name}\n      ${name} --force\n      ${name} --env-file .env.local\n`
+  })
+  process.exit(0)
+}
+
+// Load .env file if specified or use default
+const outputFile = String(args.values['output'] || '.env')
+loadEnvFile(args.values['env-file'] ? String(args.values['env-file']) : outputFile)
+
+const clientId = String(args.values['client-id'] || process.env['YOTO_CLIENT_ID'] || DEFAULT_CLIENT_ID)
+const refreshToken = String(args.values['refresh-token'] || process.env['YOTO_REFRESH_TOKEN'] || '')
+const accessToken = String(process.env['YOTO_ACCESS_TOKEN'] || '')
+const force = Boolean(args.values['force'])
+
+if (!refreshToken) {
+  console.error('❌ No refresh token found')
+  console.error('Provide a refresh token via:')
+  console.error('  - Command line flag: --refresh-token')
+  console.error('  - Environment variable: YOTO_REFRESH_TOKEN')
+  console.error('  - .env file (loaded automatically or specify with --env-file)')
+  console.error('\n💡 Tip: Run yoto-auth to get a refresh token')
+  process.exit(1)
+}
+
+if (!accessToken) {
+  console.error('❌ No access token found')
+  console.error('Provide an access token via:')
+  console.error('  - Environment variable: YOTO_ACCESS_TOKEN')
+  console.error('  - .env file (loaded automatically or specify with --env-file)')
+  console.error('\n💡 Tip: Run yoto-auth to get an access token')
+  process.exit(1)
+}
+
+async function main () {
+  printHeader('Yoto Token Refresh')
+
+  try {
+    // Create client with token refresh handler
+    const client = new YotoClient({
+      clientId,
+      refreshToken,
+      accessToken,
+      onTokenRefresh: async (tokens) => {
+        // This will be called after successful refresh
+        // Convert RefreshSuccessEvent to YotoTokenResponse format
+        await saveTokensToEnv(outputFile, {
+          access_token: tokens.accessToken,
+          refresh_token: tokens.refreshToken,
+          token_type: 'Bearer',
+          expires_in: tokens.expiresAt - Math.floor(Date.now() / 1000)
+        }, tokens.clientId)
+      },
+      onRefreshStart: () => {
+        console.log('\n🔄 Refreshing tokens...')
+      },
+      onRefreshError: (error) => {
+        console.error('\n⚠️  Token refresh failed:', error.message)
+      },
+      onInvalid: (error) => {
+        console.error('\n❌ Refresh token is invalid or expired')
+        console.error(error.message)
+        console.error('\n💡 Tip: Run yoto-auth to get a new set of tokens.')
+      }
+    })
+
+    // Check if token needs refresh
+    if (!force && client.token.isValid()) {
+      const timeRemaining = client.token.getTimeRemaining()
+      const minutes = Math.floor(timeRemaining / 60)
+      const hours = Math.floor(minutes / 60)
+      if (hours > 0) {
+        console.log(`\n✅ Token is still valid for ${hours} hour(s) ${minutes % 60} minute(s)`)
+      } else {
+        console.log(`\n✅ Token is still valid for ${minutes} minute(s)`)
+      }
+      console.log('💡 Use --force to refresh anyway')
+      process.exit(0)
+    }
+
+    if (force) {
+      console.log('\n⚡ Forcing token refresh...')
+    } else {
+      console.log('\n⚠️  Token needs refresh')
+    }
+
+    // Manually trigger refresh
+    const tokens = await client.token.refresh()
+
+    console.log('\n✅ Token refresh successful!')
+
+    // Show expiration info
+    const expiresDate = new Date(tokens.expiresAt * 1000)
+    const timeRemaining = tokens.expiresAt - Math.floor(Date.now() / 1000)
+    const minutes = Math.floor(timeRemaining / 60)
+    const hours = Math.floor(minutes / 60)
+
+    if (hours > 0) {
+      console.log(`⏰ New token valid for ${hours} hour(s) ${minutes % 60} minute(s)`)
+    } else {
+      console.log(`⏰ New token valid for ${minutes} minute(s)`)
+    }
+    console.log(`   Expires: ${expiresDate.toISOString()}`)
+
+    console.log(`\n✨ Tokens saved to ${outputFile}`)
+    console.log('\nYou can now use these environment variables:')
+    console.log('  - YOTO_ACCESS_TOKEN')
+    console.log('  - YOTO_REFRESH_TOKEN')
+    console.log('  - YOTO_CLIENT_ID')
+
+    process.exit(0)
+  } catch (error) {
+    handleCliError(error)
+  }
+}
+
+// Run the main function
+await main().catch(err => {
+  console.error('\n❌ Unexpected error:')
+  console.error(err)
+  process.exit(1)
+})

package/bin/token-info.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=token-info.d.ts.map

package/bin/token-info.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-info.d.ts","sourceRoot":"","sources":["token-info.js"],"names":[],"mappings":""}