skapi 2.4.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
skapi/_forward.py ADDED
@@ -0,0 +1,484 @@
1
+ """
2
+ Request forwarding (call another API through Skapi, with your stored client secrets) and
3
+ inquiries, ported from skapi-js (src/methods/request.ts).
4
+
5
+ Answers arrive by polling, exactly as skapi-js does without its realtime connection: a queued or
6
+ streamed request is dispatched, then polled until it settles. Streamed text is handed to an
7
+ on_stream(text, seq) callback as it arrives.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import base64
13
+ import json
14
+ import random
15
+ import string
16
+ import time
17
+ import uuid
18
+ import warnings
19
+ from typing import Any, Callable, Dict, Optional
20
+
21
+ from ._database import _prepare_files
22
+ from ._http import js_json
23
+ from ._user import _url, validate_email
24
+ from .errors import SkapiError
25
+
26
+ METHODS = ("get", "post", "delete", "put", "patch", "head")
27
+ UPPER_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"]
28
+ STREAM_DEGRADED_RETRIES = 3
29
+ MULTIPART_LIMIT = 2 * 1024 * 1024 - 64 * 1024
30
+
31
+
32
+ def _jd(v):
33
+ """A value as it appears in an error message; never fails on odd types."""
34
+ return json.dumps(v, default=repr, ensure_ascii=False)
35
+
36
+
37
+ def _p(message: str, code: str = "INVALID_PARAMETER") -> SkapiError:
38
+ return SkapiError(message, code)
39
+
40
+
41
+ def _absolute_url(v: Any, field: str = "url") -> str:
42
+ if v == "*":
43
+ return v
44
+ try:
45
+ from urllib.parse import urlsplit
46
+ parts = urlsplit(v)
47
+ if not parts.scheme or not parts.netloc:
48
+ raise ValueError
49
+ except (ValueError, TypeError, AttributeError):
50
+ raise _p(f'"{v}" is an invalid url.') from None
51
+ return v
52
+
53
+
54
+ def request_key(method: str, url: str, service: str, request_id: str) -> str:
55
+ """The full id skapi-js and the server know a forwarded request by."""
56
+ return f"[{method.upper()}]{url.lower()}#{service}:{request_id}"
57
+
58
+
59
+ def _has_secret(v: Any) -> bool:
60
+ if isinstance(v, str):
61
+ return "$CLIENT_SECRET" in v
62
+ if isinstance(v, dict):
63
+ return any(_has_secret(x) for x in v.values())
64
+ if isinstance(v, list):
65
+ return any(_has_secret(x) for x in v)
66
+ return False
67
+
68
+
69
+ def _is_envelope(v: Any) -> bool:
70
+ return isinstance(v, dict) and isinstance(v.get("status"), str) and isinstance(v.get("id"), str) and "in_queue" in v
71
+
72
+
73
+ def _deliver_chunks(result: Any, cursor: int, on_stream: Callable) -> tuple:
74
+ moved = False
75
+ chunks = result.get("chunks") if isinstance(result, dict) else None
76
+ if isinstance(chunks, list):
77
+ for c in sorted((c for c in chunks if isinstance(c, dict) and isinstance(c.get("seq"), int)), key=lambda c: c["seq"]):
78
+ if c["seq"] > cursor:
79
+ cursor = c["seq"]
80
+ moved = True
81
+ if isinstance(c.get("txt"), str) and c["txt"]:
82
+ try:
83
+ on_stream(c["txt"], c["seq"])
84
+ except Exception as err:
85
+ # the request goes on; the callback's error is reported, not raised
86
+ warnings.warn(f"on_stream raised {err!r} for chunk {c['seq']}", RuntimeWarning, stacklevel=2)
87
+ last = result.get("last_seq") if isinstance(result, dict) else None
88
+ if isinstance(last, int) and not isinstance(last, bool) and last > cursor:
89
+ cursor = last
90
+ moved = True
91
+ return cursor, moved
92
+
93
+
94
+ def _multipart(form: Dict[str, Any]) -> tuple:
95
+ """A multipart/form-data body from a dict: files as file parts, the rest as text."""
96
+ boundary = "----skapi" + uuid.uuid4().hex
97
+ out = []
98
+
99
+ def text_part(name, value):
100
+ out.append(f'--{boundary}\r\nContent-Disposition: form-data; name="{name}"\r\n\r\n'.encode("utf-8") + value.encode("utf-8") + b"\r\n")
101
+
102
+ def file_part(name, entry):
103
+ safe = entry["filename"].replace('"', "%22").replace("\r", "").replace("\n", "")
104
+ out.append(f'--{boundary}\r\nContent-Disposition: form-data; name="{name}"; filename="{safe}"\r\n'
105
+ f'Content-Type: {entry["content_type"] or "application/octet-stream"}\r\n\r\n'.encode("utf-8") + entry["content"] + b"\r\n")
106
+
107
+ for name, value in form.items():
108
+ for v in value if isinstance(value, list) else [value]:
109
+ if isinstance(v, dict) and "file" in v:
110
+ file_part(name, _prepare_files([dict(v, name=name)])[0])
111
+ elif isinstance(v, (bytes, bytearray)):
112
+ file_part(name, {"filename": name, "content": bytes(v), "content_type": None})
113
+ elif v is None:
114
+ text_part(name, "")
115
+ elif isinstance(v, bool):
116
+ text_part(name, "true" if v else "false")
117
+ elif isinstance(v, (dict, list)):
118
+ text_part(name, js_json(v))
119
+ else:
120
+ text_part(name, js_json(v) if isinstance(v, float) else str(v))
121
+ out.append(f"--{boundary}--\r\n".encode("utf-8"))
122
+ return b"".join(out), f"multipart/form-data; boundary={boundary}"
123
+
124
+
125
+ class ForwardMixin:
126
+ """Mixed into Skapi."""
127
+
128
+ # ---- forwardRequest -----------------------------------------------------------------------------
129
+
130
+ def forward_request(self, options: Dict[str, Any], form: Optional[Dict[str, Any]] = None, *,
131
+ on_stream: Optional[Callable[[str, int], None]] = None) -> Any:
132
+ """
133
+ Calls another API through Skapi. options: url (required), method, headers, data, params,
134
+ secretName (a client secret stored on skapi.com; put "$CLIENT_SECRET" where it goes),
135
+ skapiHeaders, queue, expires, stream, poll (milliseconds between checks), multipart.
136
+
137
+ Without queue/poll/stream: returns the API's answer. With poll or stream: waits for the
138
+ answer and returns it, handing streamed text to on_stream(text, seq) as it arrives. With a
139
+ queue and no poll: returns {id, status, queue_name, in_queue, request_id} at once; check it
140
+ later with forward_request_poll(request_id).
141
+ """
142
+ if not isinstance(options, dict):
143
+ raise _p('"options" is required in the second argument.')
144
+ if options.get("apiKeyHeader") is not None or options.get("apiKeyScheme") is not None:
145
+ raise _p('"apiKeyHeader" and "apiKeyScheme" are no longer supported. Store the key as a client secret, name it with "secretName", and put "$CLIENT_SECRET" where the key goes.')
146
+ multipart = options.get("multipart")
147
+ if multipart is not None and not isinstance(multipart, bool):
148
+ raise _p('"multipart" should be type: <boolean>.')
149
+ response_type = options.get("responseType")
150
+ if response_type is not None:
151
+ if response_type == "response":
152
+ raise _p('"responseType": "response" is not available here. The request is relayed from the server and what comes back is the stored answer, not a live Response; the destination\'s status code is the "status_code" of the row forward_request_history lists.')
153
+ if response_type not in ("json", "text"):
154
+ raise _p('"responseType" should be either "json" or "text".')
155
+ method = options.get("method") or "POST"
156
+ merge_into = "params" if isinstance(method, str) and method.lower() in ("get", "delete", "head") else "data"
157
+
158
+ params: Dict[str, Any] = {"url": options.get("url"), "method": method}
159
+ for k in ("secretName", "headers", "data", "params", "skapiHeaders", "service", "owner", "queue", "expires", "stream", "realtime", "poll"):
160
+ if k in options and options[k] is not None:
161
+ params[k] = options[k]
162
+
163
+ if multipart:
164
+ if options.get("data") is not None:
165
+ raise _p('"data" cannot be sent with "multipart": true. The form itself is the body.')
166
+ if form is None:
167
+ raise _p('"multipart": true needs a form body in the first argument.')
168
+ if not isinstance(form, dict):
169
+ raise _p('"form" should be a submit event, a form element, FormData, or an object.')
170
+ body, content_type = _multipart(form)
171
+ b64 = base64.b64encode(body).decode("ascii")
172
+ if len(b64) > MULTIPART_LIMIT:
173
+ raise _p(f"Multipart body is too large: {len(b64)} bytes once base64 encoded, and the limit is {MULTIPART_LIMIT}. Upload the file first and send its url instead.")
174
+ params["body_b64"] = b64
175
+ params["body_content_type"] = content_type
176
+ elif isinstance(form, dict) and form:
177
+ if params.get(merge_into) is not None and not isinstance(params[merge_into], dict):
178
+ raise _p(f'"{merge_into}" should be type: <object>.')
179
+ if len(json.dumps(form, default=str).encode("utf-8")) > 2 * 1024 * 1024:
180
+ raise SkapiError("Data should not exceed 2MB", "INVALID_REQUEST")
181
+ params[merge_into] = dict(form, **(params.get(merge_into) or {}))
182
+
183
+ return self._dispatch_forward(params, on_stream, response_type)
184
+
185
+ def _dispatch_forward(self, params: Dict[str, Any], on_stream: Optional[Callable], response_type: Optional[str]) -> Any:
186
+ secret_named = bool(params.get("secretName"))
187
+ poll = params.pop("poll", None)
188
+ if isinstance(poll, (int, float)) and not isinstance(poll, bool) and poll < 0:
189
+ raise _p('"poll" should be a non-negative number.')
190
+ latency = poll if isinstance(poll, (int, float)) and not isinstance(poll, bool) else (1000 if poll else 0)
191
+ self._ensure_connection()
192
+ signed_in = self._signed_in()
193
+ if (latency or params.get("stream")) and not params.get("queue"):
194
+ params["queue"] = f"{(self._user or {}).get('user_id') or 'anonymous'}-" + "".join(random.choice(string.ascii_letters + string.digits) for _ in range(6))
195
+
196
+ body: Dict[str, Any] = {}
197
+ url = params.get("url")
198
+ if not url or not isinstance(url, str):
199
+ raise _p('"url" should be type: <string>.')
200
+ _absolute_url(url)
201
+ body["url"] = url
202
+ has_secret = "$CLIENT_SECRET" in url
203
+ if "secretName" in params:
204
+ if not isinstance(params["secretName"], str):
205
+ raise _p(f'{_jd(params["secretName"])} is invalid in "secretName". allowed type or value is: Type<string>.')
206
+ body["secretName"] = params["secretName"]
207
+ m = params.get("method")
208
+ if m and (not isinstance(m, str) or m.lower() not in METHODS):
209
+ raise _p('"method" should be one of "GET", "POST", "PUT", "PATCH", "DELETE" or "HEAD".')
210
+ body["method"] = m.lower()
211
+ for k in ("stream", "realtime"):
212
+ if k in params:
213
+ if not isinstance(params[k], bool):
214
+ raise _p(f'"{k}" should be type: <boolean>.')
215
+ body[k] = params[k]
216
+ if "headers" in params:
217
+ h = params["headers"]
218
+ if h and not isinstance(h, dict):
219
+ raise _p('"headers" should be type: <object>.')
220
+ for k in (h or {}):
221
+ if str(k).lower().startswith("x-skapi-"):
222
+ raise _p(f'"headers" cannot set "{k}": the "x-skapi-" prefix is reserved. Use "skapiHeaders" to tell the destination who the caller is.')
223
+ has_secret = has_secret or _has_secret(h)
224
+ body["headers"] = h
225
+ if "skapiHeaders" in params:
226
+ sh = params["skapiHeaders"]
227
+ if isinstance(sh, bool):
228
+ body["skapiHeaders"] = sh
229
+ elif isinstance(sh, dict):
230
+ body["skapiHeaders"] = {"user": bool(sh.get("user")), "service": bool(sh.get("service"))}
231
+ else:
232
+ raise _p('"skapiHeaders" should be type: <boolean> or { user?: boolean; service?: boolean }.')
233
+ for k in ("data", "params"):
234
+ if k in params:
235
+ v = params[k]
236
+ if v and not isinstance(v, dict):
237
+ raise _p(f'"{k}" should be type: <object>.')
238
+ has_secret = has_secret or _has_secret(v)
239
+ body[k] = v
240
+ for k in ("body_b64", "body_content_type"):
241
+ if k in params:
242
+ body[k] = params[k]
243
+ if "expires" in params:
244
+ if isinstance(params["expires"], bool) or not isinstance(params["expires"], (int, float)):
245
+ raise _p(f'{_jd(params["expires"])} is invalid in "expires". allowed type or value is: Type<number>.')
246
+ body["expires"] = params["expires"]
247
+ if "queue" in params:
248
+ if not isinstance(params["queue"], str):
249
+ raise _p(f'{_jd(params["queue"])} is invalid in "queue". allowed type or value is: Type<string>.')
250
+ body["queue"] = params["queue"]
251
+ for k in ("service", "owner"):
252
+ if k in params:
253
+ body[k] = params[k]
254
+ if body.get("realtime") and not body.get("stream"):
255
+ raise _p('"realtime" requires "stream": true.')
256
+ if body.get("body_b64") and body.get("data"):
257
+ raise _p('"data" cannot be sent with "multipart": true.')
258
+ if secret_named and not has_secret:
259
+ body.pop("secretName", None)
260
+
261
+ token = self._fresh_id_token() if signed_in else None
262
+ extra = {"X-Access-Token": self._session.access_token.jwt_token} if signed_in else None
263
+ res = self._requester.request("csr", body, auth=signed_in, token=token, extra_headers=extra)
264
+
265
+ service = params.get("service") or self.service
266
+ if _is_envelope(res) and res.get("status") in ("running", "pending"):
267
+ full_id = request_key(body["method"], url, service, res["id"])
268
+ res["request_id"] = full_id
269
+ if latency > 0 or body.get("stream"):
270
+ res = self.forward_request_poll(full_id, poll=latency or 1000, on_stream=on_stream,
271
+ service=params.get("service"), owner=params.get("owner"))
272
+ return self._response_type(res, response_type)
273
+
274
+ @staticmethod
275
+ def _response_type(res: Any, response_type: Optional[str]) -> Any:
276
+ if not response_type or _is_envelope(res) or (isinstance(res, dict) and res.get("status") == "stopped"):
277
+ return res
278
+ if response_type == "text":
279
+ return res if isinstance(res, str) else js_json(res)
280
+ if isinstance(res, str):
281
+ try:
282
+ return json.loads(res)
283
+ except ValueError:
284
+ return res
285
+ return res
286
+
287
+ def _request_id(self, request_id: Any, url: Optional[str], method: Optional[str], service: Optional[str]) -> str:
288
+ if not isinstance(request_id, str) or not request_id:
289
+ raise _p('"requestId" should be type: <string>.')
290
+ if "#" in request_id:
291
+ return request_id
292
+ if not isinstance(url, str) or not isinstance(method, str) or not url or not method:
293
+ raise _p('"url" and "method" are required to address a request by its short id.')
294
+ _absolute_url(url)
295
+ return request_key(method, url, service or self.service, request_id)
296
+
297
+ def forward_request_poll(self, request_id: str, *, poll: float = 1000, url: Optional[str] = None, method: Optional[str] = None,
298
+ on_stream: Optional[Callable[[str, int], None]] = None,
299
+ service: Optional[str] = None, owner: Optional[str] = None) -> Any:
300
+ """Waits for a queued request (its request_id, or its short id with url and method) and returns the answer."""
301
+ if isinstance(poll, bool) or not isinstance(poll, (int, float)):
302
+ raise _p('"poll" should be a number.')
303
+ if poll < 0:
304
+ raise _p('"poll" should be a non-negative number.')
305
+ poll = poll or 1000
306
+ full_id = self._request_id(request_id, url, method, service)
307
+ self._ensure_connection()
308
+ cursor, stalled = 0, 0
309
+ while True:
310
+ time.sleep(poll / 1000)
311
+ while True:
312
+ body = {"id": full_id, "service": service or self.service, "owner": owner or self.owner}
313
+ if on_stream:
314
+ body["since"] = cursor
315
+ result = self._call("csr-poll", body, auth=self._signed_in())
316
+ # Chunks, "more" and a running status belong to skapi's status envelope. A resolved
317
+ # read is the destination's own body, returned as it is: a "chunks", "more" or
318
+ # "status": "pending" key in THAT is the destination's data, not text to stream or
319
+ # a cue to read again.
320
+ envelope = _is_envelope(result)
321
+ moved = False
322
+ if on_stream and envelope:
323
+ cursor, moved = _deliver_chunks(result, cursor, on_stream)
324
+ running = envelope and result.get("status") in ("running", "pending")
325
+ more = envelope and bool(result.get("more"))
326
+ if more and moved:
327
+ stalled = 0
328
+ continue
329
+ if running:
330
+ stalled = 0
331
+ break
332
+ stalled = stalled + 1 if more else 0
333
+ if more and stalled < STREAM_DEGRADED_RETRIES:
334
+ break
335
+ return result
336
+
337
+ def forward_request_stream(self, request_id: str, options: Optional[Dict[str, Any]] = None, *,
338
+ on_stream: Optional[Callable[[str, int], None]] = None) -> Any:
339
+ """Reads a streamed request's text from `since` (or the start) until it settles; returns the final answer."""
340
+ options = dict(options or {})
341
+ poll = options.get("poll")
342
+ latency = poll if isinstance(poll, (int, float)) and not isinstance(poll, bool) else 1000
343
+ if latency < 0:
344
+ raise _p('"poll" should be a non-negative number.')
345
+ if "since" in options and (isinstance(options["since"], bool) or not isinstance(options["since"], (int, float))):
346
+ raise _p('"since" should be a number.')
347
+ full_id = self._request_id(request_id, options.get("url"), options.get("method"), options.get("service"))
348
+ self._ensure_connection()
349
+ cursor = int(options.get("since") or 0) if (options.get("since") or 0) > 0 else 0
350
+ stalled = 0
351
+ while True:
352
+ result = self._call("csr-poll", {"id": full_id, "service": options.get("service") or self.service,
353
+ "owner": options.get("owner") or self.owner, "since": cursor}, auth=self._signed_in())
354
+ if not _is_envelope(result):
355
+ return result
356
+ moved = False
357
+ if on_stream:
358
+ cursor, moved = _deliver_chunks(result, cursor, on_stream)
359
+ elif isinstance(result.get("last_seq"), int) and result["last_seq"] > cursor:
360
+ cursor, moved = result["last_seq"], True
361
+ running = result.get("status") in ("running", "pending")
362
+ more = bool(result.get("more"))
363
+ if more and moved:
364
+ continue
365
+ stalled = stalled + 1 if more else 0
366
+ if not running and (not more or stalled >= STREAM_DEGRADED_RETRIES):
367
+ return result
368
+ time.sleep(latency / 1000)
369
+
370
+ def forward_request_finalize(self, request_id: str, data: Any = None, options: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
371
+ """Stores `data` as a streamed request's final answer, so later polls return it."""
372
+ options = dict(options or {})
373
+ full_id = self._request_id(request_id, options.get("url"), options.get("method"), options.get("service"))
374
+ self._ensure_connection()
375
+ body: Dict[str, Any] = {"id": full_id}
376
+ if data is not None:
377
+ body["data"] = data
378
+ body.update({"service": options.get("service") or self.service, "owner": options.get("owner") or self.owner})
379
+ return self._call("csr-finalize", body, auth=self._signed_in())
380
+
381
+ def forward_request_history(self, params: Dict[str, Any], fetch_options: Optional[dict] = None) -> dict:
382
+ """The forwarded requests you made to one url and method, newest last, with their answers."""
383
+ self._ensure_connection()
384
+ params = dict(params or {})
385
+ service = params.get("service") or self.service
386
+ owner = params.get("owner") or self.owner
387
+ for key in ("url", "method"):
388
+ if key not in params:
389
+ raise _p(f'Key "{key}" is required.')
390
+ if not isinstance(params["url"], str):
391
+ raise _p(f'{_jd(params["url"])} is invalid in "url". allowed type or value is: Type<string>.')
392
+ if params["method"] not in UPPER_METHODS:
393
+ raise _p(f'{_jd(params["method"])} is invalid in "method". allowed types or values are: ' + ", ".join(_jd(m) for m in UPPER_METHODS) + ".")
394
+ if "status" in params and params["status"] not in ("pending", "running", "resolved", "failed"):
395
+ raise _p(f'{_jd(params["status"])} is invalid in "status". allowed types or values are: "pending", "running", "resolved", "failed".')
396
+ for k in ("queue", "queue_exclude"):
397
+ if k in params and params[k] is not None and not isinstance(params[k], str):
398
+ raise _p(f'{_jd(params[k])} is invalid in "{k}". allowed type or value is: Type<string>.')
399
+ for k in ("compact", "queue_exact"):
400
+ if k in params and not isinstance(params[k], bool):
401
+ raise _p(f'{_jd(params[k])} is invalid in "{k}". allowed type or value is: Type<boolean>.')
402
+ prefix = request_key(params["method"], params["url"], service, "")
403
+ req: Dict[str, Any] = {"id": prefix, "queue": params.get("queue"), "status": params.get("status"), "service": service, "owner": owner}
404
+ if params.get("compact"):
405
+ req["compact"] = True
406
+ if params.get("queue_exact"):
407
+ req["queue_exact"] = True
408
+ if params.get("queue_exclude"):
409
+ req["queue_exclude"] = params["queue_exclude"]
410
+ req = {k: v for k, v in req.items() if v}
411
+ if req.get("queue"):
412
+ req["id_prefix"] = req.pop("id")
413
+ res = self._call("csr-poll", req, auth=self._signed_in(), fetch_options=fetch_options)
414
+ if isinstance(res, dict) and isinstance(res.get("list"), list):
415
+ out = []
416
+ for r in res["list"]:
417
+ rslv = r.get("rslv") or {}
418
+ item = {
419
+ "id": r.get("id"),
420
+ "status_code": rslv.get("status_code") if isinstance(rslv, dict) else None,
421
+ "response_body": (rslv.get("body") or rslv.get("truncated")) if isinstance(rslv, dict) else None,
422
+ }
423
+ for key, src in (("error", "err"), ("created", "stmp"), ("updated", "utmp")):
424
+ if src in r:
425
+ item[key] = r[src]
426
+ if isinstance(r.get("att"), (int, float)):
427
+ item["executed"] = r["att"] * 1000
428
+ if isinstance(r.get("rtmp"), (int, float)):
429
+ item["responded"] = r["rtmp"]
430
+ for key, src in (("request_body", "reqbdy"), ("expires", "expt"), ("status", "stts"), ("queue_name", "qid"),
431
+ ("request_text", "reqtxt"), ("response_text", "rslvtxt")):
432
+ if src in r:
433
+ item[key] = r[src]
434
+ if r.get("rslvmk") is not None:
435
+ item["response_complete_marker"] = bool(r["rslvmk"])
436
+ if r.get("cmpct"):
437
+ item["compact"] = True
438
+ item["request_id"] = prefix + str(r.get("id"))
439
+ out.append(item)
440
+ res["list"] = out
441
+ return res
442
+
443
+ def cancel_forward_request(self, params: Dict[str, Any]) -> Dict[str, Any]:
444
+ """Cancels a queued request that has not run yet: {url, method, id}."""
445
+ params = dict(params or {})
446
+ for key in ("url", "method", "id"):
447
+ if key not in params:
448
+ raise _p(f'Key "{key}" is required.')
449
+ if params["method"] not in UPPER_METHODS:
450
+ raise _p(f'{_jd(params["method"])} is invalid in "method". allowed types or values are: ' + ", ".join(_jd(m) for m in UPPER_METHODS) + ".")
451
+ for key in ("url", "id", "queue"):
452
+ if key in params and not isinstance(params[key], str):
453
+ raise _p(f'{_jd(params[key])} is invalid in "{key}". allowed type or value is: Type<string>.')
454
+ self._ensure_connection()
455
+ service = params.get("service") or self.service
456
+ full_id = request_key(params["method"], params["url"], service, params["id"])
457
+ return self._call("csr-cancel", {"id": full_id, "service": service, "owner": params.get("owner") or self.owner}, auth=self._signed_in())
458
+
459
+ def forward_request_queue_count(self, params: Dict[str, Any]) -> Dict[str, Any]:
460
+ """How many requests are waiting in one of your queues. Signed-in users only."""
461
+ params = dict(params or {})
462
+ if not params.get("queue"):
463
+ raise _p('"queue" is required.')
464
+ res = self._call("csr-poll", {"service": params.get("service") or self.service, "owner": params.get("owner") or self.owner,
465
+ "queue": params["queue"] + ":"}, auth=True)
466
+ if isinstance(res, dict) and isinstance(res.get("queue_name"), str):
467
+ res["queue_name"] = res["queue_name"].rstrip(":")
468
+ return res
469
+
470
+ # ---- inquiry ----------------------------------------------------------------------------------
471
+
472
+ def send_inquiry(self, data: Dict[str, Any]) -> str:
473
+ """Sends a message to the project's owner: {name, email, subject, message}."""
474
+ self._ensure_connection()
475
+ data = dict(data or {})
476
+ for key in ("name", "email", "subject", "message"):
477
+ if key not in data:
478
+ raise _p(f'Key "{key}" is required.')
479
+ for key in ("name", "subject", "message"):
480
+ if not isinstance(data[key], str):
481
+ raise _p(f'{_jd(data[key])} is invalid in "{key}". allowed type or value is: Type<string>.')
482
+ validate_email(data["email"])
483
+ self._call("send-inquiry", {k: data[k] for k in ("name", "email", "subject", "message")})
484
+ return "SUCCESS: Inquiry has been sent."