앱 매니페스트

sayren.app.json은 앱이 무엇을 요청하는지 선언하는 파일입니다. 설치 동의 화면·상점 플랫폼의 앱 정보·실행 제한이 모두 이 파일에서 나옵니다. 아는 키만 받습니다. 모르는 키가 있으면 app verify·app deploy가 실패합니다.

{
  "handle": "order-slack",
  "name": "주문 알림",
  "description": "결제된 주문을 Slack 채널로 보냅니다",
  "icon": "icon.png",
  "readme": "README.md",
  "supportEmail": "help@example.com",
  "scopes": ["order:r", "product:r"],
  "network": { "hosts": ["hooks.slack.com", "*.example.com"] },
  "events": ["ORDER.PAID", "ORDER.CANCELED"],
  "ui": { "adminPage": { "entry": "ui/index.html" } },
  "settings": {
    "webhookUrl": { "type": "string", "label": "Slack 웹훅 주소", "secret": true, "required": true },
    "minAmount": { "type": "number", "label": "알림 최소 금액", "default": 0 },
    "channel": {
      "type": "select",
      "label": "채널",
      "options": [{ "value": "ops", "label": "운영" }, { "value": "cs", "label": "고객센터" }],
      "default": "ops"
    }
  },
  "secrets": ["SLACK_SIGNING_SECRET"]
}

필드

handle로 쓸 수 없는 이름이 있습니다: www·api·app·apps·admin·accounts·store·mcp·docs·sayren·preview·runner· static·cdn, 그리고 -preview로 끝나는 이름.

목록 정보

상점 플랫폼 앱 › 앱 목록의 카드와 앱 상세에 보이는 값입니다. 앱 폴더에 두고 sayren app deploy로 코드와 함께 올립니다. 버전마다 남고, 상점에는 현재 버전(release한 버전)의 값이 보입니다. developer.sayren.app › {앱} › 목록 정보에서 미리 봅니다.

규칙을 벗어나면 app verify·app deploy가 올리기 전에 멈추고, 서버 빌드도 VERIFY 단계에서 MANIFEST_INVALID로 실패합니다. sayren app init은 README.md 틀을 만듭니다.

권한

scopes에 적은 권한을 설치할 때 셀러가 한 번에 전부 동의합니다. 일부만 허락하는 선택은 없습니다. 앱은 동의한 권한만 쓸 수 있고, 설치한 사람의 역할이 가진 권한을 넘는 앱은 설치할 수 없습니다(예: 관리자는 settlement:r 앱을 설치하지 못합니다).

앱이 요청할 수 없는 권한이 있습니다. 구성원(member:*), 상점 설정 수정(store:rw), 웹훅(webhook:*), 스토어프론트(storefront:*), 감사 로그(audit:r)입니다. 이런 권한이 필요한 연동은 액세스 토큰으로 합니다. 또 권한이 있어도 결제 설정·구성원· 액세스 토큰 발급처럼 상점 플랫폼에서만 하는 작업은 앱이 할 수 없습니다.

외부 호스트

앱 코드의 fetch는 network.hosts에 적은 호스트와 sayren API(api.sayren.app)에만 나갑니다. 그 밖의 요청은 403으로 막힙니다. 동의 화면에 「이 앱이 데이터를 보내는 곳」으로 그대로 보입니다.

• 소문자 호스트명만. https://·경로·포트는 쓰지 않습니다. 실제 요청은 https://·443 포트만 나갑니다
• 와일드카드는 한 단계만: *.example.com은 a.example.com에 맞고 a.b.example.com·example.com에는 맞지 않습니다
• IP 주소, localhost, sayren 플랫폼 호스트(sayren.app·sayren.co·avarlabs.com 아래)는 쓸 수 없습니다
• 리다이렉트를 따라가지 않습니다. 허용 호스트가 다른 호스트로 보내면 그 응답(3xx)을 그대로 받습니다

설정 필드

settings의 각 키가 상점 플랫폼 앱 상세의 설정 폼 한 줄이 됩니다. 키는 영문자로 시작하는 영문·숫자·밑줄 40자입니다.

값은 앱 코드에서 ctx.settings.{키}로 읽습니다. 비어 있는 필드는 없거나 null입니다.

검증

npx sayren app verify가 올리지 않고 검사만 합니다. app deploy도 같은 검사를 거치고 통과해야 올립니다.

형식 오류(모르는 키, 글자 수, 호스트 형식)는 해당 경로와 함께 보고합니다.