macro_api

macro_api

A comprehensive API toolkit for various services including YouTube, Spotify, Valorant, DeepSeek, and ChatGPT.

License: Apache 2.0 npm version TypeScript 4.9.5

Installation

npm install macro_api

or

yarn add macro_api

Features

• YouTube Notification System: Monitor YouTube channels and send notifications through Discord webhooks
• Spotify API Integration: Complete wrapper for interacting with Spotify API endpoints
• Valorant Stats: System to get Valorant player statistics and game data
• DeepSeek API: Interface for interacting with DeepSeek AI models
• ChatGPT API: Interface for interacting with OpenAI's ChatGPT models

Usage Examples

YouTube Notification System

Monitor a YouTube channel for new videos and send notifications to Discord:

TypeScript

import { YouTubeNotify } from 'macro_api';
// Create a new YouTube notification monitor
const ytNotifier = new YouTubeNotify({
channelId: 'UC_x5XG1OV2P6uZZ5FSM9Ttw', // Google Developers channel
apiKey: 'YOUR_YOUTUBE_API_KEY',
checkIntervalMs: 600000 // 10 minutes
});
// Set up Discord webhook
ytNotifier.setWebhook('https://discord.com/api/webhooks/your-webhook-url');
// Start monitoring
ytNotifier.startMonitoring();
// To stop monitoring
// ytNotifier.stopMonitoring();
// To manually check for new videos
const newVideos = await ytNotifier.manualCheck();
console.log(Found ${newVideos.length} new videos);

Spotify API

Interact with Spotify API to get tracks, create playlists, and more:

TypeScript

import { SpotifyAPI } from 'macro_api';
// Create a new Spotify API client
const spotify = new SpotifyAPI({
clientId: 'YOUR_CLIENT_ID',
clientSecret: 'YOUR_CLIENT_SECRET',
redirectUri: 'YOUR_REDIRECT_URI'
});
// Get authorization URL
const authUrl = spotify.getAuthorizationUrl([
'user-read-private',
'playlist-modify-public'
]);
console.log(Please authorize the app: ${authUrl});
// Exchange authorization code for access token
await spotify.exchangeCode('AUTHORIZATION_CODE');
// Get the current user
const user = await spotify.getCurrentUser();
console.log(Logged in as: ${user.display_name});
// Search for tracks
const searchResults = await spotify.search('Metallica', ['track'], { limit: 5 });
// Create a playlist and add tracks
const playlist = await spotify.createPlaylist(user.id, 'Awesome Playlist', true, 'Created with macro_api');
await spotify.addTracksToPlaylist(
playlist.id,
searchResults.tracks.items.map((track: any) => track.uri)
);

Valorant Stats

Get player statistics and information from Valorant:

TypeScript

import { Valorant } from 'macro_api';
// Create a new Valorant API client
const valorant = new Valorant();
// Get player account details
const account = await valorant.getAccount('Username', 'Tag');
console.log(Player ID: ${account.puuid});
// Get player MMR details
const mmr = await valorant.getMMR('Username', 'Tag');
console.log(Current Rank: ${mmr.currenttierpatched});
// Get player's match history
const matches = await valorant.getMatchHistory('na', 'Username', 'Tag', { queue: 'competitive' });
console.log(Last ${matches.length} matches:);
// Get player's comprehensive stats
const stats = await valorant.getPlayerStats('na', 'Username', 'Tag');
console.log(Win Rate: ${stats.overview.winRate});
console.log(K/D Ratio: ${stats.combat.kd});
console.log(Favorite Agent: ${stats.favorites.agents[0]?.agent});

DeepSeek API

Interact with DeepSeek AI models:

TypeScript

import { DeepSeek } from 'macro_api';
// Create a new DeepSeek API client
const deepseek = new DeepSeek({
apiKey: 'YOUR_DEEPSEEK_API_KEY'
});
// Simple chat with DeepSeek
const response = await deepseek.chat(
'What are the main differences between TypeScript and JavaScript?',
'You are a helpful programming assistant'
);
console.log(response);
// Generate code with DeepSeek
const code = await deepseek.generateCode(
'Write a function to calculate the Fibonacci sequence'
);
console.log(code.choices[0]?.text);
// Full conversation
const conversation = await deepseek.conversation([
{ role: 'system', content: 'You are a helpful assistant.' },
{ role: 'user', content: 'What is the capital of France?' },
{ role: 'assistant', content: 'The capital of France is Paris.' },
{ role: 'user', content: 'And what is the population of Paris?' }
]);
console.log(conversation);

