SDM interceptors

Warning

Custom interceptors and their type contracts are still experimental. You can use logger, dp-kit, and matter-kit directly, but if you implement your own interceptors, expect possible API adjustments in future versions.

interceptors let you insert shared logic into SDM initialization, DP sending, and event callback chains. They are useful for logging, protocol conversion, structured state mapping, and conditional short-circuiting.

When do you need interceptors?

✅ Good fit:

You need shared logic, logging, or analytics before or after publishDps
You need to convert raw device reports into business-friendly data
You want to reuse logger, dp-kit, or matter-kit
Multiple pages depend on the same initialization or protocol processing logic

❌ Probably unnecessary:

The logic is only for one page and does not need to be reused
You only read simple DP features and useProps / useActions is enough
You do not need to change the SDM init, send, or event chains

How do you choose a built-in interceptor?

Interceptor	Best for	Core capability	Docs
`logger`	Development debugging	Prints logs for `init / request / response` chains	logger
`dp-kit`	Complex DP features	Protocol parsing, structured state, send options (`sendOptions`), optimistic UI updates	dp-kit
`matter-kit`	Matter lighting devices	Matter ↔ standard DP conversion; can be composed with `dp-kit`	matter-kit

Info

SDM mounts logger on built-in chains by default. But once you manually configure an interceptor array for a specific chain, that chain is replaced by your new array. If you still want logs, add logger back explicitly.

Integration guide

Step 1: Choose the interception point

Category	Available entries	Typical use
`init`	`initDpState`, `initDevInfo`	Adjust `dpState` or `devInfo` during initialization
`request`	`publishDps`	Format outgoing data, append params, throttle or debounce sends
`response`	`onDpDataChange`, `onDeviceInfoUpdated`, `onDeviceOnlineStatusUpdate`, `onNetworkStatusChange`, `onBluetoothAdapterStateChange`	Transform reports, sync state, or enhance events
`onInit`	`(device) => void`	Extra logic after device initialization, such as `dpKit.init(device)`

Step 2: Mount interceptors on SmartDeviceModel

src/devices/index.ts

import { SmartDeviceModel, createDpKit, logger } from '@ray-js/panel-sdk';
import { defaultSchema } from '@/devices/schema';

type SmartDeviceSchema = typeof defaultSchema;

const dpKit = createDpKit<SmartDeviceSchema>({
  sendDpOption: {
    immediate: true,
  },
});

const options = {
  interceptors: {
    onInit: (device) => {
      dpKit.init(device);
    },
    init: {
      initDpState: [logger, ...dpKit.interceptors.init.initDpState],
      initDevInfo: [logger, ...dpKit.interceptors.init.initDevInfo],
    },
    request: {
      publishDps: [logger, ...dpKit.interceptors.request.publishDps],
    },
    response: {
      onDpDataChange: [logger, ...dpKit.interceptors.response.onDpDataChange],
      onDeviceInfoUpdated: [logger, ...dpKit.interceptors.response.onDeviceInfoUpdated],
      onDeviceOnlineStatusUpdate: [logger],
      onNetworkStatusChange: [logger],
      onBluetoothAdapterStateChange: [logger],
    },
  },
};

export const devices = {
  common: new SmartDeviceModel<SmartDeviceSchema>(options),
};

If you only use one built-in kit, you can also pass interceptors: dpKit.interceptors or interceptors: matterKit.interceptors directly.

Step 3: Order multiple interceptors correctly

Interceptors in the same chain wrap in array order; earlier items receive the input first
If an interceptor does not call next(...), later interceptors and the underlying method will not run
When combining dp-kit and matter-kit for publishDps, dp-kit usually goes first and matter-kit second

request: {
  publishDps: [
    ...dpKit.interceptors.request.publishDps,
    ...matterKit.interceptors.request.publishDps,
  ],
},

Custom interceptors

Common types

