@adobe/spacecat-shared-data-access 3.23.0 → 3.25.0

package/src/models/site-ims-org-access/site-ims-org-access.collection.js

@@ -0,0 +1,190 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import BaseCollection from '../base/base.collection.js';
+import DataAccessError from '../../errors/data-access.error.js';
+import { DEFAULT_PAGE_SIZE } from '../../util/postgrest.utils.js';
+
+/**
+ * SiteImsOrgAccessCollection - Collection of cross-org delegation grants.
+ * Provides idempotent create and the 50-delegate-per-site limit.
+ *
+ * @class SiteImsOrgAccessCollection
+ * @extends BaseCollection
+ */
+class SiteImsOrgAccessCollection extends BaseCollection {
+  static COLLECTION_NAME = 'SiteImsOrgAccessCollection';
+
+  static MAX_DELEGATES_PER_SITE = 50;
+
+  /**
+   * Idempotent create: if a grant already exists for (siteId, organizationId, productCode),
+   * return the existing record. Otherwise, enforce the 50-delegate-per-site limit and create.
+   * Follows the SiteEnrollment pattern (site-enrollment.collection.js:25-32).
+   *
+   * Note: the findByIndexKeys + allBySiteId + super.create sequence is not atomic. Concurrent
+   * requests can both pass the idempotency check (creating duplicates) or both pass the limit
+   * check (exceeding it). A DB-level unique constraint on (siteId, organizationId, productCode)
+   * is the authoritative guard against duplicates.
+   */
+  async create(item, options = {}) {
+    if (item?.organizationId && item?.targetOrganizationId
+      && item.organizationId === item.targetOrganizationId) {
+      const message = 'Cannot create self-delegation: organizationId and targetOrganizationId must differ';
+      this.log.warn(`[SiteImsOrgAccess] Self-delegation rejected: org=${item.organizationId}`);
+      const err = new DataAccessError(message);
+      err.status = 409;
+      throw err;
+    }
+
+    if (item?.siteId && item?.organizationId && item?.productCode) {
+      const existing = await this.findByIndexKeys({
+        siteId: item.siteId,
+        organizationId: item.organizationId,
+        productCode: item.productCode,
+      });
+      if (existing) {
+        this.log.info(`[SiteImsOrgAccess] Idempotent create: returning existing grant for site=${item.siteId} org=${item.organizationId} product=${item.productCode}`);
+        return existing;
+      }
+    }
+
+    // Enforce 50-active-delegate-per-site limit; expired grants do not count.
+    if (item?.siteId) {
+      const allGrants = await this.allBySiteId(item.siteId);
+      const activeGrants = allGrants.filter(
+        (g) => !g.getExpiresAt() || new Date(g.getExpiresAt()) > new Date(),
+      );
+      if (activeGrants.length >= SiteImsOrgAccessCollection.MAX_DELEGATES_PER_SITE) {
+        const message = `Cannot add delegate: site already has ${activeGrants.length}/${SiteImsOrgAccessCollection.MAX_DELEGATES_PER_SITE} active delegates`;
+        this.log.warn(`[SiteImsOrgAccess] Delegate limit reached for site=${item.siteId}`);
+        const err = new DataAccessError(message);
+        err.status = 409;
+        throw err;
+      }
+    }
+
+    const created = await super.create(item, options);
+    this.log.info(`[SiteImsOrgAccess] New grant created: id=${created.getId()} site=${item.siteId} org=${item.organizationId} product=${item.productCode}`);
+    return created;
+  }
+
+  /**
+   * @param {object} query - PostgREST query builder (result of .from(...).select(...))
+   * @returns {Promise<Array<{grant: object, targetOrganization: object}>>}
+   * @private
+   */
+  async #fetchGrantsWithTargetOrg(query) {
+    const allResults = [];
+    let offset = 0;
+    let keepGoing = true;
+    const orderedQuery = query.order('id');
+
+    while (keepGoing) {
+      // eslint-disable-next-line no-await-in-loop
+      const { data, error } = await orderedQuery.range(offset, offset + DEFAULT_PAGE_SIZE - 1);
+
+      if (error) {
+        this.log.error(`[SiteImsOrgAccess] Failed to query grants with target org - ${error.message}`, error);
+        throw new DataAccessError(
+          'Failed to query grants with target organization',
+          { entityName: 'SiteImsOrgAccess', tableName: 'site_ims_org_accesses' },
+          error,
+        );
+      }
+
+      if (!data || data.length === 0) {
+        keepGoing = false;
+      } else {
+        allResults.push(...data);
+        keepGoing = data.length >= DEFAULT_PAGE_SIZE;
+        offset += DEFAULT_PAGE_SIZE;
+      }
+    }
+
+    return allResults.map((row) => ({
+      grant: {
+        id: row.id,
+        siteId: row.site_id,
+        organizationId: row.organization_id,
+        targetOrganizationId: row.target_organization_id,
+        productCode: row.product_code,
+        role: row.role,
+        grantedBy: row.granted_by,
+        expiresAt: row.expires_at,
+      },
+      targetOrganization: {
+        id: row.organizations.id,
+        imsOrgId: row.organizations.ims_org_id,
+      },
+    }));
+  }
+
+  /**
+   * Returns all grants for the given delegate organization with the target organization's
+   * id and imsOrgId embedded via PostgREST resource embedding (INNER JOIN). This avoids
+   * a separate batch query to resolve target org IMS identifiers.
+   *
+   * Returns plain objects, not model instances. Access properties directly
+   * (e.g., `entry.grant.productCode`, `entry.targetOrganization.imsOrgId`).
+   *
+   * @param {string} organizationId - UUID of the delegate organization.
+   * @returns {Promise<Array<{
+   *   grant: {id: string, siteId: string, organizationId: string,
+   *     targetOrganizationId: string, productCode: string, role: string,
+   *     grantedBy: string|null, expiresAt: string|null},
+   *   targetOrganization: {id: string, imsOrgId: string}
+   * }>>}
+   */
+  async allByOrganizationIdWithTargetOrganization(organizationId) {
+    if (!organizationId) {
+      throw new DataAccessError('organizationId is required', { entityName: 'SiteImsOrgAccess', tableName: 'site_ims_org_accesses' });
+    }
+    // eslint-disable-next-line max-len
+    const select = 'id, site_id, organization_id, target_organization_id, product_code, role, granted_by, expires_at, organizations!site_ims_org_accesses_target_organization_id_fkey(id, ims_org_id)';
+    return this.#fetchGrantsWithTargetOrg(
+      this.postgrestService.from('site_ims_org_accesses').select(select).eq('organization_id', organizationId),
+    );
+  }
+
+  /**
+   * Bulk variant of allByOrganizationIdWithTargetOrganization. Fetches grants for multiple
+   * delegate organizations in a single PostgREST IN query with target org embedding.
+   * Returns an empty array when organizationIds is empty.
+   *
+   * @param {string[]} organizationIds - UUIDs of the delegate organizations.
+   * @returns {Promise<Array<{
+   *   grant: {id: string, siteId: string, organizationId: string,
+   *     targetOrganizationId: string, productCode: string, role: string,
+   *     grantedBy: string|null, expiresAt: string|null},
+   *   targetOrganization: {id: string, imsOrgId: string}
+   * }>>}
+   */
+  async allByOrganizationIdsWithTargetOrganization(organizationIds) {
+    if (!organizationIds || organizationIds.length === 0) {
+      return [];
+    }
+    if (organizationIds.length > SiteImsOrgAccessCollection.MAX_DELEGATES_PER_SITE) {
+      throw new DataAccessError(
+        `allByOrganizationIdsWithTargetOrganization: organizationIds array exceeds maximum of ${SiteImsOrgAccessCollection.MAX_DELEGATES_PER_SITE}`,
+        { entityName: 'SiteImsOrgAccess', tableName: 'site_ims_org_accesses' },
+      );
+    }
+    // eslint-disable-next-line max-len
+    const select = 'id, site_id, organization_id, target_organization_id, product_code, role, granted_by, expires_at, organizations!site_ims_org_accesses_target_organization_id_fkey(id, ims_org_id)';
+    return this.#fetchGrantsWithTargetOrg(
+      this.postgrestService.from('site_ims_org_accesses').select(select).in('organization_id', organizationIds),
+    );
+  }
+}
+
+export default SiteImsOrgAccessCollection;