GitHub API

Interact with GitHub API to manage repositories, issues, pull requests, and more:

TypeScript

import { GitHubAPI } from 'macro_api';
// Create a new GitHub API client
const github = new GitHubAPI({
token: 'YOUR_GITHUB_PERSONAL_ACCESS_TOKEN'
});
// Get user information
const user = await github.getUser('octocat');
console.log(Username: ${user.login}, Followers: ${user.followers});
// Get repositories for a user
const repos = await github.getUserRepos('octocat', { sort: 'updated', per_page: 5 });
console.log(Found ${repos.length} repositories);
// Get a specific repository
const repo = await github.getRepo('octocat', 'Hello-World');
console.log(Repository: ${repo.name}, Stars: ${repo.stargazers_count});
// Create an issue
const issue = await github.createIssue('your-username', 'your-repo', {
title: 'Found a bug',
body: 'This is a description of the bug',
labels: ['bug', 'important']
});
console.log(Created issue #${issue.number}: ${issue.title});
// Create a pull request
const pr = await github.createPullRequest('your-username', 'your-repo', {
title: 'Fix bug in authentication',
head: 'fix-auth-bug',
base: 'main',
body: 'This PR fixes the authentication issue reported in #42'
});
console.log(Created PR #${pr.number});
// Search repositories
const searchResults = await github.searchRepositories('javascript framework stars:>1000', {
sort: 'stars',
order: 'desc',
per_page: 5
});
console.log(Found ${searchResults.total_count} repositories);
searchResults.items.forEach(item => {
console.log(${item.full_name} - ${item.stargazers_count} stars);
});
// Create a release
const release = await github.createRelease('your-username', 'your-repo', {
tag_name: 'v1.0.0',
name: 'Version 1.0.0',
body: 'First stable release with the following features...',
draft: false,
prerelease: false
});
console.log(Created release: ${release.name}, Download URL: ${release.zipball_url});

ChatGPT API

Interact with OpenAI's models:

TypeScript

import { ChatGPT } from 'macro_api';
// Create a new ChatGPT API client
const chatgpt = new ChatGPT({
apiKey: 'YOUR_OPENAI_API_KEY'
});
// Simple chat with ChatGPT
const response = await chatgpt.chat(
'Explain the concept of quantum computing in simple terms',
'You are a helpful assistant that explains complex topics in simple language'
);
console.log(response);
// Using function calling
const functionCall = await chatgpt.withFunctions(
'What is the weather like in Berlin today?',
[
{
name: 'get_weather',
description: 'Get the current weather in a location',
parameters: {
type: 'object',
properties: {
location: {
type: 'string',
description: 'The city and state, e.g., San Francisco, CA'
}
},
required: ['location']
}
}
]
);
console.log(functionCall);
// Generate embeddings
const embeddings = await chatgpt.embed('Hello world');
console.log(Embedding dimension: ${embeddings[0].embedding.length});

API Documentation

YouTubeNotify

The YouTube notification system monitors YouTube channels for new videos and sends notifications via Discord webhooks.

<h4 class="font-medium mb-2 text-gray-800 dark:text-gray-200">Constructor</h4>
<div class="bg-gray-100 dark:bg-gray-800 rounded-lg overflow-hidden mb-4">
  <pre class="p-4 overflow-x-auto text-sm font-mono">

new YouTubeNotify(options: { channelId: string; // YouTube channel ID to monitor apiKey: string; // YouTube Data API key checkIntervalMs?: number; // Check interval in milliseconds (default: 600000 - 10 minutes) maxResults?: number; // Maximum number of videos to fetch (default: 5) includeDescription?: boolean; // Include video description in notifications (default: false) mentionEveryone?: boolean; // Mention @everyone in notifications (default: false) })

<h4 class="font-medium mb-2 text-gray-800 dark:text-gray-200">Methods</h4>
<ul class="list-disc pl-5 text-gray-700 dark:text-gray-300">
  <li><code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">setWebhook(url: string)</code>: Set the Discord webhook URL for notifications</li>
  <li><code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">startMonitoring()</code>: Start monitoring the channel for new videos</li>
  <li><code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">stopMonitoring()</code>: Stop monitoring the channel</li>
  <li><code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">manualCheck()</code>: Manually check for new videos and return any found</li>
</ul>

SpotifyAPI

Complete wrapper for the Spotify API to interact with all endpoints.

<h4 class="font-medium mb-2 text-gray-800 dark:text-gray-200">Constructor</h4>
<div class="bg-gray-100 dark:bg-gray-800 rounded-lg overflow-hidden mb-4">
  <pre class="p-4 overflow-x-auto text-sm font-mono">

new SpotifyAPI(options: { clientId: string; // Spotify API client ID clientSecret: string; // Spotify API client secret redirectUri?: string; // OAuth redirect URI (required for authorization) })

<h4 class="font-medium mb-2 text-gray-800 dark:text-gray-200">Authentication Methods</h4>
<ul class="list-disc pl-5 text-gray-700 dark:text-gray-300 mb-4">
  <li><code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">getAuthorizationUrl(scopes: string[], state?: string)</code>: Get the authorization URL for OAuth login</li>
  <li><code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">exchangeCode(code: string)</code>: Exchange authorization code for access token</li>
  <li><code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">setAccessToken(token: string, expiresIn: number, refreshToken?: string)</code>: Set access token manually</li>
  <li><code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">refreshAccessToken()</code>: Refresh the access token using the refresh token</li>
</ul>

<h4 class="font-medium mb-2 text-gray-800 dark:text-gray-200">API Methods</h4>
<ul class="list-disc pl-5 text-gray-700 dark:text-gray-300">
  <li><strong>User:</strong> <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">getCurrentUser()</code>, <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">getUser(userId: string)</code></li>
  <li><strong>Tracks:</strong> <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">getTrack(trackId: string)</code>, <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">getTracks(trackIds: string[])</code></li>
  <li><strong>Albums:</strong> <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">getAlbum(albumId: string)</code>, <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">getAlbumTracks(albumId: string, params?)</code></li>
  <li><strong>Artists:</strong> <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">getArtist(artistId: string)</code>, <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">getArtistAlbums(artistId: string, params?)</code>, <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">getArtistTopTracks(artistId: string, market?)</code></li>
  <li><strong>Playlists:</strong> <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">getPlaylist(playlistId: string)</code>, <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">getPlaylistTracks(playlistId: string, params?)</code>, <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">createPlaylist(userId: string, name: string, isPublic?, description?)</code>, <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">addTracksToPlaylist(playlistId: string, trackUris: string[], position?)</code></li>
  <li><strong>Player:</strong> <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">getCurrentlyPlaying()</code>, <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">getPlaybackState()</code>, <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">controlPlayback(action: 'play' | 'pause' | 'next' | 'previous', deviceId?)</code></li>
  <li><strong>Search:</strong> <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">search(query: string, types: Array<'album' | 'artist' | 'playlist' | 'track'>, params?)</code></li>
  <li><strong>Recommendations:</strong> <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">getRecommendations(params)</code></li>
</ul>

Valorant

API client for retrieving Valorant player statistics and game data.

<h4 class="font-medium mb-2 text-gray-800 dark:text-gray-200">Constructor</h4>
<div class="bg-gray-100 dark:bg-gray-800 rounded-lg overflow-hidden mb-4">
  <pre class="p-4 overflow-x-auto text-sm font-mono">

new Valorant(apiKey?: string) // Optional API key for Henrik's Valorant API

<h4 class="font-medium mb-2 text-gray-800 dark:text-gray-200">Methods</h4>
<ul class="list-disc pl-5 text-gray-700 dark:text-gray-300">
  <li><strong>Account:</strong> <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">getAccount(name: string, tag: string)</code></li>
  <li><strong>MMR:</strong> <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">getMMR(name: string, tag: string, options?: { region?: string })</code></li>
  <li><strong>Match History:</strong> <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">getMatchHistory(region: string, name: string, tag: string, options?)</code></li>
  <li><strong>Stats:</strong> <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">getLifetimeStats(region: string, name: string, tag: string)</code>, <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">getPlayerStats(region: string, name: string, tag: string, mode?)</code></li>
  <li><strong>Match Data:</strong> <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">getMatch(matchId: string)</code></li>
  <li><strong>Leaderboards:</strong> <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">getLeaderboard(options: { region: string, size?: number, startIndex?: number })</code></li>
  <li><strong>Game Data:</strong> <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">getAgents(language?)</code>, <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">getWeapons(language?)</code>, <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">getMaps(language?)</code>, <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">getStatus(region?)</code></li>
</ul>

DeepSeek

Client for interacting with DeepSeek's AI models.

<h4 class="font-medium mb-2 text-gray-800 dark:text-gray-200">Constructor</h4>
<div class="bg-gray-100 dark:bg-gray-800 rounded-lg overflow-hidden mb-4">
  <pre class="p-4 overflow-x-auto text-sm font-mono">

new DeepSeek(config: { apiKey: string; // DeepSeek API key baseUrl?: string; // API base URL (default: 'https://api.deepseek.com/v1') })

<h4 class="font-medium mb-2 text-gray-800 dark:text-gray-200">Methods</h4>
<ul class="list-disc pl-5 text-gray-700 dark:text-gray-300">
  <li><strong>Chat:</strong> <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">createChatCompletion(options)</code>, <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">createStreamingChatCompletion(options, onData, onError?, onEnd?)</code></li>
  <li><strong>Completions:</strong> <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">createCompletion(options)</code></li>
  <li><strong>Embeddings:</strong> <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">createEmbeddings(options)</code></li>
  <li><strong>Helper Methods:</strong> <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">chat(prompt, systemPrompt?, model?)</code>, <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">conversation(messages, model?)</code>, <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">generateCode(prompt, options?)</code></li>
  <li><strong>Models:</strong> <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">listModels()</code></li>
</ul>

ChatGPT

Client for interacting with OpenAI's models.

<h4 class="font-medium mb-2 text-gray-800 dark:text-gray-200">Constructor</h4>
<div class="bg-gray-100 dark:bg-gray-800 rounded-lg overflow-hidden mb-4">
  <pre class="p-4 overflow-x-auto text-sm font-mono">

new ChatGPT(config: { apiKey: string; // OpenAI API key organizationId?: string; // OpenAI organization ID baseUrl?: string; // API base URL (default: 'https://api.openai.com/v1') })

<h4 class="font-medium mb-2 text-gray-800 dark:text-gray-200">Methods</h4>
<ul class="list-disc pl-5 text-gray-700 dark:text-gray-300">
  <li><strong>Chat:</strong> <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">createChatCompletion(options)</code>, <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">createStreamingChatCompletion(options, onData, onError?, onEnd?)</code></li>
  <li><strong>Embeddings:</strong> <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">createEmbeddings(options)</code>, <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">embed(text, model?)</code></li>
  <li><strong>Helper Methods:</strong> <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">chat(prompt, systemPrompt?, model?)</code>, <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">conversation(messages, model?)</code>, <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">withFunctions(prompt, functions, model?)</code>, <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">withTools(prompt, tools, model?)</code></li>
  <li><strong>Models:</strong> <code class="px-1 py-0.5 bg-gray-200 dark:bg-gray-700 rounded text-sm font-mono">listModels()</code></li>
</ul>

License

Apache License 2.0. See the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Author

CPTCR -

Changelog

[3.0.0] - 2025-06-10

This is a major feature release, introducing several new service integrations and a complete overhaul of the core architecture to improve performance, developer experience, and reliability.

Added

New API Integrations

• Stripe: Added a comprehensive module for the Stripe API.

  • Includes methods for creating payment intents, managing customers, and handling subscriptions.

• Slack: Added support for the Slack API.

  • Includes methods for sending messages to channels and users, creating rich message blocks, and managing conversations.

• SendGrid: Added a module for the SendGrid API.

  • Includes methods for sending transactional emails using dynamic templates and managing contact lists.

• Vercel: Added support for the Vercel API to enable CI/CD and deployment workflows.

  • Includes methods for triggering deployments, listing projects, and managing deployment domains.

• AWS S3: Added a powerful module for Amazon S3.

  • Includes methods for uploading, downloading, and deleting objects, as well as listing bucket contents.

• Docker Hub: Added support for the Docker Hub API.

  • Includes methods for inspecting repository details, listing image tags, and checking image metadata.

Architectural & DevOps Enhancements

• Intelligent Caching System:

  • Implemented a new caching layer to reduce redundant API calls and improve performance.
  • Supports a default in-memory cache for ease of use.
  • Supports optional integration with external Redis instances for distributed applications.

• Standardized Error Framework:

  • Introduced a hierarchy of custom error classes (AuthenticationError, RateLimitError, NotFoundError, ServiceUnreachableError) that extends a base MacroApiError. This provides consistent and predictable error handling across all integrations.

• Enterprise-Grade Request Management:

  • Implemented an automatic retry mechanism with exponential backoff for handling transient network errors.
  • Added request batching capabilities for select APIs (e.g., AWS S3 object deletion) to improve bulk operation performance.

• CI/CD & Quality Assurance:

  • Integrated a full CI/CD pipeline using GitHub Actions to automate testing, linting, and package publishing, ensuring higher code quality and reliability.

Changed

• BREAKING CHANGE: The initialization process for all API clients has been standardized to accommodate new features like caching and request management. Please consult the documentation for updated configuration options.