SDK7 APIs: make a clearly definition

[leanmendoza]

There is a misunderstanding about what APIs are usable and what aren't.

Glossary:

• Foundation client: refers to https://github.com/decentraland/unity-renderer/
• 🏷️ : inheritance from SDK6

Current protocol status

✅ ~system/CommsApi

• async getActiveVideoStreams

✅ ~system/PortableExperiences

• async spawn
• async kill
• async exit
• async getPortableExperiencesLoaded

✅ ~system/RestrictedActions

• async movePlayerTo
• async teleportTo
• async triggerEmote
• async changeRealm
• async openExternalUrl
• async openNftDialog
• async setCommunicationsAdapter
• async triggerSceneEmote

✅ ~system/Runtime

• async getRealm
• async getWorldTime
• async readFile
• async getSceneInformation

✅ ~system/SignedFetch

• async signedFetch
• async getHeaders

✅ system/EngineApi (SDK7 methods)

• async crdtSendToRenderer ✅
• async crdtGetState ✅
• async crdtGetMessageFromRenderer ❌
  • remove

⚠️🏷️ system/EngineApi (SDK6 methods)

• async sendBatch @deprecated ⚠️ 🏷️
  • Only Foundation Client exposes it
• async subscribe @deprecated ⚠️ 🏷️
  • Only Foundation Client exposes it
• async unsubscribe @deprecated ⚠️ 🏷️
  • Only Foundation Client exposes it

⚠️🏷️ ~system/Players

• async getPlayerData

• async getPlayersInScene

• async getConnectedPlayers

• only Foundation client exposes this

• When the Foundation client implements the ECS approach, stop exposing it

⚠️🏷️ ~system/UserIdentity

Same as ~system/Players, probably getting the PlayerIdentityData.get(engine.PlayerEntity)

• async getUserPublicKey
• async getUserData
• Only Foundation client exposes this
• When the Foundation client implements the ECS approach, stop exposing it

⚠️ ~system/EthereumController

Marked as deprecated for SDK7 runtime:

• async requirePayment ❌ 🏷️
  • remove
  • export a function in the SDK with a similar behavior
• async signMessage ❌ 🏷️
  • remove
  • export a function in the SDK with a similar behavior
• async convertMessageToObject ❌ 🏷️
  • remove
• async getUserAccount ❌ 🏷️
  • remove

The only exposed to SDK7 should be:

• async sendAsync ✅

❌ 🏷️ ~system/UserActionModule

• async requestTeleport
  • ❌ remove

⚠️ 🏷️ ~system/CommunicationsController

• async send: marked as deprecated in https://github.com/decentraland/protocol/blob/75f18e8094a0435594eecfbb6e020614b2a86c69/proto/decentraland/kernel/apis/communications_controller.proto#L11
  • Foundation client implements it
  • ⚠️ This is connected with ~system/EngineApi :: sendBatch method (comms event)
• ⚠️ TBD official functionality for runtime 7

👀 ❌ ~system/Scene

• Stop exposing it
• Maintain API to deployed scenes (wrap the ~system/Runtime)
• async getSceneInfo ⚠️

❌🏷️ ~system/EnvironmentApi (deprecated)

• remove the API
  This API shouldn't be exposed to SDK7
• async getBootstrapData
• async isPreviewMode
• async getPlatform
• async areUnsafeRequestAllowed
• async getCurrentRealm
• async getExplorerConfiguration
• async getDecentralandTime

(Optional to clients for now) ~system/Testing

• async logTestResult
• async plan
• async setCameraTransform

Current apis.d.ts exposed

/**
  * CommsApi
  */
declare module "~system/CommsApi" {
    export function getActiveVideoStreams(body: VideoTracksActiveStreamsRequest): Promise<VideoTracksActiveStreamsResponse>;
}

/**
  * CommunicationsController
  */
declare module "~system/CommunicationsController" {
    export function send(body: RealSendRequest): Promise<RealSendResponse>;
}

/**
  * EngineApi
  */
declare module "~system/EngineApi" {
    export function sendBatch(body: ManyEntityAction): Promise<SendBatchResponse>;
    export function subscribe(body: SubscribeRequest): Promise<SubscribeResponse>;
    export function unsubscribe(body: UnsubscribeRequest): Promise<UnsubscribeResponse>;
    export function crdtSendToRenderer(body: CrdtSendToRendererRequest): Promise<CrdtSendToResponse>;
    export function crdtGetState(body: CrdtSendToRendererRequest): Promise<CrdtGetStateResponse>;
    export function crdtGetMessageFromRenderer(body: CrdtMessageFromRendererRequest): Promise<CrdtMessageFromRendererResponse>;
}

/**
  * EnvironmentApi
  */
