Building Apps — Developer Guide

┌──────────────┐       webhook        ┌──────────────┐
│  StoreTalk   │ ───────────────────→ │   Your App   │
│  Flow Engine │                      │    Server    │
│              │ ←─────────────────── │              │
│              │      callback        │              │
└──────────────┘                      └──────────────┘
        ↕                                    ↕
   WhatsApp API                        Your Web UI
   (sends CTA button                   (customer browses,
    to customer)                        places order, etc.)

SESSION phase       : browsing → cart_updated → order_confirmed (terminal ✓)
                                                      ↓
                                              [flow resumes here]
FULFILLMENT phase   : order_accepted → picking → preparing → shipped → delivered

npm install @citymapia-llc/storetalk-app-sdk

import { StoreTalkApp } from '@citymapia-llc/storetalk-app-sdk';
import Fastify from 'fastify';

export const app = new StoreTalkApp({
  slug: 'my-app',
  secret: process.env.STORETALK_APP_SECRET!,
  lifecycle: [
    { status: 'started',  phase: 'session', terminal: false },
    { status: 'completed', phase: 'session', terminal: true,
      variables: ['result'] },
  ],
});

// Handle incoming session.create
app.onSessionCreate(async (event) => {
  // Return a URL StoreTalk will send as a WhatsApp CTA button
  return {
    status: 'success',
    session: {
      url: `https://my-app.example.com/s/${event.delivery_id}`,
      expires_in_seconds: 1800,
    },
    message: {
      body: 'Tap to get started',
      button_text: 'Open',
    },
  };
});

// Your HTTP server
const fastify = Fastify();
fastify.post('/webhook', async (req, reply) => {
  return app.handleWebhook(req.raw, reply.raw);
});
fastify.listen({ port: 3000 });

await app.complete(
  { deliveryId, callbackUrl },
  'completed',
  { result: 'Customer entered: Hello!' }
);

{
  "slug": "my-app",
  "actions": [
    {
      "slug": "open_form",
      "label": "Open Form",
      "description": "Show a feedback form to the customer"
    }
  ],
  "lifecycle": [...],
  "sdk_version": "0.6.0",
  "webhook_url": "https://my-app.example.com/webhook",
  "public_url": "https://my-app.example.com"
}

fastify.get('/api/manifest', async () => app.manifest());

// Non-terminal — keeps the lifecycle open
await app.pushFulfillment(session, 'shipped', {
  tracking_number: 'AWB123456',
});

// Terminal — closes the fulfillment lifecycle
await app.completeFulfillment(session, 'delivered', {
  delivery_time: '3:45 PM',
});

// Shorten a URL with an explicit expiry
const result = await app.shortenUrl('https://shop.storetalk.app/orders/abc?token=eyJhbG...', {
  expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString(),
  refId: `order:${orderId}`,                 // for bulk revoke later
  tenantId: install.tenantId,
});
// → { code: "Xy7q2kF", shortUrl: "https://s.storetalk.app/Xy7q2kF", expiresAt: "..." }

// Or, if your URL carries a JWT, let the SDK extract the `exp` claim:
const result = await app.shortenJwtUrl(longUrl, jwt, {
  refId: `order:${orderId}`,
  tenantId: install.tenantId,
});

// Revoke every short URL this app minted with refId "order:123"
await app.revokeShortUrlsByRef(`order:${orderId}`);

// Or revoke a single code if you tracked it explicitly
await app.revokeShortUrl(code);

async function shortenOrFallback(url: string, opts: ShortenUrlOptions): Promise<string> {
  try {
    const result = await app.shortenUrl(url, opts);
    return result.shortUrl;
  } catch (err) {
    console.warn('[shortener] failed, using long URL', err);
    return url;
  }
}

// apps/storetalk-meet/src/routes/manifest.ts
const app = new StoreTalkApp({
  slug: 'storetalk-meet',
  serviceContracts: ['meet'],
  // ...
});

// apps/booking-pro/src/routes/manifest.ts
const app = new StoreTalkApp({
  slug: 'booking-pro',
  serviceDependencies: ['payment', 'meet'],
  // ...
});

const result = await app.requestService('payment', {
  installId: install.id,
  amount: 50000,        // in paise
  currency: 'INR',
  description: 'Booking #4821',
});

// result.data is whatever the provider returned synchronously
const { orderId, key } = result.data;

app.onServiceResponse('payment', async (event) => {
  // event.requestId, event.deliveryId, event.status, event.data
});

app.registerServiceHandler('meet', async (event) => {
  // event.payload was sent by the consumer
  const room = await createRoom(event.payload);
  return { data: { joinUrl: room.url, roomId: room.id } };
});

try {
  await app.requestService('payment', { ... });
  return 'payment_collected';
} catch (err) {
  // No payment provider configured — proceed as a free booking
  return 'free_booking';
}

X-StoreTalk-Signature: sha256=<hex>
X-StoreTalk-Timestamp: <unix_seconds>
X-StoreTalk-Event: <event_type>

X-App-Signature: sha256=<hex>
X-App-Id: <your_app_slug>

HMAC_SHA256(APP_SECRET, rawRequestBody) → hex lowercase

app.mountDebug(fastify, '/debug');