v1.1.0

.eslintrc.json

@@ -4,6 +4,7 @@
     "node": true
   },
   "extends": [
+    "airbnb-base",
     "airbnb-typescript/base",
     "plugin:@typescript-eslint/recommended",
     "plugin:prettier/recommended"
@@ -20,6 +21,24 @@
   },
   "rules": {
     "import/prefer-default-export": "off",
-    "@typescript-eslint/no-explicit-any": "off"
+    "@typescript-eslint/no-explicit-any": "off",
+    "import/extensions": [
+      "error",
+      "ignorePackages",
+      {
+        "js": "never",
+        "jsx": "never",
+        "ts": "never",
+        "tsx": "never"
+      }
+    ],
+    "import/no-extraneous-dependencies": [
+      "error",
+      {
+        "devDependencies": ["**/*.test.ts"],
+        "optionalDependencies": false,
+        "peerDependencies": false
+      }
+    ]
   }
 }

.github/workflows/release.yml

@@ -0,0 +1,45 @@
+name: auto-release
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: ["14"]
+
+    environment:
+      name: Production
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: use node.js ${{ matrix.node_version }}
+        uses: actions/setup-node@v2
+        with:
+          node-version: ${{ matrix.node_version }}
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: install dependencies
+        run: yarn --frozen-lockfile
+
+      - name: check types
+        run: yarn typecheck
+
+      - name: lint
+        run: yarn lint
+
+      - name: test
+        run: yarn test
+        env:
+          ICLOUD_USERNAME: ${{secrets.ICLOUD_USERNAME}}
+          ICLOUD_APP_SPECIFIC_PASSWORD: ${{secrets.ICLOUD_APP_SPECIFIC_PASSWORD}}
+
+      - name: publish package
+        run: yarn run publish
+        env:
+          NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}

.gitignore

@@ -83,6 +83,7 @@ typings/
 # Nuxt.js build / generate output
 .nuxt
 dist
+dist-esm
 
 # Gatsby files
 .cache/

CHANGELOG.md

@@ -0,0 +1,26 @@
+##### v1.1.0
+
+**breaking changes**
+
+- `DAVClient` is no longer a type returned by `createDAVClient`, instead it's a class that can be instantiated.
+- `timeRange` in `fetchCalendarObjects` is now validated against `ISO_8601` standard and invalid format will throw an error.
+- typescript target changed to `es2015`, if you are on `node >= 10` and `browsers that are not IE and have been updated since 2015`, you should be fine. support for `es5` output is not possible with added `esm` support.
+
+**features**
+
+- added a new way to create `DAVClient` by `new DAVClient(...params)`.
+- added support for `esm`.
+
+##### improvements
+
+- typescript checks are now with `strict` enabled, which means better types and less bugs.
+- added more exports, now all internal functions are exported.
+- multiple documentation improvements.
+
+##### v1.0.6
+
+Fixed a bug where timeRange filter sometimes might be in the wrong format.
+
+##### v1.0.3
+
+Fixed a bug where calendar objects with `http` in its id would cause operations on it to fail.

README.md

@@ -24,6 +24,7 @@ webdav request made easy
 
 - Easy to use, well documented JSON based WEBDAV API
 - Works in both `Browsers` and `Node.js`
+- Supports Both `commonjs` and `esm`
 - OAuth2 & Basic Auth helpers built-in
 - Native typescript, fully linted and well tested
 - Supports WEBDAV, CALDAV, CARDDAV
