Kappapps SDK

Appearance

Class: AppServiceService ​

Service for managing app services: functions exposed by an app/widget, declared along with their arguments, and callable by the platform, other apps or the AI (depending on the allowed domains).

Remarks ​

Available everywhere via k.services. You never have to instantiate this service yourself — it is created by the SDK when the app/widget starts.

Two complementary uses: implementing a service declared in the app's config with `implements` (provider side), and calling a service with `call` (consumer side).

Example ​

ts
// Implement the "spawn" service declared in the app's config
await k.services.implements('spawn', async (args) => {
    spawnEntity(args.type);
    return { ok: true };
});

Implements ​

Methods ​

call() ​

ts
call(
   name, 
   args, 
options?): Promise<any>;

Calls an app service by name, with its arguments, and waits for its response.

Parameters ​

name ​

string

Name of the service to call.

args ​

Record<string, any>

Arguments passed to the service (key/value pairs).

options? ​

Optional call options.

timeoutSeconds? ​

number

Maximum time (in seconds) to wait for the response, forwarded to the backend if set.

Returns ​

Promise<any>

The response returned by the called service.

Throws ​

Rejects on transport failure or an exception in the provider callback (requires the updated provider SDK and Core). The rejection carries status and reason. A returned business result such as {ok: false, reason: ...} remains a normal result; legacy providers can still resolve exceptions as data.

Example ​

ts
const result = await k.services.call('spawn', { type: 'boss' }, { timeoutSeconds: 5 });

See ​

implements to provide a service.

create() ​

ts
create(data): Promise<AppServiceModel>;

Declares and registers a new app service on the backend, and keeps a local record of it so it can respond to incoming calls.

Parameters ​

data ​

AppServiceData

The service definition — see AppServiceData (name, description, arguments, allowed domains, required role, call callback…).

Returns ​

Promise<AppServiceModel>

The created AppServiceModel, once backend registration succeeds.

Throws ​

Rejects with the registration error. The failed local model is discarded, so a later call can retry registration.

Remarks ​

In practice, you most often go through `implements`, which reuses the config already declared in the app/widget and simply wires up the callback.

See ​

implements and remove.

get() ​

ts
get(): Promise<AppServiceData[]>;

Fetches the list of app services registered on the backend.

Returns ​

Promise<AppServiceData[]>

An array of AppServiceData describing the available services.

implements() ​

ts
implements(name, callback): Promise<AppServiceModel>;

Implements a service already declared in the app/widget config: wires up the callback executed on every incoming call to that service.

Parameters ​

name ​

string

Name of the service to implement (must match a service declared in the app's or widget's config).

callback ​

AppServiceCallFunction

Function (AppServiceCallFunction) called with the call's arguments, returning a promise that resolves with the service's response.

Returns ​

Promise<AppServiceModel>

The matching AppServiceModel, once registration succeeds. If the service is already registered, its callback is simply replaced; otherwise it is created via `create`.

Throws ​

Rejects with the registration error if registration fails.

Remarks ​

Available only inside an app or a widget: throws an error if the service is not declared in the config, or if the context is neither an app nor a widget. Concurrent calls replace the callback but wait for the same registration result. After a failed registration, a later call starts a new registration attempt.

Example ​

ts
await k.services.implements('getScore', async (args) => {
    return { score: getScore(args.playerId) };
});

See ​

call to call a service.

remove() ​

ts
remove(name): Promise<void>;

Removes an app service, both locally and on the backend.

Parameters ​

name ​

string

Name of the service to remove.

Returns ​

Promise<void>

A promise that resolves once the removal is complete.

See ​

create.