Skip to content

Commit 6651793

Browse files
Signals
1 parent 36ee719 commit 6651793

10 files changed

Lines changed: 550 additions & 3 deletions

File tree

‎linkedapi/client.py‎

Lines changed: 93 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
from __future__ import annotations
22

33
from typing import Any, overload
4-
from urllib.parse import urlencode
4+
from urllib.parse import quote, urlencode
55

66
from linkedapi.config import LinkedApiConfig
77
from linkedapi.errors import LinkedApiError
@@ -78,7 +78,7 @@
7878
SyncNetwork,
7979
WithdrawConnectionRequest,
8080
)
81-
from linkedapi.types import AccountInfo, LinkedApiActionError, serialize_value
81+
from linkedapi.types import AccountInfo, LinkedApiActionError, LinkedApiResponse, serialize_value
8282
from linkedapi.types.message import (
8383
ConversationPollRequest,
8484
ConversationPollResult,
@@ -88,6 +88,14 @@
8888
InboxPollRequest,
8989
)
9090
from linkedapi.types.network import NetworkEvent, NetworkPollRequest
91+
from linkedapi.types.signals import (
92+
CreateSignalParams,
93+
GetSignalsParams,
94+
Signal,
95+
SignalEvent,
96+
SignalIdParams,
97+
SignalPollRequest,
98+
)
9199
from linkedapi.types.statistics import ApiUsageAction, ApiUsageParams
92100

93101

@@ -352,6 +360,75 @@ def poll_network(
352360
],
353361
)
354362

363+
def create_signal(self, params: CreateSignalParams) -> MappedResponse[Signal]:
364+
"""Create a signal: one thing for the account to watch on LinkedIn.
365+
366+
Creating a signal that already exists on the account returns that signal instead of a
367+
second one. Raises LinkedApiError "invalidRequestPayload" or "signalLimitReached".
368+
"""
369+
370+
result = _signal_result(self.http_client.post("/signals", serialize_value(params)))
371+
return MappedResponse(data=Signal.model_validate(result), errors=[])
372+
373+
def get_signals(self, params: GetSignalsParams | None = None) -> MappedResponse[list[Signal]]:
374+
"""List the account's signals, optionally only those of one type or status."""
375+
376+
query = urlencode(serialize_value(params) if params is not None else {})
377+
result = _signal_result(self.http_client.get(f"/signals?{query}" if query else "/signals"))
378+
return MappedResponse(
379+
data=[Signal.model_validate(item) for item in result.get("signals", [])],
380+
errors=[],
381+
)
382+
383+
def get_signal(self, params: SignalIdParams) -> MappedResponse[Signal]:
384+
"""Retrieve one signal. Raises LinkedApiError "signalNotFound"."""
385+
386+
result = _signal_result(self.http_client.get(_signal_path(params.signal_id)))
387+
return MappedResponse(data=Signal.model_validate(result), errors=[])
388+
389+
def pause_signal(self, params: SignalIdParams) -> MappedResponse[Signal]:
390+
"""Pause a signal. A paused signal is not checked; its events stay available.
391+
392+
Raises LinkedApiError "signalNotFound" or "signalStopped".
393+
"""
394+
395+
result = _signal_result(self.http_client.post(f"{_signal_path(params.signal_id)}/pause"))
396+
return MappedResponse(data=Signal.model_validate(result), errors=[])
397+
398+
def resume_signal(self, params: SignalIdParams) -> MappedResponse[Signal]:
399+
"""Resume a paused signal. Its first check reports what appeared while it was paused, as
400+
far as LinkedIn still shows it.
401+
402+
Raises LinkedApiError "signalNotFound", "signalStopped" or "signalLimitReached".
403+
"""
404+
405+
result = _signal_result(self.http_client.post(f"{_signal_path(params.signal_id)}/resume"))
406+
return MappedResponse(data=Signal.model_validate(result), errors=[])
407+
408+
def delete_signal(self, params: SignalIdParams) -> MappedResponse[bool]:
409+
"""Delete a signal. Its checks stop at once; the events it produced stay available
410+
through poll_signals. Raises LinkedApiError "signalNotFound"."""
411+
412+
result = _signal_result(self.http_client.delete(_signal_path(params.signal_id)))
413+
return MappedResponse(data=result.get("deleted") is True, errors=[])
414+
415+
def poll_signals(
416+
self,
417+
request: SignalPollRequest | None = None,
418+
) -> MappedResponse[list[SignalEvent]]:
419+
"""Read the events your signals detected, newest first.
420+
421+
Pass "since": without it every retained event is returned. On each next request pass the
422+
"detected_at" of the newest event you have, and process each event once by its "id".
423+
"""
424+
425+
payload = serialize_value(request) if request is not None else {}
426+
result = _signal_result(self.http_client.post("/signals/poll", payload))
427+
return MappedResponse(
428+
data=[SignalEvent.model_validate(item) for item in result.get("events", [])],
429+
errors=[],
430+
)
431+
355432
def get_account_info(self) -> MappedResponse[AccountInfo]:
356433
"""Retrieve basic information about the current LinkedIn account."""
357434