Type	Chain	Purpose
`Interceptor`	Generic	A quick way to define a general-purpose interceptor
`InitDpStateInterceptor`	`init.initDpState`	Shared processing around `dpState` initialization
`InitDevInfoInterceptor`	`init.initDevInfo`	Shared processing around `devInfo` initialization
`PublishDpsInterceptor`	`request.publishDps`	Rewrite outgoing params, append DP features, or change options
`OnDpDataChangeInterceptor`	`response.onDpDataChange`	Convert raw device reports into business state
`OnDeviceInfoUpdatedInterceptor`	`response.onDeviceInfoUpdated`	React to device info updates
`OnDeviceOnlineStatusUpdateInterceptor`	`response.onDeviceOnlineStatusUpdate`	React to online/offline updates
`OnNetworkStatusChangeInterceptor`	`response.onNetworkStatusChange`	React to network changes
`OnBluetoothAdapterStateChangeInterceptor`	`response.onBluetoothAdapterStateChange`	React to Bluetooth state changes

For group scenarios, there are also OnGroupDpDataChangeInterceptor and OnGroupInfoChangeInterceptor. This guide focuses on the most common single-device SDM chains.

Execution model

Info

Interceptors use a three-layer curried shape: ctx => next => data.

Parameter	Description
`ctx.type`	The current chain name, such as `publishDps` or `onDpDataChange`
`ctx.log`	The logger for the current chain, supporting `log.info / log.warn / log.fatal`
`ctx.instance`	The current `SmartDeviceModel` instance, which can access `getDpState()`, `getDevInfo()`, and more
`next`	The next interceptor or the underlying method; the chain continues only if you call it
`data`	The current request input or event payload

const interceptor = (ctx) => (next) => (data) => {
  return next(data);
};

Common patterns

1. Append or rewrite data before sending

import { PublishDpsInterceptor } from '@ray-js/panel-sdk';

export const appendExtraDp: PublishDpsInterceptor<SmartDeviceSchema> =
  (ctx) => (next) => (dpState, options) => {
    const nextDpState = {
      ...dpState,
      power_go: !ctx.instance.getDpState().power_go,
    };

    ctx.log.info('append extra dp before publishDps', nextDpState, 'appendExtraDp');

    return next(nextDpState, options);
  };

2. Convert raw reports into business data

import { DpState, DpValue, OnDpDataChangeInterceptor } from '@ray-js/panel-sdk';

export const mapDpsToDpState: OnDpDataChangeInterceptor<
  SmartDeviceSchema,
  DpState
> = (ctx) => (next) => (data) => {
  const devInfo = ctx.instance.getDevInfo();
  const dpState = {} as DpState;

  Object.keys(data.dps).forEach((dpId) => {
    dpState[devInfo.idCodes[dpId]] = data.dps[dpId] as DpValue;
  });

  return next(dpState);
};

3. Short-circuit the rest of the chain

import { Interceptor } from '@ray-js/panel-sdk';

export const skipWhenReadonly: Interceptor<SmartDeviceSchema> =
  (ctx) => (next) => (data) => {
    const isReadonlyMode = true;

    if (isReadonlyMode) {
      ctx.log.info('skip current interceptor chain', data, 'skipWhenReadonly');
      return null;
    }

    return next(data);
  };

#SDM interceptors

#When do you need interceptors?

#How do you choose a built-in interceptor?

#Integration guide

#Step 1: Choose the interception point

#Step 2: Mount interceptors on SmartDeviceModel

#Step 3: Order multiple interceptors correctly

#Custom interceptors

#Common types

#Execution model

#Common patterns

#Further reading

#logger

#dp-kit

#matter-kit

#SmartDeviceModel

SDM interceptors

When do you need interceptors?

How do you choose a built-in interceptor?

Integration guide

Step 1: Choose the interception point

Step 2: Mount interceptors on SmartDeviceModel

Step 3: Order multiple interceptors correctly

Custom interceptors

Common types

Execution model

Common patterns

Further reading

logger

dp-kit

matter-kit

SmartDeviceModel