Skip to content

Commit c3a2525

Browse files
jeoooojeoooo
committed
Refactor PocketbaseArduino to PocketbaseExtended; add structured response handling and extend API methods
- Renamed library from PocketbaseArduino to PocketbaseExtended for clarity. - Introduced PBResponse struct for structured error handling across API methods. - Added extended methods (getOneEx, getListEx, createEx, updateEx, deleteRecordEx) that return PBResponse. - Updated convenience methods to maintain backward compatibility. - Enhanced README with installation instructions, API reference, and examples. - Added new example sketches demonstrating CRUD operations, authentication, and error handling. - Updated library properties for versioning and description.
1 parent c3e1fff commit c3a2525

9 files changed

Lines changed: 793 additions & 627 deletions

‎PocketbaseExtended.cpp‎

Lines changed: 283 additions & 314 deletions
Large diffs are not rendered by default.

‎PocketbaseExtended.h‎

Lines changed: 97 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -5,99 +5,110 @@
55

66
#include "Arduino.h"
77

8+
#if defined(ESP8266)
89
#include <ESP8266HTTPClient.h>
910
#include <ESP8266WiFi.h>
10-
#include <ESP8266HTTPClient.h>
11-
1211
#include <BearSSLHelpers.h>
12+
#elif defined(ESP32)
13+
#include <HTTPClient.h>
14+
#include <WiFi.h>
15+
#include <WiFiClientSecure.h>
16+
#endif
1317

