JSDoc writer works with collections

lib/suma/anon_proxy/member_contact.rb

@@ -74,9 +74,9 @@ def after_destroy
 #  external_relay_id | text                     | NOT NULL DEFAULT ''::text
 # Indexes:
 #  anon_proxy_member_contacts_pkey                          | PRIMARY KEY btree (id)
-#  anon_proxy_member_contacts_email_relay_key_key           | UNIQUE btree (email, relay_key)
-#  anon_proxy_member_contacts_phone_relay_key_key           | UNIQUE btree (phone, relay_key)
+#  anon_proxy_member_contacts_email_index                   | btree (email)
 #  anon_proxy_member_contacts_member_id_index               | btree (member_id)
+#  anon_proxy_member_contacts_phone_index                   | btree (phone)
 #  anon_proxy_member_contacts_search_content_trigram_index  | gist (search_content)
 #  anon_proxy_member_contacts_search_content_tsvector_index | gin (to_tsvector('english'::regconfig, search_content))
 # Check constraints:

lib/suma/payment/funding_transaction/stripe_card_strategy.rb

@@ -133,7 +133,8 @@ def _external_link_deps
 #  originating_card_id | integer                  | NOT NULL
 #  charge_json         | jsonb                    |
 # Indexes:
-#  payment_funding_transaction_stripe_card_strategies_pkey | PRIMARY KEY btree (id)
+#  payment_funding_transaction_stripe_card_strategies_pkey         | PRIMARY KEY btree (id)
+#  payment_funding_transaction_stripe_card_strategies_originating_ | btree (originating_card_id)
 # Foreign key constraints:
 #  payment_funding_transaction_stripe_car_originating_card_id_fkey | (originating_card_id) REFERENCES payment_cards(id)
 # Referenced By:

lib/suma/service/collection.rb

@@ -17,14 +17,14 @@ class Suma::Service::Collection
   attr_accessor :url
 
   class BaseEntity < Suma::Service::Entities::Base
-    expose :object do |_|
+    expose :object, documentation: {type: String} do |_|
       "list"
     end
-    expose :current_page
-    expose :page_count
-    expose :total_count
-    expose :more?, as: :has_more
-    expose :url do |inst, opts|
+    expose :current_page, documentation: {type: Integer}
+    expose :page_count, documentation: {type: Integer}
+    expose :total_count, documentation: {type: Integer}
+    expose :more?, as: :has_more, documentation: {type: "Boolean"}
+    expose :url, documentation: {type: String} do |inst, opts|
       inst.url || Suma::Service.request_path(opts[:env])
     end
     # expose :items do |_|
@@ -59,7 +59,8 @@ def self.prepare_entity(item_entity)
       collection_entity = Suma::Service::Collection.collection_entity_cache[item_entity]
       if collection_entity.nil?
         collection_entity = Class.new(Suma::Service::Collection::BaseEntity) do
-          def self.name = "Suma::Service::Collection::Entity"
+          entity_name = item_entity.respond_to?(:name) ? item_entity.name : item_entity
+          define_singleton_method(:name) { "#{entity_name}Collection" }
           expose :items, using: item_entity
         end
         Suma::Service::Collection.collection_entity_cache[item_entity] = collection_entity

lib/suma/service/entity_jsdoc_writer.rb

@@ -52,7 +52,7 @@ def self.gather_entity_classes(glob: nil, prefix: nil)
     end
 
     # Documentation hint (e.g. documentation: { type: "String" })
-    (type = documentation[:type].to_s) if documentation.is_a?(Hash) && documentation[:type]
+    (type = getname(documentation[:type])) if documentation.is_a?(Hash) && documentation[:type]
 
     return "?" unless type
 
@@ -146,13 +146,15 @@ def self.gather_entity_classes(glob: nil, prefix: nil)
 
   # Derive a clean JSDoc identifier from an entity class name.
   protected def jsdoc_entity_name(klass)
-    name = klass.respond_to?(:name) ? klass.name : klass.to_s
+    name = getname(klass)
     # We don't want namespaces
     name = name.split("::").last
     # Strip trailing "Entity" suffix for brevity, e.g. UserEntity → User
     return name.sub(/_?Entity$/, "")
   end
 
+  protected def getname(x) = x.respond_to?(:name) ? x.name : x.to_s
+
   # Build JSDoc typedef for a single entity class
   protected def typedef_for(entity_class)
     lines = []

spec/suma/service/entity_jsdoc_writer_spec.rb

@@ -1,11 +1,12 @@
 # frozen_string_literal: true
 
 require "suma/service/entity_jsdoc_writer"
