{"id":35441923,"url":"https://github.com/adobe/spacecat-api-service","last_synced_at":"2026-05-30T08:01:50.893Z","repository":{"id":217801784,"uuid":"700271527","full_name":"adobe/spacecat-api-service","owner":"adobe","description":"Edge Delivery services experience success as a service automation: SpaceCat + Star Catalogue","archived":false,"fork":false,"pushed_at":"2026-05-27T07:53:37.000Z","size":124534,"stargazers_count":6,"open_issues_count":100,"forks_count":12,"subscribers_count":28,"default_branch":"main","last_synced_at":"2026-05-27T08:26:26.623Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adobe.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-10-04T09:25:26.000Z","updated_at":"2026-05-27T07:01:27.000Z","dependencies_parsed_at":"2024-03-23T17:40:47.233Z","dependency_job_id":"618492d5-ae36-4193-bbe9-cdcbbb21e9ea","html_url":"https://github.com/adobe/spacecat-api-service","commit_stats":null,"previous_names":["adobe/spacecat-api-service"],"tags_count":1636,"template":false,"template_full_name":null,"purl":"pkg:github/adobe/spacecat-api-service","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adobe%2Fspacecat-api-service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adobe%2Fspacecat-api-service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adobe%2Fspacecat-api-service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adobe%2Fspacecat-api-service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adobe","download_url":"https://codeload.github.com/adobe/spacecat-api-service/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adobe%2Fspacecat-api-service/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33684413,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-03T00:17:45.757Z","updated_at":"2026-05-30T08:01:50.875Z","avatar_url":"https://github.com/adobe.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SpaceCat API Service\n\n\u003e Provides an HTTP API to interact with SpaceCat data\n\n## HTTP API Doc\n\nhttps://opensource.adobe.com/spacecat-api-service/\n\n### Semrush proxy (`/serenity/*`)\n\nServer-side proxy in front of the Semrush AIO API. See [docs/serenity.md](docs/serenity.md)\nfor the operator guide (auth flow, workspace resolution, error envelopes, smoke\nrunbook).\n\n### Build documentation locally\n\n```bash\n$ npm run docs\n```\n\n### Serve the documentation locally\n\n```bash\n$ npm run docs:serve\n```\n\n## Installation\n\n```bash\n$ npm install @adobe/spacecat-api-service\n```\n\n## Usage\n\nSee the [API documentation](docs/API.md).\n\n## Development\n\n### Prerequisites\n\n- **Node.js** (see `.nvmrc` for version)\n- **Docker Desktop** (or equivalent Docker daemon)\n- **AWS CLI** + ECR access for the private `mysticat-data-service` image\n\n### Option 1: Local PostgreSQL via Docker (Recommended)\n\nThe API service uses PostgreSQL + PostgREST as its data backend. The same Docker Compose stack used by integration tests can be used for local development.\n\n#### 1. Authenticate Docker to ECR (first time / every 12 hours)\n\nThe data-service image is hosted in a private AWS ECR registry under **SpaceCat Development (AWS3338)**.\n\n1. Get temporary AWS credentials from KLAM for the **SpaceCat Development (AWS3338)** account\n2. Add them to `~/.aws/credentials` under a profile name of your choice (e.g. `spacecat-dev`):\n\n```ini\n[spacecat-dev]\naws_access_key_id = \u003cyour-access-key-id\u003e\naws_secret_access_key = \u003cyour-secret-access-key\u003e\naws_session_token = \u003cyour-session-token\u003e\n```\n\n3. Authenticate Docker to ECR (replace `spacecat-dev` with your profile name):\n\n```bash\naws ecr get-login-password --profile spacecat-dev --region us-east-1 \\\n  | docker login --username AWS --password-stdin 682033462621.dkr.ecr.us-east-1.amazonaws.com\n```\n\nECR login tokens expire after 12 hours. Re-run step 3 if you see `pull access denied` errors.\n\n#### 2. Start the database stack\n\n```bash\ndocker compose -f test/it/postgres/docker-compose.yml up -d\n```\n\nThis starts:\n- **PostgreSQL 16** on port `55432`\n- **PostgREST** (with auto-applied dbmate migrations) on port `3300`\n\nWait for PostgREST to become ready:\n\n```bash\ncurl -sf http://localhost:3300/ \u003e /dev/null \u0026\u0026 echo \"Ready\" || echo \"Not ready yet\"\n```\n\n#### 3. Create your `.env` file\n\n```bash\ncp .env.example .env\n```\n\nAll required variables (including `POSTGREST_API_KEY`) are pre-filled with working local-dev values. See [`.env.example`](.env.example) for details. The canonical source of truth for env variables is `test/it/env.js`.\n\n#### 4. Start the development server\n\n```bash\nnpm start\n```\n\nThe server will start on `http://localhost:3002` by default.\n\n#### 5. Tear down the database stack\n\n```bash\ndocker compose -f test/it/postgres/docker-compose.yml down -v\n```\n\n### Option 2: Connect to Dev PostgREST Directly (No Docker)\n\nIf you don't want to run Docker locally, you can point the API service directly at the dev environment's PostgREST instance via CloudFront. This requires VPN access from a supported Adobe office (Basel, Dublin, San Jose).\n\n\u003e **Limitations**: The anonymous PostgREST role only supports **SELECT** and **INSERT**. UPDATE and DELETE operations require a `POSTGREST_API_KEY` JWT signed with the dev environment's secret (stored in Vault).\n\n1. Copy the `.env.example` and update the PostgREST URL to the dev CloudFront URL:\n\n```bash\ncp .env.example .env\n```\n\n```plaintext\nPOSTGREST_URL=\u003cdev CloudFront URL\u003e\n```\n\nFind the dev CloudFront URL in the [mysticat-data-service CLAUDE.md](https://github.com/adobe/mysticat-data-service/blob/main/CLAUDE.md) under \"CloudFront URLs\" (not listed here as this is a public repo).\n\n2. Start the dev server:\n\n```bash\nnpm start\n```\n\n### Option 3: Full mysticat-data-service Stack\n\nFor a richer local environment (Swagger UI, separate test database, persistent data), clone the [mysticat-data-service](https://git.corp.adobe.com/anthropic/mysticat-data-service) repo and use its Docker Compose setup:\n\n```bash\ncd /path/to/mysticat-data-service/docker\ndocker compose up -d\n```\n\nThis starts:\n- **PostgreSQL 16** on port `5432` (with persistent volume and auto-applied migrations)\n- **PostgREST** on port `3000`\n- **Swagger UI** on port `8080` (API exploration at http://localhost:8080)\n\nThen use the same `.env` from Option 1 (`cp .env.example .env`), but change the PostgREST URL:\n\n```plaintext\nPOSTGREST_URL=http://localhost:3000\n```\n\n### Changing the Port\n\nThe dev server defaults to port `3002`. To change it, set the `PORT` variable in your `.env` file:\n\n```plaintext\nPORT=3001\n```\n\n### Build\n\n```bash\n$ npm install\n```\n\n### Test\n\n```bash\n$ npm test\n```\n\n### E2E Tests\n\nEnd-to-end tests validate the API against the live CI environment.\n\n#### Setup\n\nAdd the following to your `.env` file:\n\n```plaintext\nUSER_API_KEY=your_api_key_for_ci_environment\n```\n\nThe E2E tests use a hardcoded test site ID and auto-discover opportunities/suggestions for testing.\n(You can change site id according to you)\n\n#### Run E2E Tests Locally\n\n```bash\n$ npm run test-e2e\n```\n\n### Lint\n\n```bash\n$ npm run lint\n```\n\n### Integration Tests\n\nIntegration tests validate the full API lifecycle against real database backends (DynamoDB and PostgreSQL). They test routing, controllers, DTOs, access control, and data access in a single pass — no mocks.\n\n```bash\n# DynamoDB suite (requires Java 17+)\n$ npx mocha --require test/it/dynamo/harness.js --timeout 30000 'test/it/dynamo/**/*.test.js'\n\n# PostgreSQL suite (requires Docker + ECR access)\n$ npx mocha --require test/it/postgres/harness.js --timeout 30000 'test/it/postgres/**/*.test.js'\n```\n\nBoth suites run automatically in CI as parallel GitHub Actions jobs. For the full guide on structure, extending tests, and troubleshooting, see [test/it/README.md](test/it/README.md).\n\n## Required ENV Variables\n\nCurrently, audit worker requires two env variables:\n\n```plaintext\nAUDIT_JOBS_QUEUE_URL=url of the queue to send audit jobs to\nAUDIT_REPORT_SLACK_CHANNEL_ID=slack channel id to send the audit reports to\nRUM_DOMAIN_KEY=global domain key for the rum api\nSLACK_BOT_TOKEN=slack bot's token,\n```\n\nFulfillment worker requires the following env variable:\n\n```plaintext\nFULFILLMENT_EVENTS_QUEUE_URL=url of the queue to send fulfillment events to\n```\n\nOrganizations controller requires the following env variable:\n\n```plaintext\nSLACK_URL_WORKSPACE_EXTERNAL=url of the external Slack workspace, used to generate the Slack channel url\n```\n\nSlack controller requires the following env variables:\n\n```plaintext\nIMS_CLIENT_ID=client id for the IMS API\nIMS_HOST=host for the IMS API\nIMS_CLIENT_CODE=client code for the IMS API\nIMS_CLIENT_SECRET=client secret for the IMS API\n\nSLACK_TOKEN_WORKSPACE_EXTERNAL_ELEVATED=Slack token for the external workspace, elevated permissions\nSLACK_OPS_CHANNEL_WORKSPACE_EXTERNAL=channel ID to use for operations messages in the external workspace\nAGENT_WORKFLOW_STATE_MACHINE_ARN=ARN of the generic agent Step Functions workflow (used by the brand-profile Slack command)\n```\n\nLLMO onboarding requires the following env variable:\n\n```plaintext\nSLACK_LLMO_ALERTS_CHANNEL_ID=slack channel id for LLMO onboarding alerts (data folder exists, site already assigned)\n```\n\nSandbox audit rate-limit (optional):\n\nMinimum hours that must elapse before the same audit can run again for the same site. \nDefault is 4 hrs. Set the variable to 0 to disable the rate-limit\nentirely.\n\n```plaintext\nSANDBOX_AUDIT_RATE_LIMIT_HOURS=4\n```\n\nImport controller requires the following env variables:\n\n```plaintext\nIMPORT_CONFIGURATION=JSON document which includes the following configuration properties:\n  - allowedApiKeys: array of allowed API keys, used to authenticate import requests\n  - queues: array of queue names to use for import jobs. If a queue name is removed from this array, it will no longer be available for new import jobs\n  - queueUrlPrefix: prefix for import queue URLs (eg. https://sqs.us-east-1.amazonaws.com/1234567890/), used to create the complete queue URL for import jobs\n  - s3Bucket: the S3 bucket to store import job artifacts\n```\n\nThe `multipartFormData` wrapper uses the following optional env variables:\n\n```plaintext\nMULTIPART_FORM_FILE_COUNT_LIMIT=Maximum number of files which can be included in a multipart/form-data request (defaults to 5)\nMULTIPART_FORM_MAX_FILE_SIZE_MB=Maximum file size in MB for a single file in a multipart/form-data request (defaults to 20)\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadobe%2Fspacecat-api-service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadobe%2Fspacecat-api-service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadobe%2Fspacecat-api-service/lists"}