14-
class PocketbaseExtended
15-
{
18+
// Structured response returned by all Ex methods
19+
struct PBResponse {
20+
bool ok;
21+
int statusCode;
22+
String body;
23+
String error;
24+
};
25+
26+
class PocketbaseExtended {
1627
public:
17-
PocketbaseExtended(const char *baseUrl); // Constructor
18-
19-
// Methods to build collection and record URLs
20-
PocketbaseExtended &collection(const char *collection);
21-
22-
/**
23-
* @brief Fetches a single record from a Pocketbase collection
24-
*
25-
* @param recordId The ID of the record to view.
26-
*
27-
* @param expand (Optional) Auto expand record relations. Ex.:?expand=relField1,relField2.subRelField Supports up to 6-levels depth nested relations expansion.
28-
* The expanded relations will be appended to the record under the expand property (eg. "expand": {"relField1": {...}, ...}).
29-
* Only the relations to which the request user has permissions to view will be expanded.
30-
*
31-
* @param fields (Optional) Comma separated string of the fields to return in the JSON response (by default returns all fields). Ex.: ?fields=*,expand.relField.name
32-
* * targets all keys from the specific depth level.
33-
* In addition, the following field modifiers are also supported:
34-
* :excerpt(maxLength, withEllipsis?)
35-
* Returns a short plain text version of the field string value.
36-
* Ex.: ?fields=*,description:excerpt(200,true)
37-
*
38-
* For more information, see: https://pocketbase.io/docs
39-
*/
40-
String getOne(
41-
const char *recordId,
42-
const char *expand /* = nullptr */,
43-
const char *fields /* = nullptr */);
44-
45-
/**
46-
* @brief Deletes a single record from a Pocketbase collection
47-
*
48-
* @param recordId The ID of the record to delete.
49-
*
50-
* For more information, see: https://pocketbase.io/docs
51-
*/
52-
String deleteRecord(const char *recordId);
53-
54-
/**
55-
* @brief Fetches a multiple records from a Pocketbase collection. Supports sorting and filtering.
56-
*
57-
* @param page The page (aka. offset) of the paginated list (default to 1).
58-
*
59-
* @param perPage Specify the max returned records per page (default to 30).
60-
*
61-
* @param sort Specify the records order attribute(s).
62-
* Add - / + (default) in front of the attribute for DESC / ASC order. Ex.:
63-
* `DESC by created and ASC by id`
64-
* `?sort=-created,id`
65-
*
66-
* @param filter Filter the returned records.
67-
*
68-
* @param expand (Optional) Auto expand record relations. Ex.:?expand=relField1,relField2.subRelField Supports up to 6-levels depth nested relations expansion.
69-
* The expanded relations will be appended to the record under the expand property (eg. "expand": {"relField1": {...}, ...}).
70-
* Only the relations to which the request user has permissions to view will be expanded.
71-
*
72-
* @param fields (Optional) Comma separated string of the fields to return in the JSON response (by default returns all fields). Ex.: ?fields=*,expand.relField.name
73-
* * targets all keys from the specific depth level.
74-
* In addition, the following field modifiers are also supported:
75-
* :excerpt(maxLength, withEllipsis?)
76-
* Returns a short plain text version of the field string value.
77-
* Ex.: ?fields=*,description:excerpt(200,true)
78-
*
79-
* @param skipTotal If it is set the total counts query will be skipped and the response fields totalItems and totalPages will have -1 value.
80-
* This could drastically speed up the search queries when the total counters are not needed or cursor based pagination is used.
81-
* For optimization purposes, it is set by default for the getFirstListItem() and getFullList() SDKs methods.
82-
*
83-
* For more information, see: https://pocketbase.io/docs
84-
*/
85-
String getList(
86-
const char *page /* = nullptr */,
87-
const char *perPage /* = nullptr */,
88-
const char *sort /* = nullptr */,
89-
const char *filter /* = nullptr */,
90-
const char *skipTotal /* = nullptr */,
91-
const char *expand /* = nullptr */,
92-
const char *fields /* = nullptr */);
93-
94-
String create(const String &requestBody);
28+
explicit PocketbaseExtended(const char* baseUrl);
29+
30+
// Select the active collection (chainable)
31+
PocketbaseExtended& collection(const char* name);
32+
33+
// ---------- Extended methods (return PBResponse) ----------
34+
35+
PBResponse getOneEx(const char* recordId,
36+
const char* expand = nullptr,
37+
const char* fields = nullptr);
38+
39+
PBResponse getListEx(const char* page = nullptr,
40+
const char* perPage = nullptr,
41+
const char* sort = nullptr,
42+
const char* filter = nullptr,
43+
const char* skipTotal = nullptr,
44+
const char* expand = nullptr,
45+
const char* fields = nullptr);
46+
47+
PBResponse createEx(const String& requestBody);
48+
49+
PBResponse updateEx(const char* recordId, const String& requestBody);
50+
51+
PBResponse deleteRecordEx(const char* recordId);
52+
53+
// ---------- Convenience methods (return body String) ----------
54+
55+
String getOne(const char* recordId,
56+
const char* expand = nullptr,
57+
const char* fields = nullptr);
58+
59+
String getList(const char* page = nullptr,
60+
const char* perPage = nullptr,
61+
const char* sort = nullptr,
62+
const char* filter = nullptr,
63+
const char* skipTotal = nullptr,
64+
const char* expand = nullptr,
65+
const char* fields = nullptr);
66+
67+
String create(const String& requestBody);
68+
69+
String update(const char* recordId, const String& requestBody);
70+
71+
String deleteRecord(const char* recordId);
72+
73+
// ---------- Auth ----------
74+
75+
// POST /api/collections/{collection}/auth-with-password
76+
// On success, automatically stores the returned token.
77+
PBResponse authWithPassword(const char* identity, const char* password);
78+
79+
void setAuthToken(const String& token);
80+
String getAuthToken() const;
81+
void clearAuthToken();
82+
83+
// ---------- Configuration ----------
84+
85+
void setTimeout(uint32_t ms);
86+
void setInsecureTLS(bool enabled);
87+
void setDebug(bool enabled);
9588

9689
private:
97-
String base_url;
98-
String current_endpoint;
99-
String expand_param;
100-
String fields_param;
90+
String _baseUrl; // e.g. "http://host/api/"
91+
String _collection;
92+
String _authToken;
93+
uint32_t _timeout;
94+
bool _insecureTLS;
95+
bool _debug;
96+
97+
// Build /api/collections/{collection}/records[/recordId]
98+
String _buildRecordsUrl(const char* recordId = nullptr);
99+
100+
// Append a key=value query param; skips if value is null/empty
101+
String _appendParam(const String& url, const char* key, const char* value);
102+
103+
// Unified HTTP request helper
104+
PBResponse _request(const char* method,
105+
const String& url,
106+
const String& body = "");
107+
108+
void _debugPrint(const String& msg);
101109
};
102110

111+
// Backward-compatibility alias for sketches that used PocketbaseArduino
112+
using PocketbaseArduino = PocketbaseExtended;
113+
103114
#endif

0 commit comments

Comments
 (0)