@@ -377,3 +454,17 @@ def get_api_usage(self, params: ApiUsageParams) -> MappedResponse[list[ApiUsageA
377454
response.error.type if response.error else "httpError",
378455
response.error.message if response.error else "",
379456
)
457+
458+
459+
# Signal ids are opaque ("sigsub-..."), so they are quoted rather than validated.
460+
def _signal_path(signal_id: str) -> str:
461+
return f"/signals/{quote(signal_id, safe='')}"
462+
463+
464+
def _signal_result(response: LinkedApiResponse[Any]) -> Any:
465+
if response.success and response.result is not None:
466+
return response.result
467+
raise LinkedApiError(
468+
response.error.type if response.error else "httpError",
469+
response.error.message if response.error else "",
470+
)

‎linkedapi/errors.py‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -155,6 +155,9 @@
155155
"sessionNotFound",
156156
"noAvailableSeats",
157157
"dailyConnectionAttemptsExceeded",
158+
"signalLimitReached",
159+
"signalNotFound",
160+
"signalStopped",
158161
]
159162
LINKED_API_ERROR_TYPES: tuple[str, ...] = (
160163
"linkedApiTokenRequired",
@@ -180,6 +183,9 @@
180183
"sessionNotFound",
181184
"noAvailableSeats",
182185
"dailyConnectionAttemptsExceeded",
186+
"signalLimitReached",
187+
"signalNotFound",
188+
"signalStopped",
183189
)
184190

185191

