Initial commit

Author: Patrick Kosterman

README.md

@@ -1,2 +1,85 @@
 # passkit-golang-members-quickstart
-Quickstart to create, distribute, analyse and manage your Digital Membership for Apple Wallet and Google Pay
+
+__Important Disclaimer:__ _This repository is currently under development. Below instructions are meant as a reference for beta partners, and could be subject to changes. Please note that the environment mentioned in below Quickstart is our Development Environment, which should not be used in a production setting; this is purely for exploratory testing. Data created in our Development Environment can be purged at anytime at our discretion without notice._
+
+The PassKit IO SDK makes it quick and easy to create and install your branded membership passes for Apple Wallet and Google Pay.
+
+
+This repository has following structure with each purpose.
+- `certs` folder is a place to store your credential files.
+- `examples` folder contains SDK methods you can use to create membership cards and engage with members.
+
+## Table of Content
+* [Installation](#installation)
+* [Prerequisites](#prerequisites)
+* [Quickstart](#quickstart)
+* [Examples](#examples)
+* [GUI Tool](#gui-tool)
+* [Documentation](#documentation)
+* [Check Other Passes](#check-other-passes)
+* [Getting Help](#getting-help)
+* [License](#license)
+
+## Installation
+Install passkit-io-go with:
+```go
+go get -u github.com/PassKit/passkit-golang-sdk
+```
+Then, import SDK with:
+```go
+import(
+    "github.com/PassKit/passkit-golang-sdk/io/members"
+    "github.com/PassKit/passkit-golang-sdk/io"
+)
+```
+## Prerequisites
+1. Create a PassKit account. Sign up for free [HERE](https://dev-app.passkit.io/).
+
+2. Download three `.pem` files you received by email after sign up. 
+   
+   To re-generate credentials, visit Settings (click gear icon in top right of the PassKit.IO web app window) > Developer Credential page and click 'Generate' (Login [HERE](https://dev-app.passkit.io/)).
+   
+## Quickstart
+By completing this Quickstart, you will be able to issue a membership card for a new member.
+
+1. Get [prerequisites](#prerequisites)
+
+2. Install passkit-io-go with:
+   ```go
+   go get -u github.com/PassKit/passkit-golang-sdk
+   ```
+
+3. When you created an account (Prerequisites #1), you should have received 3 files: `certificate.pem`, `key.pem` and `ca-chain.pem` by email. Please save those 3 files under `passkit-golang-members-quickstart/certs` directory. These .pem files are required to authenticate your accesss to PassKit.IO server.
+
+4. Now we need to decrypt your `key.pem`. At your project root directory, run `cd ./certs openssl ec -in key.pem -out key.pem`. Your `key.pem` file should look like below.
+   ![ScreenShot](https://github.com/PassKit/passkit-golang-members-quickstart/images/decrypted_key_pem.png)
+   If you do not see `Proc-Type: 4,ENCEYPTED` on line 2, you have successfully decrypted `key.pem`. 
+
+5. Replace `[email protected]` in `main.go` with your email address in order to receive the welcome email with card url which your member will also receive.
+
+6. Go back to root directory with `cd ../..`. Then run `go run main.go` to create a sample program (with default template & tier) and issue a membership card against that.
+
+## Examples
+#### Issue A Membership Card.
+Follow 5 steps of [Quickstart](#quickstart) to create a sample membership card and view it on your mobile.
+
+#### Engage With Your Members
+`EngageWithMembers()` contains multiple methods you can use to engage with your members. 
+For example, you can update contents of digital membership card or send a push notification.
+
+## GUI Tool
+GUI tool can be accessed from [your PassKit.IO account](https://dev-app.passkit.io/login).
+
+## Documentation
+* [PassKit.IO Membership Official Documentation](https://docs.passkit.io/protocols/member)
+
+## Check Other Passes
+* Coupons (coming soon)
+* Flight Ticket (coming soon)
+
+## Getting Help
+* Email [[email protected]](email:[email protected])
+* [Online chat support](https://passkit.com/)
+
+## License
+Distributed under MIT License. Details available on [license file](#).

certs/StoringPEMFilesInstruction.md

@@ -0,0 +1,19 @@
+## Required steps for storing 3 .pem files in this ./certs directory
+
+### What files do I need to store?
+- certificate.pem
+- key.pem
+- ca-chain.pem
+
+### [IMPORTANT] How can I decrypt key.pem file?
+You need to decrypt key.pem with `cd ./certs openssl ec -in key.pem -out key.pem` from project root directory.
+
+### Where do I need to store those 3 .pem files?
+Please store at passkit-golang-members-quickstart/certs directory which is the same directory as this README file.
+
+### Where can I get those 3 .pem files?
+Those files are emailed to you right after account creation or you can find them on Settings (click gear icon in top right of the PassKit.IO web app window) > Developer Credential page (https://dev-app.passkit.io/login).
+
+### Why do I need to store .pem files?
+.pem files are used to authenticate you to connect with PassKit server.
+ 

examples/connect_passkit_sdk.go

@@ -0,0 +1,43 @@
+package examples
+
+import (
+	"fmt"
+	"io/ioutil"
+	"log"
+
+	"github.com/PassKit/passkit-golang-sdk/helpers/router"
+
+	"google.golang.org/grpc"
+)
+
+var conn *grpc.ClientConn
+
+// ConnectPasskitSdk takes your credentials and establish connection with PassKit SDK.
+func ConnectPasskitSdk(clientCertFile, clientKeyFile, clientCAFile, gRPCHost, gRPCPort string) {
+	var err error
+
+	cert, err := ioutil.ReadFile(clientCertFile)
+
+	if err != nil {
+		log.Fatalf("could not load certificate file: %v", err)
+	}
+
+	key, err := ioutil.ReadFile(clientKeyFile)
+
+	if err != nil {
+		log.Fatalf("could not load key file: %v", err)
+	}
+
+	ca, err := ioutil.ReadFile(clientCAFile)
+
+	if err != nil {
+		log.Fatalf("could not load ca file: %v", err)
+	}
+
+	// Generate context object to connect to the server.
+	if conn, err = router.NewCertAuthTLSGRPCClient(fmt.Sprintf("%s:%s", gRPCHost, gRPCPort), string(cert), string(key), string(ca)); err != nil {
+		log.Fatal(err.Error())
+	}
+
+	fmt.Println("Connect SDK Success: Established connection to the server successfully.")
+}

examples/count_members.go

@@ -0,0 +1,40 @@
+package examples
+
+import (
+	"fmt"
+	"log"
+
+	"github.com/PassKit/passkit-golang-sdk/io"
+	"github.com/PassKit/passkit-golang-sdk/io/members"
+
+	"golang.org/x/net/context"
+	"google.golang.org/grpc/metadata"
+)
+
+// CountMembers takes search conditions as pagination object and returns the number of members who match with the condition.
+func CountMembers(programId string) {
+	fmt.Println("Counting member records match with conditions...")
+
+	// Generate a members module client
+	pkMembersClient := members.NewMembersClient(conn)
+
+	// Generate context object to connect to the server.
+	ctx := context.Background()
+	ctx = metadata.NewOutgoingContext(ctx, nil)
+
+	listRequest := &members.ListRequest{
+		ProgramId: programId,
+		Pagination: &io.Pagination{
+			FilterField:    []string{"programId"},
+			FilterValue:    []string{programId},
+			FilterOperator: []string{"eq"},
+		},
+	}
+
+	countResponse, err := pkMembersClient.CountMembers(ctx, listRequest)
+	if err != nil {
+		log.Fatalf("Count member err: %v\n", err)
+	}
+
+	fmt.Printf("Count result was %v.\n", countResponse.Total)
+}

examples/create_program.go

@@ -0,0 +1,45 @@
+package examples
+
+import (
+	"fmt"
+	"log"
+
+	"github.com/PassKit/passkit-golang-sdk/io"
+	"github.com/PassKit/passkit-golang-sdk/io/members"
+
+	"golang.org/x/net/context"
+	"google.golang.org/grpc/metadata"
+)
+
+// CreateProgram takes a new program name and creates a new program. The method returns the program id.
+// A program needs to be created because program functions as a class object for tier and members.
+func CreateProgram() string {
+	fmt.Println("Start creating a membership program...")
+
+	// Generate PassKit Client object for Membership protocol.
+	pkMembersClient := members.NewMembersClient(conn)
+
+	// Generate context object to connect to the server.
+	ctx := context.Background()
+	ctx = metadata.NewOutgoingContext(ctx, nil)
+
+	// Create your membership program object.
+	program := &members.Program{
+		Name: "Membership Program",
+		Status: []io.ProjectStatus{
+			io.ProjectStatus_PROJECT_DRAFT,
+			io.ProjectStatus_PROJECT_ACTIVE_FOR_OBJECT_CREATION,
+		},
+	}
+
+	// Send gRPC request to create a membership program record.
+	programId, err := pkMembersClient.CreateProgram(ctx, program)
+	if err != nil || programId == nil {
+		log.Fatalf("Create program err: %v", err)
+	}
+
+	// You need this program id to create Tier and Member objects in order to issue membership card.
+	log.Printf("Create Program Success: You have successfully created your membership program. Your program id is %s.\n", programId.Id)
+
+	return programId.Id
+}

examples/create_tier.go

@@ -0,0 +1,67 @@
+package examples
+
+import (
+	"fmt"
+	"log"
+
+	"github.com/PassKit/passkit-golang-sdk/io"
+	"github.com/PassKit/passkit-golang-sdk/io/members"
+
+	"golang.org/x/net/context"
+	"google.golang.org/grpc/metadata"
+)
+
+// CreateTier takes a programId of an existing program, creates a new template (based of default template), creates a tier, and links this tier to the program.
+// The method returns the tier id.
+func CreateTier(programId string) string {
+	fmt.Println("Start creating a membership tier...")
+
+	// Generate a template module client
+	pkTemplatesClient := io.NewTemplatesClient(conn)
+
+	// Generate context object to connect to the server.
+	ctx := context.Background()
+	ctx = metadata.NewOutgoingContext(ctx, nil)
+
+	// In order to create a tier, we need a pass template id which holds pass design data. Let's use the default pass template for now.
+	defaultTemplateRequest := &io.DefaultTemplateRequest{
+		Protocol: io.PassProtocol_MEMBERSHIP,
+		Revision: uint32(1),
+	}
+
+	defaultPassTemplate, err := pkTemplatesClient.GetDefaultTemplate(ctx, defaultTemplateRequest)
+	if err != nil {
+		log.Fatalf("Create tier err: %v", err)
+	}
+
+	// If you use the default template, you need to set name, description and timezone because these fields are mandatory.
+	defaultPassTemplate.Name = "quick_start"
+	defaultPassTemplate.Description = "quick start sample template"
+	defaultPassTemplate.Timezone = "America/New_York"
+
+	templateId, err := pkTemplatesClient.CreateTemplate(ctx, defaultPassTemplate)
+	if templateId == nil || err != nil {
+		log.Fatalf("Could not create tier: %v", err)
+	}
+
+	// We now have a program id which we created in create_program.go example and default pass template.
+	// Let's create a tier. First, let's create a members module client.
+	pkMembersClient := members.NewMembersClient(conn)
+
+	tier := &members.Tier{
+		ProgramId:      programId,
+		PassTemplateId: templateId.Id,
+		Id:             "base",
+		TierIndex:      uint32(1),
+		Name:           "Base Tier",
+	}
+
+	tierId, err := pkMembersClient.CreateTier(ctx, tier)
+	if err != nil {
+		log.Fatalf("Create tier err: %v", err)
+	}
+
+	fmt.Printf("Create Tier Success: You have successfully created your tier. Your tier id is %s.\n", tierId.Id)
+
+	return tierId.Id
+}

examples/enrol_member.go

@@ -0,0 +1,47 @@
+package examples
+
+import (
+	"fmt"
+	"log"
+
+	"github.com/PassKit/passkit-golang-sdk/io"
+	"github.com/PassKit/passkit-golang-sdk/io/members"
+
+	"golang.org/x/net/context"
+	"google.golang.org/grpc/metadata"
+)
+
+// EnrolMember takes programId, tierId and memberDetails, creates a new member record, and sends a welcome email to deliver membership card url.
+// The method returns the member id. Member id is a part of card url.
+func EnrolMember(programId, tierId, emailAddress string) string {
+	fmt.Println("Start enrolling a member...")
+
+	// Generate a members module client
+	pkMembersClient := members.NewMembersClient(conn)
+
+	// Generate context object to connect to the server.
+	ctx := context.Background()
+	ctx = metadata.NewOutgoingContext(ctx, nil)
+
+	newMember := &members.Member{
+		TierId:    tierId,
+		ProgramId: programId,
+		MemberDetails: &io.Person{
+			Surname:      "Smith",
+			Forename:     "Bailey",
+			DisplayName:  "Bailey",
+			EmailAddress: emailAddress,
+		},
+	}
+
+	memberId, err := pkMembersClient.EnrolMember(ctx, newMember)
+	if err != nil {
+		log.Fatalf("Create tier err: %v", err)
+	}
+
+	// TODO: Change the pass url prefix to the production one
+	fmt.Printf("Enrol Member Success: You have successfully enrolled a member. Your member id is %s.\n", memberId.Id)
+	fmt.Printf("To check this member's membership card, please visit https://dev.pskt.io/%s\n", memberId.Id)
+
+	return memberId.Id
+}

examples/get_a_member.go

@@ -0,0 +1,35 @@
+package examples
+
+import (
+	"fmt"
+	"log"
+
+	"github.com/PassKit/passkit-golang-sdk/io"
+	"github.com/PassKit/passkit-golang-sdk/io/members"
+
+	"golang.org/x/net/context"
+	"google.golang.org/grpc/metadata"
+)
+
+// GetSingleMember takes memberId and returns the record of that member.
+func GetSingleMember(memberId string) {
+	fmt.Println("Getting a member record...")
+
+	// Generate a members module client
+	pkMembersClient := members.NewMembersClient(conn)
+
+	// Generate context object to connect to the server.
+	ctx := context.Background()
+	ctx = metadata.NewOutgoingContext(ctx, nil)
+
+	id := &io.Id{
+		Id: memberId,
+	}
+
+	memeberRecrod, err := pkMembersClient.GetMemberRecordById(ctx, id)
+	if err != nil {
+		log.Fatalf("Get member err: %v", err)
+	}
+
+	fmt.Printf("You have successfully retrieved a member record for [%s] %v\n", memberId, *memeberRecrod)
+}