@duabalabs/reviews-sdk

npm i @duabalabs/reviews-sdk
# or
pnpm add @duabalabs/reviews-sdk

import { createReviewsClient } from '@duabalabs/reviews-sdk';
 
const reviews = createReviewsClient({
  appKey: process.env.THREEYANAA_APP_KEY!,  // rk_<app>_… — sent as Authorization: Bearer
  // baseUrl defaults to https://api.3y3anaa.com — override for self-host/staging
});

const { review, aggregate } = await reviews.submitReview({
  subjectType: 'product',
  externalId: 'prod_123',
  subjectDisplayName: 'Kente Tote Bag',     // recorded on the subject
  subjectImageUrl: 'https://cdn.example/…',
  subjectUrl: 'https://sellub.com/p/prod_123',
  author: { externalUserId: 'user_42', displayName: 'Ama', role: 'buyer' },
  rating: 5,                                 // 1–5
  title: 'Lovely bag',
  body: 'Beautiful craftsmanship, fast delivery.',
  verified: true,                            // e.g. verified purchase
});
// → { review: Review, aggregate: ReviewAggregate }

const { items, total, hasMore, aggregate } = await reviews.getReviews({
  subjectType: 'product',
  externalId: 'prod_123',
  limit: 20,          // ≤ 100, default 20
  skip: 0,
  sort: 'newest',     // 'newest' | 'helpful' | 'highest' | 'lowest'
});

const agg = await reviews.getAggregate({ subjectType: 'product', externalId: 'prod_123' });
// → { subjectType, externalId, avgRating, reviewCount, ratingBreakdown }

const aggs = await reviews.getAggregates([
  { subjectType: 'product', externalId: 'prod_123' },
  { subjectType: 'product', externalId: 'prod_456' },
]);
// → Array<{ subjectType, externalId, avgRating, reviewCount, ratingBreakdown }>

const { helpfulCount, alreadyVoted } = await reviews.markHelpful({
  reviewId: 'abc123',
  voterExternalUserId: 'user_99',
});

const { review } = await reviews.respondToReview({
  reviewId: 'abc123',
  responderExternalUserId: 'seller_7',
  responderDisplayName: 'Accra Crafts',      // optional
  text: 'Thanks! We’ve refunded the delivery fee.',
});

const { items, total, hasMore } = await reviews.getReviewsByAuthor({
  authorExternalUserId: 'user_42',
  limit: 20,
  skip: 0,
});

const { items, total, hasMore } = await reviews.searchSubjects({
  query: 'Accra Tiles',   // at least 2 characters
  subjectType: 'business', // or 'artisan' — optional
  city: 'Accra',           // optional; region too
  limit: 10,               // ≤ 50, default 10
});
// items: ReviewSubjectMatch[] — subjectType, externalId, displayName, city,
// trustScore, isClaimed, isVerified, profileUrl, …

const { subject, matchedOn, confidence } = await reviews.resolveSubject({
  phone: '0244123456',
});
// matchedOn: 'googlePlaceId' | 'phone' | 'name' | 'name+city' | null
// confidence: 'high' (place id, phone) | 'medium' (name) | null
// subject is null (with a `hint`) when nothing matched

const net = await reviews.getNetworkReviews({ subjectType: 'business', externalId });
 
net.aggregate;       // always complete, on every plan
net.contributors;    // [{ sourceApp, reviewCount, verified }]
net.itemsTruncated;  // true on the free tier — `items` is a sample of 3
net.usage;           // { period, calls, quota, remaining }

const { trustScore, breakdown, calculatedAt } = await reviews.getTrustScore({ externalId });

const { plan, capabilities, usage } = await reviews.getEntitlement();

const hook = await reviews.registerWebhook({
  url: 'https://myshop.com/hooks/3y3anaa',          // https, public address
  events: ['review.moderated', 'review.responded'], // omit for every event
});
// hook.secret is shown ONCE — store it.

import { verifyWebhookSignature } from '@duabalabs/reviews-sdk';
 
app.post('/hooks/3y3anaa', express.raw({ type: 'application/json' }), (req, res) => {
  const ok = verifyWebhookSignature({
    secret: process.env.THREEYANAA_WEBHOOK_SECRET!,
    body: req.body,
    signature: req.header('X-3y3anaa-Signature')!,
    timestamp: req.header('X-3y3anaa-Timestamp')!,
  });
  if (!ok) return res.sendStatus(401);
  res.sendStatus(200); // ack fast; do the work after
});

type SubjectType =
  | 'artisan' | 'business' | 'client'
  | 'product' | 'shop' | 'supplier' | 'courier'
  | 'property'
  | (string & {});   // open union — any string accepted, these are canonical
 
type ReviewerRole =
  | 'artisan' | 'business' | 'client'
  | 'buyer' | 'seller' | 'courier'
  | (string & {});
 
interface ReviewAuthor {
  externalUserId: string;
  displayName?: string;
  role?: ReviewerRole;
}
 
interface RatingBreakdown { 1: number; 2: number; 3: number; 4: number; 5: number }
 
interface ReviewAggregate {
  avgRating: number;
  reviewCount: number;
  ratingBreakdown: RatingBreakdown;
}
 
interface Review {
  id: string;
  subjectType: SubjectType;
  externalId: string;
  rating: number;
  title: string | null;
  body: string | null;
  verified: boolean;
  status: 'published' | 'under_review' | 'rejected';
  author: { externalUserId: string; displayName: string | null; role: ReviewerRole | null };
  helpfulCount: number;
  response: { text: string; byDisplayName: string; at: string } | null;
  createdAt: string;
}

import { ReviewsApiError } from '@duabalabs/reviews-sdk';
 
try {
  await reviews.submitReview({ /* … */ });
} catch (e) {
  if (e instanceof ReviewsApiError) {
    console.error('reviews error', e.code, e.message);
  }
  // degrade gracefully — don't block your checkout/page on a reviews failure
}

curl -X POST https://api.3y3anaa.com/v1/reviews/resolveReviewSubject \
  -H "Authorization: Bearer $THREEYANAA_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"0244123456"}'

// server action / route handler — never client-side
await reviews.submitReview({
  subjectType: 'product',
  externalId: product.id,                    // Sellub's own product id
  subjectDisplayName: product.name,
  subjectUrl: `/product/${product.slug}`,
  author: {
    externalUserId: customer.id,             // Sellub's user id
    displayName: customerName,
    role: 'buyer',
  },
  rating,
  title,
  body,
  verified: hasSettledOrderForProduct,       // gated on a real purchase
});

const { items, aggregate } = await reviews.getReviews({
  subjectType: 'product',
  externalId: product.id,
  sort: 'helpful',
});
// render aggregate.avgRating / aggregate.reviewCount + items

const aggs = await reviews.getAggregates(
  products.map((p) => ({ subjectType: 'product', externalId: p.id })),
);