package/src/models/site-ims-org-access/site-ims-org-access.model.js

@@ -0,0 +1,32 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import BaseModel from '../base/base.model.js';
+
+/**
+ * SiteImsOrgAccess - Maps delegate orgs to sites they can access, per product.
+ * Part of the cross-org delegation feature (Option 2a Phase 1).
+ *
+ * @class SiteImsOrgAccess
+ * @extends BaseModel
+ */
+class SiteImsOrgAccess extends BaseModel {
+  static ENTITY_NAME = 'SiteImsOrgAccess';
+
+  static DELEGATION_ROLES = {
+    COLLABORATOR: 'collaborator',
+    AGENCY: 'agency',
+    VIEWER: 'viewer',
+  };
+}
+
+export default SiteImsOrgAccess;

package/src/models/site-ims-org-access/site-ims-org-access.schema.js

@@ -0,0 +1,63 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { isIsoDate, isValidUUID } from '@adobe/spacecat-shared-utils';
+import { Entitlement } from '../entitlement/index.js';
+import SchemaBuilder from '../base/schema.builder.js';
+import SiteImsOrgAccess from './site-ims-org-access.model.js';
+import SiteImsOrgAccessCollection from './site-ims-org-access.collection.js';
+
+const GRANTED_BY_PATTERN = /^(ims:\S+|slack:\S+|system)$/;
+
+const schema = new SchemaBuilder(SiteImsOrgAccess, SiteImsOrgAccessCollection)
+  .addReference('belongs_to', 'Site')
+  .addReference('belongs_to', 'Organization') // the agency/delegate org receiving access
+  // targetOrganizationId is addAttribute (not belongs_to) because SchemaBuilder's
+  // belongs_to uses the referenced model name as the FK column prefix (organization_id).
+  // We already have belongs_to Organization for the delegate org, so a second belongs_to
+  // would conflict. addAttribute with UUID validation achieves the same FK semantics
+  // without the naming collision. readOnly: true prevents the setter from being generated
+  // since the target org is part of the grant's identity — a different target means a
+  // different grant.
+  .addAttribute('targetOrganizationId', {
+    type: 'string',
+    required: true,
+    readOnly: true,
+    validate: (v) => isValidUUID(v),
+  })
+  // organizationId (delegate org, from belongs_to) and siteId are also part of the grant's
+  // identity and are readOnly by virtue of their belongs_to FK nature.
+  .addAttribute('productCode', {
+    type: Object.values(Entitlement.PRODUCT_CODES),
+    required: true,
+    readOnly: true,
+  })
+  .addAttribute('role', {
+    type: Object.values(SiteImsOrgAccess.DELEGATION_ROLES),
+    required: true,
+    default: SiteImsOrgAccess.DELEGATION_ROLES.AGENCY,
+  })
+  .addAttribute('grantedBy', {
+    type: 'string',
+    required: false,
+    validate: (v) => !v || GRANTED_BY_PATTERN.test(v),
+  })
+  .addAttribute('expiresAt', {
+    type: 'string',
+    required: false,
+    validate: (v) => !v || isIsoDate(v),
+  })
+  .addAllIndex(['organizationId'])
+  // Index for "show all delegations granted to org Z across all sites" admin query
+  .addAllIndex(['targetOrganizationId']);
+
+export default schema.build();

