synup-js 0.1.0

package/README.md

@@ -0,0 +1,290 @@
+# synup-js
+
+Node.js/TypeScript SDK for the [Synup](https://synup.com) v4 API. Manage locations, listings, reviews, analytics, and more across 50+ directories.
+
+## Installation
+
+```bash
+npm install synup-js
+```
+
+## Quick Start
+
+```typescript
+import { SynupClient } from 'synup-js';
+
+const client = new SynupClient({
+  apiKey: 'YOUR_API_KEY', // Settings -> Integrations -> Generate
+});
+
+// Fetch first 10 locations
+const result = await client.fetchAllLocations({ first: 10 });
+console.log(result.locations);
+
+// Fetch all locations (auto-paginate)
+const allLocations = await client.fetchAllLocations({ fetchAll: true });
+
+// Get reviews for a location
+const reviews = await client.fetchInteractions(16808, {
+  startDate: '2024-01-01',
+  endDate: '2024-12-31',
+});
+
+// Respond to a review
+await client.respondToReview('interaction-id', 'Thank you for the feedback!');
+```
+
+## Requirements
+
+- Node.js 18+
+- Synup API key
+
+## Method Reference
+
+### Account
+
+| Method | Description |
+|--------|-------------|
+| `fetchPlanSites()` | Get plan site allocations |
+| `fetchCountries()` | List supported countries |
+| `fetchSubscriptions()` | Get subscription details |
+| `createTemporaryCloseAutomation(opts)` | Schedule a temporary location closure |
+
+### Locations
+
+| Method | Description |
+|--------|-------------|
+| `fetchAllLocations(opts)` | List locations (paginated or fetchAll) |
+| `fetchLocationsByIds(ids)` | Fetch specific locations by ID |
+| `fetchLocationsByStoreCodes(codes)` | Fetch locations by store code |
+| `fetchLocationsByTags(tags, opts)` | Fetch locations filtered by tags |
+| `fetchLocationsByFolder(opts)` | Fetch locations in a folder |
+| `searchLocations(query, opts)` | Search locations by name/address |
+| `createLocation(data)` | Create a new location |
+| `updateLocation(data)` | Update an existing location |
+| `archiveLocations(ids)` | Archive locations |
+| `activateLocations(ids)` | Reactivate archived locations |
+| `cancelArchiveLocations(ids, scope, reason)` | Cancel a pending archive |
+
+### Tags
+
+| Method | Description |
+|--------|-------------|
+| `fetchTags()` | List all tags |
+| `addLocationTag(locationId, tag)` | Add a tag to a location |
+| `removeLocationTag(locationId, tag)` | Remove a tag from a location |
+
+### Folders
+
+| Method | Description |
+|--------|-------------|
+| `fetchFoldersFlat()` | List all folders (flat list) |
+| `fetchFoldersTree()` | List folders as a nested tree |
+| `fetchFolderDetails(opts)` | Get folder details by name or ID |
+| `createFolder(name, opts)` | Create a new folder |
+| `renameFolder(oldName, newName)` | Rename a folder |
+| `deleteFolder(name)` | Delete a folder |
+| `addLocationsToFolder(folderName, locationIds)` | Add locations to a folder |
+| `removeLocationsFromFolder(locationIds)` | Remove locations from their folder |
+
+### Listings
+
+| Method | Description |
+|--------|-------------|
+| `fetchPremiumListings(locationId)` | Get premium directory listings |
+| `fetchVoiceListings(locationId)` | Get voice search listings |
+| `fetchAdditionalListings(locationId)` | Get additional directory listings |
+| `fetchDuplicateListings(locationId)` | Get duplicate listings for a location |
+| `fetchAllDuplicateListings(opts)` | Get all duplicate listings across locations |
+| `fetchAiListings(locationId)` | Get AI-powered listing suggestions |
+| `markListingsAsDuplicate(locationId, ids)` | Mark listings as duplicates |
+| `markListingsAsNotDuplicate(locationId, ids)` | Mark listings as not duplicates |
+
+### Reviews
+
+| Method | Description |
+|--------|-------------|
+| `fetchInteractions(locationId, opts)` | Fetch reviews/interactions |
+| `fetchReviewDetails(interactionIds)` | Get detailed review data |
+| `fetchReviewSettings(locationId)` | Get review notification settings |
+| `editReviewSettings(locationId, settings)` | Update review notification settings |
+| `fetchReviewSiteConfig()` | Get review site configuration |
+| `respondToReview(interactionId, response)` | Respond to a review |
+| `editReviewResponse(reviewId, responseId, text)` | Edit an existing response |
+| `archiveReviewResponse(responseId)` | Archive a review response |
+| `fetchReviewAnalyticsOverview(locationId, opts)` | Review analytics summary |
+| `fetchReviewAnalyticsTimeline(locationId, opts)` | Review analytics over time |
+| `fetchReviewAnalyticsSitesStats(locationId, opts)` | Review analytics by site |
+| `fetchReviewPhrases(opts)` | Phrase/sentiment analysis on reviews |
+
+### Keywords
+
+| Method | Description |
+|--------|-------------|
+| `fetchKeywords(locationId)` | List tracked keywords |
+| `addKeywords(locationId, keywords)` | Add keywords to track |
+| `archiveKeyword(keywordId)` | Archive a tracked keyword |
+| `fetchKeywordsPerformance(locationId, opts)` | Keyword ranking performance |
+| `fetchRankingAnalyticsTimeline(opts)` | Ranking trends over time |
+| `fetchRankingSitewiseHistogram(opts)` | Ranking distribution by site |
+
+### Analytics
+
+| Method | Description |
+|--------|-------------|
+| `fetchGoogleAnalytics(locationId, opts)` | Google Business Profile insights |
+| `fetchBingAnalytics(locationId, opts)` | Bing Places insights |
+| `fetchFacebookAnalytics(locationId, opts)` | Facebook page insights |
+
+### Photos
+
+| Method | Description |
+|--------|-------------|
+| `fetchLocationPhotos(locationId)` | List photos for a location |
+| `fetchPhotoUploadStatus(requestId)` | Check photo upload status |
+| `addLocationPhotos(locationId, photos)` | Upload photos to a location |
+| `removeLocationPhotos(locationId, photoIds)` | Remove photos |
+| `starLocationPhotos(locationId, mediaIds, star)` | Star/unstar photos |
+
+### Connections
+
+| Method | Description |
+|--------|-------------|
+| `fetchConnectionInfo(locationId)` | Get connection status for a location |
+| `fetchConnectedAccounts(opts)` | List connected accounts |
+| `fetchConnectedAccountDetails(accountId)` | Get details for a connected account |
+| `fetchConnectedAccountFolders(accountId)` | Get folders for a connected account |
+| `fetchConnectedAccountListings(accountId, opts)` | Get listings for a connected account |
+| `fetchConnectionSuggestions(accountId, opts)` | Get matching suggestions |
+| `getOauthConnectUrl(locationId, source, successUrl, errorUrl)` | Get OAuth connect URL |
+| `connectGoogleAccount(successUrl, errorUrl)` | Connect a Google account |
+| `connectFacebookAccount(successUrl, errorUrl)` | Connect a Facebook account |
+| `oauthDisconnect(locationId, source)` | Disconnect an OAuth source |
+| `disconnectGoogleAccount(accountId)` | Disconnect a Google account |
+| `disconnectFacebookAccount(accountId)` | Disconnect a Facebook account |
+| `triggerConnectedAccountMatches(accountIds)` | Trigger matching for connected accounts |
+| `confirmConnectedAccountMatches(matchIds)` | Confirm matched listings |
+| `connectListing(locationId, listingId, accountId)` | Connect a listing manually |
+| `disconnectListing(locationId, source)` | Disconnect a listing |
+| `createGmbListing(locationId, accountId)` | Create a Google Business listing |
+
+### Campaigns
+
+| Method | Description |
+|--------|-------------|
+| `fetchReviewCampaigns(locationId, opts)` | List review solicitation campaigns |
+| `fetchReviewCampaignCustomers(campaignId)` | Get customers in a campaign |
+| `createReviewCampaign(opts)` | Create a new campaign |
+| `addReviewCampaignCustomers(campaignId, customers)` | Add customers to a campaign |
+
+### Grid Rank
+
+| Method | Description |
+|--------|-------------|
+| `fetchLocationGridReports(locationId, opts)` | List grid rank reports |
+| `fetchGridReport(reportId)` | Get a specific grid rank report |
+| `createGridReport(opts)` | Create a new grid rank report |
+
+### Users
+
+| Method | Description |
+|--------|-------------|
+| `fetchUsers()` | List all users |
+| `fetchUsersByIds(ids)` | Fetch specific users by ID |
+| `fetchRoles()` | List available roles |
+| `fetchUserResources(userId)` | Get resources assigned to a user |
+| `createUser(data)` | Create a new user |
+| `updateUser(data)` | Update an existing user |
+| `addUserLocations(userId, locationIds)` | Assign locations to a user |
+| `removeUserLocations(userId, locationIds)` | Remove location assignments |
+| `addUserFolders(userId, folderIds)` | Assign folders to a user |
+| `removeUserFolders(userId, folderIds)` | Remove folder assignments |
+| `addUserAndFolder(data)` | Create a user with a folder in one call |
+
+## Pagination
+
+Methods that return lists support cursor-based pagination:
+
+```typescript
+// Single page
+const page = await client.fetchAllLocations({ first: 25 });
+console.log(page.locations);        // Location[]
+console.log(page.pageInfo);         // { hasNextPage, endCursor, ... }
+
+// Next page
+const next = await client.fetchAllLocations({
+  first: 25,
+  after: page.pageInfo.endCursor,
+});
+
+// All pages at once
+const all = await client.fetchAllLocations({ fetchAll: true, pageSize: 100 });
+// Returns Location[] (flat array)
+```
+
+## Error Handling
+
+```typescript
+import { SynupClient, SynupAPIError } from 'synup-js';
+
+try {
+  await client.fetchAllLocations();
+} catch (error) {
+  if (error instanceof SynupAPIError) {
+    console.log(error.statusCode);    // 401, 404, 500, etc.
+    console.log(error.responseBody);  // Raw API response
+  }
+}
+```
+
+## Testing
+
+### Unit Tests
+
+Run the full unit test suite (191 tests with mocked HTTP -- no API key needed):
+
+```bash
+npm test
+```
+
+All HTTP calls are stubbed so these tests run fast and offline. They verify request construction, response parsing, pagination logic, and error handling for every SDK method.
+
+### Integration Tests
+
+Run integration tests against the real Synup API (94 tests):
+
+```bash
+SYNUP_API_KEY=your_key npm run test:integration
+```
+
+Integration tests exercise every SDK method against the live API using your account data. Read-only methods run unconditionally. Safe mutation tests (folder create/rename/delete, tag add/remove, keyword add/archive) run by default and clean up after themselves.
+
+### Destructive Integration Tests
+
+Some tests create and archive real locations. These are skipped by default and must be opted into:
+
+```bash
+RUN_DESTRUCTIVE=1 SYNUP_API_KEY=your_key npm run test:integration
+```
+
+The destructive suite covers the full location lifecycle: create, update, archive, activate, and cancel-archive. Test locations are archived at the end to avoid leaving stale data.
+
+## TypeScript Support
+
+synup-js is written in TypeScript and ships with full type definitions. It works in both JavaScript and TypeScript projects with no additional configuration. Types are included in the package -- there is no separate `@types/synup-js` to install.
+
+```typescript
+import { SynupClient, SynupAPIError } from 'synup-js';
+```
+
+## Features
+
+- **TypeScript-first** -- Full type definitions for all inputs and responses
+- **Zero dependencies** -- Uses native `fetch` (Node 18+)
+- **Auto-pagination** -- Pass `fetchAll: true` to any paginated method
+- **Automatic ID encoding** -- Pass numeric location IDs; base64 encoding is handled automatically
+- **ESM + CJS** -- Works with both module systems
+
+## License
+
+MIT