Adds ephemeral key APIs (#225)

* Added ephemeral key APIs

* Updated param docs for expand.

README.md

@@ -299,6 +299,7 @@ extension StripeSignatureError: AbortError {
 * [x] Payouts
 * [x] Refunds
 * [x] Tokens
+* [x] EphemeralKeys
 ---
 ### Payment Methods
 * [x] Payment Methods

Sources/StripeKit/Billing/Credit Notes/CreditNoteRoutes.swift

@@ -31,7 +31,7 @@ public protocol CreditNoteRoutes: StripeAPIRoute {
     ///   - refund: ID of an existing refund to link this credit note to.
     ///   - refundAmount: The integer amount in cents representing the amount to refund. If set, a refund will be created for the charge associated with the invoice.
     ///   - shippingCost: When `shipping_cost` contains the `shipping_rate` from the invoice, the `shipping_cost` is included in the credit note.
-    ///   - expand: An array of properties to expand.
+    ///   - expand: Specifies which fields in the response should be expanded.
     /// - Returns: A `StripeCreditNote`.
     func create(invoice: String,
                 lines: [[String: Any]]?,
@@ -59,7 +59,7 @@ public protocol CreditNoteRoutes: StripeAPIRoute {
     ///   - refund: ID of an existing refund to link this credit note to.
     ///   - refundAmount: The integer amount in cents representing the amount to refund. If set, a refund will be created for the charge associated with the invoice.
     ///   - shippingCost: When `shipping_cost` contains the `shipping_rate` from the invoice, the `shipping_cost` is included in the credit note.
-    ///   - expand: An array of properties to expand.
+    ///   - expand: Specifies which fields in the response should be expanded.
     func preview(invoice: String,
                  lines: [[String: Any]]?,
                  memo: String?,
@@ -77,7 +77,7 @@ public protocol CreditNoteRoutes: StripeAPIRoute {
     ///
     /// - Parameters:
     ///   - id: ID of the credit note object to retrieve.
-    ///   - expand: An array of properties to expand.
+    ///   - expand: Specifies which fields in the response should be expanded.
     /// - Returns: Returns a credit note object if a valid identifier was provided.
     func retrieve(id: String, expand: [String]?) async throws -> CreditNote
 
@@ -87,7 +87,7 @@ public protocol CreditNoteRoutes: StripeAPIRoute {
     ///   - id: ID of the credit note object to update.
     ///   - memo: Credit note memo. This will be unset if you POST an empty value.
     ///   - metadata: Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`.
-    ///   - expand: An array of properties to expand.
+    ///   - expand: Specifies which fields in the response should be expanded.
     /// - Returns: Returns the updated credit note object if the call succeeded.
     func update(id: String, memo: String?, metadata: [String: String]?, expand: [String]?) async throws -> CreditNote
 
@@ -108,7 +108,7 @@ public protocol CreditNoteRoutes: StripeAPIRoute {
     ///
     /// - Parameters:
     ///   - id: ID of the credit note object to void.
-    ///   - expand: An array of properties to expand.
+    ///   - expand: Specifies which fields in the response should be expanded.
     func void(id: String, expand: [String]?) async throws -> CreditNote
 
     /// Returns a list of credit notes.

Sources/StripeKit/Billing/Customer Balance Transactions/CustomerBalanceTransactionRoutes.swift

@@ -16,7 +16,7 @@ public protocol CustomerBalanceTransactionRoutes: StripeAPIRoute {
     ///  - customer: The customer the transaction belongs to.
     ///  - description: An arbitrary string attached to the object. Often useful for displaying to users.
     ///  - metadata: Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
-    ///  - expand: An array of properties to expand.
+    ///  - expand: Specifies which fields in the response should be expanded.
     func create(amount: Int,
                 currency: Currency,
                 customer: String,
@@ -28,7 +28,7 @@ public protocol CustomerBalanceTransactionRoutes: StripeAPIRoute {
     /// - Parameters:
     ///  - customer: The customer the transaction belongs to.
     ///  - transaction: The transaction to retrieve.
-    ///  - expand: An array of properties to expand.
+    ///  - expand: Specifies which fields in the response should be expanded.
     func retrieve(customer: String, transaction: String, expand: [String]?) async throws -> CustomerBalanceTransaction
 
     /// Most customer balance transaction fields are immutable, but you may update its `description` and `metadata`.
@@ -37,7 +37,7 @@ public protocol CustomerBalanceTransactionRoutes: StripeAPIRoute {
     ///  - transaction: The transaction to update.
     ///  - description: An arbitrary string attached to the object. Often useful for displaying to users.
     ///  - metadata: Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
-    ///  - expand: An array of properties to expand.
+    ///  - expand: Specifies which fields in the response should be expanded.
     func update(customer: String,
                 transaction: String,
                 description: String?,

Sources/StripeKit/Billing/Customer Portal/PortalSessionRoutes.swift

@@ -17,7 +17,7 @@ public protocol PortalSessionRoutes: StripeAPIRoute {
     ///   - locale: The IETF language tag of the locale Customer Portal is displayed in. If blank or auto, the customer’s `preferred_locales` or browser’s locale is used.
     ///   - onBehalfOf: The `on_behalf_of` account to use for this session. When specified, only subscriptions and invoices with this `on_behalf_of` account appear in the portal. For more information, see the docs. Use the Accounts API to modify the `on_behalf_of` account’s branding settings, which the portal displays.
     ///   - returnUrl: The default URL to redirect customers to when they click on the portal’s link to return to your website.
-    ///   - expand: An array of properties to expand.
+    ///   - expand: Specifies which fields in the response should be expanded.
     func create(customer: String,
                 configuration: [String: Any]?,
                 flowData: [String: Any]?,

Sources/StripeKit/Billing/Customer Tax IDs/CustomerTaxIDRoutes.swift

@@ -15,7 +15,7 @@ public protocol CustomerTaxIDRoutes: StripeAPIRoute {
     ///   - customer: ID of the customer.
     ///   - type: Type of the tax ID.
     ///   - value: Value of the tax ID.
-    ///   - expand: An array of properties to expand.
+    ///   - expand: Specifies which fields in the response should be expanded.
     /// - Returns: The created ``TaxID`` object.
     func create(customer: String,
                 type: TaxIDType,
@@ -27,7 +27,7 @@ public protocol CustomerTaxIDRoutes: StripeAPIRoute {
     /// - Parameters:
     ///   - id: Unique identifier of the TaxID object to retrieve.
     ///   - customer: ID of the customer.
-    ///   - expand: An array of properties to expand.
+    ///   - expand: Specifies which fields in the response should be expanded.
     /// - Returns: Returns a ``TaxID`` object if a valid identifier was provided.
     func retrieve(id: String, customer: String, expand: [String]?) async throws -> TaxID
 

Sources/StripeKit/Billing/Invoice Items/InvoiceItemRoutes.swift

@@ -31,7 +31,7 @@ public protocol InvoiceItemRoutes: StripeAPIRoute {
     ///   - taxRates: The tax rates which apply to the invoice item. When set, the `default_tax_rates` on the invoice do not apply to this invoice item.
     ///   - unitAmount: The integer unit amount in cents of the charge to be applied to the upcoming invoice. This `unit_amount` will be multiplied by the quantity to get the full amount. If you want to apply a credit to the customer’s account, pass a negative `unit_amount`.
     ///   - unitAmountDecimal: Same as `unit_amount`, but accepts a decimal value with at most 12 decimal places. Only one of `unit_amount` and `unit_amount_decimal` can be set.
-    ///   - expand: An array of properties to expand.
+    ///   - expand: Specifies which fields in the response should be expanded.
     /// - Returns: The created invoice item object is returned if successful. Otherwise, this call returns an error.
     func create(customer: String,
                 amount: Int?,
@@ -57,7 +57,7 @@ public protocol InvoiceItemRoutes: StripeAPIRoute {
     ///
     /// - Parameters:
     ///   - invoiceItem: The ID of the desired invoice item.
-    ///   - expand: An array of properties to expand.
+    ///   - expand: Specifies which fields in the response should be expanded.
     /// - Returns: Returns an invoice item if a valid invoice item ID was provided. Returns an error otherwise.
     func retrieve(invoiceItem: String, expand: [String]?) async throws -> InvoiceItem
 
@@ -79,7 +79,7 @@ public protocol InvoiceItemRoutes: StripeAPIRoute {
     ///   - taxRates: The tax rates which apply to the invoice item. When set, the `default_tax_rates` on the invoice do not apply to this invoice item.
     ///   - unitAmount: The integer unit amount in cents of the charge to be applied to the upcoming invoice. This `unit_amount` will be multiplied by the quantity to get the full amount. If you want to apply a credit to the customer’s account, pass a negative `unit_amount`.
     ///   - unitAmountDecimal: Same as `unit_amount`, but accepts a decimal value with at most 12 decimal places. Only one of `unit_amount` and `unit_amount_decimal` can be set.
-    ///   - expand: An array of properties to expand.
+    ///   - expand: Specifies which fields in the response should be expanded.
     /// - Returns: The updated invoice item object is returned upon success. Otherwise, this call returns an error.
     func update(invoiceItem: String,
                 amount: Int?,

Sources/StripeKit/Billing/Invoices/InvoiceRoutes.swift

@@ -41,7 +41,7 @@ public protocol InvoiceRoutes: StripeAPIRoute {
     ///   - shippingDetails: Shipping details for the invoice. The Invoice PDF will use the `shipping_details` value if it is set, otherwise the PDF will render the shipping address from the customer.
     ///   - statementDescriptor: Extra information about a charge for the customer’s credit card statement. It must contain at least one letter. If not specified and this invoice is part of a subscription, the default `statement_descriptor` will be set to the first subscription item’s product’s `statement_descriptor`.
     ///   - transferData: If specified, the funds from the invoice will be transferred to the destination and the ID of the resulting transfer will be found on the invoice’s charge.
-    ///   - expand: An array of properties to expand.
+    ///   - expand: Specifies which fields in the response should be expanded.
     /// - Returns: Returns the invoice object. Returns an error if the customer ID provided is invalid.
     func create(autoAdvance: Bool?,
                 collectionMethod: InvoiceCollectionMethod?,
@@ -76,7 +76,7 @@ public protocol InvoiceRoutes: StripeAPIRoute {
     ///
     /// - Parameters:
     ///   - invoice: The identifier of the desired invoice.
-    ///   - expand: An array of properties to expand.
+    ///   - expand: Specifies which fields in the response should be expanded.
     /// - Returns: Returns an invoice object if a valid invoice ID was provided. Returns an error otherwise.
     ///
     /// The invoice object contains a `lines` hash that contains information about the subscriptions and invoice items that have been applied to the invoice, as well as any prorations that Stripe has automatically calculated. Each line on the invoice has an `amount` attribute that represents the amount actually contributed to the invoice’s total. For invoice items and prorations, the amount attribute is the same as for the invoice item or proration respectively. For subscriptions, the amount may be different from the plan’s regular price depending on whether the invoice covers a trial period or the invoice period differs from the plan’s usual interval.
@@ -110,7 +110,7 @@ public protocol InvoiceRoutes: StripeAPIRoute {
     ///   - shippingDetails: Shipping details for the invoice. The Invoice PDF will use the `shipping_details` value if it is set, otherwise the PDF will render the shipping address from the customer.
     ///   - statementDescriptor: Extra information about a charge for the customer’s credit card statement. It must contain at least one letter. If not specified and this invoice is part of a subscription, the default `statement_descriptor` will be set to the first subscription item’s product’s `statement_descriptor`.
     ///   - transferData: If specified, the funds from the invoice will be transferred to the destination and the ID of the resulting transfer will be found on the invoice’s charge. This will be unset if you POST an empty value.
-    ///   - expand: An array of properties to expand.
+    ///   - expand: Specifies which fields in the response should be expanded.
     /// - Returns: Returns the invoice object.
     func update(invoice: String,
                 autoAdvance: Bool?,
@@ -148,7 +148,7 @@ public protocol InvoiceRoutes: StripeAPIRoute {
     /// - Parameters:
     ///   - invoice: The invoice to be finalized, it must have `status=draft`.
     ///   - autoAdvance: Controls whether Stripe will perform automatic collection of the invoice. When false, the invoice’s state will not automatically advance without an explicit action.
-    ///   - expand: An array of properties to expand.
+    ///   - expand: Specifies which fields in the response should be expanded.
     /// - Returns: Returns an invoice object with `status=open`.
     func finalize(invoice: String, autoAdvance: Bool?, expand: [String]?) async throws -> Invoice
 
@@ -162,7 +162,7 @@ public protocol InvoiceRoutes: StripeAPIRoute {
     ///   - paidOutOfBand: Boolean representing whether an invoice is paid outside of Stripe. This will result in no charge being made.
     ///   - paymentMethod: A PaymentMethod to be charged. The PaymentMethod must be the ID of a PaymentMethod belonging to the customer associated with the invoice being paid.
     ///   - source: A payment source to be charged. The source must be the ID of a source belonging to the customer associated with the invoice being paid.
-    ///   - expand: An array of properties to expand.
+    ///   - expand: Specifies which fields in the response should be expanded.
     /// - Returns: Returns the invoice object.
     func pay(invoice: String,
              forgive: Bool?,
@@ -179,23 +179,23 @@ public protocol InvoiceRoutes: StripeAPIRoute {
     ///
     /// - Parameters:
     ///   - invoice: The invoice you would like to send. The billing mode for this invoice must be `send_invoice`.
-    ///   - expand: An array of properties to expand.
+    ///   - expand: Specifies which fields in the response should be expanded.
     /// - Returns: Returns the invoice object.
     func send(invoice: String, expand: [String]?) async throws -> Invoice
 
     /// Mark a finalized invoice as void. This cannot be undone. Voiding an invoice is similar to [deletion](https://stripe.com/docs/api/invoices/void#delete_invoice), however it only applies to finalized invoices and maintains a papertrail where the invoice can still be found.
     ///
     /// - Parameters:
     ///   - invoice: ID of invoice to void. It must be finalized.
-    ///   - expand: An array of properties to expand.
+    ///   - expand: Specifies which fields in the response should be expanded.
     /// - Returns: Returns the voided invoice object.
     func void(invoice: String, expand: [String]?) async throws -> Invoice
 
     /// Marking an invoice as uncollectible is useful for keeping track of bad debts that can be written off for accounting purposes.
     ///
     /// - Parameters:
     ///   - invoice: The identifier of the invoice to be marked as uncollectible. The invoice must be `open`.
-    ///   - expand: An array of properties to expand.
+    ///   - expand: Specifies which fields in the response should be expanded.
     /// - Returns: Returns the invoice object
     func markUncollectible(invoice: String, expand: [String]?) async throws -> Invoice
 

Sources/StripeKit/Billing/Plans/PlanRoutes.swift

@@ -30,7 +30,7 @@ public protocol PlanRoutes: StripeAPIRoute {
     ///   - transformUsage: Apply a transformation to the reported usage or set quantity before computing the billed price. Cannot be combined with `tiers`.
     ///   - trialPeriodDays: Default number of trial days when subscribing a customer to this plan using `trial_from_plan=true`.
     ///   - usageType: Configures how the quantity per period should be determined, can be either `metered` or `licensed`. `licensed` will automatically bill the `quantity` set for a plan when adding it to a subscription, `metered` will aggregate the total usage based on usage records. Defaults to `licensed`.
-    ///   - expand: An array of properties to expand.
+    ///   - expand: Specifies which fields in the response should be expanded.
     /// - Returns: Returns the plan object
     func create(amount: Int?,
                 currency: Currency,
@@ -55,7 +55,7 @@ public protocol PlanRoutes: StripeAPIRoute {
     ///
     /// - Parameters:
     ///   - plan: The ID of the desired plan.
-    ///   - expand: An array of properties to expand.
+    ///   - expand: Specifies which fields in the response should be expanded.
     /// - Returns: Returns a plan if a valid plan ID was provided. Returns an error otherwise.
     func retrieve(plan: String, expand: [String]?) async throws -> Plan
 
@@ -68,7 +68,7 @@ public protocol PlanRoutes: StripeAPIRoute {
     ///   - nickname: A brief description of the plan, hidden from customers. This will be unset if you POST an empty value.
     ///   - product: The product the plan belongs to. Note that after updating, statement descriptors and line items of the plan in active subscriptions will be affected.
     ///   - trialPeriodDays: Default number of trial days when subscribing a customer to this plan using `trial_from_plan=true`.
-    ///   - expand: An array of properties to expand.
+    ///   - expand: Specifies which fields in the response should be expanded.
     /// - Returns: The updated plan object is returned upon success. Otherwise, this call returns an error.
     func update(plan: String,
                 active: Bool?,