package/src/models/suggestion-grant/index.d.ts

@@ -0,0 +1,30 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import type { BaseCollection, BaseModel } from '../index';
+
+export interface SuggestionGrant extends BaseModel {
+  getGrantId(): string;
+  getSuggestionId(): string;
+  getSiteId(): string;
+  getTokenId(): string;
+  getTokenType(): string;
+  getGrantedAt(): string;
+}
+
+export interface SuggestionGrantCollection extends BaseCollection<SuggestionGrant> {
+  findBySuggestionIds(suggestionIds: string[]): Promise<{ data: Array<{ suggestion_id: string; grant_id: string }>; error: object | null }>;
+  invokeGrantSuggestionsRpc(suggestionIds: string[], siteId: string, tokenType: string, cycle: string): Promise<{ data: Array | null; error: object | null }>;
+  splitSuggestionsByGrantStatus(suggestionIds: string[]): Promise<{ grantedIds: string[]; notGrantedIds: string[]; grantIds: string[] }>;
+  isSuggestionGranted(suggestionId: string): Promise<boolean>;
+  grantSuggestions(suggestionIds: string[], siteId: string, tokenType: string): Promise<{ success: boolean; reason?: string; grantedSuggestions?: Array }>;
+}

package/src/models/suggestion-grant/index.js

