From 59ee0901c94980ab2b0dc3dd4d496b2f4ed04b50 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Wed, 29 Apr 2026 14:20:38 +0530 Subject: [PATCH] Enhance presence API methods by adding detailed parameter specifications for update and upsert actions. Separate client-side and server-side SDK method definitions to clarify authentication requirements and improve usability. This update includes new parameters for presence management, ensuring better handling of user presence logs. --- .../Modules/Presences/HTTP/Update.php | 59 +++++++++++--- .../Modules/Presences/HTTP/Upsert.php | 81 ++++++++++++++++--- 2 files changed, 114 insertions(+), 26 deletions(-) diff --git a/src/Appwrite/Platform/Modules/Presences/HTTP/Update.php b/src/Appwrite/Platform/Modules/Presences/HTTP/Update.php index 9675c8f6da..55970bcd8a 100644 --- a/src/Appwrite/Platform/Modules/Presences/HTTP/Update.php +++ b/src/Appwrite/Platform/Modules/Presences/HTTP/Update.php @@ -7,6 +7,7 @@ use Appwrite\Extend\Exception; use Appwrite\Platform\Modules\Presences\HTTP\Action as PresenceAction; use Appwrite\SDK\AuthType; use Appwrite\SDK\Method; +use Appwrite\SDK\Parameter; use Appwrite\SDK\Response as SDKResponse; use Appwrite\Utopia\Database\Documents\User; use Appwrite\Utopia\Response; @@ -42,19 +43,51 @@ class Update extends PresenceAction ->label('event', 'presences.[presenceId].update') ->label('audits.event', 'presence.update') ->label('audits.resource', 'presence/{response.$id}') - ->label('sdk', new Method( - namespace: 'presences', - group: 'presences', - name: 'updatePresence', - description: 'Update a presence log by its unique ID.', - auth: [AuthType::ADMIN, AuthType::KEY, AuthType::SESSION, AuthType::JWT], - responses: [ - new SDKResponse( - code: Response::STATUS_CODE_OK, - model: Response::MODEL_PRESENCE, - ), - ], - )) + ->label('sdk', [ + // Client-side SDK: `userId` is not accepted (session callers can only update their own presence). + new Method( + namespace: 'presences', + group: 'presences', + name: 'updatePresence', + description: 'Update a presence log by its unique ID.', + auth: [AuthType::SESSION], + responses: [ + new SDKResponse( + code: Response::STATUS_CODE_OK, + model: Response::MODEL_PRESENCE, + ), + ], + parameters: [ + new Parameter('presenceId', optional: false), + new Parameter('status', optional: true), + new Parameter('expiry', optional: true), + new Parameter('metadata', optional: true), + new Parameter('permissions', optional: true), + ], + ), + // Server-side SDK: `userId` is required when authenticating with API keys/JWT. + new Method( + namespace: 'presences', + group: 'presences', + name: 'updatePresence', + description: 'Update a presence log by its unique ID.', + auth: [AuthType::KEY, AuthType::JWT, AuthType::ADMIN], + responses: [ + new SDKResponse( + code: Response::STATUS_CODE_OK, + model: Response::MODEL_PRESENCE, + ), + ], + parameters: [ + new Parameter('presenceId', optional: false), + new Parameter('userId', optional: false), + new Parameter('status', optional: true), + new Parameter('expiry', optional: true), + new Parameter('metadata', optional: true), + new Parameter('permissions', optional: true), + ], + ), + ]) ->param('presenceId', '', fn (Database $dbForProject) => new UID($dbForProject->getAdapter()->getMaxUIDLength()), 'Presence unique ID.', false, ['dbForProject']) ->param('userId', null, new Nullable(new UID()), 'User ID.', true) ->param('status', null, new Nullable(new Text(Database::LENGTH_KEY)), 'Presence status.', true) diff --git a/src/Appwrite/Platform/Modules/Presences/HTTP/Upsert.php b/src/Appwrite/Platform/Modules/Presences/HTTP/Upsert.php index 00ef174bd7..0fb31f83cb 100644 --- a/src/Appwrite/Platform/Modules/Presences/HTTP/Upsert.php +++ b/src/Appwrite/Platform/Modules/Presences/HTTP/Upsert.php @@ -8,6 +8,7 @@ use Appwrite\Extend\Exception; use Appwrite\Platform\Modules\Presences\HTTP\Action as PresenceAction; use Appwrite\SDK\AuthType; use Appwrite\SDK\Method; +use Appwrite\SDK\Parameter; use Appwrite\SDK\Response as SDKResponse; use Appwrite\Usage\Context; use Appwrite\Utopia\Database\Documents\User; @@ -46,19 +47,73 @@ class Upsert extends PresenceAction ->label('event', 'presences.[presenceId].upsert') ->label('audits.event', 'presence.upsert') ->label('audits.resource', 'presence/{response.$id}') - ->label('sdk', new Method( - namespace: 'presences', - group: 'presences', - name: 'upsertPresence', - description: 'Create or update a presence log by its unique ID.', - auth: [AuthType::ADMIN, AuthType::KEY, AuthType::SESSION, AuthType::JWT], - responses: [ - new SDKResponse( - code: Response::STATUS_CODE_OK, - model: Response::MODEL_PRESENCE, - ), - ], - )) + ->label('sdk', [ + // Client-side SDK: `userId` is not accepted (session callers should just upsert their own presence). + new Method( + namespace: 'presences', + group: 'presences', + name: 'upsertPresence', + description: 'Create or update a presence log by its unique ID.', + auth: [AuthType::SESSION], + responses: [ + new SDKResponse( + code: Response::STATUS_CODE_OK, + model: Response::MODEL_PRESENCE, + ), + ], + parameters: [ + new Parameter('presenceId', optional: false), + new Parameter('status', optional: false), + new Parameter('permissions', optional: true), + new Parameter('expiry', optional: true), + new Parameter('metadata', optional: true), + ], + ), + // Server-side SDK: `userId` is required when authenticating with API keys/JWT. + new Method( + namespace: 'presences', + group: 'presences', + name: 'upsertPresence', + description: 'Create or update a presence log by its unique ID.', + auth: [AuthType::KEY, AuthType::JWT], + responses: [ + new SDKResponse( + code: Response::STATUS_CODE_OK, + model: Response::MODEL_PRESENCE, + ), + ], + parameters: [ + new Parameter('presenceId', optional: false), + new Parameter('userId', optional: false), + new Parameter('status', optional: false), + new Parameter('permissions', optional: true), + new Parameter('expiry', optional: true), + new Parameter('metadata', optional: true), + ], + ), + // Console SDK (admin): still operates with `userId`. + new Method( + namespace: 'presences', + group: 'presences', + name: 'upsertPresence', + description: 'Create or update a presence log by its unique ID.', + auth: [AuthType::ADMIN], + responses: [ + new SDKResponse( + code: Response::STATUS_CODE_OK, + model: Response::MODEL_PRESENCE, + ), + ], + parameters: [ + new Parameter('presenceId', optional: false), + new Parameter('userId', optional: false), + new Parameter('status', optional: false), + new Parameter('permissions', optional: true), + new Parameter('expiry', optional: true), + new Parameter('metadata', optional: true), + ], + ), + ]) ->param('presenceId', '', fn (Database $dbForProject) => new UID($dbForProject->getAdapter()->getMaxUIDLength()), 'Presence unique ID.', false, ['dbForProject']) ->param('userId', null, new Nullable(new UID()), 'User ID.', true) ->param('status', '', new Text(Database::LENGTH_KEY), 'Presence status.', false)