Merge pull request #12 from checkout/PRISM-10620-draft-public-docs-an…

…d-readm-es-for-risk-i-os

PRISM-10620 - Add documentation and templates

.github/CONTRIBUTING.md

@@ -0,0 +1,33 @@
+# Contributing Guidelines
+
+## Reporting Issues
+
+A great way to contribute to the project
+is to send a detailed issue when you encounter a problem.
+We always appreciate a well-written, thorough bug report.
+
+Check that the project issues database
+doesn't already include that problem or suggestion before submitting an issue.
+If you find a match, add a quick "+1" or "I have this problem too."
+Doing this helps prioritize the most common problems and requests.
+
+When reporting issues, please include the following:
+
+* The version of Xcode you're using
+* The version of iOS you're targeting
+* The full output of any stack trace or compiler error
+* A code snippet that reproduces the described behavior, if applicable
+* Any other details that would be useful in understanding the problem
+
+This information will help us review and fix your issue faster.
+
+## Sending a Pull Request
+
+**Before submitting a pull request,** please make sure the following is done:
+
+1.  Fork [the repository](https://github.com/checkout/checkout-risk-sdk-ios) and create your branch from `main`.
+2.  If you've added code that should be tested, please add tests.
+3.  If you've changed APIs, update the documentation.
+4.  Ensure the test suite passes.
+5.  Format your code.
+6.  Make sure your code lints.

.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,15 @@
+Before you open an issue, please check if a similar issue already exists or has been closed before.
+
+### When reporting a bug, please be sure to include the following:
+
+* [ ] A descriptive title
+* [ ] An _isolated_ way to reproduce the behavior (example: GitHub repository with code isolated to the issue that anyone can clone to observe the problem)
+* [ ] What version of `Risk` you're using, and the platform(s) you're running it on
+* [ ] The behavior you expect to see, and the actual behavior
+
+### When you open an issue for a feature request, please add as much detail as possible:
+
+* [ ] A descriptive title
+* [ ] A description of the problem you're trying to solve, including _why_ you think this is a problem
+* [ ] An overview of the suggested solution
+* [ ] If the feature changes current behavior, reasons why your solution is better

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,30 @@
+## Issue
+
+_Issue ticket number and link._
+
+## Proposed changes
+
+_Describe the big picture of your changes here to communicate to the maintainers why we should accept this pull request. If it fixes a bug or resolves a feature request, be sure to link to that issue._
+
+## Test Steps
+
+_If there's any functionality change, please list a step by step guide of how to verify the changes._
+
+> For instance testing a timeout feature:
+> 1. On the `APIService`, change the `timeoutInterval` to 0.0001.
+> 2. Make a network call and assert that the request timed out.
+> 3. Revert the value after testing.
+
+## Checklist
+
+_Put an `x` in the boxes that apply. You can also fill these out after creating the PR. If you're unsure about any of them, don't hesitate to ask. We're here to help! This is simply a reminder of what we are going to look for before merging your code._
+
+* [ ] Reviewers assigned
+* [ ] I have performed a self-review of my code and manual testing
+* [ ] Lint and unit tests pass locally with my changes
+* [ ] I have added tests that prove my fix is effective or that my feature works
+* [ ] I have added necessary documentation (if applicable)
+
+## Further comments
+
+_If this is a relatively large or complex change, kick off the discussion by explaining why you choose the solution you did and what alternatives you considered, etc..._

.github/partial-readmes/Installation.md

@@ -0,0 +1,52 @@
+# Installation Guide
+
+We've done our best to support the most common distribution methods on iOS. We are in strong favour of [SPM](#Swift-Package-Manager) (Swift Package Manager) but if for any reason this doesn't work for you, we also support [Cocoapods](#Cocoapods).
+
+### Swift Package Manager
+[Swift Package Manager](https://swift.org/package-manager/) integrated with the Swift build system to automate the process of downloading, compiling, and linking dependencies. It should work out of the box on latest Xcode projects since Xcode 11 and has had a lot of community support, seeing huge adoption over the recent years. This is our preferred distribution method for Risk iOS and is the easiest one to integrate, keep updated and build around.
+
+```swift
+let package = Package(
+    ...
+    dependencies: [
+        .package(url: "https://github.com/checkout/checkout-risk-sdk-ios", from: "...")
+    ]
+    ...
+)
+```
+<!-- TODO: update tag version (https://checkout.atlassian.net/browse/PRISM-10088) -->
+
+If you've never used it before, get started with Apple's step by step guide into [adding package dependencies to your app](https://developer.apple.com/documentation/xcode/adding-package-dependencies-to-your-app) . Just use this repository's URL (https://github.com/checkout/checkout-risk-sdk-ios) when adding dependency.
+
+
+### CocoaPods
+[CocoaPods](http://cocoapods.org) is the traditional dependency manager for Apple projects. We do support it, but recommend using SPM given it is Apple's preferred dependency manager.
+
+Make sure cocoapods is installed on your machine by running
+```bash
+$ pod --version
+```
+Any version newer than **1.10.0** is a good sign. If not installed, or unsupported, follow [Cocoapods Getting Started](https://guides.cocoapods.org/using/getting-started.html)
+
+Once Cocoapods of a valid version is on your machine, to integrate Risk into your Xcode project, update your `Podfile`:
+```ruby
+source 'https://github.com/CocoaPods/Specs.git'
+platform :ios, '12.0'
+use_frameworks!
+
+target '<Your Target Name>' do
+    pod 'Risk', '~> 1.0' 
+end
+```
+<!-- TODO: Update pod version (https://checkout.atlassian.net/browse/PRISM-10088) -->
+
+Then, run the following command in terminal:
+
+```bash
+$ pod install
+```
+
+To update your existing Cocoapod dependencies, use:
+```bash
+$ pod update
+```

.swiftpm/xcode/xcshareddata/xcschemes/Risk.xcscheme

@@ -51,6 +51,16 @@
       debugDocumentVersioning = "YES"
       debugServiceExtension = "internal"
       allowLocationSimulation = "YES">
+      <BuildableProductRunnable
+         runnableDebuggingMode = "0">
+         <BuildableReference
+            BuildableIdentifier = "primary"
+            BlueprintIdentifier = "BA0B00442AD6A5280037D9FF"
+            BuildableName = "RiskExample.app"
+            BlueprintName = "RiskExample"
+            ReferencedContainer = "container:iOSExampleRiskSPM/RiskExample.xcodeproj">
+         </BuildableReference>
+      </BuildableProductRunnable>
    </LaunchAction>
    <ProfileAction
       buildConfiguration = "Release"

README.md

@@ -1,2 +1,138 @@
 #  Risk iOS package
+<!-- TODO: Uncomment when repo is public (https://checkout.atlassian.net/browse/PRISM-10088) -->
+<!-- [![CocoaPods Compatible](https://img.shields.io/cocoapods/v/Risk.svg)](https://img.shields.io/cocoapods/v/Risk)
+![GitHub release (latest by date)](https://img.shields.io/github/v/release/checkout/checkout-risk-sdk-ios?label=spm)
+[![Platform](https://img.shields.io/cocoapods/p/Risk.svg?style=flat)]()
+![license](https://img.shields.io/github/license/checkout/checkout-risk-sdk-ios.svg) -->
+The package helps collect device data for merchants with direct integration (standalone) with the package and those using [Checkout's Frames iOS package](https://github.com/checkout/frames-ios).
 
+## Table of contents
+- [Risk iOS package](#risk-ios-package)
+  - [Table of contents](#table-of-contents)
+  - [Requirements](#requirements)
+  - [Documentation](#documentation)
+    - [Usage guide](#usage-guide)
+    - [Public API](#public-api)
+    - [Additional Resources](#additional-resources)
+  - [Demo projects](#demo-projects)
+  - [Changelog](#changelog)
+  - [Contributing](#contributing)
+  - [License](#license)
+
+
+## Requirements
+- iOS 12.0+
+- Xcode 12.4+
+- Swift 5.3+
+
+## Documentation
+### Usage guide
+  1. Add `Risk` as a package dependency - _see [Installation guide](https://github.com/checkout/checkout-risk-sdk-ios/blob/main/.github/partial-readmes/Integration.md) on how to add our SDK in your iOS app via SPM or Cocoapods._
+  2. Obtain a public API key from [Checkout Dashboard](https://dashboard.checkout.com/developers/keys).
+  3. Initialise the package with the `getInstance` method passing in the required configuration (public API key and environment), then publish the device data with the `publishData` method, see example below.
+```swift
+// Example usage of package
+let yourConfig = RiskConfig(publicKey: "pk_qa_xxx", environment: RiskEnvironment.qa)
+
+Risk.getInstance(config: yourConfig) { riskInstance in
+    riskInstance?.publishData() { response in
+        print(response.deviceSessionID)
+    }
+}
+ ```
+
+### Public API
+The package exposes two methods:
+1. `getInstance` - This is a method that returns a singleton instance of Risk. When the method is called, preliminary checks are made to Checkout's internal API(s) that retrieves the public keys used to initialise the package used in collecting device data, if the checks fail or the merchant is disabled, nil will be returned, else, if the checks are successful, the `Risk` instance is returned to the consumer of the package which can now be used to publish the data with the `publishData` method.
+
+    <details>
+    <summary>Arguments</summary>
+
+    ```swift
+    public struct RiskConfig {
+        public let publicKey: String
+        public let environment: RiskEnvironment
+        public let framesMode: Bool
+
+        public init(publicKey: String, environment: RiskEnvironment, framesMode: Bool = false) {
+            self.publicKey = publicKey
+            self.environment = environment
+            self.framesMode = framesMode
+        }
+    }
+
+    public enum RiskEnvironment {
+        case qa
+        case sandbox
+        case prod
+    }
+    ```
+    </details>
+
+    <details>
+    <summary>Responses</summary>
+
+    ```swift
+    public class Risk {
+        ...
+
+        public func publishData(...) ... {
+                ...
+        }
+    }
+    ```
+    </details>
+
+
+2. `publishData` - This is used to publish and persist the device data.
+
+    <details>
+    <summary>Arguments</summary>
+
+    ```swift
+    public func publishData(cardToken: String? = nil, completion: @escaping (Result<PublishRiskData, RiskError>) -> Void) {
+            ...
+    }
+    ```
+    </details>
+
+    <details>
+    <summary>Responses</summary>
+
+    ```swift
+    public struct PublishRiskData {
+        public let deviceSessionID: String
+    }
+
+    public enum RiskError: Error, Equatable {
+        case description(String)
+
+        var localizedDescription: String {
+            switch self {
+            case .description(let errorMessage):
+                return errorMessage
+            }
+        }
+    }
+    ```
+    </details>
+
+### Additional Resources
+<!-- TODO: Add website documentation link here (https://checkout.atlassian.net/browse/PRISM-10088) - [Risk iOS SDK documentation](https://docs.checkout.com/risk/overview) -->
+- [Frames iOS SDK documentation](https://www.checkout.com/docs/developer-resources/sdks/frames-ios-sdk)
+
+## Demo projects
+Our sample application showcases our prebuilt UIs and how our SDK works. You can run this locally once you clone the repository (whether directly via git or with suggested integration methods).
+
+Our demo apps also test the supported integration methods (SPM, Cocoapods), so if you're having any problems there, they should offer a working example. You will find them in the root of the repository, inside respective folders:
+- iOSExampleRiskCocoapods - (Cocoapods distribution)
+- iOSExampleRiskSPM - (SPM distribution)
+
+## Changelog
+Find our CHANGELOG.md [here](https://github.com/checkout/checkout-risk-sdk-ios/blob/main/.github/CHANGELOG.md).
+
+## Contributing
+Find our guide to start contributing [here](https://github.com/checkout/checkout-risk-sdk-ios/blob/main/.github/CONTRIBUTING.md).
+
+## License
+Risk iOS is released under the MIT license. [See LICENSE](https://github.com/checkout/checkout-risk-sdk-ios/blob/main/LICENSE) for details.

iOSExampleRiskSPM/RiskExample.xcodeproj/project.pbxproj

@@ -447,7 +447,7 @@
 					"@executable_path/Frameworks",
 				);
 				MARKETING_VERSION = 1.0;
-				PRODUCT_BUNDLE_IDENTIFIER = com.checkout.RiskExample;
+				PRODUCT_BUNDLE_IDENTIFIER = com.checkout.RiskSPMiOSExample;
 				PRODUCT_NAME = "$(TARGET_NAME)";
 				SWIFT_EMIT_LOC_STRINGS = YES;
 				SWIFT_VERSION = 5.0;
@@ -475,7 +475,7 @@
 					"@executable_path/Frameworks",
 				);
 				MARKETING_VERSION = 1.0;
-				PRODUCT_BUNDLE_IDENTIFIER = com.checkout.RiskExample;
+				PRODUCT_BUNDLE_IDENTIFIER = com.checkout.RiskSPMiOSExample;
 				PRODUCT_NAME = "$(TARGET_NAME)";
 				SWIFT_EMIT_LOC_STRINGS = YES;
 				SWIFT_VERSION = 5.0;