Write readme (#12)

Author: evanfuller

CODEOWNERS

@@ -0,0 +1,3 @@
+# These owners will be the default owners for everything in
+# the repo.
+* @evanfuller @galennightfall @dhertz

CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# Contributing
+
+Thank you for considering contributing to the Nightfall Java SDK.
+
+There are many ways to contribute, such as:
+* Writing code samples
+* Suggesting documentation improvements
+* Submitting bug reports and feature requests
+* Writing code to improve the library itself.
+
+Please, don't use the issue tracker for personal support questions. Feel free to reach out to `[email protected]`
+to address those issues.
+
+## Responsibilities
+* Ensure cross-platform compatibility for every change that's accepted. Windows, Mac, Debian & Ubuntu Linux, etc.
+* Ensure backwards compatibility with Java 8
+* Create issues for each major change and enhancement that you wish to make.
+* Discuss proposed changes transparently and collect community feedback.
+* Avoid introducing new external dependencies whenever possible. When absolutely required, validate the software
+licenses used by these dependencies (e.g. avoid unintentional copyleft requirements).
+
+## How to report a bug
+
+### Security Disclosures 
+If you find a security vulnerability, do NOT open an issue. Email `[email protected]` instead.
+
+In order to determine whether you are dealing with a security issue, ask yourself the following questions:
+* Can I access something that's not mine, or something I shouldn't have access to?
+* Can I disable something for other people?
+* Is there a potential vulnerability stemming from a library dependency?
+
+If you answered yes to any of the above questions, then you're probably dealing with a security issue.
+Note that even if you answer "no" to all questions, you may still be dealing with a security issue, so if you're
+unsure, just email us at `[email protected]`.
+
+### Creating an Issue
+When filing an issue, make sure to answer these questions:
+1. What version of Java are you using?
+2. What operating system and processor architecture are you using?
+3. How did you discover the issue?
+4. Is the issue reproducible? What are the steps to reproduce?
+5. What did you expect to see?
+6. What did you see instead?
+
+
+## Suggesting a New Feature
+
+If you find yourself wishing for a feature that doesn't exist in this SDK, you are probably not alone.
+There are bound to be others out there with similar needs. Open an issue on our issues list on GitHub which
+describes the feature you would like to see, why you need it, and how it should work.
+
+## Code Review
+
+The core team looks at open pull requests on a regular basis. In order for your pull request to be merged, it
+must meet the following requirements:
+* It must pass the checkstyle linter; this should be run automatically when you run `mvn package`.
+* It must add unit tests to cover any new functionality.
+* It must get approval from one of the code owners.
+
+If a pull request remains idle for more than two weeks, we may close it.

README.md

@@ -1 +1,148 @@
-# nightfall-java-sdk
+# Nightfall Java SDK
+
+**Embed Nightfall scanning and detection functionality into Java applications**
+
+<!-- TODO add badges [![Build Status](https://travis-ci.org/joemccann/dillinger.svg?branch=master)](https://travis-ci.org/joemccann/dillinger)
+-->
+
+##  Features
+
+This SDK provides Java bindings for the Nightfall API. It allows you to add functionality to your applications to
+scan plain text and files in order to detect different categories of information. You can leverage any of
+the detectors in Nightfall's pre-built library, or you may programmatically define your own custom detectors. 
+
+Additionally, this library provides convenience features such as encapsulating the steps to chunk and upload files.
+
+To obtain an API Key, login to the [Nightfall dashboard](https://app.nightfall.ai/) and click the section
+titled "Manage API Keys".
+
+See our [developer documentation](https://docs.nightfall.ai/docs/entities-and-terms-to-know) for more details about
+integrating with the Nightfall API.
+
+## Dependencies
+
+The Nightfall Java SDK requires Java 8 or later.
+
+For a full list of external dependencies please consult `pom.xml`.
+
+## Installation
+
+### Maven
+Add the following to your project's `pom.xml`:
+
+``` xml
+<dependency>
+    <groupId>ai.nightfall</groupId>
+    <artifactId>scan-api</artifactId>
+    <version>1.0.0</version>
+</dependency>
+```
+
+### Gradle
+Add the following to your project's `dependencies`:
+
+```
+implementation group: 'ai.nightfall.api', name: 'scan', version: '1.0'
+```
+
+### Building Locally
+
+Alternatively, if you would like to build the project yourself:
+1. Clone this git repository
+2. Run `mvn package` from the top-level directory.
+3. The `build` directory should contain two artifacts: `api-$VERSION.jar` and `api-$VERSION-shaded.jar`. The former
+contains *only* the compiled source files of this project, whereas the latter includes the compiled dependencies. 
+4. Take whichever jar you prefer from the `build/` directory and add it to your project's classpath.
+
+## Usage
+
+### Scanning Plain Text
+
+Nightfall provides pre-built detector types, covering data types ranging from PII to PHI to credentials. The following
+snippet shows an example of how to scan using pre-built detectors.
+
+####  Sample Code
+
+```java
+// By default, the client reads the API key from the environment variable NIGHTFALL_API_KEY
+try (NightfallClient c = NightfallClient.Builder.defaultClient()) {
+
+    // Define some detectors to use to scan your data
+    Detector creditCard = new Detector("CREDIT_CARD_NUMBER");
+    Detector ssn = new Detector("US_SOCIAL_SECURITY_NUMBER");
+
+    // A rule contains a set of detectors to scan with
+    DetectionRule rule = new DetectionRule();
+    rule.setDetectors(Arrays.asList(creditCard, ssn));
+    rule.setLogicalOp("ANY");
+
+    List<String> payload = Arrays.asList("hello world", "my SSN is 678-99-8212", "4242-4242-4242-4242");
+    ScanTextConfig config = ScanTextConfig.fromDetectionRuleUUIDs(Arrays.asList(rule), 20);
+    ScanTextRequest req = new ScanTextRequest(payload, config);
+
+    ScanTextResponse response = c.scan(req);
+    System.out.println("findings: " + response.getFindings());
+}
+```
+
+### Scanning Files
+
+Scanning common file types like PDF's or office documents typically requires cumbersome text
+extraction methods like OCR.
+
+Rather than implementing this functionality yourself, the Nightfall API allows you to upload the
+original files, and then we'll handle the heavy lifting.
+
+The file upload process is implemented as a series of requests to upload the file in chunks. The library
+provides a single method that wraps the steps required to upload your file. Please refer to the
+[API Reference](https://docs.nightfall.ai/reference) for more details.
+
+The file is uploaded synchronously, but as files can be arbitrarily large, the scan itself is conducted asynchronously.
+The results from the scan are delivered by webhook; for more information about setting up a webhook server, refer to
+[the docs](https://docs.nightfall.ai/docs/creating-a-webhook-server).
+
+#### Sample Code
+
+```java
+// By default, the client reads the API key from the environment variable NIGHTFALL_API_KEY
+try (NightfallClient c = NightfallClient.Builder.defaultClient()) {
+
+    // Define some detectors to use to scan your data
+    Detector creditCard = new Detector("CREDIT_CARD_NUMBER");
+    Detector ssn = new Detector("US_SOCIAL_SECURITY_NUMBER");
+
+    // A rule contains a set of detectors to scan with
+    DetectionRule rule = new DetectionRule();
+    rule.setDetectors(Arrays.asList(creditCard, ssn));
+    rule.setLogicalOp("ANY");
+
+    // File scans are conducted asynchronously, so provide a webhook route to an HTTPS server to send results to.
+    String webhookResponseListenerURL = "https://my-service.com/nightfall/listener";
+    ScanPolicy policy = ScanPolicy.fromDetectionRules(Arrays.asList(rule), webhookResponseListenerURL);
+    ScanFileRequest req = new ScanFileRequest(policy, "my request metadata");
+
+    // Upload the data to the API, then trigger the async scan
+    File file = new File("./super-secret-credit-cards.pdf");
+    try (InputStream stream = new FileInputStream(file)) {
+        ScanFileResponse response = c.scanFile(req, stream, file.length());
+        System.out.println("started scan: " + response.toString());
+    }
+}
+```
+
+
+## Contributing
+
+Contributions are welcome! Open a pull request to fix a bug, or open an issue to discuss a new feature
+or change. Please adhere to the linting criteria defined in `checkstyle.xml`, and be sure to add unit
+tests for any new functionality you add.
+
+Refer to `CONTRIBUTING.md` for the full details.
+
+## License
+
+This code is licensed under the terms of the MIT License. See [here](https://opensource.org/licenses/MIT)
+for more information.
+
+Java is licensed by Oracle. See [here](https://www.oracle.com/java/technologies/javase/jdk-faqs.html)
+for more information.

src/main/java/ai/nightfall/scan/model/ScanFileResponse.java

@@ -32,4 +32,12 @@ public UUID getId() {
     public String getMessage() {
         return message;
     }
+
+    @Override
+    public String toString() {
+        return "ScanFileResponse{"
+                + "id=" + id
+                + ", message='" + message + '\''
+                + '}';
+    }
 }