docs(zoe): ZoeService methods (WIP)

NOTE: getTerms() type no longer conditional; OK?

packages/zoe/src/zoeService/installationStorage.js

@@ -67,7 +67,7 @@ export const makeInstallationStorage = (getBundleCapForID, zoeBaggage) => {
  * an instance is started.
  */
 
- /** @type {InstallBundle} */
+ /** @type {ZoeService['install']} */
  const installSourceBundle = async (bundle, bundleLabel) => {
  typeof bundle === 'object' || Fail`a bundle must be provided`;
  /** @type {Installation} */

packages/zoe/src/zoeService/internal-types.js

@@ -127,16 +127,16 @@
  * @property {GetAssetKindByBrand} getAssetKindByBrand
  * @property {DepositPayments} depositPayments
  * @property {Issuer<'set'>} invitationIssuer
- * @property {InstallBundle} installBundle
- * @property {InstallBundleID} installBundleID
- * @property {GetBundleIDFromInstallation} getBundleIDFromInstallation
+ * @property {ZoeService['install']} installBundle
+ * @property {ZoeService['installBundleID']} installBundleID
+ * @property {ZoeService['getBundleIDFromInstallation']} getBundleIDFromInstallation
  * @property {import('./utils.js').GetPublicFacet} getPublicFacet
- * @property {GetBrands} getBrands
- * @property {GetIssuers} getIssuers
+ * @property {ZoeService['getBrands']} getBrands
+ * @property {ZoeService['getIssuers']} getIssuers
  * @property {import('./utils.js').GetTerms} getTerms
- * @property {GetOfferFilter} getOfferFilter
- * @property {SetOfferFilter} setOfferFilter
- * @property {GetInstallationForInstance} getInstallationForInstance
+ * @property {ZoeService['getOfferFilter']} getOfferFilter
+ * @property {(instance: Instance, strings: string[]) => void} setOfferFilter
+ * @property {ZoeService['getInstallationForInstance']} getInstallationForInstance
  * @property {GetInstanceAdmin} getInstanceAdmin
  * @property {UnwrapInstallation} unwrapInstallation
  * @property {GetProposalShapeForInvitation} getProposalShapeForInvitation

packages/zoe/src/zoeService/invitationQueries.js

@@ -4,7 +4,7 @@ import { assert, details as X, Fail, quote as q } from '@agoric/assert';
 import { E } from '@endo/eventual-send';
 
 export const makeInvitationQueryFns = invitationIssuer => {
- /** @type {GetInvitationDetails} */
+ /** @type {ZoeService['getInvitationDetails']} */
  const getInvitationDetails = async invitationP => {
  const onRejected = reason => {
  const err = assert.error(
@@ -21,11 +21,11 @@ export const makeInvitationQueryFns = invitationIssuer => {
  return invAmount.value[0];
  };
 
- /** @type {GetInstance} */
+ /** @type {ZoeService['getInstance']} */
  const getInstance = invitation =>
  E.get(getInvitationDetails(invitation)).instance;
 
- /** @type {GetInstallation} */
+ /** @type {ZoeService['getInstallation']} */
  const getInstallation = invitation =>
  E.get(getInvitationDetails(invitation)).installation;
 

packages/zoe/src/zoeService/offer/offer.js

@@ -15,7 +15,7 @@ import '../internal-types.js';
 const { quote: q, Fail } = assert;
 
 export const makeOfferMethod = offerDataAccess => {
- /** @type {Offer} */
+ /** @type {ZoeService['offer']} */
  const offer = async (
  invitation,
  uncleanProposal = harden({}),

packages/zoe/src/zoeService/types.js

@@ -2,10 +2,16 @@
 
 /// <reference types="ses"/>
 /**
- * @import { Installation } from './utils.js'
- * @import { InstallationStart } from './utils.js'
+ * @import { Installation, InstallationStart, Instance } from './utils.js'
+ * @import {VatAdminSvc} from '@agoric/swingset-vat'
  */
 
+// @@@
+// * TODO remove support for source bundles, leaving only support for hash bundles.
+// * {@link https://github.com/Agoric/agoric-sdk/issues/4565}
+// TODO consolidate installBundleID into install.
+// https://github.com/Agoric/agoric-sdk/issues/4974
+
 /**
  * @typedef {object} ZoeService
  *
@@ -21,7 +27,7 @@
  * within its vat. The contract and ZCF never have direct access to
  * the users' payments or the Zoe purses.
  *
- * @property {GetInvitationIssuer} getInvitationIssuer
+ * @property {() => Promise<Issuer<'set'>>} getInvitationIssuer
  *
  * Zoe has a single `invitationIssuer` for the entirety of its
  * lifetime. By having a reference to Zoe, a user can get the
@@ -30,136 +36,22 @@
  * creates the ERTP payments that represent the right to interact with
  * a smart contract in particular ways.
  *
- * @property {InstallBundle} install
- * @property {InstallBundleID} installBundleID
- * @property {import('./utils.js').StartInstance} startInstance
- * @property {Offer} offer
- * @property {import('./utils.js').GetPublicFacet} getPublicFacet
- * @property {GetIssuers} getIssuers
- * @property {GetBrands} getBrands
- * @property {import('./utils.js').GetTerms} getTerms
- * @property {GetOfferFilter} getOfferFilter
- * @property {GetInstallationForInstance} getInstallationForInstance
- * @property {GetInstance} getInstance
- * @property {GetInstallation} getInstallation
- * @property {GetInvitationDetails} getInvitationDetails
- * Return an object with the instance, installation, description, invitation
- * handle, and any custom properties specific to the contract.
- * @property {GetFeeIssuer} getFeeIssuer
- * @property {GetConfiguration} getConfiguration
- * @property {GetBundleIDFromInstallation} getBundleIDFromInstallation
- * @property {(invitationHandle: InvitationHandle) => Pattern | undefined} getProposalShapeForInvitation
- */
-
-/**
- * @callback GetInvitationIssuer
- * @returns {Promise<Issuer<'set'>>}
- */
-
-/**
- * @callback GetFeeIssuer
- * @returns {Promise<Issuer<'nat'>>}
- */
-
-/**
- * @callback GetConfiguration
- * @returns {{
- * feeIssuerConfig: FeeIssuerConfig,
- * }}
- */
-
-/**
- * @callback GetIssuers
- * @param {import('./utils.js').Instance<any>} instance
- * @returns {Promise<IssuerKeywordRecord>}
- */
-
-/**
- * @callback GetBrands
- * @param {import('./utils.js').Instance<any>} instance
- * @returns {Promise<BrandKeywordRecord>}
- */
-
-/**
- * @callback GetOfferFilter
- * @param {import('./utils.js').Instance<any>} instance
- * @returns {string[]}
- */
-
-/**
- * @callback SetOfferFilter
- * @param {Instance} instance
- * @param {string[]} strings
- */
-
-/**
- * @callback GetInstallationForInstance
- * @param {import('./utils.js').Instance<any>} instance
- * @returns {Promise<Installation>}
- */
-
-/**
- * @callback GetInstance
- * @param {ERef<Invitation>} invitation
- * @returns {Promise<import('./utils.js').Instance<any>>}
- */
-
-/**
- * @callback GetInstallation
- * @param {ERef<Invitation>} invitation
- * @returns {Promise<Installation>}
- */
-
-/**
- * @callback GetInvitationDetails
- * @param {ERef<Invitation<any, any>>} invitation
- * @returns {Promise<InvitationDetails>}
- */
-
-// TODO remove support for source bundles, leaving only support for hash bundles.
-// https://github.com/Agoric/agoric-sdk/issues/4565
-/**
- * @callback InstallBundle
- *
+ * @property {(bundle: Bundle | SourceBundle, bundleLabel?: string) => Promise<Installation>} install
  * Create an installation by safely evaluating the code and
  * registering it with Zoe. Returns an installation.
  *
- * @param {Bundle | SourceBundle} bundle
- * @param {string} [bundleLabel]
- * @returns {Promise<Installation>}
- */
-
-// TODO consolidate installBundleID into install.
-// https://github.com/Agoric/agoric-sdk/issues/4974
-/**
- * @callback InstallBundleID
- *
+ * @property {(bundleID: BundleID, bundleLabel?: string) => Promise<Installation>} installBundleID
  * Create an installation from a Bundle ID. Returns an installation.
  *
- * @param {BundleID} bundleID
- * @param {string} [bundleLabel]
- * @returns {Promise<Installation>}
- */
-
-/**
- * @callback GetBundleIDFromInstallation
- *
- * Verify that an alleged Installation is real, and return the Bundle ID it
- * will use for contract code.
+ * @property {import('./utils.js').StartInstance} startInstance
  *
- * @param {ERef<Installation>} allegedInstallation
- * @returns {Promise<BundleID>}
- */
-
-/**
- * @typedef {<Result, Args = undefined>(
+ * @property {<Result, Args = undefined>(
  * invitation: ERef<Invitation<Result, Args>>,
  * proposal?: Proposal,
  * paymentKeywordRecord?: PaymentPKeywordRecord,
  * offerArgs?: Args,
- * ) => Promise<UserSeat<Result>>
- * } Offer
- *
+ * ) => Promise<UserSeat<Result>>} offer
+ * @property {import('./utils.js').GetPublicFacet} getPublicFacet
  * To redeem an invitation, the user normally provides a proposal (their
  * rules for the offer) as well as payments to be escrowed by Zoe. If
  * either the proposal or payments would be empty, indicate this by
@@ -173,6 +65,40 @@
  * `paymentKeywordRecord` is a record with keywords as keys, and the
  * values are the actual payments to be escrowed. A payment is
  * expected for every rule under `give`.
+ *
+ * @property {(instance: Instance<any>) => Promise<IssuerKeywordRecord>} getIssuers
+ *
+ * @property {(instance: Instance) => Promise<BrandKeywordRecord>} getBrands
+ * Get the current mapping of keywords to brands, as from {@link getTerms}
+ *
+ * @property {<SF>(instance: Instance<SF>) => Promise<StandardTerms & import('./utils').StartParams<SF>["terms"]>} getTerms
+ * Each Zoe contract instance has an customTerms, issuers,
+ * and brands. The customTerms are never changed, but new issuers (and their
+ * matching brands) may be added by the contract code.
+ *
+ * @property {(instance: Instance<any>) => string[]} getOfferFilter
+ *
+ * @property {(instance: Instance<any>) => Promise<Installation>} getInstallationForInstance
+ *
+ * @property {(invitation: ERef<Invitation>) => Promise<Instance<any>>} getInstance
+ *
+ * @property {(invitation: ERef<Invitation>) => Promise<Installation>} getInstallation
+ *
+ * @property {(invitation: ERef<Invitation<any, any>>) => Promise<InvitationDetails>} getInvitationDetails
+ *
+ * Return an object with the instance, installation, description, invitation
+ * handle, and any custom properties specific to the contract.
+ * @property {() => Promise<Issuer<'nat'>>} getFeeIssuer
+ *
+ * @property {() => {
+ * feeIssuerConfig: FeeIssuerConfig,
+ * }} getConfiguration
+ *
+ * Verify that an alleged Installation is real, and return the Bundle ID it
+ * will use for contract code.
+ * @property {(allegedInstallation: ERef<Installation>) => Promise<BundleID>} getBundleIDFromInstallation
+ *
+ * @property {(invitationHandle: InvitationHandle) => Pattern | undefined} getProposalShapeForInvitation
  */
 
 /**
@@ -274,14 +200,6 @@
  * `{ afterDeadline: { timer :Timer<Deadline>, deadline :Deadline } }`
  */
 
-/**
- * @import { Instance } from './utils.js'
- */
-
-/**
- * @import {VatAdminSvc} from '@agoric/swingset-vat'
- */
-
 /**
  * @typedef {{bundleCap: import('@agoric/swingset-vat').BundleCap } | {name: string} | {id: BundleID}} ZCFSpec
  */