declare module "~system/EnvironmentApi" {
	export function getBootstrapData(body: GetBootstrapDataRequest): Promise<BootstrapDataResponse>;
    export function isPreviewMode(body: IsPreviewModeRequest): Promise<PreviewModeResponse>;
    export function getPlatform(body: GetPlatformRequest): Promise<GetPlatformResponse>;
    export function areUnsafeRequestAllowed(body: AreUnsafeRequestAllowedRequest): Promise<AreUnsafeRequestAllowedResponse>;
    export function getCurrentRealm(body: GetCurrentRealmRequest): Promise<GetCurrentRealmResponse>;
    export function getExplorerConfiguration(body: GetExplorerConfigurationRequest): Promise<GetExplorerConfigurationResponse>;
    export function getDecentralandTime(body: GetDecentralandTimeRequest): Promise<GetDecentralandTimeResponse>;
}

/**
  * EthereumController
  */
declare module "~system/EthereumController" {
    export function requirePayment(body: RequirePaymentRequest): Promise<RequirePaymentResponse>;
    export function signMessage(body: SignMessageRequest): Promise<SignMessageResponse>;
    export function convertMessageToObject(body: ConvertMessageToObjectRequest): Promise<ConvertMessageToObjectResponse>;
    export function sendAsync(body: SendAsyncRequest): Promise<SendAsyncResponse>;
    export function getUserAccount(body: GetUserAccountRequest): Promise<GetUserAccountResponse>;
}

/**
  * Players
  */
declare module "~system/Players" {
    export function getPlayerData(body: GetPlayerDataRequest): Promise<PlayersGetUserDataResponse>;
    export function getPlayersInScene(body: GetPlayersInSceneRequest): Promise<PlayerListResponse>;
    export function getConnectedPlayers(body: GetConnectedPlayersRequest): Promise<PlayerListResponse>;
}

/**
  * PortableExperiences
  */
declare module "~system/PortableExperiences" {
    export function spawn(body: SpawnRequest): Promise<SpawnResponse>;
    export function kill(body: KillRequest): Promise<KillResponse>;
    export function exit(body: ExitRequest): Promise<ExitResponse>;
    export function getPortableExperiencesLoaded(body: GetPortableExperiencesLoadedRequest): Promise<GetPortableExperiencesLoadedResponse>;
}

/**
  * RestrictedActions
  */
declare module "~system/RestrictedActions" {
    export function movePlayerTo(body: MovePlayerToRequest): Promise<MovePlayerToResponse>;
    export function teleportTo(body: TeleportToRequest): Promise<TeleportToResponse>;
    export function triggerEmote(body: TriggerEmoteRequest): Promise<TriggerEmoteResponse>;
    export function changeRealm(body: ChangeRealmRequest): Promise<SuccessResponse>;
    export function openExternalUrl(body: OpenExternalUrlRequest): Promise<SuccessResponse>;
    export function openNftDialog(body: OpenNftDialogRequest): Promise<SuccessResponse>;
    export function setCommunicationsAdapter(body: CommsAdapterRequest): Promise<SuccessResponse>;
    export function triggerSceneEmote(body: TriggerSceneEmoteRequest): Promise<SuccessResponse>;
}

/**
  * Runtime
  */
declare module "~system/Runtime" {
    export function getRealm(body: GetRealmRequest): Promise<GetRealmResponse>;
    export function getWorldTime(body: GetWorldTimeRequest): Promise<GetWorldTimeResponse>;
    export function readFile(body: ReadFileRequest): Promise<ReadFileResponse>;
    export function getSceneInformation(body: CurrentSceneEntityRequest): Promise<CurrentSceneEntityResponse>;
}

/**
  * Scene
  */
declare module "~system/Scene" {
    export function getSceneInfo(body: GetSceneRequest): Promise<GetSceneResponse>;
}

/**
  * SignedFetch
  */
declare module "~system/SignedFetch" {
    export function signedFetch(body: SignedFetchRequest): Promise<FlatFetchResponse>;
    export function getHeaders(body: SignedFetchRequest): Promise<GetHeadersResponse>;

}

/**
  * Testing
  */
declare module "~system/Testing" {
    export function logTestResult(body: TestResult): Promise<TestResultResponse>;
    export function plan(body: TestPlan): Promise<TestPlanResponse>;
    export function setCameraTransform(body: SetCameraTransformTestCommand): Promise<SetCameraTransformTestCommandResponse>;
}

/**
  * UserActionModule
  */
declare module "~system/UserActionModule" {
    export function requestTeleport(body: RequestTeleportRequest): Promise<RequestTeleportResponse>;
}

/**
  * UserIdentity
  */
declare module "~system/UserIdentity" {
    export function getUserPublicKey(body: GetUserPublicKeyRequest): Promise<GetUserPublicKeyResponse>;
    export function getUserData(body: GetUserDataRequest): Promise<GetUserDataResponse>;
}