앱 만들기

sayren 앱은 코드를 올리면 sayren이 빌드하고 실행하는 앱입니다. 서버를 따로 두지 않습니다. 주문이 결제되면 앱의 함수가 실행되고, 상점 플랫폼에 앱 화면을 더할 수 있습니다. 앱은 설치한 상점의 권한만 가지며, 어떤 권한을 쓰고 어디로 데이터를 보내는지 설치할 때 셀러가 동의합니다.

npx sayren login                      # Sayren 계정으로 로그인
npx sayren app init order-slack       # 앱 폴더 만들기 + 앱 등록
cd order-slack && npm install
npx sayren app dev --store store_…    # 로컬 실행
npx sayren app deploy                 # 번들 → 올리기 → 검사 → 새 버전
npx sayren app release 1              # 버전 1을 현재 버전으로

개발자 포털 **developer.sayren.app**에서도 같은 일을 합니다 — 앱 만들기, 앱 배포 키 발행, 버전·설치·로그 보기, 개발 상점 만들기. 터미널 흐름과 포털 흐름 중 편한 쪽을 쓰십시오.

준비물

• Sayren 계정. npx sayren login 또는 developer.sayren.app에서 로그인합니다
• Node.js 20 이상, sayren CLI 0.5.0 이상(npx sayren은 최신 버전을 씁니다)
• 테스트할 상점. 없으면 아래 「개발 상점」을 만듭니다

1. 앱 폴더 만들기

npx sayren app init order-slack

