Skip to content

Commit eeb253d

Browse files
johnbrandborgjohnbrandborg
authored
Release 1.7.0: Planhat time models, docs sidebar, fixes (#17)
Bump version to 1.7.0 for tagging. Add Time_Entry and Timesheet Planhat models with duplicate() for time entries; fix objectives URI and Conversation docstring key. Split Planhat docs under Interfaces in Sphinx. Made-with: Cursor
1 parent 26faf21 commit eeb253d

7 files changed

Lines changed: 214 additions & 156 deletions

File tree

‎docs/changelog.rst‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,21 @@
11
Changelog
22
=========
33

4+
Release 1.7.0 (March 25, 2026)
5+
-------------------------------
6+
7+
Features:
8+
- Planhat: add ``Time_Entry`` and ``Timesheet`` models (``timeentries`` and ``timesheets``).
9+
- Planhat: add ``duplicate()`` on the time entry model for bulk duplicate-by-id.
10+
11+
Fixes:
12+
- Planhat: correct Objective resource path from ``onjectives`` to ``objectives``.
13+
- Planhat: fix Conversation model YAML so ``docstring`` is applied.
14+
15+
Documentation:
16+
- Nest Planhat under Interfaces in the Sphinx sidebar (``interfaces.rst`` + ``planhat.rst``).
17+
- Align Planhat documentation links with https://www.planhat.com/developers.
18+
419
Release 1.6.0 (March 10, 2026)
520
-------------------------------
621

‎docs/interfaces.rst‎

Lines changed: 3 additions & 152 deletions
Original file line numberDiff line numberDiff line change
@@ -6,156 +6,7 @@ Interfaces
66
Within CRUDs pre-configured Interfaces have been created. To use an Interface
77
import them from interface packages under ``cruds.interfaces.<name>``.
88

9-
Currently available:
9+
.. toctree::
10+
:maxdepth: 1
1011

11-
* Planhat
12-
13-
Planhat
14-
-------
15-
16-
Planhat is a comprehensive customer success platform with immense capabilities. CRUDs offers a
17-
full implementation of the Planhat platform as an Interface, providing complete API coverage
18-
for all major Planhat features and data models.
19-
20-
**Official Documentation URL:** https://docs.planhat.com/
21-
22-
**API Endpoints:**
23-
24-
* Main API: https://api.planhat.com/
25-
* Analytics API: https://analytics.planhat.com/
26-
27-
**Authentication:**
28-
29-
* Primary authentication via API token
30-
* Secondary authentication via tenant token for analytics endpoints
31-
* Configurable rate limiting (default: 200 calls per minute)
32-
33-
**Core Features Supported:**
34-
35-
**Data Models (20+ entities):**
36-
37-
* **Asset** - Track nested objects like product instances, devices, or custom entities
38-
* **Campaign** - Manage customer campaigns and adoption initiatives
39-
* **Churn** - Log customer churn events and reasons
40-
* **Company** - Core customer accounts with hierarchical structure support
41-
* **Conversation** - Email, chat, support tickets, and custom communication types
42-
* **Custom_Field** - Extend any object with custom properties
43-
* **Enduser** - Individual contacts at customer companies with domain auto-assignment
44-
* **Invoice** - Track billing and invoicing history
45-
* **Issue** - Bug reports and feature requests (Jira integration support)
46-
* **License** - Subscription management with MRR/ARR calculations
47-
* **Metrics** - Dimension data for customer success metrics
48-
* **NPS** - Net Promoter Score survey responses and scoring
49-
* **Note** - Manual notes and conversation logging
50-
* **Objective** - Customer success goals and health tracking
51-
* **Opportunity** - Sales opportunities and expansion tracking
52-
* **Project** - Time-bound initiatives with custom fields
53-
* **Sale** - Non-recurring revenue tracking
54-
* **Task** - Task management with calendar integration
55-
* **Ticket** - Support ticket management with external system sync
56-
* **User** - Team member management and access control
57-
* **Workspace** - Sub-instance tracking for multi-department engagement
58-
59-
**Standard CRUD Operations:**
60-
61-
All models support the following operations:
62-
63-
* ``create()`` - Create new records
64-
* ``update()`` - Update existing records by ID, External ID, or Source ID
65-
* ``get_by_id()`` - Retrieve records by ID, External ID, or Source ID
66-
* ``get_list()`` - Retrieve paginated lists with filtering and sorting
67-
* ``delete()`` - Remove records
68-
* ``bulk_upsert()`` - Batch create/update operations (up to 5,000 items per request)
69-
70-
**Specialized Methods:**
71-
72-
**Company Model:**
73-
74-
* ``get_lean_list()`` - Lightweight company list for ID matching
75-
76-
**Metrics Model:**
77-
78-
* ``epoc_days_format()`` - Convert dates to epoch days format
79-
* ``get_dimension_data()`` - Retrieve time-series metrics data
80-
* ``bulk_insert_metrics()`` - Batch insert metrics with auto-chunking
81-
82-
**User Activity Model:**
83-
84-
* ``create_activity()`` - Track user engagement events
85-
* ``segment()`` - User segmentation and analytics
86-
87-
**Advanced Features:**
88-
89-
**Bulk Operations:**
90-
91-
* Auto-chunking for large datasets
92-
* Configurable chunk sizes
93-
* Response aggregation and error handling
94-
* Rate limiting with automatic delays
95-
96-
**Data Formatting:**
97-
98-
* Epoch days date format support
99-
* External ID and Source ID reference support
100-
* Custom field extensibility
101-
102-
**Integration Capabilities:**
103-
104-
* CRM system synchronization (Salesforce, etc.)
105-
* Ticketing system integration (Zendesk, etc.)
106-
* Product management tool integration (Jira, Product Board, Aha!)
107-
* NPS tool imports
108-
* Calendar system integration (Google Calendar)
109-
* Webhook support for real-time data sync
110-
111-
**Error Handling:**
112-
113-
* Custom exception classes for bulk operations
114-
* Comprehensive error reporting
115-
* Automatic retry mechanisms
116-
117-
Example Usage:
118-
119-
.. code-block:: python
120-
121-
>>> from cruds.interfaces.planhat import Planhat
122-
>>>
123-
>>> # Initialize with API token and optional tenant token
124-
>>> planhat = Planhat(
125-
... api_token="hJA4eO3tJPhDck1aKLvQ5osvNUfKYdJ7H",
126-
... tenant_token="1d5df0f5-f217-49da-8997-2878f5986a9f"
127-
... )
128-
>>>
129-
>>> # Get comprehensive help
130-
>>> help(planhat)
131-
>>>
132-
>>> # Retrieve a company by external ID
133-
>>> company = planhat.company.get_by_id("extid-21432948")
134-
>>>
135-
>>> # Bulk upsert licenses
136-
>>> licenses_data = [
137-
... {"name": "Premium Plan", "companyId": "extid-123", "value": 1000},
138-
... {"name": "Basic Plan", "companyId": "extid-456", "value": 500}
139-
... ]
140-
>>> result = planhat.license.bulk_upsert(licenses_data)
141-
>>>
142-
>>> # Track user activity
143-
>>> activity_data = {
144-
... "event": "login",
145-
... "userId": "user123",
146-
... "companyId": "extid-123",
147-
... "timestamp": "2024-01-15T10:30:00Z"
148-
... }
149-
>>> planhat.user_activity.create_activity(activity_data)
150-
>>>
151-
>>> # Insert metrics data
152-
>>> metrics_data = {
153-
... "dimensionId": "daily_logins",
154-
... "companyId": "extid-123",
155-
... "value": 150,
156-
... "time": "2024-01-15T00:00:00Z"
157-
... }
158-
>>> planhat.metrics.bulk_insert_metrics([metrics_data])
159-
160-
The configuration file for this Interface can be found on
161-
`Github <https://github.com/johnbrandborg/cruds/blob/main/src/cruds/interfaces/planhat/configuration.yaml>`_.
12+
planhat

‎docs/planhat.rst‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
Planhat
2+
=======
3+
4+
Planhat is a comprehensive customer success platform with immense capabilities. CRUDs offers a
5+
full implementation of the Planhat platform as an Interface, providing complete API coverage
6+
for all major Planhat features and data models.
7+
8+
**Official Documentation URL:** https://www.planhat.com/developers
9+
10+
**API Endpoints:**
11+
12+
* Main API: https://api.planhat.com/
13+
* Analytics API: https://analytics.planhat.com/
14+
15+
**Authentication:**
16+
17+
* Primary authentication via API token
18+
* Secondary authentication via tenant token for analytics endpoints
19+
* Configurable rate limiting (default: 200 calls per minute)
20+
21+
**Core Features Supported:**
22+
23+
**Data Models (20+ entities):**
24+
25+
* **Asset** - Track nested objects like product instances, devices, or custom entities
26+
* **Campaign** - Manage customer campaigns and adoption initiatives
27+
* **Churn** - Log customer churn events and reasons
28+
* **Company** - Core customer accounts with hierarchical structure support
29+
* **Conversation** - Email, chat, support tickets, and custom communication types
30+
* **Custom_Field** - Extend any object with custom properties
31+
* **Enduser** - Individual contacts at customer companies with domain auto-assignment
32+
* **Invoice** - Track billing and invoicing history
33+
* **Issue** - Bug reports and feature requests (Jira integration support)
34+
* **License** - Subscription management with MRR/ARR calculations
35+
* **Metrics** - Dimension data for customer success metrics
36+
* **NPS** - Net Promoter Score survey responses and scoring
37+
* **Note** - Manual notes and conversation logging
38+
* **Objective** - Customer success goals and health tracking
39+
* **Opportunity** - Sales opportunities and expansion tracking
40+
* **Project** - Time-bound initiatives with custom fields
41+
* **Sale** - Non-recurring revenue tracking
42+
* **Task** - Task management with calendar integration
43+
* **Ticket** - Support ticket management with external system sync
44+
* **Time_Entry** - Time logs; includes ``duplicate()`` for bulk duplicate by id
45+
* **Timesheet** - Collections of time entries per user
46+
* **User** - Team member management and access control
47+
* **Workspace** - Sub-instance tracking for multi-department engagement
48+
49+
**Standard CRUD Operations:**
50+
51+
All models support the following operations:
52+
53+
* ``create()`` - Create new records
54+
* ``update()`` - Update existing records by ID, External ID, or Source ID
55+
* ``get_by_id()`` - Retrieve records by ID, External ID, or Source ID
56+
* ``get_list()`` - Retrieve paginated lists with filtering and sorting
57+
* ``delete()`` - Remove records
58+
* ``bulk_upsert()`` - Batch create/update operations (up to 5,000 items per request)
59+
60+
**Specialized Methods:**
61+
62+
**Company Model:**
63+
64+
* ``get_lean_list()`` - Lightweight company list for ID matching
65+
66+
**Metrics Model:**
67+
68+
* ``epoc_days_format()`` - Convert dates to epoch days format
69+
* ``get_dimension_data()`` - Retrieve time-series metrics data
70+
* ``bulk_insert_metrics()`` - Batch insert metrics with auto-chunking
71+
72+
**User Activity Model:**
73+
74+
* ``create_activity()`` - Track user engagement events
75+
* ``segment()`` - User segmentation and analytics
76+
77+
**Advanced Features:**
78+
79+
**Bulk Operations:**
80+
81+
* Auto-chunking for large datasets
82+
* Configurable chunk sizes
83+
* Response aggregation and error handling
84+
* Rate limiting with automatic delays
85+
86+
**Data Formatting:**
87+
88+
* Epoch days date format support
89+
* External ID and Source ID reference support
90+
* Custom field extensibility
91+
92+
**Integration Capabilities:**
93+
94+
* CRM system synchronization (Salesforce, etc.)
95+
* Ticketing system integration (Zendesk, etc.)
96+
* Product management tool integration (Jira, Product Board, Aha!)
97+
* NPS tool imports
98+
* Calendar system integration (Google Calendar)
99+
* Webhook support for real-time data sync
100+
101+
**Error Handling:**
102+
103+
* Custom exception classes for bulk operations
104+
* Comprehensive error reporting
105+
* Automatic retry mechanisms
106+
107+
Example Usage:
108+
109+
.. code-block:: python
110+
111+
>>> from cruds.interfaces.planhat import Planhat
112+
>>>
113+
>>> # Initialize with API token and optional tenant token
114+
>>> planhat = Planhat(
115+
... api_token="hJA4eO3tJPhDck1aKLvQ5osvNUfKYdJ7H",
116+
... tenant_token="1d5df0f5-f217-49da-8997-2878f5986a9f"
117+
... )
118+
>>>
119+
>>> # Get comprehensive help
120+
>>> help(planhat)
121+
>>>
122+
>>> # Retrieve a company by external ID
123+
>>> company = planhat.company.get_by_id("extid-21432948")
124+
>>>
125+
>>> # Bulk upsert licenses
126+
>>> licenses_data = [
127+
... {"name": "Premium Plan", "companyId": "extid-123", "value": 1000},
128+
... {"name": "Basic Plan", "companyId": "extid-456", "value": 500}
129+
... ]
130+
>>> result = planhat.license.bulk_upsert(licenses_data)
131+
>>>
132+
>>> # Track user activity
133+
>>> activity_data = {
134+
... "event": "login",
135+
... "userId": "user123",
136+
... "companyId": "extid-123",
137+
... "timestamp": "2024-01-15T10:30:00Z"
138+
... }
139+
>>> planhat.user_activity.create_activity(activity_data)
140+
>>>
141+
>>> # Insert metrics data
142+
>>> metrics_data = {
143+
... "dimensionId": "daily_logins",
144+
... "companyId": "extid-123",
145+
... "value": 150,
146+
... "time": "2024-01-15T00:00:00Z"
147+
... }
148+
>>> planhat.metrics.bulk_insert_metrics([metrics_data])
149+
150+
The configuration file for this Interface can be found on
151+
`Github <https://github.com/johnbrandborg/cruds/blob/main/src/cruds/interfaces/planhat/configuration.yaml>`_.

‎src/cruds/__init__.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,6 @@
2828
from .core import Client
2929

3030
__author__: str = "John Brandborg"
31-
__version__: str = "1.6.0"
31+
__version__: str = "1.7.0"
3232

3333
__all__: list = ["Client", "auth"]

‎src/cruds/interfaces/planhat/configuration.yaml‎

Lines changed: 23 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ api:
1313
the tenant token (like 'segment') or no auth token but the tenant token is
1414
supplied directly to the method.
1515
16-
API Documentation: https://docs.planhat.com/#introduction
16+
API Documentation: https://www.planhat.com/developers
1717
1818
methods:
1919
- __init__
@@ -90,7 +90,7 @@ api:
9090
uri: companies
9191

9292
- name: Conversation
93-
doctring: |
93+
docstring: |
9494
Conversations can be of different types such as email, chat, support tickets and
9595
manually logged notes. You can also create your own types in Planhat to represent
9696
things such as "in person meeting", "Training" etc. The default types (email, chat,
@@ -227,7 +227,7 @@ api:
227227
track objectives and the health per objective.
228228
229229
Pro-tip: use your average Objective health in the Health Score!
230-
uri: onjectives
230+
uri: objectives
231231

232232
- name: user_activity
233233
docstring: |
@@ -296,6 +296,26 @@ api:
296296
- delete
297297
uri: tickets
298298

299+
- name: Time_Entry
300+
docstring: |
301+
A single time log for tracking time. API path: timeentries. Duplicate
302+
existing entries via duplicate() with payload {"ids": ["...", ...]}.
303+
methods:
304+
- create
305+
- update
306+
- get_by_id
307+
- get_list
308+
- delete
309+
- bulk_upsert
310+
- duplicate
311+
uri: timeentries
312+
313+
- name: Timesheet
314+
docstring: |
315+
A collection of time entries for a user, used for tracking time.
316+
API path: timesheets.
317+
uri: timesheets
318+
299319
- name: User
300320
docstring: |
301321
Users are all your team members that need access to Planhat. Users can be created in

0 commit comments

Comments
 (0)