From 496b8777db7413724544bbd7ae546eeae9525c7f Mon Sep 17 00:00:00 2001
From: Nicolas Ayral Seydoux <nseydoux@inrupt.com>
Date: Tue, 17 Dec 2024 23:14:48 +0100
Subject: [PATCH] Add API docs

---
 src/gConsent/index.ts       |  1 +
 src/gConsent/query/query.ts | 39 +++++++++++++++++++++++++++++++++++++
 src/index.ts                |  1 +
 3 files changed, 41 insertions(+)

diff --git a/src/gConsent/index.ts b/src/gConsent/index.ts
index 13f92662..c02b5f3e 100644
--- a/src/gConsent/index.ts
+++ b/src/gConsent/index.ts
@@ -50,6 +50,7 @@ export {
   CredentialResult,
   CredentialStatus,
   CredentialType,
+  DURATION,
   query,
 } from "./query/query";
 
diff --git a/src/gConsent/query/query.ts b/src/gConsent/query/query.ts
index 226460ad..d33f5c83 100644
--- a/src/gConsent/query/query.ts
+++ b/src/gConsent/query/query.ts
@@ -40,6 +40,13 @@ export type CredentialType =
   | "SolidAccessGrant"
   | "SolidAccessDenial";
 
+export const DURATION = {
+  ONE_DAY: "P1D",
+  ONE_WEEK: "P7D",
+  ONE_MONTH: "P1M",
+  THREE_MONTHS: "P3M",
+} as const;
+
 export type CredentialFilter = {
   type?: CredentialType;
   status?: CredentialStatus;
@@ -147,6 +154,38 @@ function toQueryUrl(endpoint: URL, filter: CredentialFilter): URL {
   return result;
 }
 
+/**
+ * Query for Access Requests or Access Grants based on a given filter.
+ *
+ * @param filter the query filter
+ * @param options query options
+ * @returns a paginated set of Access Credential matching the given filter
+ * @since unreleased
+ *
+ * @example
+ * ```
+ *  // Get the first results page.
+ *  const activeGrantsToday = await query(
+ *       {
+ *         type: "SolidAccessGrant",
+ *         status: "Active",
+ *         issuedWithin: DURATION.ONE_DAY,
+ *       },
+ *       {
+ *         fetch: session.fetch,
+ *         queryEndpoint: config.queryEndpoint,
+ *       },
+ *     );
+ * // Get the next results page.
+ * const activeGrantsToday2 = await query(
+ *       activeGrantsToday.next,
+ *       {
+ *         fetch: session.fetch,
+ *         queryEndpoint: config.queryEndpoint,
+ *       },
+ *     );
+ * ```
+ */
 export async function query(
   filter: CredentialFilter,
   options: {
diff --git a/src/index.ts b/src/index.ts
index b3d25304..a1d0d1bc 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -51,6 +51,7 @@ export {
   CredentialStatus,
   CredentialType,
   denyAccessRequest,
+  DURATION,
   getAccessApiEndpoint,
   getAccessGrant,
   getAccessGrantAll,