order-slack이 앱 handle입니다. 소문자·숫자·하이픈 3~40자이고 전 세계에서 하나뿐이어야 합니다. 앱 화면 주소의 라벨 (https://apps-order-slack.sayren.app)로도 씁니다. 처음 실행하면 내 계정의 개발자 조직(개인)이 자동으로 만들어지고 앱이 등록됩니다. 포털에서 먼저 만든 앱이면 그 폴더에 .sayren/app.json(appId·handle)을 두거나 포털의 「CLI 연결」 안내를 따릅니다.

order-slack/
  sayren.app.json      앱 매니페스트
  package.json         @sayren/app 의존성
  src/server.ts        이벤트 함수·HTTP 핸들러
  ui/                  상점 플랫폼 앱 화면(선택, 정적 파일)
  .sayren/app.json     등록된 앱 id(커밋하지 않습니다)

매니페스트

{
  "handle": "order-slack",
  "name": "주문 알림",
  "description": "결제된 주문을 Slack 채널로 보냅니다",
  "scopes": ["order:r"],
  "network": { "hosts": ["hooks.slack.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 }
  }
}

전체 필드는 매니페스트를 참고하십시오.

앱 코드

import { defineApp } from "@sayren/app";

export default defineApp({
  events: {
    "ORDER.PAID": async (event, ctx) => {
      const order = await ctx.api.orders.get(event.data.orderId);
      if (order.totalAmount < Number(ctx.settings.minAmount ?? 0)) return;
      await fetch(ctx.settings.webhookUrl as string, {
        method: "POST",
        headers: { "content-type": "application/json" },
        body: JSON.stringify({ text: `주문 ${order.orderNo} 결제 완료` }),
      });
    },
  },
  http: {
    "GET /summary": async (_request, ctx) => {
      const orders = await ctx.api.orders.list({ limit: 5 });
      return Response.json({ recent: orders.items });
    },
  },
});

• ctx.api는 설치된 상점의 Store SDK 클라이언트입니다. 토큰을 넣을 필요가 없습니다.
• ctx.settings는 셀러가 채운 설정값입니다. 비밀 필드도 여기서 읽습니다.
• fetch는 매니페스트 network.hosts에 적은 호스트와 sayren API에만 나갑니다.

상세는 앱 코드를 참고하십시오.

2. 로컬에서 실행하기

npx sayren app dev --store store_abc123

앱을 내 컴퓨터에서 실행합니다. 이벤트와 HTTP 핸들러가 실제 상점(--store)의 데이터를 읽습니다. --store는 내가 소유자·관리자인 상점이나 개발 상점이어야 합니다. 다른 터미널에서 이벤트를 흉내 냅니다.

npx sayren app trigger ORDER.PAID --order ord_01J…      # 실제 주문으로 이벤트 함수 실행
npx sayren app trigger ORDER.PAID --data '{"orderId":"ord_01J…"}'

HTTP 핸들러는 http://localhost:4020/_http/summary처럼 직접 부릅니다. 앱 화면은 http://localhost:4020/에서 열립니다.

3. 올리기와 버전

npx sayren app deploy -m "첫 버전"

CLI가 src/server.ts를 한 파일로 번들하고(의존성은 앱 폴더의 node_modules에서), ui/의 정적 파일과 함께 올립니다. sayren은 의존성 검사 → 매니페스트 검증 → 번들 검사(크기·비밀 값 형식) → 업로드를 하고 버전을 만듭니다. 단계와 결과가 터미널에 흐르고, 실패하면 단계·오류 코드·로그 꼬리를 보여 줍니다. 올리기 전 로컬 검사만 하려면 npx sayren app verify입니다.

버전은 만들어도 바로 쓰이지 않습니다. 현재 버전으로 정해야 설치된 상점에서 실행됩니다.

npx sayren app release 1

권한·외부 호스트·이벤트가 이전 버전보다 넓어진 버전은 기존 설치에 곧바로 적용되지 않고 셀러의 재동의를 기다립니다. 자세한 규칙은 버전과 배포에 있습니다.

4. 상점에 설치하기

developer.sayren.app **› {앱} › [내 상점에 설치]**를 누르면 Sayren 계정의 동의 화면이 열립니다. 설치할 상점을 고르고 앱이 요청한 권한·외부 호스트·이벤트를 확인한 뒤 동의하면 상점 플랫폼의 앱 화면으로 이동합니다. 필수 설정이 비어 있으면 설정 폼이 먼저 보입니다.

설치된 상점에서 주문이 결제되면 ORDER.PAID 함수가 실행됩니다. 실행 결과는 다음 두 곳에서 봅니다.

npx sayren app logs --tail

• 개발자: developer.sayren.app › {앱} › 로그 — 호출별 결과·소요 시간·console.log 출력·예외(7일 보관)
• 셀러: 앱 › {앱} › 실행 기록 — 이벤트별 성공·실패. 로그 본문은 보이지 않습니다

개발 상점

실결제 없이 앱을 테스트하는 상점입니다. 테스트 결제만 되고 실결제를 열 수 없습니다. 개발자당 5개까지이고 일반 상점 소유 한도와 따로 셉니다.

npx sayren app dev-store create "알림 앱 테스트"

developer.sayren.app › 개발 상점에서도 만듭니다. 개발 상점은 보통 상점과 같이 상품·주문·결제(테스트)를 다룰 수 있습니다.

앱 배포 키

CI처럼 사람이 로그인하지 않는 곳에서 deploy·release·status·logs·secret을 돌리려면 앱 배포 키를 씁니다. developer.sayren.app › {앱} › 키에서 발행하고(값은 만들 때 한 번만 보입니다) SAYREN_APP_KEY 환경 변수나 --key로 줍니다.

SAYREN_APP_KEY=sak_… npx sayren app deploy -m "$GIT_COMMIT"
SAYREN_APP_KEY=sak_… npx sayren app release 3

키는 발행한 앱의 명령에만 쓰입니다. 앱 만들기·개발 상점·설치는 계정 로그인이 필요합니다. 키가 샜으면 포털에서 폐기하고 새로 발행합니다.

명령 모음

모든 명령은 앱 폴더(sayren.app.json이 있는 폴더)에서 실행합니다. 다른 폴더면 --dir을 줍니다. 인증은 --key·SAYREN_APP_KEY(앱 배포 키) → --token·SAYREN_TOKEN → npx sayren login 순서입니다.

다음 단계

• 매니페스트 — 모든 필드와 검증 규칙
• 앱 코드 — ctx, 이벤트 함수, HTTP 핸들러, 한도
• 이벤트 — 받을 수 있는 이벤트와 필요한 권한
• 상점 플랫폼 앱 화면 — ui/ 폴더와 세션
• 설정과 비밀 값
• 버전과 배포
• 앱 설치와 관리 — 셀러가 보는 화면