@@ -49,7 +50,7 @@ yarn add tsdav
 import { createDAVClient } from 'tsdav';
 
 (async () => {
-  const googleClient = await createDAVClient({
+  const client = await createDAVClient({
     serverUrl: 'https://apidata.googleusercontent.com/caldav/v2/',
     credentials: {
       refreshToken: 'YOUR_REFRESH_TOKEN_WITH_CALDAV_PERMISSION',
@@ -90,6 +91,59 @@ import { createDAVClient } from 'tsdav';
 })();
 ```
 
+After `v1.1.0`, you have a new way of creating clients.
+
+##### Google CALDAV
+
+```ts
+import { DAVClient } from 'tsdav';
+
+const client = new DAVClient({
+  serverUrl: 'https://apidata.googleusercontent.com/caldav/v2/',
+  credentials: {
+    refreshToken: 'YOUR_REFRESH_TOKEN_WITH_CALDAV_PERMISSION',
+  },
+  authMethod: 'Oauth',
+  defaultAccountType: 'caldav',
+});
+
+(async () => {
+  await googleClient.login();
+
+  const calendars = await client.fetchCalendars();
+
+  const calendarObjects = await client.fetchCalendarObjects({
+    calendar: calendars[0],
+  });
+})();
+```
+
+##### Apple CARDDAV
+
+```ts
+import { DAVClient } from 'tsdav';
+
+const client = new DAVClient({
+  serverUrl: 'https://contacts.icloud.com',
+  credentials: {
+    username: 'YOUR_APPLE_ID',
+    password: 'YOUR_APP_SPECIFIC_PASSWORD',
+  },
+  authMethod: 'Basic',
+  defaultAccountType: 'carddav',
+});
+
+(async () => {
+  await client.login();
+
+  const addressBooks = await client.fetchAddressBooks();
+
+  const vcards = await client.fetchVCards({
+    addressBook: addressBooks[0],
+  });
+})();
+```
+
 ### Documentation
 
 Check out the [Documentation](https://tsdav.vercel.app/)
@@ -100,12 +154,11 @@ Check out the [Documentation](https://tsdav.vercel.app/)
 
 [![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fllldar%2FtsDAV.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fllldar%2FtsDAV?ref=badge_large)
 
-### RELEASE NOTES
-
-##### v1.0.6
+### Changelog
 
-Fixed a bug where timeRange filter sometimes might be in the wrong format.
+refers to [Changelog](./CHANGELOG.md)
 
-##### v1.0.3
+### Debugging
 
-Fixed a bug where calendar objects with `http` in its id would cause operations on it to fail.
+this package uses `debug` package,
+add `tsdav:*` to `DEBUG` env variable to enable debug logs

docs/docs/caldav/calendarQuery.md

@@ -34,7 +34,7 @@ const results = await calendarQuery({
 - `props` **required**, array of [DAVProp](../types/DAVProp.md)
 - `filters` array of [DAVFilter](../types/DAVFilter.md)
 - `depth` [DAVDepth](../types/DAVDepth.md)
-- `timezone` iana timezone name
+- `timezone` iana timezone name, like `America/Los_Angeles`
 - `headers` request headers
 
 ### Return Value

docs/docs/caldav/fetchCalendarObjects.md

@@ -21,8 +21,8 @@ const objects = await fetchCalendarObjects({
 - `objectUrls` calendar object urls to fetch
 - `filters` array of [DAVFilter](../types/DAVFilter.md)
 - `timeRange` time range in iso format
-  - `start` start time in [ISO 8601 format](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) `YYYY-MM-DDTHH:mm:ss.sssZ`
-  - `end` end time in [ISO 8601 format](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) `YYYY-MM-DDTHH:mm:ss.sssZ`
+  - `start` start time in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601), format that's not in ISO 8601 will cause an error be thrown.
+  - `end` end time in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601), format that's not in ISO 8601 will cause an error be thrown.
 - `headers` request headers
 
 ### Return Value

docs/docs/caldav/syncCalendars.md

@@ -33,13 +33,15 @@ const { created, updated, deleted } = await syncCalendars({
 
 ### Arguments
 
-**required**
-
 - `oldCalendars` **required**, locally version of calendars of this account, should contain [calendar objects](../types/DAVCalendarObject.md) as well if `detailedResult` is `false`
 - `account` the account which calendars belong to,
 - `detailedResult` if falsy, the result would be latest version of the calendars of this account, otherwise they would be separated into three groups of `created`, `updated`, and `deleted`.
 - `headers` request headers
 
+:::info
+`objects` inside `oldCalendars` are not needed when `detailedResult` is `true`.
+:::
+
 ### Return Value
 
 depend on `detailedResult` option

docs/docs/helpers/authHelpers.md

@@ -1,4 +1,3 @@
-
 # AuthHelpers
 
 ### getBasicAuthHeaders
@@ -11,14 +10,15 @@ const result = getBasicAuthHeaders({
   password: '12345',
 });
 ```
+
 #### Return Value
+
 ```ts
 {
-  authorization: 'Basic dGVzdDoxMjM0NQ=='
+  authorization: 'Basic dGVzdDoxMjM0NQ==';
 }
 ```
 
-
 ### fetchOauthTokens
 
 fetch oauth token using code obtained from oauth2 authorization code grant
@@ -34,6 +34,7 @@ const tokens = await fetchOauthTokens({
 ```
 
 #### Return Value
+
 ```ts
 {
   access_token: 'kTKGQ2TBEqn03KJMM9AqIA';
@@ -42,7 +43,7 @@ const tokens = await fetchOauthTokens({
   id_token: 'TKfsafGQ2JMM9AqIA';
   token_type: 'bearer';
   scope: 'openid email';
-};
+}
 ```
 
 ### refreshAccessToken
@@ -55,10 +56,11 @@ const result = await refreshAccessToken({
   clientSecret: 'clientSecret',
   tokenUrl: 'https://oauth.example.com/tokens',
   refreshToken: 'iHwWwqytfW3AfOjNbM1HLg',
-})
+});
 ```
 
 #### Return Value
+
 ```ts
 {
   access_token: 'eeMCxYgdCF3xfLxgd1NE8A';
@@ -77,10 +79,11 @@ const result = await getOauthHeaders({
   clientSecret: 'clientSecret',
   tokenUrl: 'https://oauth.example.com/tokens',
   redirectUrl: 'https://yourdomain.com/oauth-callback',
-})
+});
 ```
 
 #### Return Value
+
 ```ts
 {
   tokens: {
@@ -95,4 +98,21 @@ const result = await getOauthHeaders({
     authorization: `Bearer q-2OCH2g3RctZOJOG9T2Q`,
   },
 }
-```
+```
+
+### defaultParam
+
+:::caution
+Internal function, not intended to be used outside.
+:::
+
+Provide default parameter for passed in function and allows default parameters be overridden when the function was actually passed with same parameters.
+would only work on functions that have only one object style parameter.
+
+```ts
+const fn1 = (params: { a?: number; b?: number }) => {
+  const { a = 0, b = 0 } = params;
+  return a + b;
+};
+const fn2 = defaultParam(fn1, { b: 10 });
+```