@iris-technologies/api

@iris-technologies/api

A TypeScript client library for the Iris advertising API.

Installation

npm install @iris-technologies/api

Usage

import { IrisClient } from '@iris-technologies/api';

// Initialize the client
const client = new IrisClient('your-api-key', ['politics', 'gambling']);

// Get an advertisement
const ad = await client.getAd(
  'user input context',
  'assistant response context', 
  'user-123'
);

if (ad) {
  console.log('Ad text:', ad.text);
  console.log('Ad URL:', ad.url);
} else {
  console.log('No ad available');
}

API Reference

IrisClient

Constructor

new IrisClient(apiKey: string, excludedTopics: string[])

• apiKey: Your Iris API key
• excludedTopics: Array of topic strings to exclude from ads

Methods

getAd(inputPrompt: string, responsePrompt: string, userId: string): Promise<AdResponse | null>

Retrieves a targeted advertisement based on the provided context.

Parameters:

• inputPrompt: The user's input context
• responsePrompt: The assistant's response context
• userId: Unique identifier for the user

Returns:

• AdResponse | null: Advertisement object with text and url properties, or null if no ad is available

updateExcludedTopics(excludedTopics: string[]): void

Updates the list of excluded topics.

getExcludedTopics(): string[]

Returns a copy of the current excluded topics array.

Types

interface AdResponse {
  text: string;
  url: string;
}

Error Handling

The client handles errors silently and logs them to the console. All methods return null or safe defaults when errors occur.

Development

# Install dependencies
npm install

# Build the package
npm run build

# Watch mode for development
npm run dev

# Clean build artifacts
npm run clean

Publishing to NPM

Initial Setup

• Create an NPM account (if you don't have one):

  npm adduser
  

  Or login to existing account:

  npm login
  

• Verify your login:

  npm whoami
  

• Update package.json metadata:

  • Update author field with your information
  • Update repository.url with your actual GitHub repository
  • Update homepage and bugs.url with correct URLs

Pre-Publishing Checklist

Before publishing, ensure:

• All tests pass (when tests are added)
• Code builds successfully (npm run build)
• Version number is updated appropriately
• CHANGELOG is updated (if you maintain one)
• README is up to date
• All dependencies are properly declared
• API endpoint is configured correctly

Publishing Commands

Test Publishing (Dry Run)

# See what would be published without actually publishing
npm run publish:dry-run

Version Management

# Patch version (1.0.0 → 1.0.1) - for bug fixes
npm run version:patch

# Minor version (1.0.0 → 1.1.0) - for new features
npm run version:minor

# Major version (1.0.0 → 2.0.0) - for breaking changes
npm run version:major

Publishing Releases

# Publish patch version (auto-increments and publishes)
npm run publish:patch

# Publish minor version
npm run publish:minor

# Publish major version
npm run publish:major

# Publish beta version (tagged as beta)
npm run publish:beta

Manual Publishing

# Manual version bump
npm version patch  # or minor/major

# Manual publish
npm publish

# Publish with specific tag
npm publish --tag beta

Release Process

• Make your changes and commit them
• Run tests and ensure everything works
• Choose version type (patch/minor/major following semantic versioning)
• Use publishing command:

  npm run publish:patch  # Most common for bug fixes
  

• Verify publication at https://www.npmjs.com/package/@iris-technologies/api

NPM Scripts Reference

Script	Description
npm run build	Compile TypeScript to JavaScript
npm run dev	Watch mode for development
npm run clean	Remove build artifacts
npm run version:patch	Bump patch version
npm run version:minor	Bump minor version
npm run version:major	Bump major version
npm run publish:patch	Version bump + publish patch
npm run publish:minor	Version bump + publish minor
npm run publish:major	Version bump + publish major
npm run publish:beta	Publish with beta tag
npm run publish:dry-run	Test publish without actually publishing

Troubleshooting

Permission denied errors:

npm login
# Re-authenticate and try again

Version already exists:

npm run version:patch  # Increment version first
npm publish

Package name conflicts:

• Scoped packages like @iris-technologies/api require organization membership
• Consider using @your-username/iris-api if @iris organization doesn't exist