@@ -0,0 +1,19 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import SuggestionGrant from './suggestion-grant.model.js';
+import SuggestionGrantCollection from './suggestion-grant.collection.js';
+
+export {
+  SuggestionGrant,
+  SuggestionGrantCollection,
+};

package/src/models/suggestion-grant/suggestion-grant.collection.js

@@ -0,0 +1,177 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { hasText } from '@adobe/spacecat-shared-utils';
+
+import BaseCollection from '../base/base.collection.js';
+import DataAccessError from '../../errors/data-access.error.js';
+
+/**
+ * SuggestionGrantCollection - Manages SuggestionGrant records (suggestion_grants table).
+ * Table is insert-only; inserts happen via grant_suggestions RPC. This collection
+ * provides read-only lookup by suggestion IDs.
+ *
+ * @class SuggestionGrantCollection
+ * @extends BaseCollection
+ */
+class SuggestionGrantCollection extends BaseCollection {
+  static COLLECTION_NAME = 'SuggestionGrantCollection';
+
+  /**
+   * Finds all grant rows for the given suggestion IDs (suggestion_id, grant_id only).
+   *
+   * @async
+   * @param {string[]} suggestionIds - Suggestion IDs to look up.
+   * @returns {Promise<Array<{suggestion_id: string, grant_id: string}>>}
+   * @throws {DataAccessError} - On query failure.
+   */
+  async findBySuggestionIds(suggestionIds) {
+    if (!Array.isArray(suggestionIds) || suggestionIds.length === 0) {
+      return [];
+    }
+    const { data, error } = await this.postgrestService
+      .from(this.tableName)
+      .select('suggestion_id,grant_id')
+      .in('suggestion_id', suggestionIds);
+
+    if (error) {
+      throw new DataAccessError('Failed to find grants by suggestion IDs', this, error);
+    }
+
+    return data ?? [];
+  }
+
+  /**
+   * Invokes the grant_suggestions RPC. Inserts suggestion_grants rows and consumes one token.
+   * RPC name and parameter shape live in this collection (suggestion_grants).
+   *
+   * @async
+   * @param {string[]} suggestionIds - Suggestion IDs to grant.
+   * @param {string} siteId - Site ID.
+   * @param {string} tokenType - Token type.
+   * @param {string} cycle - Token cycle (e.g. '2025-01').
+   * @returns {Promise<{ data: Array|null, error: object|null }>}
+   */
+  async invokeGrantSuggestionsRpc(suggestionIds, siteId, tokenType, cycle) {
+    return this.postgrestService.rpc('grant_suggestions', {
+      p_suggestion_ids: suggestionIds,
+      p_site_id: siteId,
+      p_token_type: tokenType,
+      p_cycle: cycle,
+    });
+  }
+
+  /**
+   * Splits suggestion IDs into those that are granted and those that are not.
+   * A suggestion is considered granted if it has at least one row in suggestion_grants.
+   *
+   * @async
+   * @param {string[]} suggestionIds - Suggestion IDs to check.
+   * @returns {Promise<{ grantedIds: string[], notGrantedIds: string[], grantIds: string[] }>}
+   * @throws {DataAccessError} - On invalid input or query failure.
+   */
+  async splitSuggestionsByGrantStatus(suggestionIds) {
+    if (!Array.isArray(suggestionIds)) {
+      throw new DataAccessError('splitSuggestionsByGrantStatus: suggestionIds must be an array', this);
+    }
+
+    const deduped = [...new Set(suggestionIds.filter((id) => hasText(id)))];
+
+    if (deduped.length === 0) {
+      return { grantedIds: [], notGrantedIds: [], grantIds: [] };
+    }
+
+    try {
+      const rows = await this.findBySuggestionIds(deduped);
+      const grantedIdSet = new Set(rows.map((r) => r.suggestion_id));
+      const grantedIds = deduped.filter((id) => grantedIdSet.has(id));
+      const notGrantedIds = deduped.filter((id) => !grantedIdSet.has(id));
+      const grantIds = [...new Set(rows.map((r) => r.grant_id).filter(Boolean))];
+
+      return { grantedIds, notGrantedIds, grantIds };
+    } catch (err) {
+      if (err instanceof DataAccessError) throw err;
+      this.log.error('splitSuggestionsByGrantStatus failed', err);
+      throw new DataAccessError('Failed to split suggestions by grant status', this, err);
+    }
+  }
+
+  /**
+   * Returns whether a single suggestion is granted (has at least one row in suggestion_grants).
+   *
+   * @async
+   * @param {string} suggestionId - Suggestion ID to check.
+   * @returns {Promise<boolean>} True if the suggestion is granted,
+   *   false otherwise or if id is empty.
+   */
+  async isSuggestionGranted(suggestionId) {
+    if (!hasText(suggestionId)) return false;
+    const { grantedIds } = await this.splitSuggestionsByGrantStatus([suggestionId]);
+    return grantedIds.length > 0;
+  }
+
+  /**
+   * Grants one or more suggestions by consuming a single token for the given token type.
+   * Resolves the current cycle token via TokenCollection#findBySiteIdAndTokenType
+   * (which auto-creates if missing), checks that at least one token remains, then calls the
+   * grant_suggestions RPC to atomically consume one token and insert suggestion grants for
+   * the entire list of IDs.
+   *
+   * @async
+   * @param {string[]} suggestionIds - Suggestion IDs to grant (one token consumed for the list).
+   * @param {string} siteId - The site ID that owns the token allocation.
+   * @param {string} tokenType - Token type (e.g. 'grant_cwv').
+   * @returns {Promise<{ success: boolean, reason?: string, grantedSuggestions?: Array }>}
+   * @throws {DataAccessError} - On missing inputs or RPC failure.
+   */
+  async grantSuggestions(suggestionIds, siteId, tokenType) {
+    if (!Array.isArray(suggestionIds) || suggestionIds.some((id) => !hasText(id))) {
+      throw new DataAccessError('grantSuggestions: suggestionIds must be an array of non-empty strings', this);
+    }
+    if (!hasText(siteId)) {
+      throw new DataAccessError('grantSuggestions: siteId is required', this);
+    }
+    if (!hasText(tokenType)) {
+      throw new DataAccessError('grantSuggestions: tokenType is required', this);
+    }
+
+    const tokenCollection = this.entityRegistry.getCollection('TokenCollection');
+    const token = await tokenCollection.findBySiteIdAndTokenType(siteId, tokenType);
+
+    if (!token || token.getRemaining() < 1) {
+      return { success: false, reason: 'no_tokens' };
+    }
+
+    const cycle = token.getCycle();
+    const rpcResult = await this.invokeGrantSuggestionsRpc(
+      suggestionIds,
+      siteId,
+      tokenType,
+      cycle,
+    );
+    const { data, error } = rpcResult;
+
+    if (error) {
+      this.log.error('grantSuggestions: RPC failed', error);
+      throw new DataAccessError('Failed to grant suggestions (grant_suggestions)', this, error);
+    }
+
+    const row = Array.isArray(data) && data.length > 0 ? data[0] : null;
+    if (!row || !row.success) {
+      return { success: false, reason: row?.reason || 'rpc_no_result' };
+    }
+
+    return { success: true, grantedSuggestions: row.granted_suggestions };
+  }
+}
+
+export default SuggestionGrantCollection;

