feat(drs-client): add S3 upload and SNS publish for brand presence analysis

[irenelagno]

Summary

• Adds uploadExcelToDrs() to DrsClient — uploads a brand presence Excel file directly to the DRS S3 bucket at external/spacecat/{siteId}/{brandSlug}/{jobId}/source.xlsx
• Adds publishBrandPresenceAnalyze() to DrsClient — publishes a JOB_COMPLETED SNS event to DRS_SNS_TOPIC_ARN to trigger DRS Fargate analysis
• Adds isS3Configured() guard method (checks DRS_S3_BUCKET + DRS_SNS_TOPIC_ARN)
• Updates TypeScript declarations and adds @aws-sdk/client-s3 + @aws-sdk/client-sns dependencies
• Adds implementation plan doc at docs/plans/2026-04-22-geo-brand-presence-drs-sns-migration.md

This is PR B of the geo-brand-presence DRS SNS migration. It unblocks the spacecat-audit-worker (PR D) to replace the existing HTTP call to POST /sites/{siteId}/brand-presence/analyze with a direct S3 + SNS pattern.

Cross-repo dependencies

PR	Repo	Description
PR A	llmo-data-retrieval-service	Extends fargate_trigger.py; deletes HTTP endpoint
PR B (this)	spacecat-shared	Adds uploadExcelToDrs() and publishBrandPresenceAnalyze() to DrsClient
PR C	spacecat-infrastructure	Provisions DRS_S3_BUCKET, DRS_SNS_TOPIC_ARN env vars and IAM grants
PR D #2410	spacecat-audit-worker	Replaces Mystique callback with direct DRS integration — depends on this PR and PR C

Test plan

• 71 tests passing, 100% line/statement/branch/function coverage
• isS3Configured() — missing bucket, missing topicArn, both set
• uploadExcelToDrs() — success (verifies bucket, key, ContentType, SSE), not configured, missing required fields, empty buffer, S3 error propagation
• publishBrandPresenceAnalyze() — success (verifies TopicArn, full message shape, MessageAttributes), optional fields absent when not passed, not configured, missing required fields, SNS error propagation
• createFrom() — reads DRS_S3_BUCKET and DRS_SNS_TOPIC_ARN from env

🤖 Generated with Claude Code

[irenelagno]

Cross-repo: geo-brand-presence DRS SNS migration

This PR is PR B of a four-repo migration. Related PRs:

PR	Repo	Description
A	llmo-data-retrieval-service #1397	DRS: synthetic job support + bucket policy granting SpaceCat cross-account write
B (this)	spacecat-shared	spacecat-shared-drs-client v1.5.0 — uploadExcelToDrs + publishBrandPresenceAnalyze
C	spacecat-infrastructure #475	Lambda role IAM permissions (S3 write + SNS publish)
D	spacecat-audit-worker #2410	Refresh handler changes — depends on B published + C deployed

Rollout order: A, B, C can merge in any order. D cannot merge until B is published as an npm package and C is deployed to staging.

[github-actions]

This PR will trigger a minor release when merged.

[irenelagno]

Bug: publishBrandPresenceAnalyze generates a new jobId internally, breaking the S3 key ↔ SNS job_id contract required by DRS

uploadExcelToDrs(siteId, jobId, buffer) builds the S3 key as external/spacecat/{siteId}/{jobId}/source.xlsx.
publishBrandPresenceAnalyze then generates its own fresh spacecat-{uuid} as job_id — so the SNS job_id never matches the S3 key the caller used for upload.

DRS PR #1484 (Fix #3) derives result_location from the SNS job_id: s3://{bucket}/external/spacecat/{siteId}/{job_id}/source.xlsx. With the current design the derived path doesn't exist — the file is at the uploadExcelToDrs-time jobId, not the SNS-time jobId.

Fix: accept jobId as an optional parameter, defaulting to a generated value only when not provided:

async publishBrandPresenceAnalyze(siteId, {
  jobId = `spacecat-${randomUUID()}`,
  resultLocation,
  webSearchProvider,
  configVersion,
  week,
  year,
  runFrequency,
  brand,
  imsOrgId,
} = {}) {

The caller (spacecat-audit-worker PR #2410) then generates jobId once per sheet, passes it to both uploadExcelToDrs and publishBrandPresenceAnalyze, ensuring S3 key == SNS job_id end-to-end.

[solaris007]

🎉 This PR is included in version @adobe/spacecat-shared-drs-client-v1.6.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