@salla.sa/app-functions-types

Public, types-only definitions for authoring Salla App Functions.

This package contains no runtime code — only TypeScript declarations. Partners author their App Function against these shapes (event payloads, the handler signature, and the response envelope) and export an events map. The platform injects the real, private SDK (@salla.sa/functions-sdk) at deploy time, so the partner never depends on it directly.

Install

pnpm add -D @salla.sa/app-functions-types

It's a dev dependency: nothing from this package ends up in your bundle — it only types your code.

Usage

import type { FunctionResponse, StoreOrder } from "@salla.sa/app-functions-types";

// A simple App Function handler receiving the store `Order` tracking payload.
const orderCreated = (ctx: StoreOrder): FunctionResponse<{ orderId: string }> => {
  const order = ctx.payload.properties;
  if (!order || !order.order_id) {
    return { success: false, message: "Order missing id", error: { message: "invalid" } };
  }
  return {
    success: true,
    data: { orderId: order.order_id },
    message: `Order ${order.reference_id ?? order.order_id} received`,
  };
};

export default orderCreated;

Package layout

src/
  shared/
    common.ts               # Merchant, EventSettings, IdName
    admin-event.ts          # MoneyAmount, DateTime, TaxAmount
    store-event.ts          # StoreEventContext and related sub-types
  admin-events/             # Backend webhook event payloads (15 domains)
    app.ts
    brand.ts
    cart.ts
    category.ts
    customer.ts
    invoice.ts
    misc.ts                 # Internal helper types (re-exported with Misc* prefix)
    onboarding.ts
    order.ts
    order-status-updated.ts
    product.ts
    shipments.ts
    shippings.ts
    specialoffer.ts
    store.ts
  responses/
    general-response.ts     # BaseResponse, GeneralSuccessResponse, ErrorResponse,
                            #   ValidationErrorResponse, GeneralErrorResponse, GeneralResponse
    generic-response.ts     # GenericResponse
  communication-events/
    communication.ts        # CommunicationEvent (sms.send, email.send, whatsapp.send)
  general-events/
    promotion-clicked.ts    # PromotionClickedEvent
    promotion-viewed.ts     # PromotionViewedEvent
  store-events/             # Segment-style storefront tracking events (36 files)
    address-added.ts
    address-updated.ts
    cart-shared.ts
    cart-updated.ts
    cart-viewed.ts
    checkout.ts
    checkout-started.ts
    checkout-step-completed.ts
    checkout-step-viewed.ts
    coupon-applied.ts
    coupon-denied.ts
    coupon-entered.ts
    coupon-removed.ts
    map-clicked.ts
    order.ts                # StoreOrder, OrderEventType
    order-cancelled.ts
    order-completed.ts
    order-refunded.ts
    order-updated.ts
    payment-failed.ts
    payment-info-entered.ts
    payment-pending.ts
    payment-submitted.ts
    payment-succeeded.ts
    product-added.ts
    product-added-to-wishlist.ts
    product-clicked.ts
    product-list-filtered.ts
    product-list-sorted.ts
    product-list-viewed.ts
    product-removed.ts
    product-removed-from-wishlist.ts
    product-reviewed.ts
    product-searched.ts
    product-shared.ts
    product-viewed.ts
    wishlist-product-added-to-cart.ts
  user-information-events/  # User identity analytics events
    signed-in.ts
    signed-out.ts
    signed-up.ts
    user-profile-updated.ts
  webhook-events/           # Real-time product webhook events
    product-brand-updated.ts
    product-category-updated.ts
    product-channel-changed.ts
    product-image-updated.ts
    product-price-updated.ts
    product-status-updated.ts
    product-tags-updated.ts
  index.ts                  # Barrel — re-exports everything
dist/                       # Published output (.d.ts only, generated by build)

What's exported

Shared building blocks

| Export | Source | Description | | --- | --- | --- | | Merchant | shared/common | { id: number \| string; [key: string]: any } — the store/merchant context attached to every event. | | EventSettings | shared/common | { [key: string]: any } \| null — optional per-event configuration from the platform. | | IdName | shared/common | Simple { id: number; name: string } tuple used across payloads. | | MoneyAmount | shared/admin-event | { amount, currency } — monetary value with ISO currency code. | | DateTime | shared/admin-event | { date, timezone_type, timezone } — serialized date from the admin backend. | | TaxAmount | shared/admin-event | { percent, amount } — tax breakdown. | | StoreEventContext | shared/store-event | Full tracking context (user agent, locale, traits, page, screen, campaign, app, scope). | | StoreEventTraits | shared/store-event | User profile traits attached to store events. | | StoreEventPage | shared/store-event | Web page info (path, url, referrer, title, etc.). | | StoreEventScreen | shared/store-event | Display info (width, height, density). | | StoreEventCampaign | shared/store-event | UTM parameters (source, medium, content, referrer). | | StoreEventApp | shared/store-event | App metadata (name, version, build, platform). | | StoreEventScope | shared/store-event | Store scope/channel info (id, languages, currencies, countries). |

Response envelope

| Export | Description | | --- | --- | | BaseResponse | Base shape: { status: number; success: boolean; message?: string }. | | GeneralSuccessResponse | success: true, status: 200 \| 201 \| 202 \| 204, data: any. | | ErrorResponse | success: false, status is one of the standard HTTP error codes (400–504), message: string. | | ValidationErrorResponse | success: false, status: 422, with error.fields map for per-field validation errors. | | GeneralErrorResponse | Union of ValidationErrorResponse \| ErrorResponse. | | GeneralResponse | Union of GeneralErrorResponse \| GeneralSuccessResponse. | | GenericResponse | Simple { success: boolean; data?: any } for lightweight handlers. |