+require "suma/admin_api"
 
 RSpec.describe Suma::Service::EntityJsdocWriter do
   it "writes entities" do
     Class.new(Grape::Entity) do
-      def self.name = "TestEntity"
+      define_singleton_method(:name) { "TestEntity" }
       expose :x
       expose :y, using: self
       expose :doc, documentation: {type: "String", desc: "Help text"}
@@ -16,6 +17,58 @@ def self.name = "TestEntity"
     end
     cls = described_class.gather_entity_classes(prefix: "TestEntity")
     s = described_class.new.build(cls)
-    expect(s).to include("@typedef {Object} Test")
+    expect(s).to include(<<~STR)
+      /**
+       * @typedef {Object} Test
+       * @description Auto-generated from TestEntity
+       * @property {?} x
+       * @property {Test} y
+       * @property {string} doc - Help text
+       * @property {TestEntity} docT - Help text
+       * @property {?} n1
+       */
+    STR
+  end
+
+  it "writes admin model entities" do
+    activity_entity = Class.new(Suma::AdminAPI::Entities::BaseModelEntity) do
+      define_singleton_method(:name) { "AdminTestActivityEntity" }
+      model Suma::Member::Activity
+      expose :id
+    end
+
+    Class.new(Suma::AdminAPI::Entities::BaseModelEntity) do
+      define_singleton_method(:name) { "AdminTestMemberEntity" }
+      model Suma::Member
+      expose_related :activities, with: activity_entity
+    end
+
+    cls = described_class.gather_entity_classes(prefix: "AdminTest")
+    s = described_class.new.build(cls)
+    expect(s).to include(<<~STR)
+      /**
+       * @typedef {Object} AdminTestActivity
+       * @description Auto-generated from AdminTestActivityEntity
+       * @property {number} id
+       */
+
+      /**
+       * @typedef {Object} AdminTestActivityEntityCollection
+       * @description Auto-generated from AdminTestActivityEntityCollection
+       * @property {string} object
+       * @property {number} currentPage
+       * @property {number} pageCount
+       * @property {number} totalCount
+       * @property {boolean} hasMore
+       * @property {string} url
+       * @property {AdminTestActivity} items
+       */
+
+      /**
+       * @typedef {Object} AdminTestMember
+       * @description Auto-generated from AdminTestMemberEntity
+       * @property {AdminTestActivityEntityCollection} activities
+       */
+    STR
   end
 end

webapp/src/typedefs.js

@@ -1,5 +1,5 @@
 // Auto-generated JSDoc typedefs from Grape::Entity