package/src/models/suggestion-grant/suggestion-grant.model.js

@@ -0,0 +1,26 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import BaseModel from '../base/base.model.js';
+
+/**
+ * SuggestionGrant - Record that a suggestion was granted (has a row in suggestion_grants).
+ * Table is insert-only; rows are created via grant_suggestions RPC.
+ *
+ * @class SuggestionGrant
+ * @extends BaseModel
+ */
+class SuggestionGrant extends BaseModel {
+  static ENTITY_NAME = 'SuggestionGrant';
+}
+
+export default SuggestionGrant;

package/src/models/suggestion-grant/suggestion-grant.schema.js

@@ -0,0 +1,74 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { isValidUUID } from '@adobe/spacecat-shared-utils';
+
+import SchemaBuilder from '../base/schema.builder.js';
+import SuggestionGrant from './suggestion-grant.model.js';
+import SuggestionGrantCollection from './suggestion-grant.collection.js';
+
+/*
+ * SuggestionGrant: suggestion_grants table (insert-only via grant_suggestions RPC).
+ * Columns: id, grant_id, suggestion_id, site_id, token_id, token_type, created_at, granted_at.
+ * Table has no updated_at/updated_by; those defaults are ignored for PostgREST.
+ */
+
+const schema = new SchemaBuilder(SuggestionGrant, SuggestionGrantCollection)
+  .addAttribute('updatedAt', {
+    type: 'string', required: true, readOnly: true, postgrestIgnore: true,
+  })
+  .addAttribute('updatedBy', {
+    type: 'string', required: false, postgrestIgnore: true,
+  })
+  .addIndex({ composite: ['suggestionId'] }, { composite: [] })
+  .addAttribute('suggestionId', {
+    type: 'string',
+    required: true,
+    readOnly: true,
+    validate: (value) => isValidUUID(value),
+    postgrestField: 'suggestion_id',
+  })
+  .addAttribute('grantId', {
+    type: 'string',
+    required: true,
+    readOnly: true,
+    validate: (value) => isValidUUID(value),
+    postgrestField: 'grant_id',
+  })
+  .addAttribute('siteId', {
+    type: 'string',
+    required: true,
+    readOnly: true,
+    validate: (value) => isValidUUID(value),
+    postgrestField: 'site_id',
+  })
+  .addAttribute('tokenId', {
+    type: 'string',
+    required: true,
+    readOnly: true,
+    validate: (value) => isValidUUID(value),
+    postgrestField: 'token_id',
+  })
+  .addAttribute('tokenType', {
+    type: 'string',
+    required: true,
+    readOnly: true,
+    postgrestField: 'token_type',
+  })
+  .addAttribute('grantedAt', {
+    type: 'string',
+    required: true,
+    readOnly: true,
+    postgrestField: 'granted_at',
+  });
+
+export default schema.build();

package/src/models/token/index.js

@@ -0,0 +1,19 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import Token from './token.model.js';
+import TokenCollection from './token.collection.js';
+
+export {
+  Token,
+  TokenCollection,
+};