feat(platforms): Add custom event and update README

.env.example

@@ -0,0 +1,15 @@
+# Salla App Functions — environment
+#
+# Copy this file to `.env` and fill in your own values:
+#
+#   cp .env.example .env
+#
+# `.env` is gitignored. It configures the Salla CLI on your machine only — it is
+# NOT shipped to the deployed function. Per-merchant secrets (API keys, URLs)
+# belong in your app's settings form, which arrives as `context.settings`.
+
+# The Partner app your functions deploy to.
+# Find it in the Partner Portal (https://salla.partners/), or run `salla app list`.
+# Without it you must pass the id on every command:
+#   salla app functions deploy <app_id>
+SALLA_APP_ID=1234567890

.github/CODEOWNERS

@@ -1 +1 @@
-* @SallaApp/opensource
+* @SallaApp/opensource @mzfrshk @muhammad-shaeel

.gitignore

@@ -39,3 +39,8 @@ Thumbs.db
 *~
 *.bak
 *.tmp
+
+pnpm-lock.yaml
+pnpm-workspace.yaml
+package-lock.json
+yarn.lock

package.json

@@ -1,9 +1,9 @@
 {
-  "name": "app-functions-cli-template",
+  "name": "app-functions-starter-kit",
   "version": "1.0.0",
   "private": true,
   "type": "module",
-  "description": "Template to create App Functions with Salla CLI.",
+  "description": "Starter kit to create App Functions with Salla CLI.",
   "main": "dist/index.js",
   "exports": {
     ".": "./dist/index.js"
@@ -12,7 +12,6 @@
     "dist"
   ],
   "scripts": {
-    "postinstall": "npm install -g @salla.sa/cli",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
@@ -22,9 +21,11 @@
   "engines": {
     "node": ">=20.19.0"
   },
+  "dependencies": {
+    "@salla.sa/cli": "^3.2.30"
+  },
   "devDependencies": {
-    "@salla.sa/cli": "^3.2.30",
-    "@salla.sa/app-functions-types": "^0.3.0",
+    "@salla.sa/app-functions-types": "^0.5.0",
     "@eslint/js": "^10.0.1",
     "eslint": "^9.39.2",
     "eslint-config-prettier": "^10.1.8",

src/functions/custom-event-sync.ts

@@ -0,0 +1,24 @@
+import type { FunctionResponse, SallaCustomEvent } from '@salla.sa/app-functions-types';
+
+/**
+ * Handler for the `custom.event.sync` event.
+ *
+ * Every handler follows the same contract: it receives the typed event
+ * `context` (the custom event lives at `context.payload.data`) and returns a
+ * `FunctionResponse` — either a success or an error. Handlers may also be
+ * `async` and return a `Promise<FunctionResponse>`.
+ */
+export const customEventSync = (context: SallaCustomEvent): FunctionResponse => {
+  const eventData = context.payload.data;
+
+  console.log(`Custom event received with data: ${JSON.stringify(eventData)}`);
+
+  // Do your work here — call an API, enqueue a job, enrich the order, …
+
+  return {
+    success: true,
+    status: 200,
+    message: `Custom event invoked successfully.`,
+    data: { foo: 'bar' }
+  };
+};

src/index.ts

@@ -7,6 +7,7 @@
  * just the handlers this map points at.
  */
 import type { DefineEvents } from '@salla.sa/app-functions-types';
+import { customEventSync } from './functions/custom-event-sync';
 import { customerLogin } from './functions/customer-login';
 import { orderCreated } from './functions/order-created';
 
@@ -33,7 +34,8 @@ const defineEvents: DefineEvents = (events) => events;
  */
 const events = defineEvents({
   'order.created': orderCreated,
-  'customer.login': customerLogin
+  'customer.login': customerLogin,
+  'custom.event.sync': customEventSync
 });
 
 // The Salla runtime imports this default export and dispatches every event to its handler.

test/index.spec.ts

@@ -5,7 +5,7 @@ import events from '../src';
 /*
  * These tests exercise the handlers exactly the way the platform does: they
  * look each handler up in the exported `events` map and call it with a context
- * object. Use them as a template — copy a block, swap in your event, and assert
+ * object. Use them as a starter kit — copy a block, swap in your event, and assert
  * on the response your handler returns.
  *
  * The tricky part of testing handlers is that the real webhook payloads have
@@ -22,10 +22,10 @@ type CustomerData = Customer['payload']['data'];
  *  the fields it DOES provide are still checked against the real payload types. */
 type DeepPartial<T> = {
   [K in keyof T]?: T[K] extends (infer U)[]
-    ? DeepPartial<U>[]
-    : T[K] extends object
-      ? DeepPartial<T[K]>
-      : T[K];
+  ? DeepPartial<U>[]
+  : T[K] extends object
+  ? DeepPartial<T[K]>
+  : T[K];
 };
 
 /** Confines the "fill in the fields I didn't bother to set" cast to one spot,