-// Generated: 2026-04-26 10:37:07
+// Generated: 2026-06-02 15:30:02
 // Entities: Suma::API::AnonProxy::AnonProxyVendorAccountEntity, Suma::API::AnonProxy::AnonProxyVendorAccountPollResultEntity, Suma::API::AnonProxy::AnonProxyVendorAccountUIStateEntity, Suma::API::Auth::AuthFlowMemberEntity, Suma::API::Commerce::BaseOfferingProductEntity, Suma::API::Commerce::CartEntity, Suma::API::Commerce::CartItemEntity, Suma::API::Commerce::ChargeContributionEntity, Suma::API::Commerce::CheckoutConfirmationEntity, Suma::API::Commerce::CheckoutConfirmationItemEntity, Suma::API::Commerce::CheckoutConfirmationProductEntity, Suma::API::Commerce::CheckoutEntity, Suma::API::Commerce::CheckoutItemEntity, Suma::API::Commerce::CheckoutProductEntity, Suma::API::Commerce::DetailedOrderHistoryEntity, Suma::API::Commerce::FulfillmentOptionAddressEntity, Suma::API::Commerce::FulfillmentOptionEntity, Suma::API::Commerce::OfferingEntity, Suma::API::Commerce::OfferingWithContextEntity, Suma::API::Commerce::OrderHistoryCollection, Suma::API::Commerce::OrderHistoryFundingTransactionEntity, Suma::API::Commerce::OrderHistoryItemEntity, Suma::API::Commerce::PricedOfferingProductEntity, Suma::API::Commerce::SimpleOrderHistoryEntity, Suma::API::Commerce::UnclaimedOrderCollection, Suma::API::Commerce::VendorEntity, Suma::API::Entities::BaseEntity, Suma::API::Entities::CurrencyEntity, Suma::API::Entities::CurrentMemberEntity, Suma::API::Entities::ImageEntity, Suma::API::Entities::LedgerEntity, Suma::API::Entities::LedgerLineEntity, Suma::API::Entities::LedgerLineUsageDetailsEntity, Suma::API::Entities::LocaleEntity, Suma::API::Entities::MemberPreferencesEntity, Suma::API::Entities::MobilityChargeEntity, Suma::API::Entities::MobilityChargeLineItemEntity, Suma::API::Entities::MobilityTripEntity, Suma::API::Entities::PaymentInstrumentEntity, Suma::API::Entities::PreferencesSubscriptionEntity, Suma::API::Entities::RegistrationLinkEntity, Suma::API::Entities::VendorServiceEntity, Suma::API::Images::UploadedFileEntity, Suma::API::Ledgers::LedgerLinesEntity, Suma::API::Ledgers::LedgersViewEntity, Suma::API::Me::DashboardAlertEntity, Suma::API::Me::DashboardEntity, Suma::API::Me::ProgramEntity, Suma::API::Mobility::MobilityDetailedVehicleEntity, Suma::API::Mobility::MobilityMapEntity, Suma::API::Mobility::MobilityMapFeaturesEntity, Suma::API::Mobility::MobilityMapProviderEntity, Suma::API::Mobility::MobilityMapRestrictionEntity, Suma::API::Mobility::MobilityMapVehicleEntity, Suma::API::Mobility::MobilityTripCollectionEntity, Suma::API::Mobility::RateEntity, Suma::API::Mobility::SimpleRateEntity, Suma::API::PaymentInstruments::MutationPaymentInstrumentEntity, Suma::API::Payments::FundingTransactionEntity, Suma::API::Preferences::PublicPrefsEntity, Suma::API::Preferences::PublicPrefsMemberEntity
 
 /**
@@ -28,7 +28,10 @@
  * @property {boolean} needsLinking
  * @property {?} requiresPaymentMethod
  * @property {?} hasPaymentMethod
- * @property {?} promptForPaymentMethod
+ * @property {?} balancePayoffNeeded
+ * @property {?} showPaymentStep
+ * @property {?} termStepIndex
+ * @property {?} linkStepIndex
  * @property {?} descriptionText
  * @property {?} termsText
  * @property {?} helpText
@@ -225,11 +228,12 @@
 /**
  * @typedef {Object} OrderHistoryCollection
  * @description Auto-generated from Suma::API::Commerce::OrderHistoryCollection
- * @property {?} object
- * @property {?} currentPage
+ * @property {string} object
+ * @property {number} currentPage
  * @property {number} pageCount
  * @property {number} totalCount
- * @property {?} hasMore
+ * @property {boolean} hasMore
+ * @property {string} url
  * @property {SimpleOrderHistory} items
  * @property {DetailedOrderHistory} detailedOrders
  */
@@ -288,11 +292,12 @@
 /**
  * @typedef {Object} UnclaimedOrderCollection
  * @description Auto-generated from Suma::API::Commerce::UnclaimedOrderCollection
- * @property {?} object
- * @property {?} currentPage
+ * @property {string} object
+ * @property {number} currentPage
  * @property {number} pageCount
  * @property {number} totalCount
- * @property {?} hasMore
+ * @property {boolean} hasMore
+ * @property {string} url
  * @property {DetailedOrderHistory} items
  */
 
@@ -339,6 +344,7 @@
  * @property {?} showPrivateAccounts
  * @property {MemberPreferences} preferences
  * @property {?} hasOrderHistory
+ * @property {Money} chargeableCashBalance
  * @property {?} finishedSurveyTopics
  * @property {RegistrationLink} registrationLink
  */
@@ -481,11 +487,12 @@
 /**
  * @typedef {Object} LedgerLines
  * @description Auto-generated from Suma::API::Ledgers::LedgerLinesEntity
- * @property {?} object
- * @property {?} currentPage
+ * @property {string} object
+ * @property {number} currentPage
  * @property {number} pageCount
  * @property {number} totalCount
- * @property {?} hasMore
+ * @property {boolean} hasMore
+ * @property {string} url
  * @property {LedgerLine} items
  * @property {number} ledgerId
  */
@@ -589,11 +596,12 @@
 /**
  * @typedef {Object} MobilityTripCollection
  * @description Auto-generated from Suma::API::Mobility::MobilityTripCollectionEntity
- * @property {?} object
- * @property {?} currentPage
+ * @property {string} object
+ * @property {number} currentPage
  * @property {number} pageCount
  * @property {number} totalCount
- * @property {?} hasMore
+ * @property {boolean} hasMore
+ * @property {string} url
  * @property {MobilityTrip} items
  * @property {MobilityTrip} ongoing
  * @property {?} weeks