@proof-socials/socials

Public npm package with Instagram and Google Business Profile (GMB) primitives only:

• OAuth URL building and token exchange/refresh
• Profile, stats, reviews, and location data fetch
• GMB Pub/Sub push verification and review payload resolution (API fetch + normalization)
• Minimal validation (socialsConfigSchema, token expiry helpers)

This package intentionally does not include Statsnapp app logic (database repositories, token persistence orchestration, or storage-shaped DTO mappers). Keep that in your consumer app.

Requirements

• Node.js 22+ (see .nvmrc)
• npm org/user with publish access to @proof-socials (for maintainers)

Install

npm install @proof-socials/socials

Public releases do not require auth to install.

Local development

cd proof-socials
npm install
npm run dev          # tsup --watch
npm link

# In your app:
npm link @proof-socials/socials

Scripts

| Script | Description | |--------|-------------| | npm run build | Clean + dual CJS/ESM build | | npm run test | Jest unit tests | | npm run test:exports | Build + verify require and import resolve | | npm run typecheck | tsc --noEmit | | npm run release | Publish to npm (public) |

CI/CD (automatic publish)

On every push to main (and on PRs), the CI workflow runs build + tests. npm publish runs only when package.json version changes on a main push.

npm run version:patch   # or version:minor / version:major
git push origin main

See CONTRIBUTING.md for details. Add repo secret NPM_TOKEN (automation token with publish + bypass 2FA).

Publish manually (maintainers)

Package is public (publishConfig.access: public). prepublishOnly runs test:exports.

Option A — automation/granular token (recommended for CI)

Create a token at npmjs.com → Access Tokens:

• Type: Granular or Automation
• Permissions: Read and write on @proof-socials/* (or all packages)
• Enable “Bypass two-factor authentication for write operations” (required if your account has 2FA)

export NPM_TOKEN="npm_..."
npm run release

Option B — npm login + authenticator OTP

npm login
NPM_OTP=123456 npm run release   # 6-digit code from your 2FA app

Troubleshooting E403 (2FA required)

Your token is valid but npm still requires either --otp or a token with bypass 2FA enabled. Classic session tokens from npm login cannot publish without NPM_OTP.

Usage

import { ig, gmb, webhooks, socialsConfigSchema } from '@proof-socials/socials'

const config = socialsConfigSchema.parse({
  appBaseUrl: process.env.APP_URL!,
  instagram: {
    clientId,
    clientSecret,
    scopes: process.env.INSTAGRAM_SCOPES!,
    redirectPath: '/api/social/instagram',
    graphApiVersion: 'v23.0',
  },
  googleBusiness: {
    clientId,
    clientSecret,
    scopes: process.env.GOOGLE_BUSINESS_SCOPES!,
    redirectPath: '/api/social/google-business',
  },
  square: {
    clientId,
    clientSecret,
    scopes: process.env.SQUARE_SCOPES!,
    environment: 'sandbox',
    redirectPath: '/api/social/square',
  },
  shopify: {
    clientId,
    clientSecret,
    scopes: process.env.SHOPIFY_SCOPES!,
    redirectPath: '/api/social/shopify',
  },
  webhooks: { gmbPubsub: { audience, pubsubTopic } },
})

const authUrl = ig.buildInstagramAuthUrl(config, state)
const stats = await ig.fetchInstagramStats(config, accessToken)
const reviews = await gmb.fetchGmbReviewsForDisplay(oauthClient, locationName)
const ok = await webhooks.verifyPubSubPushRequest(config, authorizationHeader)

Token persistence and refresh orchestration belong in the consumer (e.g. Prisma); use isAccessTokenExpired and normalizeRefreshToken only as helpers.

OAuth scopes

Every integration requires scopes in config — the package does not pick scopes for you at runtime. Choose scopes per product; reference constants are exported if you want a starting point:

| Integration | Config field | Scope format | Reference export | |-------------|--------------|--------------|------------------| | Instagram | instagram.scopes | comma-separated | ig.INSTAGRAM_OAUTH_SCOPE | | Google Business | googleBusiness.scopes | space-separated URLs | gmb.GOOGLE_BUSINESS_SCOPE | | Square | square.scopes | space-separated | square.SQUARE_OAUTH_SCOPES.join(' ') | | Shopify | shopify.scopes | comma-separated | (define per app in Shopify Partner dashboard) |

import { ig, gmb, square, socialsConfigSchema } from '@proof-socials/socials'

const config = socialsConfigSchema.parse({
  // ...
  instagram: { /* ... */, scopes: process.env.INSTAGRAM_SCOPES! },
  square: { /* ... */, scopes: process.env.SQUARE_SCOPES! },
})

Package layout

src/
  config.ts              # socialsConfigSchema, buildRedirectUri
  token-utils.ts         # TTL + refreshToken normalization
  instagram/             # OAuth, graph, fetch-stats, fetch-summary
  google-business/       # OAuth, API fetch, notifications setup
  webhooks/              # Pub/Sub verify, GMB review payload resolution

Exports (v1.0)

| Export | Highlights | |--------|------------| | ig | OAuth, fetchInstagramStats, fetchInstagramProfileSummary, graph helpers | | gmb | OAuth, listReviews, fetchGmbReviewsForDisplay, location/review fetch, notification registration | | webhooks | verifyPubSubPushRequest, resolveGmbReviewPayload, resource name helpers | | Root | socialsConfigSchema, buildRedirectUri, isAccessTokenExpired, normalizeRefreshToken |