‎linkedapi/types/__init__.py‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -310,6 +310,21 @@
310310
SearchPostsPersonFilter,
311311
SearchPostsPersonFilterEntry,
312312
)
313+
from linkedapi.types.signals import (
314+
CreateSignalParams,
315+
GetSignalsParams,
316+
Signal,
317+
SignalComment,
318+
SignalEvent,
319+
SignalEventType,
320+
SignalIdParams,
321+
SignalPollRequest,
322+
SignalPostSearchFilter,
323+
SignalReaction,
324+
SignalStatus,
325+
SignalStoppedReason,
326+
SignalType,
327+
)
313328
from linkedapi.types.statistics import (
314329
ApiUsageAction,
315330
ApiUsageParams,
@@ -340,6 +355,8 @@
340355
SetWebhookParams,
341356
SetWebhookPayloadModeParams,
342357
SetWebhookSigningParams,
358+
SignalWebhookEvent,
359+
SignalWebhookEventData,
343360
UnknownWebhookEvent,
344361
WebhookDelivery,
345362
WebhookDeliveryStatus,
@@ -420,6 +437,7 @@
420437
"CreateReconnectionSessionResult",
421438
"CreateRepostParams",
422439
"CreateRepostResult",
440+
"CreateSignalParams",
423441
"DeleteLimitEntry",
424442
"DeleteLimitsParams",
425443
"DeleteWebhookHeaderParams",
@@ -440,6 +458,7 @@
440458
"GetConnectionSessionParams",
441459
"GetLimitsParams",
442460
"GetLimitsUsageParams",
461+
"GetSignalsParams",
443462
"IgnoreInvitationParams",
444463
"InboxMessage",
445464
"InboxPersonMessage",
@@ -657,6 +676,19 @@
657676
"SetWebhookParams",
658677
"SetWebhookPayloadModeParams",
659678
"SetWebhookSigningParams",
679+
"Signal",
680+
"SignalComment",
681+
"SignalEvent",
682+
"SignalEventType",
683+
"SignalIdParams",
684+
"SignalPollRequest",
685+
"SignalPostSearchFilter",
686+
"SignalReaction",
687+
"SignalStatus",
688+
"SignalStoppedReason",
689+
"SignalType",
690+
"SignalWebhookEvent",
691+
"SignalWebhookEventData",
660692
"StCompanyDm",
661693
"StCompanyEmployee",
662694
"StCompanyEmployeesFilter",

‎linkedapi/types/signals.py‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
from __future__ import annotations
2+
3+
from typing import Any, Literal
4+
5+
from pydantic import Field
6+
7+
from linkedapi.types.base import LinkedApiModel
8+
from linkedapi.types.post import PostAuthor, PostComment, ReactionType
9+
from linkedapi.types.profile_viewers import ProfileViewer
10+
from linkedapi.types.search_posts import (
11+
PostSearchContentType,
12+
PostSearchPostedBy,
13+
SearchPostResult,
14+
SearchPostsCompanyFilterEntry,
15+
SearchPostsPersonFilterEntry,
16+
)
17+
18+
SignalType = Literal[
19+
"personPosts",
20+
"companyPosts",
21+
"postSearch",
22+
"postEngagement",
23+
"network",
24+
"profileViewers",
25+
]
26+
SignalStatus = Literal["active", "paused", "stopped"]
27+
SignalStoppedReason = Literal["targetNotFound", "watchPeriodEnded"]
28+
SignalEventType = Literal[
29+
"postPublished",
30+
"postFound",
31+
"commentAdded",
32+
"reactionAdded",
33+
"profileViewed",
34+
"connectionAccepted",
35+
"connectionAdded",
36+
"connectionRequestReceived",
37+
]
38+
39+
40+
class SignalPostSearchFilter(LinkedApiModel):
41+
"""The filters a "postSearch" signal accepts: the content search filters other than sort,
42+
date and author."""
43+
44+
content_type: PostSearchContentType | None = None
45+
posted_by: list[PostSearchPostedBy] | None = None
46+
mentioning_members: list[SearchPostsPersonFilterEntry] | None = None
47+
mentioning_companies: list[SearchPostsCompanyFilterEntry] | None = None
48+
author_companies: list[SearchPostsCompanyFilterEntry] | None = None
49+
author_industries: list[str] | None = None
50+
51+
52+
class CreateSignalParams(LinkedApiModel):
53+
"""A signal to create. The "type" decides the target field.
54+
55+
"personPosts" takes "person_url", "companyPosts" takes "company_url", "postSearch" takes
56+
"term" (a phrase or a list of up to three) and an optional "filter", "postEngagement" takes
57+
"post_url" or "my_posts=True", and "network" and "profileViewers" take none. "label" is your
58+
own identifier, up to 64 characters, returned with the signal and every event it produces.
59+
"""
60+
61+
type: SignalType
62+
label: str | None = Field(default=None, max_length=64)
63+
person_url: str | None = None
64+
company_url: str | None = None
65+
post_url: str | None = None
66+
my_posts: Literal[True] | None = None
67+
term: str | list[str] | None = None
68+
filter: SignalPostSearchFilter | None = None
69+
70+
71+
class GetSignalsParams(LinkedApiModel):
72+
type: SignalType | None = None
73+
status: SignalStatus | None = None
74+
75+
76+
class SignalIdParams(LinkedApiModel):
77+
signal_id: str
78+
79+
80+
class SignalPollRequest(LinkedApiModel):
81+
"""Pass "since" as the "detected_at" of the newest event you have; without it every
82+
retained event is returned."""
83+
84+
since: str | None = None
85+
signal_id: str | None = None
86+
signal_type: SignalType | None = None
87+
event_type: SignalEventType | None = None
88+
89+
90+
class Signal(LinkedApiModel):
91+
id: str | None = None
92+
type: SignalType | str | None = None
93+
label: str | None = None
94+
status: SignalStatus | str | None = None
95+
# Why Linked API stopped the signal; None unless status is "stopped".
96+
stopped_reason: SignalStoppedReason | str | None = None
97+
created_at: str | None = None
98+
baseline_at: str | None = None
99+
last_checked_at: str | None = None
100+
next_check_at: str | None = None
101+
person_url: str | None = None
102+
company_url: str | None = None
103+
post_url: str | None = None
104+
my_posts: bool | None = None
105+
term: str | list[str] | None = None
106+
filter: dict[str, Any] | None = None
107+
108+
109+
class SignalComment(PostComment):
110+
parent_comment_urn: str | None = None
111+
112+
113+
class SignalReaction(LinkedApiModel):
114+
actor: PostAuthor | None = None
115+
type: ReactionType | str | None = None
116+
117+
118+
class SignalEvent(LinkedApiModel):
119+
"""One event a signal detected. Which subject fields are set depends on "type": "post" for
120+
postPublished and postFound, "post_url" with "comment" or "reaction", "viewer" for
121+
profileViewed, and "person_urn" with "person_url" for the connection events."""
122+
123+
id: str | None = None
124+
signal_id: str | None = None
125+
signal_type: SignalType | str | None = None
126+
label: str | None = None
127+
type: SignalEventType | str | None = None
128+
# When Linked API recorded the event, not when it happened on LinkedIn.
129+
detected_at: str | None = None
130+
post: SearchPostResult | None = None
131+
post_url: str | None = None
132+
comment: SignalComment | None = None
133+
reaction: SignalReaction | None = None
134+
viewer: ProfileViewer | None = None
135+
person_urn: str | None = None
136+
person_url: str | None = None

0 commit comments

Comments
 (0)