SDK Reference

npm install @specify-sh/sdk

import Specify, { ImageFormat } from '@specify-sh/sdk';

// Initialize the SDK
const specify = new Specify({
  publisherKey: 'spk_your_publisher_key_here'
});

// Serve an ad to a wallet address
try {
  const ad = await specify.serve('0x742d35Cc6634C0532925a3b8D57C11E4a3e1A510', ImageFormat.LANDSCAPE);
  if (ad) {
    console.log('Ad content:', ad);
    console.log('Headline:', ad.headline);
    console.log('Content:', ad.content);
    console.log('Image URL:', ad.imageUrl);
    console.log('CTA:', ad.ctaLabel, '->', ad.ctaUrl);
  } else {
    console.log('No ad found for this wallet');
  }
} catch (error) {
  console.error('Error serving ad:', error);
}

const specify = new Specify(config: SpecifyInitConfig);

const specify = new Specify({
  publisherKey: 'spk_1234567890abcdef1234567890abcdef'
});

serve(
  addressOrAddresses: Address | Address[], 
  imageFormat: ImageFormat
): Promise<SpecifyAd | null

import { ImageFormat } from 'specify-publisher-sdk';

const ad = await specify.serve(
  '0x742d35Cc6634C0532925a3b8D57C11E4a3e1A510',
  ImageFormat.LANDSCAPE
);

const ad = await specify.serve([
  '0x742d35Cc6634C0532925a3b8D57C11E4a3e1A510',
  '0x8ba1f109551bD432803012645Hac136c0532925a',
  '0x1234567890123456789012345678901234567890'
], ImageFormat.LONG_BANNER);

import { AuthenticationError, ValidationError, NotFoundError, APIError, ImageFormat } from 'specify-publisher-sdk';

try {
  const ad = await specify.serve(walletAddress, ImageFormat.LANDSCAPE);
  
  if (ad) {
    // Display the ad
    displayAd(ad);
  } else {
    // Handle no ad case
    showFallbackContent();
  }
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Invalid input:', error.message);
  } else if (error instanceof NotFoundError) {
    console.log('No ad available');
    showFallbackContent();
  } else if (error instanceof AuthenticationError) {
    console.error('Authentication failed. Check your publisher key.');
  } else if (error instanceof APIError) {
    console.error('API error:', error.message);
    showErrorMessage();
  } else {
    console.error('Unexpected error:', error);
  }
}

import React, { useState, useEffect } from 'react';
import Specify, { SpecifyAd, ValidationError, NotFoundError, ImageFormat } from 'specify-publisher-sdk';

const specify = new Specify({
  publisherKey: process.env.REACT_APP_SPECIFY_PUBLISHER_KEY!
});

interface AdComponentProps {
  walletAddress: string;
  imageFormat?: ImageFormat;
}

const AdComponent: React.FC<AdComponentProps> = ({ 
  walletAddress, 
  imageFormat = ImageFormat.LANDSCAPE 
}) => {
  const [ad, setAd] = useState<SpecifyAd | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    const fetchAd = async () => {
      try {
        setLoading(true);
        setError(null);
        
        const adData = await specify.serve(walletAddress, imageFormat);
        setAd(adData);
      } catch (err) {
        if (err instanceof ValidationError) {
          setError('Invalid wallet address');
        } else if (err instanceof NotFoundError) {
          setAd(null); // No ad available
        } else {
          setError('Failed to load ad');
        }
      } finally {
        setLoading(false);
      }
    };

    if (walletAddress) {
      fetchAd();
    }
  }, [walletAddress, imageFormat]);

  if (loading) return <div>Loading ad...</div>;
  if (error) return <div>Error: {error}</div>;
  if (!ad) return <div>No ad available</div>;

  return (
    <div className="ad-container">
      <div className="ad-header">
        <img src={ad.communityLogo} alt={ad.communityName} className="community-logo" />
        <span className="community-name">{ad.communityName}</span>
      </div>
      <h3 className="ad-headline">{ad.headline}</h3>
      <img src={ad.imageUrl} alt={ad.headline} className="ad-image" />
      <p className="ad-content">{ad.content}</p>
      <a href={ad.ctaUrl} className="ad-cta" target="_blank" rel="noopener noreferrer">
        {ad.ctaLabel}
      </a>
    </div>
  );
};

export default AdComponent;

import express from 'express';
import Specify, { ValidationError, NotFoundError, ImageFormat } from 'specify-publisher-sdk';

const app = express();
const specify = new Specify({
  publisherKey: process.env.SPECIFY_PUBLISHER_KEY!
});

app.get('/api/ads/:walletAddress', async (req, res) => {
  try {
    const { walletAddress } = req.params;
    const { format = 'LANDSCAPE' } = req.query;
    
    const ad = await specify.serve(walletAddress, format as ImageFormat);
    
    if (ad) {
      res.json({ 
        success: true, 
        ad: {
          ...ad,
          // You can transform or add additional fields here
          timestamp: new Date().toISOString()
        }
      });
    } else {
      res.status(404).json({ success: false, message: 'No ad found' });
    }
  } catch (error) {
    if (error instanceof ValidationError) {
      res.status(400).json({ 
        success: false, 
        message: error.message,
        details: error.details 
      });
    } else if (error instanceof NotFoundError) {
      res.status(404).json({ success: false, message: 'No ad found' });
    } else {
      console.error('Server error:', error);
      res.status(500).json({ success: false, message: 'Internal server error' });
    }
  }
});

app.listen(3000, () => {
  console.log('Server running on port 3000');
});