Skip to content

Commit 59d7ff4

Browse files
burmeciaburmecia
authored
add cal.com fdw folder (#365)
1 parent e2bdb28 commit 59d7ff4

File tree

12 files changed

+1029
-1
lines changed

12 files changed

+1029
-1
lines changed

‎Cargo.toml

+1
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ members = [
55
"wrappers",
66
]
77
exclude = [
8+
"wasm-wrappers/fdw/cal_fdw",
89
"wasm-wrappers/fdw/calendly_fdw",
910
"wasm-wrappers/fdw/helloworld_fdw",
1011
"wasm-wrappers/fdw/snowflake_fdw",

‎README.md

+1
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@
2222
| [Snowflake](./wasm-wrappers/fdw/snowflake_fdw) | A Wasm FDW for [Snowflake](https://www.snowflake.com/) | ✅ | ✅ |
2323
| [Paddle](./wasm-wrappers/fdw/paddle_fdw) | A Wasm FDW for [Paddle](https://www.paddle.com/) | ✅ | ✅ |
2424
| [Calendly](./wasm-wrappers/fdw/calendly_fdw) | A Wasm FDW for [Calendly](https://www.calendly.com/) | ✅ | ❌ |
25+
| [Cal.com](./wasm-wrappers/fdw/cal_fdw) | A Wasm FDW for [Cal.com](https://www.cal.com/) | ✅ | ❌ |
2526

2627
### Warning
2728

‎docs/catalog/cal.md

+280
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,280 @@
1+
---
2+
source:
3+
documentation:
4+
author: supabase
5+
tags:
6+
- wasm
7+
- official
8+
---
9+
10+
# Cal.com
11+
12+
[Cal.com](https://cal.com/) is an open source scheduling platform.
13+
14+
The Cal Wrapper is a WebAssembly(Wasm) foreign data wrapper which allows you to read data from your Cal.com account for use within your Postgres database.
15+
16+
!!! warning
17+
18+
Restoring a logical backup of a database with a materialized view using a foreign table can fail. For this reason, either do not use foreign tables in materialized views or use them in databases with physical backups enabled.
19+
20+
## Supported Data Types
21+
22+
| Postgres Data Type | Cal.com Data Type |
23+
| ------------------ | ------------------ |
24+
| boolean | Boolean |
25+
| bigint | Number |
26+
| double precision | Number |
27+
| text | String |
28+
| jsonb | Json |
29+
30+
The Cal.com API uses JSON formatted data, please refer to [Cal.com API docs](https://cal.com/docs/api-reference/v2/introduction) for more details.
31+
32+
!!! note
33+
34+
This foreign data wrapper only supports Cal.com API v2.
35+
36+
## Available Versions
37+
38+
| Version | Wasm Package URL | Checksum |
39+
| ------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
40+
| 0.1.0 | `https://github.com/supabase/wrappers/releases/download/wasm_cal_fdw_v0.1.0/cal_fdw.wasm` | `tbd` |
41+
42+
## Preparation
43+
44+
Before you get started, make sure the `wrappers` extension is installed on your database:
45+
46+
```sql
47+
create extension if not exists wrappers with schema extensions;
48+
```
49+
50+
and then create the Wasm foreign data wrapper:
51+
52+
```sql
53+
create foreign data wrapper wasm_wrapper
54+
handler wasm_fdw_handler
55+
validator wasm_fdw_validator;
56+
```
57+
58+
### Secure your credentials (optional)
59+
60+
By default, Postgres stores FDW credentials inside `pg_catalog.pg_foreign_server` in plain text. Anyone with access to this table will be able to view these credentials. Wrappers is designed to work with [Vault](https://supabase.com/docs/guides/database/vault), which provides an additional level of security for storing credentials. We recommend using Vault to store your credentials.
61+
62+
```sql
63+
-- Save your Cal.com API key in Vault and retrieve the `key_id`
64+
insert into vault.secrets (name, secret)
65+
values (
66+
'cal',
67+
'<Cal.com API Key>' -- Cal.com API key
68+
)
69+
returning key_id;
70+
```
71+
72+
### Connecting to Cal.com
73+
74+
We need to provide Postgres with the credentials to access Cal.com and any additional options. We can do this using the `create server` command:
75+
76+
=== "With Vault"
77+
78+
```sql
79+
create server cal_server
80+
foreign data wrapper wasm_wrapper
81+
options (
82+
fdw_package_url 'https://github.com/supabase/wrappers/releases/download/wasm_cal_fdw_v0.1.0/cal_fdw.wasm',
83+
fdw_package_name 'supabase:cal-fdw',
84+
fdw_package_version '0.1.0',
85+
fdw_package_checksum 'tbd',
86+
api_url 'https://api.cal.com/v2', -- optional
87+
api_key_id '<key_ID>' -- The Key ID from above.
88+
);
89+
```
90+
91+
=== "Without Vault"
92+
93+
```sql
94+
create server cal_server
95+
foreign data wrapper wasm_wrapper
96+
options (
97+
fdw_package_url 'https://github.com/supabase/wrappers/releases/download/wasm_cal_fdw_v0.1.0/cal_fdw.wasm',
98+
fdw_package_name 'supabase:cal-fdw',
99+
fdw_package_version '0.1.0',
100+
fdw_package_checksum 'tbd',
101+
api_url 'https://api.cal.com/v2', -- optional
102+
api_key 'cal_live_1234...' -- Cal.com API key
103+
);
104+
```
105+
106+
Note the `fdw_package_*` options are required, which specify the Wasm package metadata. You can get the available package version list from [above](#available-versions).
107+
108+
### Create a schema
109+
110+
We recommend creating a schema to hold all the foreign tables:
111+
112+
```sql
113+
create schema if not exists cal;
114+
```
115+
116+
## Creating Foreign Tables
117+
118+
The Cal.com Wrapper supports data reads from below objects in Cal.com.
119+
120+
| Integration | Select | Insert | Update | Delete | Truncate |
121+
| -------------| :----: | :----: | :----: | :----: | :------: |
122+
| My Profile | ✅ | ❌ | ❌ | ❌ | ❌ |
123+
| Event Types | ✅ | ❌ | ❌ | ❌ | ❌ |
124+
| Bookings | ✅ | ❌ | ❌ | ❌ | ❌ |
125+
| Calendars | ✅ | ❌ | ❌ | ❌ | ❌ |
126+
| Schedules | ✅ | ❌ | ❌ | ❌ | ❌ |
127+
| Conferencing | ✅ | ❌ | ❌ | ❌ | ❌ |
128+
129+
For example:
130+
131+
```sql
132+
create foreign table cal.my_profile (
133+
id bigint,
134+
username text,
135+
email text,
136+
attrs jsonb
137+
)
138+
server cal_server
139+
options (
140+
object 'my_profile'
141+
);
142+
143+
create foreign table cal.event_types (
144+
attrs jsonb
145+
)
146+
server cal_server
147+
options (
148+
object 'event-types'
149+
);
150+
151+
create foreign table cal.bookings (
152+
attrs jsonb
153+
)
154+
server cal_server
155+
options (
156+
object 'bookings'
157+
);
158+
159+
create foreign table cal.calendars (
160+
attrs jsonb
161+
)
162+
server cal_server
163+
options (
164+
object 'calendars'
165+
);
166+
167+
create foreign table cal.schedules (
168+
id bigint,
169+
name text,
170+
attrs jsonb
171+
)
172+
server cal_server
173+
options (
174+
object 'schedules'
175+
);
176+
177+
create foreign table cal.conferencing (
178+
id bigint,
179+
attrs jsonb
180+
)
181+
server cal_server
182+
options (
183+
object 'conferencing'
184+
);
185+
```
186+
187+
!!! note
188+
189+
- All the supported columns are listed above, other columns are not allowd.
190+
- The `attrs` is a special column which stores all the object attributes in JSON format, you can extract any attributes needed from it. See more examples below.
191+
192+
### Foreign table options
193+
194+
The full list of foreign table options are below:
195+
196+
- `object` - Object name in Cal.com, required.
197+
198+
Supported objects are listed below:
199+
200+
| Object name |
201+
| ------------------------ |
202+
| my_profile |
203+
| event-types |
204+
| bookings |
205+
| calendars |
206+
| schedules |
207+
| conferencing |
208+
209+
## Query Pushdown Support
210+
211+
This FDW doesn't support query pushdown.
212+
213+
## Examples
214+
215+
Below are some examples on how to use Cal.com foreign tables.
216+
217+
### Basic example
218+
219+
This example will create a "foreign table" inside your Postgres database and query its data. First, we can create a schema to hold all the Cal.com foreign tables.
220+
221+
```sql
222+
create schema if not exists cal;
223+
```
224+
225+
Then create the foreign table and query it, for example:
226+
227+
```sql
228+
create foreign table cal.my_profile (
229+
id bigint,
230+
username text,
231+
email text,
232+
attrs jsonb
233+
)
234+
server cal_server
235+
options (
236+
object 'my_profile'
237+
);
238+
239+
-- query current user used for the Cal.com API request
240+
select * from cal.my_profile;
241+
```
242+
243+
`attrs` is a special column which stores all the object attributes in JSON format, you can extract any attributes needed from it. See more examples below.
244+
245+
### Query JSON attributes
246+
247+
```sql
248+
create foreign table cal.bookings (
249+
attrs jsonb
250+
)
251+
server cal_server
252+
options (
253+
object 'bookings'
254+
);
255+
256+
create foreign table cal.event_types (
257+
attrs jsonb
258+
)
259+
server cal_server
260+
options (
261+
object 'event-types'
262+
);
263+
264+
-- extract bookings
265+
select
266+
bk->>'id' as id,
267+
bk->>'title' as title,
268+
bk->>'userPrimaryEmail' as email
269+
from cal.bookings t
270+
cross join json_array_elements((attrs->'bookings')::json) bk;
271+
272+
-- extract event types
273+
select
274+
etg->'profile'->>'name' as profile,
275+
et->>'id' as id,
276+
et->>'title' as title
277+
from cal.event_types t
278+
cross join json_array_elements((attrs->'eventTypeGroups')::json) etg
279+
cross join json_array_elements((etg->'eventTypes')::json) et;
280+
```

‎docs/catalog/index.md

+3-1
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ hide:
1313
| Auth0 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
1414
| AWS Cognito | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
1515
| BigQuery | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ |
16+
| Cal.com | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
1617
| Calendly | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
1718
| ClickHouse | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ |
1819
| Firebase | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
@@ -33,7 +34,8 @@ See [Developing a Wasm Wrapper](../guides/create-wasm-wrapper.md) for instructio
3334

3435
| Integration | Developer | Docs | Source |
3536
| ----------- | :------------------------------: | :----------------------------------: | :------------------------------------------------------------------------------------: |
36-
| Calendly | [Supabase](https://supabase.com) | [Link](calendly.md) | [Link](https://github.com/supabase/wrappers/tree/main/wasm-wrappers/fdw/calendly_fdw) |
37+
| Cal.com | [Supabase](https://supabase.com) | [Link](cal.md) | [Link](https://github.com/supabase/wrappers/tree/main/wasm-wrappers/fdw/cal_fdw) |
38+
| Calendly | [Supabase](https://supabase.com) | [Link](calendly.md) | [Link](https://github.com/supabase/wrappers/tree/main/wasm-wrappers/fdw/calendly_fdw) |
3739
| Notion | [Supabase](https://supabase.com) | [Link](notion.md) | [Link](https://github.com/supabase/wrappers/tree/main/wasm-wrappers/fdw/notion_fdw) |
3840
| Paddle | [Supabase](https://supabase.com) | [Link](paddle.md) | [Link](https://github.com/supabase/wrappers/tree/main/wasm-wrappers/fdw/paddle_fdw) |
3941
| Snowflake | [Supabase](https://supabase.com) | [Link](snowflake.md) | [Link](https://github.com/supabase/wrappers/tree/main/wasm-wrappers/fdw/snowflake_fdw) |

‎docs/catalog/wasm/index.md

+12
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,18 @@ Foreign data wrappers built with Wasm which can be used on Supabase platform.
1313

1414
<div class="grid cards" markdown>
1515

16+
- :simple-webassembly: &nbsp; **[Cal.com](../cal.md)**
17+
18+
----
19+
20+
Foreign data wrapper for [Cal.com](https://cal.com/).
21+
22+
Supported by [Supabase](https://www.supabase.com)
23+
24+
:octicons-tag-24: [v0.1.0](https://github.com/supabase/wrappers/releases/tag/cal_fdw_v0.1.0) &nbsp;
25+
:octicons-code-24: [source](https://github.com/supabase/wrappers/tree/wasm_cal_fdw_v0.1.0/wasm-wrappers/fdw/calendly_fdw) &nbsp;
26+
:material-file-document: [docs](../cal.md)
27+
1628
- :simple-webassembly: &nbsp; **[Calendly](../calendly.md)**
1729

1830
----

‎mkdocs.yaml

+1
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ nav:
2828
- SQL Server: 'catalog/mssql.md'
2929
- Wasm:
3030
- catalog/wasm/index.md
31+
- Cal.com: 'catalog/cal.md'
3132
- Calendly: 'catalog/calendly.md'
3233
- Notion: 'catalog/notion.md'
3334
- Paddle: 'catalog/paddle.md'

0 commit comments

Comments
 (0)