Admin events (backend webhooks)

Fired by the Salla admin backend when merchant data changes. Every event context type has the shape:

interface SomeEvent {
  payload: { event: string; created_at: string; merchant: number; data: { ... } };
  merchant: Merchant;
  settings?: EventSettings;
}

| Export | Source file | Covers | | --- | --- | --- | | App (and related) | admin-events/app | App install / uninstall events. | | Brand (and related) | admin-events/brand | Brand created / updated / deleted. | | Cart (and related) | admin-events/cart | Cart events from the admin. | | Category (and related) | admin-events/category | Category created / updated / deleted. | | Customer (and related) | admin-events/customer | Customer created / updated / deleted. | | Invoice (and related) | admin-events/invoice | Invoice lifecycle events. | | Onboarding (and related) | admin-events/onboarding | Merchant onboarding events. | | Order (and related) | admin-events/order | Order created / updated / etc. | | OrderStatusUpdated (and related) | admin-events/order-status-updated | Order status change events. | | Product (and related) | admin-events/product | Product created / updated / deleted. | | Shipments (and related) | admin-events/shipments | Shipment lifecycle events. | | Shippings (and related) | admin-events/shippings | Shipping rate events. | | SpecialOffer (and related) | admin-events/specialoffer | Special offer events. | | Store (and related) | admin-events/store | Store setting change events. | | Misc, MiscData, MiscCustomer, MiscProduct, MiscPromotion, MiscStatus, MiscCustomized, MiscPrice, MiscSalePrice, MiscRegularPrice, MiscOrder, MiscTotal, MiscItemsItem | admin-events/misc | Internal helper types re-exported with Misc* prefix to avoid namespace collisions. |

Communication events

| Export | Event names | | --- | --- | | CommunicationEvent | communication.sms.send, communication.email.send, communication.whatsapp.send |

General (analytics) events

| Export | Event name | | --- | --- | | PromotionClickedEvent | Promotion banner / element clicked. | | PromotionViewedEvent | Promotion banner / element viewed. |

Store events (Segment-style tracking)

Fired from the customer-facing storefront. All store events carry a StoreEventContext.

Cart

| Export | Event name | | --- | --- | | CartUpdatedEvent | Cart contents changed. | | CartViewedEvent | Cart page viewed. | | CartSharedEvent | Cart shared. |

Product

| Export | Event name | | --- | --- | | ProductViewedEvent | Product detail page viewed. | | ProductClickedEvent | Product clicked in a list. | | ProductAddedEvent | Product added to cart. | | ProductRemovedEvent | Product removed from cart. | | ProductSearchedEvent | Product search performed. | | ProductSharedEvent | Product shared. | | ProductReviewedEvent | Product reviewed. |

Product lists

| Export | Event name | | --- | --- | | ProductListViewedEvent | A product list / category viewed. | | ProductListFilteredEvent | Product list filtered. | | ProductListSortedEvent | Product list sorted. |

Checkout

| Export | Event name | | --- | --- | | CheckoutStartedEvent | Checkout flow started. | | CheckoutStepViewedEvent | A checkout step viewed. | | CheckoutStepCompletedEvent | A checkout step completed. |

Payment

| Export | Event name | | --- | --- | | PaymentSubmittedEvent | Payment form submitted. | | PaymentSucceededEvent | Payment succeeded. | | PaymentFailedEvent | Payment failed. | | PaymentPendingEvent | Payment pending. | | PaymentInfoEnteredEvent | Payment info entered. |

Coupons

| Export | Event name | | --- | --- | | CouponEnteredEvent | Coupon code entered. | | CouponAppliedEvent | Coupon successfully applied. | | CouponRemovedEvent | Coupon removed. | | CouponDeniedEvent | Coupon rejected. |

Orders

| Export | Event name | | --- | --- | | OrderCompletedEvent | Order completed (storefront). | | OrderCancelledEvent | Order cancelled (storefront). | | OrderRefundedEvent | Order refunded (storefront). | | OrderUpdatedEvent | Order updated (storefront). | | StoreOrder, OrderEventType | Shared order shape and event-name union for store-side order events. |

Wishlist

| Export | Event name | | --- | --- | | ProductAddedToWishlistEvent | Product added to wishlist. | | ProductRemovedFromWishlistEvent | Product removed from wishlist. | | WishlistProductAddedToCartEvent | Wishlist product added to cart. |

Address & misc

| Export | Event name | | --- | --- | | AddressAddedEvent | Shipping address added. | | AddressUpdatedEvent | Shipping address updated. | | MapClickedEvent | Map element clicked (address/location flow). |

User information events

| Export | Event name | | --- | --- | | SignedUpEvent | User registered. | | SignedInEvent | User logged in. | | SignedOutEvent | User logged out. | | UserProfileUpdatedEvent | User profile updated. |

Webhook events (product updates)

Real-time product change webhooks distinct from the admin event bus.

| Export | Event name | | --- | --- | | ProductPriceUpdatedEvent | Product price changed. | | ProductBrandUpdatedEvent | Product brand changed. | | ProductCategoryUpdatedEvent | Product category changed. | | ProductStatusUpdatedEvent | Product status changed. | | ProductImageUpdatedEvent | Product image changed. | | ProductChannelChangedEvent | Product channel assignment changed. | | ProductTagsUpdatedEvent | Product tags changed. |

Develop

pnpm install
pnpm run build         # tsc --emitDeclarationOnly → dist/*.d.ts
pnpm run typecheck     # tsc --noEmit
pnpm run lint          # eslint --cache .
pnpm run format        # prettier --write .
pnpm run format:check  # prettier -c .

prepublishOnly runs clean && build automatically before npm publish / pnpm publish.

License

MIT